This document provides details of the Order API.
We recommend 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.
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 Provided |
Pre-existing in Ometria |
Action |
|
ID |
No |
A new profile is created. The new profile has no marketing preferences associated with it. |
|
ID |
Yes |
Order is associated with existing profile. |
|
|
No |
A new profile is created. The new profile has no marketing preferences associated with it. |
|
|
Yes |
Order 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. |
|
ID |
No |
A new profile is created. The new profile has no marketing preferences associated with it. |
|
ID |
Yes |
Order is associated with existing profile. |
|
Firstname & Lastname |
N/A |
Order is created and not associated with any profile. |
Refunds
When processing refunds in 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:
|
Value |
Description |
|
quantity_refunded |
The number of units of that line item that have been refunded. |
|
refunded |
The total price of refunded products in this line item. |
|
quantity |
The quantity of the products purchased after the refunded units. |
|
total |
The total price for the line item after the refunded units. |
|
grand_total |
The overall grand total for the order after the refunded units. |
|
subtotal |
The subtotal of the order after the refunded units. |
|
tax |
The tax for the refunded line item. |
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.
|
Value |
Description |
|
is_valid |
false |
|
status |
refunded |
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.
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 Provided |
Pre-existing in Ometria |
Action |
|
product_id |
No |
A new product is created with the attributes passed in the orderlineitem. |
|
product_id |
Yes |
orderlineitem is associated with the existing product. |
|
sku |
No |
The 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. |
|
sku |
Yes |
orderlineitem 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.
The latest currency rates are pulled into Ometria hourly.
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
Order Objects
OrderExtendedLineItemBaseTotal
OrderExtendedLineItemLocalTotal
List Orders
Path
GET /orders
Description
List orders with optional filters
Request Parameters
|
limit |
Number of items to return. Max 250. |
|
type |
string (default: "10") |
|
in |
query |
|
offset |
Index of first record. |
|
type |
string (default: "0") |
|
in |
query |
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"
}
]
[
{
"@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. |
|
type |
string |
|
in |
path |
|
limit |
Number of items to return. Max 250. |
|
type |
string (default: "10') |
|
in |
query |
|
offset |
Index of first record. |
|
type |
string (default: "0") |
|
in |
query |
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 object. For multi currency use OrderExtended. |
Request Parameters
|
order_id |
ID of order being created or updated. |
|
type |
string |
|
in |
path |
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.
|
Value |
Type |
Description |
Required |
|
@type |
string |
The value must be "order". This shows that this record represents an order object. |
Required |
|
id |
string |
Required |
|
|
timestamp |
string (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_total |
number (float) |
The grand total of the order. |
Required |
|
subtotal |
number (float) |
The subtotal of this order. |
|
|
discount |
number (float) |
This value should be negative or 0. Not positive. |
|
|
shipping |
number (float) |
The shipping cost of this order. |
|
|
tax |
number (float) |
The tax amount of this order. |
|
|
currency |
string (3 chars) |
The currency for this order. Following ISO 4217. |
Required |
|
web_id |
string |
The web ID passed with through the JS tracker, this is only required if the value is different to the id. |
|
|
status |
string |
Code representing the status of this order 'complete', 'pending', 'shipped' etc. |
|
|
is_valid |
boolean |
Sets the order to valid or invalid. Valid orders are counted in reporting. |
|
|
customer |
|||
|
lineitems |
object[] |
Array of OrderLineItem objects representing the items in this order. |
|
|
ip_address |
string |
IP address of visitor who placed order if known. |
|
|
channel |
string online |
Channel of this order. E.g., 'online', 'instore', 'amazon' etc. |
|
|
store |
string |
Code representing the store the order was placed in. |
|
|
payment_method |
string |
Code representing payment method. |
|
|
shipping_method |
string |
Code representing shipping method. |
|
|
shipping_address |
Address this order was shipped to. |
||
|
billing_address |
Address this order was billed to. |
||
|
coupon_code |
string |
Coupon code applied to this order. |
|
|
properties |
object |
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.
|
Value |
Type |
Description |
Required |
|
city |
string |
The town or city of the address. |
|
|
state |
string |
The state or county of the address. |
|
|
postcode |
string |
The postcode or zipcode of the address. |
|
|
country_code |
string (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.
|
Value |
Type |
Description |
Required |
|
id |
string |
The ID of the customer. See Customer. |
|
|
|
string |
The email address of the customer. |
|
|
firstname |
string |
The first name of the customer. |
|
|
lastname |
string |
The last name of the customer |
Example
{
"email": "john.smith@example.com",
"firstname": "John",
"id": "546548",
"lastname": "Smith"
}
OrderExtended:object
Describes an Order record.
|
Value |
Type |
Description |
Required |
|
@type |
string |
The value must be "order". This shows that this record represents an order object. |
Required |
|
id |
string |
Required |
|
|
timestamp |
string (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_id |
string |
The web ID passed with through the JS tracker, this is only required if the value is different to the id. |
|
|
status |
string |
Code representing the status of this order 'complete', 'pending', 'shipped' etc. |
|
|
is_valid |
boolean |
Sets the order to valid or invalid. Valid orders are counted in reporting. |
|
|
customer |
|||
|
lineitems |
object[] |
Array of OrderLineItem objects representing the items in this order. |
|
|
ip_address |
string |
IP address of visitor who placed order if known. |
|
|
channel |
string online |
Channel of this order. E.g., 'online', 'instore', 'amazon' etc. |
|
|
store |
string |
Code representing the store the order was placed in. |
|
|
payment_method |
string |
Code representing payment method. |
|
|
shipping_method |
string |
Code representing shipping method. |
|
|
shipping_address |
Address this order was shipped to. |
||
|
billing_address |
Address this order was billed to. |
||
|
coupon_code |
string |
Coupon code applied to this order. |
|
|
properties |
object |
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
|
Value |
Type |
Description |
Required |
|
currency |
string (3 chars) |
The base currency totals. The base currency is the currency your Ometria account is set to report in. Following ISO 4217 |
Required |
|
shipping |
number (float) |
The value of the shipping in the base currency |
|
|
tax |
number (float) |
The value of the tax in the base currency |
|
|
discount |
number (float) |
The value of the discount in the base currency as a negative number |
|
|
subtotal |
number (float) |
The value of the subtotal in the base currency |
|
|
grand_total |
number (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
|
Value |
Type |
Description |
Required |
|
currency |
string (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_price |
number (float) |
The value of the unit price in the base currency |
Required |
|
discount |
number (float) |
The value of the discount on the lineitem in the base currency as a negative number |
|
|
refunded |
number (float) |
The total price of refunded products in this line item. Note. If refunding a partial or whole order, see section Refunds. |
|
|
subtotal |
number (float) |
The subtotal of this lineitem in the base currency (after refunded amounts have been taken into consideration). |
Required |
|
tax |
number (float) |
The tax of this lineitem in the base currency (after refunded amounts have been taken into consideration). |
|
|
total |
number (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
|
Value |
Type |
Description |
Required |
|
currency |
string (3 chars) |
The currency of the local lineitem totals. Following ISO 4217 |
|
|
unit_price |
number (float) |
The value of the unit price in the local currency |
Required |
|
discount |
number (float) |
The value of the discount on the lineitem in the local currency as a negative number |
|
|
refunded |
number (float) |
The total price of refunded products in this line item. Note. If refunding a partial or whole order, see Refunds. |
|
|
subtotal |
number (float) |
The subtotal of this lineitem in the local currency (after refunded amounts have been taken into consideration). |
Required |
|
tax |
number (float) |
The tax of this lineitem in the local currency (after refunded amounts have been taken into consideration). |
|
|
total |
number (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
|
Value |
Type |
Description |
Required |
|
currency |
string (3 chars) |
The currency of the local totals. Following ISO 4217 |
Required |
|
shipping |
number (float) |
The value of the shipping in the local currency |
|
|
tax |
number (float) |
The value of the tax in the local currency |
|
|
discount |
number (float) |
The value of the discount in the local currency as a negative number |
|
|
subtotal |
number (float) |
The value of the subtotal in the local currency |
|
|
grand_total |
number (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.
|
Value |
Type |
Description |
Required |
|
product_id |
string |
The ID of the product. One of product_id or sku is required. |
Required |
|
variant_id |
string |
The ID of the variant of the product (if applicable). |
|
|
quantity |
integer |
The number of products in the line item (not inclusive of any refunded items). |
Required |
|
sku |
string |
The SKU of the product. One of product_id or sku is required. |
Required |
|
unit_price |
number (float) |
The unit price of the product in this line item. |
Required |
|
quantity_refunded |
integer |
The number of products refunded in the line item. |
|
|
refunded |
number (float) |
The total price of refunded products in this line item. Note. If refunding a partial or whole order, see Refunds. |
|
|
subtotal |
number (float) |
The subtotal of this lineitem (after refunded amounts have been taken into consideration). |
Required |
|
tax |
number (float) |
The tax of this lineitem (after refunded amounts have been taken into consideration). |
|
|
total |
number (float) |
The total price of this line item (after refunded amounts have been taken into consideration). |
|
|
discount |
number (float) |
Must be a negative number. |
|
|
is_on_sale |
boolean |
Indicating whether the product was on sale when the order was placed. |
|
|
variant_options |
object |
An array of OrderLineItemVariantOption objects. |
|
|
totals |
|||
|
properties |
object |
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.
|
Value |
Type |
Description |
Required |
|
type |
string |
The type of the variant option. |
Required |
|
id |
string |
The id of the variant option. |
Required |
|
label |
string |
The label of the variant option. |
Required |
Example
{
"id": "size:5",
"label": "5",
"type": "size"
}
Comments
0 comments
Please sign in to leave a comment.