Orders
We are no longer updating this site. For user documentation, please go to User Docs. For developer documentation, please go to Developer Docs. If you have any questions or feedback, please submit a ticket.
Orders in Zaius are created and updated via Events.
Each Order generates an order purchase event per order line item.
i.e. An order with three line items would generate three order events.
Top-level information about the order (e.g. billing address, coupon, tax) are stored in the Orders object and linked to order events on Order ID (
order_id). All Zaius events (and, as a result, order line items) are immutable, meaning that cannot be changed once uploaded to Zaius. If you need to process returns, refunds or cancellations please refer to the relevant documentation.
Display Name | Field Name | Data Type | Description |
Order ID | order_id | Text | The unique identifier related to this order. |
Product ID | product_id | Text | The unique identifier for the order line item. |
Order Item: Price | price | Number | The price for the order item. |
Order Item: Quantity | quantity | Number | The number of items purchased. |
Order Item: Discount | discount | Number | The discount (if any) for the given line item. |
Order Item: Subtotal | subtotal | Number | The calculated subtotal for the given product and quantity, typically calculated after any discounts. |
While order events cannot be updated, the Order Summary can be updated at any point using the Objects endpoint. Updates made via the Objects endpoint will not generate events.
Display Name | Field Name | Data Type | Description |
Order ID | order_id | Text | Required. The unique identifier related to this order. |
Status | status | Text | Required. The status of the order is taken from the event action. |
Tax | tax | Number | |
Discount | discount | Number | Typically the total value of discounts for the order, including line item and order level discounts. |
Shipping | shipping | Number | |
Subtotal | subtotal | Number | Subtotal may be taken either before or after discounting, but generally should be before shipping or tax. See below for more information. |
Total | total | Number | Total should include the final amount charged to the customer after all goods, discounts, tax, and shipping are calculated. See below for more information. |
Billing Address* | bill_address | Text | The billing address for the order, lines delimited by commas. Lines should include: Street 1, Street 2, City, State/Region/Province, ZIP/Postal Code, Country. To leave a field blank, be sure to include the comma delimiter (e.g. Street 1,,City) |
Shipping Address | ship_address | Text | The shipping address for the order, lines delimited by commas. Lines should include: Street 1, Street 2, City, State/Region/Province, ZIP/Postal Code, Country. To leave a field blank, be sure to include the comma delimiter (e.g. Street 1,,City) |
Phone* | phone | Text | |
Coupon Code | coupon_code | Text | |
First Name* | first_name | Text | Should match the billed customer. |
Last Name* | last_name | Text | Should match the billed customer. |
Name* | name | Text | Should match the billed customer. |
Email* | email | Text | |
Other identifiers (such as an ecomm platform id) can be added to the order record. A minimum of one identifier is required to process an order.
*This data plus any other identifiers will be used to create a customer record, if one does not already exist or to fill in missing info on an existing record. Info will not be overwritten if it already exists. In the case of identifiers email, phone, etc, multiple values can be stored/added to a single customer record; these identifiers are also used to match the order to an existing customer.
Zaius does not automatically calculate totals and subtotals at the order level based on item level subtotals or tax, shipping, and discounts. Instead, you will send these values as you would like them represented. Different ecommerce platforms handle the definition of subtotal differently, with some of them including discounts before the subtotal and others including discounts after the subtotal, but before the total. Still others handle line item discounts differently than order-level discounts.
The most important thing is to be consistent between historic imports and real-time orders, to ensure that subtotal and total are always calculated the same way across your customers and orders. To help you make this decision, please be aware that LTV and Average Order Value in Zaius (along with similarly derived fields) are based on the order subtotal.
The recommended method of sending historical Order data is to send the data via API or CSV. CSV files can be uploaded in the UI or via Amazon (AWS) S3. The fields utilized in either method adhere to the schema outlined above.
To process returns, refunds and cancellations, send an event with an event type of
order and one of the following event actions:The following event actions treat
-30 and 30 as a subtotal identically. They both create new events that subtract from the original order total.- 1.
return- a customer has returned some or all of the items in an order and been refunded. - 2.
refund- a customer has been issued a refund for a given order. Semantically, refunds are treated the same as returns in Zaius (e.g., negative impact on revenue). You can use either. Use both if you want to distinguish between inventory being returned to you (a return) and just money being issued to the original purchaser (a refund). If inventory is returned and money is issued back to the purchaser, Zaius recommends using the 'return' order action. - 3.
cancel- a customer has canceled their order. The order purchase and cancel events remain in Zaius (e.g., on the customer profile page, and for segmentation), and revenue is negatively impacted, but the order no longer figures in to determining the customer's lifecycle. This is in contrast to returns and refunds, where the order still counts in determining the order count, and thus lifecycle, for a customer.
Note that order returns, refunds, and cancels can be partial. Zaius determines if they are partial by tracking whether the running tally of the order's subtotal field across all events is greater than zero (partial) or not.
Zaius allows the subtotal and total fields for an order to go negative (e.g. to support purchase and refund events coming in out of order, or to support cases where the refund amount legitimately exceeds the purchase amount). Be cautious not to issue duplicate refund, return, and cancel events.
The actions
purchase, refund, return, and cancel behave as above. However, the action on the order can be customized to your business. These custom statuses are treated as below:- 1.If the order exists, the order details are not updated (i.e. the order total would not be incremented). The order information can sent as pass-through to an event triggered marketing campaign without concern about changing order details.
- 2.If the order does not exist, the order is created according to the details on the request.
Last modified 10mo ago