Introduction

This document provides details of the Order API. It is recommended that you read both the Data API Introduction page and the Ometria Data Architecture pages before integrating with Ometria. The easiest way to add order data to Ometria is to use the Push API and the Order API should only be used for specific cases.


If you sell products in multiply currencies, then use the OrderExtended objects to ensure currency conversion takes place.


Where base currency is used, this is the currency your Ometria account is set to report in. Local currency is the currency the product was sold in.

Contents

About The Order API

The Order API provides methods to create, update and retrieve orders. To create and update orders in bulk, see the Push API.

Customer

The customer used in the order can be associated with an existing profile or create a new customer or even be not associated with a customer at all (for example where the order was made in a store and the customer was not identified).

Note. The ID in in the OrderCustomer object is the Customer_ID detailed on the Contact object.

The following table provides details of how different customers are processed.

Values ProvidedPre-existing in OmetriaAction
ID
Email
NoA new profile is created. The new profile has no marketing preferences associated with it.
ID
Email
YesOrder is associated with existing profile.
EmailNoA new profile is created. The new profile has no marketing preferences associated with it.
EmailYesOrder is associated with existing profile.
Where multiple email exist with different customer_IDs, the order will be associated with the record without a customer_ID.
If a record does not exist with just email, a new profile will be created. The new profile has no marketing preferences associated with it.
IDNoA new profile is created. The new profile has no marketing preferences associated with it.
IDYesOrder is associated with existing profile.
Firstname & LastnameN/AOrder is created and not associated with any profile.

Refunds

When processing refunds within Ometria, different actions need to be taken whether the order is partially or fully refunded.

Partial Refunds

Partial refunds is where one or more of the total number of products purchased are refunded.

In this case the following values need to be passed for each line item being refunded.

ValueDescription
quantity_refundedThe number of units of that line item that have been refunded
refunded

The total price of refunded products in this line item

quantityThe quantity of the products purchased after the refunded units
totalThe total price for the line item after the refunded units

Full Refund

A full refund is where all products purchased are refunded.

In this case, the whole order needs to be resubmitted with the following values set.

ValueDescription
is_validfalse
statusrefunded

Note. Updating the order timestamps when refunding an order can affect the reporting. If you want the reporting to show when the order was made, then do not update the timestamps. If you want the reporting to show when the items are refunded, update the order timestamp. When updating timestamps, be aware that this can trigger automation campaigns.

Note. When retrieving an order via the API, the value total_unit_quantity_refunded is automatically calculated by Ometria.

Product Matching

When passing orderlineitems, it is possible to pass either the product_id or sku. If the sku is passed, this is used to identify the right product in the database.

The following table provides details of how orderlineitems are processed.

Values ProvidedPre-existing in OmetriaAction
product_idNoA new product is created with the attributes passed in the orderlineitem.
product_idYesorderlineitem is associated with the existing product. 
skuNoThe order is created, but the product is not created. The order will contain the correct values, but you will not be able to report on the product.
skuYesorderlineitem is associated with the existing product.

Note. When no sku match is found and a product is created with a matching sku after the order event, the sku will not be historically matched. To correct this orderlineitem, repush the order after the product has been created.

Currency Exchange

When passing orders that are not in the account base currency, a conversion will take place using the currency exchange rate as supplied by openexchangerates.org.

Store IDs

The store identifier (used in orders and in the javascript tracking layer) can be any string value. We recommend the use of the sites domain name (e.g. example.com). If your store has variable 'sub-stores' (e.g. different territories) we recommend the naming convention <domain>/<language> (e.g. example.com/uk).

It is also acceptable to use numeric store IDs if you have these defined, e.g. "123".

Order Methods

List Orders

Get Order

Create Order

Order Objects

Order

OrderAddress

OrderCustomer

OrderExtended

OrderExtendedBaseTotal

OrderExtendedLineItemBaseTotal

OrderExtendedLineItemLocalTotal

OrderExtendedLineItemTotals

OrderExtendedLocalTotal

OrderExtendedTotals

OrderLineItem

OrderLineItemVariantOption


List Orders

Path

GET /orders

Description

List orders with optional filters

Request Parameters

limit

Number of items to return. Max 250.

typestring (default: "10")
inquery
offset

Index of first record.

typestring (default: "0")
inquery

Responses

200 OK

Array<Order>

List of Order objects

403 Forbidden

API key is not authorised to access this resource


Response Example (200 OK)

[
  {
    "@type": "order",
    "billing_address": {
      "city": "London",
      "country_code": "GB",
      "postcode": "W1K 4TG",
      "state": "Greater London"
    },
    "channel": "online",
    "coupon_code": "FJ45-TJ5Y-5YK3-T894",
    "currency": "GBP",
    "customer": {
      "email": "john.smith@example.com",
      "firstname": "John",
      "lastname": "Smith"
    },
    "discount": -5,
    "grand_total": 96.4,
    "id": "123553",
    "ip_address": "127.0.0.1",
    "is_valid": true,
    "lineitems": [
      {
        "product_id": "SS14-059493",
        "properties": {
          "custom_key": "custom value"
        },
        "quantity": 2,
        "sku": "SS14-059493-S5",
        "total": 100,
        "unit_price": 50,
        "variant_options": [
          {
            "id": "large",
            "label": "Large",
            "type": "size"
          },
          {
            "id": "color-45",
            "label": "Blue",
            "type": "color"
          }
        ]
      }
    ],
    "payment_method": "card",
    "properties": {
      "custom_key": "custom value"
    },
    "shipping": 2,
    "shipping_address": {
      "city": "London",
      "country_code": "GB",
      "postcode": "W1K 4TG",
      "state": "Greater London"
    },
    "shipping_method": "standard",
    "status": "complete",
    "store": "example.com/en",
    "subtotal": 83.33,
    "tax": 16.07,
    "timestamp": "2015-01-02T09:00:00+00",
    "web_id": "891743"
  }
]

Get Order

Path

GET /orders/{order_id}

Description

Return a single Order item

Request Parameters

order_id

ID of order to fetch.

typestring
inpath
limit

Number of items to return. Max 250.

typestring (default: "10')
inquery
offset

Index of first record.

typestring (default: "0")
inquery

Responses

200 OK Order

Order object

403 Forbidden

API key is not authorised to access this resource

404 Not Found

Order with specified ID was not found

Response Example (200 OK)

{
  "@type": "order",
  "billing_address": {
    "city": "London",
    "country_code": "GB",
    "postcode": "W1K 4TG",
    "state": "Greater London"
  },
  "channel": "online",
  "coupon_code": "FJ45-TJ5Y-5YK3-T894",
  "currency": "GBP",
  "customer": {
    "email": "john.smith@example.com",
    "firstname": "John",
    "lastname": "Smith"
  },
  "discount": -5,
  "grand_total": 96.4,
  "id": "123553",
  "ip_address": "127.0.0.1",
  "is_valid": true,
  "lineitems": [
    {
      "product_id": "SS14-059493",
      "properties": {
        "custom_key": "custom value"
      },
      "quantity": 2,
      "sku": "SS14-059493-S5",
      "total": 100,
      "unit_price": 50,
      "variant_options": [
        {
          "id": "large",
          "label": "Large",
          "type": "size"
        },
        {
          "id": "color-45",
          "label": "Blue",
          "type": "color"
        }
      ]
    }
  ],
  "payment_method": "card",
  "properties": {
    "custom_key": "custom value"
  },
  "shipping": 2,
  "shipping_address": {
    "city": "London",
    "country_code": "GB",
    "postcode": "W1K 4TG",
    "state": "Greater London"
  },
  "shipping_method": "standard",
  "status": "complete",
  "store": "example.com/en",
  "subtotal": 83.33,
  "tax": 16.07,
  "timestamp": "2015-01-02T09:00:00+00",
  "web_id": "891743"
}

Create Order

Path

POST /orders/{order_id}

Description

Create new or update an existing order

Request Body

Order

Order object.

For multi currency use OrderExtended.

Request Parameters

order_idID of order being created or updated.
typestring
inpath

Responses

200 OK

Order object successfully created or updated

403 Forbidden

API key is not authorised to access this resource

Request Example

{
  "@type": "order",
  "billing_address": {
    "city": "London",
    "country_code": "GB",
    "postcode": "W1K 4TG",
    "state": "Greater London"
  },
  "channel": "online",
  "coupon_code": "FJ45-TJ5Y-5YK3-T894",
  "currency": "GBP",
  "customer": {
    "email": "john.smith@example.com",
    "firstname": "John",
    "lastname": "Smith"
  },
  "discount": -5,
  "grand_total": 96.4,
  "id": "123553",
  "ip_address": "127.0.0.1",
  "is_valid": true,
  "lineitems": [
    {
      "product_id": "SS14-059493",
      "properties": {
        "custom_key": "custom value"
      },
      "quantity": 2,
      "sku": "SS14-059493-S5",
      "total": 100,
      "unit_price": 50,
      "variant_options": [
        {
          "id": "large",
          "label": "Large",
          "type": "size"
        },
        {
          "id": "color-45",
          "label": "Blue",
          "type": "color"
        }
      ]
    }
  ],
  "payment_method": "card",
  "properties": {
    "custom_key": "custom value"
  },
  "shipping": 2,
  "shipping_address": {
    "city": "London",
    "country_code": "GB",
    "postcode": "W1K 4TG",
    "state": "Greater London"
  },
  "shipping_method": "standard",
  "status": "complete",
  "store": "example.com/en",
  "subtotal": 83.33,
  "tax": 16.07,
  "timestamp": "2015-01-02T09:00:00+00",
  "web_id": "891743"
}

Order:object

Describes an Order record.

ValueTypeDescriptionRequired
@typestring

The value must be "order". This shows that this record represents an order object.

Required
idstring
Required
timestampstring (date-time)

Date and time the order was placed on the site or in store. Following ISO 8601 dateTime format with timezone offset YYYY-MM-DDThh:mm:ss+Z.

Required
grand_totalnumber (float)

The grand total of the order.

Required
subtotal

number (float)

The subtotal of this order.


discountnumber (float)

This value should be negative or 0. Not positive.


shippingnumber (float)

The shipping cost of this order.


taxnumber (float)

The tax amount of this order.


currencystring (3 chars)

The currency for this order. Following ISO 4217.

Required
web_idstring

The web ID passed with through the JS tracker, this is only required if the value is different to the id.


statusstring

Code representing the status of this order 'complete', 'pending', 'shipped' etc.


is_validboolean

Sets the order to valid or invalid. Valid orders are counted in reporting.


customerOrderCustomer

lineitemsobject[]

Array of OrderLineItem objects representing the items in this order.


ip_addressstring

IP address of visitor who placed order if known.


channelstring online

Channel of this order. E.g., 'online', 'instore', 'amazon' etc.


storestring

Code representing the store the order was placed in.


payment_methodstring

Code representing payment method.


shipping_methodstring

Code representing shipping method.


shipping_addressOrderAddress

Address this order was shipped to.


billing_addressOrderAddress

Address this order was billed to.


coupon_codestring

Coupon code applied to this order.


propertiesobject

Custom key / value pairs accessible in emails using this order object


Example

{
  "@type": "order",
  "billing_address": {
    "city": "London",
    "country_code": "GB",
    "postcode": "W1K 4TG",
    "state": "Greater London"
  },
  "channel": "online",
  "coupon_code": "FJ45-TJ5Y-5YK3-T894",
  "currency": "GBP",
  "customer": {
    "email": "john.smith@example.com",
    "firstname": "John",
    "lastname": "Smith"
  },
  "discount": -5,
  "grand_total": 96.4,
  "id": "123553",
  "ip_address": "127.0.0.1",
  "is_valid": true,
  "lineitems": [
    {
      "product_id": "SS14-059493",
      "properties": {
        "custom_key": "custom value"
      },
      "quantity": 2,
      "sku": "SS14-059493-S5",
      "total": 100,
      "unit_price": 50,
      "variant_options": [
        {
          "id": "large",
          "label": "Large",
          "type": "size"
        },
        {
          "id": "color-45",
          "label": "Blue",
          "type": "color"
        }
      ]
    }
  ],
  "payment_method": "card",
  "properties": {
    "custom_key": "custom value"
  },
  "shipping": 2,
  "shipping_address": {
    "city": "London",
    "country_code": "GB",
    "postcode": "W1K 4TG",
    "state": "Greater London"
  },
  "shipping_method": "standard",
  "status": "complete",
  "store": "example.com/en",
  "subtotal": 83.33,
  "tax": 16.07,
  "timestamp": "2015-01-02T09:00:00+00",
  "web_id": "891743"
}

OrderAddress:object

Describes an Address.

ValueTypeDescriptionRequired
citystring

The town or city of the address.


statestring

The state or county of the address.


postcodestring

The postcode or zipcode of the address.


country_codestring (2 chars)

The country for this address. Following ISO 3166-1 alpha-2.


Example

{
  "city": "London",
  "country_code": "GB",
  "postcode": "W1K 4TG",
  "state": "Greater London"
}

OrderCustomer:object

Describes the customer details attached to an Order.

ValueTypeDescriptionRequired
idstring

The ID of the customer. See Customer.


emailstring

The email address of the customer.


firstnamestring

The first name of the customer.


lastnamestring

The last name of the customer


Example

{
  "email": "john.smith@example.com",
  "firstname": "John",
  "id": "546548",
  "lastname": "Smith"
}

OrderExtended:object

Describes an Order record.

ValueTypeDescriptionRequired
@typestring

The value must be "order". This shows that this record represents an order object.

Required
idstring
Required
timestampstring (date-time)

Date and time the order was placed on the site or in store. Following ISO 8601 dateTime format with timezone offset YYYY-MM-DDThh:mm:ss+Z.

Required
totals: OrderExtendedTotals

Required
web_idstring

The web ID passed with through the JS tracker, this is only required if the value is different to the id.


statusstring

Code representing the status of this order 'complete', 'pending', 'shipped' etc.


is_validboolean

Sets the order to valid or invalid. Valid orders are counted in reporting.


customerOrderCustomer

lineitemsobject[]

Array of OrderLineItem objects representing the items in this order.


ip_addressstring

IP address of visitor who placed order if known.


channelstring online

Channel of this order. E.g., 'online', 'instore', 'amazon' etc.


storestring

Code representing the store the order was placed in.


payment_methodstring

Code representing payment method.


shipping_methodstring

Code representing shipping method.


shipping_addressOrderAddress

Address this order was shipped to.


billing_addressOrderAddress

Address this order was billed to.


coupon_codestring

Coupon code applied to this order.


propertiesobject

Custom key / value pairs accessible in emails using this order object


Example

{
  "@type": "order",
  "billing_address": {
    "city": "London",
    "country_code": "GB",
    "postcode": "W1K 4TG",
    "state": "Greater London"
  },
  "channel": "online",
  "coupon_code": "FJ45-TJ5Y-5YK3-T894",
  "customer": {
    "email": "john.smith@example.com",
    "firstname": "John",
    "lastname": "Smith"
  },
  "id": "123553",
  "ip_address": "127.0.0.1",
  "is_valid": true,
  "lineitems": [
    {
      "product_id": "SS14-059493",
      "properties": {
        "custom_key": "custom value"
      },
      "quantity": 2,
      "sku": "SS14-059493-S5",
      "totals": {
        "base": {
          "currency": "GBP",
          "discount": -4,
          "subtotal": 99,
          "tax": 0,
          "total": 95,
          "unit_price": 99
        },
        "local": {
          "currency": "USD",
          "discount": -9,
          "subtotal": 129,
          "tax": 0,
          "total": 120,
          "unit_price": 129
        }
      },
      "unit_price": 50,
      "variant_options": [
        {
          "id": "large",
          "label": "Large",
          "type": "size"
        },
        {
          "id": "color-45",
          "label": "Blue",
          "type": "color"
        }
      ]
    }
  ],
  "payment_method": "card",
  "properties": {
    "custom_key": "custom value"
  },
  "shipping_address": {
    "city": "London",
    "country_code": "GB",
    "postcode": "W1K 4TG",
    "state": "Greater London"
  },
  "shipping_method": "standard",
  "status": "complete",
  "store": "example.com/en",
  "timestamp": "2015-01-02T09:00:00+00",
  "totals": {
    "base": {
      "currency": "USD",
      "discount": -10,
      "grand_total": 149,
      "shipping": 10,
      "tax": 20
    },
    "local": {
      "currency": "USD",
      "discount": -10,
      "grand_total": 149,
      "shipping": 10,
      "tax": 20
    }
  },
  "web_id": "891743"
}

OrderExtendedBaseTotal:object

The totals of this order represented in the base currency

ValueTypeDescriptionRequired
currencystring (3 chars)

The base currency totals. The base currency is the currency your Ometria account is set to report in. Following ISO 4217

Required
shippingnumber (float)

The value of the shipping in the base currency


taxnumber (float)

The value of the tax in the base currency


discountnumber (float)

The value of the discount in the base currency as a negative number


subtotalnumber (float)

The value of the subtotal in the base currency


grand_totalnumber (float)

The value of the grand total in the base currency

Required

Example

{
  "currency": "USD",
  "discount": -10,
  "grand_total": 149,
  "shipping": 10,
  "tax": 20
}

OrderExtendedLineItemBaseTotal:object

The totals of this lineitem represented in the base currency

ValueTypeDescriptionRequired
currencystring (3 chars)

The currency of the base lineitem totals. The base currency is the currency your Ometria account is set to report in. Following ISO 4217


unit_pricenumber (float)

The value of the unit price in the base currency

Required
discountnumber (float)

The value of the discount on the lineitem in the base currency as a negative number


refundednumber (float)

The total price of refunded products in this line item.

Note. If refunding a partial or whole order, see section Refunds.


subtotalnumber (float)

The subtotal of this lineitem in the base currency (after refunded amounts have been taken into consideration).

Required
taxnumber (float)

The tax of this lineitem in the base currency (after refunded amounts have been taken into consideration).


totalnumber (float)

The total price of this line item in the base currency (after refunded amounts have been taken into consideration).

Required

Example

{
  "currency": "GBP",
  "discount": -4,
  "subtotal": 95,
  "tax": 0,
  "total": 95,
  "unit_price": 99
}

OrderExtendedLineItemLocalTotal:object

The totals of this lineitem represented in the local currency

ValueTypeDescriptionRequired
currencystring (3 chars)

The currency of the local lineitem totals. Following ISO 4217


unit_pricenumber (float)

The value of the unit price in the local currency

Required
discountnumber (float)

The value of the discount on the lineitem in the local currency as a negative number


refundednumber (float)

The total price of refunded products in this line item.

Note. If refunding a partial or whole order, see section Refunds.


subtotalnumber (float)

The subtotal of this lineitem in the local currency (after refunded amounts have been taken into consideration).

Required
taxnumber (float)

The tax of this lineitem in the local currency (after refunded amounts have been taken into consideration).


totalnumber (float)

The total price of this line item in the local currency (after refunded amounts have been taken into consideration).

Required

Example

{
  "currency": "USD",
  "discount": -9,
  "subtotal": 120,
  "tax": 0,
  "total": 120,
  "unit_price": 129
}

OrderExtendedLineItemTotals:object

The totals of the lineitem. This can be used to express the order value in a base currency and a local currency.

base: OrderExtendedLineItemBaseTotal 
local: OrderExtendedLineItemLocalTotal

Example

{
  "base": {
    "currency": "GBP",
    "discount": -4,
    "total": 95,
    "unit_price": 99
  },
  "local": {
    "currency": "USD",
    "discount": -9,
    "total": 120,
    "unit_price": 129
  }
}

OrderExtendedLocalTotal:object

The totals of this order represented in the local currency

ValueTypeDescriptionRequired
currencystring (3 chars)

The currency of the local totals. Following ISO 4217

Required
shippingnumber (float)

The value of the shipping in the local currency


taxnumber (float)

The value of the tax in the local currency


discountnumber (float)

The value of the discount in the local currency as a negative number


subtotalnumber (float)

The value of the subtotal in the local currency


grand_totalnumber (float)

The value of the grand total in the local currency

Required

Example

{
  "currency": "USD",
  "discount": -10,
  "grand_total": 149,
  "shipping": 10,
  "tax": 20
}

OrderExtendedTotals:object

The totals of the order in a base currency and a local currency. If this object is not passed, Ometria will make a currency conversion based on the days exchange rate using openexchangerates.org.

base: OrderExtendedBaseTotal 
local: OrderExtendedLocalTotal

Example

{
  "base": {
    "currency": "USD",
    "discount": -10,
    "grand_total": 149,
    "shipping": 10,
    "tax": 20
  },
  "local": {
    "currency": "USD",
    "discount": -10,
    "grand_total": 149,
    "shipping": 10,
    "tax": 20
  }
}


OrderLineItem: object

Describes an individual product line item added to an Order.

ValueTypeDescriptionRequired
product_idstring

The ID of the product. One of product_id or sku is required.

Required
variant_idstring

The ID of the variant of the product (if applicable).


quantityinteger

The number of products in the line item (not inclusive of any refunded items).

Required
skustring

The SKU of the product. One of product_id or sku is required.

Required
unit_pricenumber (float)

The unit price of the product in this line item.

Required
quantity_refundedinteger

The number of products refunded in the line item.


refundednumber (float)

The total price of refunded products in this line item.

Note. If refunding a partial or whole order, see section Refunds.


subtotalnumber (float)

The subtotal of this lineitem (after refunded amounts have been taken into consideration).

Required
taxnumber (float)

The tax of this lineitem (after refunded amounts have been taken into consideration).


totalnumber (float)

The total price of this line item (after refunded amounts have been taken into consideration).


discountnumber (float)

Must be a negative number.


is_on_saleboolean

Indicating whether the product was on sale when the order was placed.


variant_optionsobjectAn array of OrderLineItemVariantOption objects.


totalsOrderExtendedLineItemTotals

propertiesobject

Custom key / value pairs accessible in emails using the related Order object.


Example

{
  "discount": -10,
  "is_on_sale": true,
  "product_id": "SS14-059493",
  "properties": {
    "custom_key": "custom value"
  },
  "quantity": 2,
  "sku": "SS14-059493-S5",
  "subtotal": 100,
  "tax": 0,
  "total": 100,
  "unit_price": 50,
  "variant_options": [
    {
      "id": "large",
      "label": "Large",
      "type": "size"
    },
    {
      "id": "color-45",
      "label": "Blue",
      "type": "color"
    }
  ]
}



OrderLineItemVariantOption: object

Describes the configurable options attached to a Lineitem.

ValueTypeDescriptionRequired
typestring

The type of the variant option.

Required
idstring

The id of the variant option.

Required
labelstring

The label of the variant option.

Required

Example

{
  "id": "size:5",
  "label": "5",
  "type": "size"
}