Dev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunitySubmit a ticketLog In
GitHubNuGetDev CommunitySubmit a ticket

Upload an order purchase/return/refund/cancellation event to Optimizely Data Platform (ODP).

The type parameter must always be set to order. Then, use the action parameter to define whether you are submitting an order purchase, return, refund, or cancellation.



Additional parameters:

  • ts – (Optional) Specify the time of the order purchase, return, refund, or cancellation.
  • total and subtotal – The absolute amount specified is subtracted from the existing value.
  • tax and shipping – (Optional) If specified, these values overwrite any existing value and should be the positive remainder.

Item fields defined in the data.order.items array are mapped to the Events object, one record per item in the order. For more information, see the developer documentation on orders in ODP.



Do not add custom fields to the data.order.items array. ODP does not process and map them to any object.

Only custom fields at the data.order level are copied to each item in the items array.

Order purchase

Set action to purchase.

  • An order purchase event automatically creates an order object.
  • An order purchase event does not create a product object. You must create the product object before submitting an order purchase event using one of the following methods:

Order return and refund

To process a return or refund, set action to return or refund, respectively.

Refunds are treated the same as returns in ODP as both have a negative impact on revenue. Using both lets you distinguish between inventory being returned (return) as opposed to money being issued to the original purchaser without any inventory being returned (refund).

If the inventory is returned and money is issued back to the purchaser, use the return action.

You do not need to input line items in the items array to process a partial refund. To send a partial refund, set the parameters as shown below:

  • type – order
  • action– refund



    You can also set the action to return to indicate that inventory is returned, but only a partial refund is issued back to the purchaser.

  • – Set this to the partial refund amount (ODP interprets this as the amount to deduct from the original order).
  • data.order.subtotal – Set this to the partial refund amount (ODP interprets this as the amount to deduct from the original order).

For example:

    "identifiers": {
      "email": "[email protected]"
    "type": "order",
    "action": "refund",
    "data": {
      "order": {
        "order_id": "ABC",
        "total": 10,
        "subtotal": 10

Order cancellation

Set action to cancel if the customer canceled their order.

Order purchase and cancel events remain in ODP (for example, on the customer profile page and for segmentation), and revenue is negatively impacted, but the order no longer figures into 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.

Click Try It! to start a request and see the response here!