Details about the order data

Field NameTypeRequiredDetails
idNumberread onlyInternal Omnivore identifier for the order. 

StringnoThe code for the Marketplace. Possible values here (todo)
order_numberStringyesThe order number as created in the Marketplace. This is usually the handle for the orders
alt_order_numberStringnoAn alternate order number in the Marketplace. Some marketplaces (eg eBay) are using different values depending on where the information is displayed. 
retailer_order_idNumbernoWhen the order is created in the retailer system, this field can contain the order identifier from that system. (usually the database table id)
retailer_order_numberStringnoWhen the order is created in the retailer system, this field can contain the order number from that system. Most Omnivore integrations will get this value from the retailer system in te process of creating the order.
statusStringrequired for updateThe status of the order in Omnivore.
Todo values
total_pricePrice objectrequired for createThe total value of the order, including shipping but excluding additional fees and taxes that are charged by the Marketplace to the buyer
additional_feeMoney objectnoSome Marketplaces will charge an extra fee
additional_taxMoneynoSome Marketplaces (eg eBay) will charge the buyer an extra tax depending on their location. 
customer first_nameStringyes
customer last_nameStringyes
customer emailString no
shipping_addressAddressyesRequired for the create order method. Raed-only afterwards.
billing_addressAddressnoWhen not provided, the shipping_address data is copied into this field
shipping pricePriceyesThis is required when the order is created
shipping carrierStringnoThis can be optionally set when the order status is set to "shipped"
shipping methodStringyesA values set by the marketplace
shipping tracking_codeString noThis can be optionally set when the order status is set to "shipped"
line_itemsLIst of Line Item objectsyesAt least one line item must be provided in an order
transactionsList of Money objectsyesA list of transactions between the Marketplace and the buyer. For most orders that are valid, not cancelled or refunded, there is a single transaction that reflects the amount paid by the buyer and the respective currency, usually the currency of the marketplace.

Depending on marketplace type, this element may also contain a transactionId element and a type element, both relating to the payment transaction that occurred in the marketplace.  For example type = 'paypal' and transactionId = [PayPal transaction ID]
customer_messageString noAlso called "customer checkout message", it's a free text field where the buyer can provide additional info to facilitate order delivery.
createdDatetimeread onlyThe date and time when the order was created in Omnivore
updatedDatetimeread onlyThe date and time when the order was updated in Omnivore
created_in_marketplaceDatetimerequired for createThe date and time when the order was created in the Marketplace.
country_codeStringyes2 letter country code, as per
Line Item
idNumberread-onlyOmnivore internal line item identfier
product_skuStringread-onlyThe retailer sku of the product. This value is set by Omnivore by decoding the marketplace sku
variant_skuStringread-onlyThe retailer sku of the variant. This value is set by Omnivore by decoding the marketplace sku
marketplace_skuStringyesThe sku value of the item as known in the marketplace.
nameStringnoThe name of the product. 
unit_pricePriceyesThe price of a unit as sold in the Marketplace. 
quantityNumberyesHow many units of the item were sold.

Order Statuses

Retailer Order state changes are made through submitting change via the REST interface or in the Omnivore UI.  Certain states are transient and Omnivore will move the order automatically through to its next state once the designated action is completed.  Depending on whether the order is pick-up-in-store or ship-from-warehouse, there is a specific lifecycle as shown in the order lifecycle diagram below.

The full list of order statuses are here, in the order of where they are possible in the order lifecycle.

1. 'created' – initial state

(standard flow) : 2. if the retailer integration pushes order to the retailer's webservice: 'pending-payment-confirmed' – pending invoicing

(alternative flow) : 2. if the retailer integration pulls orders from Omnivore:  'pending-retailer-confirmation' – pending invoicing

2.1. 'hold' – order has been put on hold

2.2. 'pending-retailer-cancellation' – retailer has signalled that the order cannot be fulfilled (e.g. zero stock)

2.2.1 'retailer-cancellation' – order now cancelled

2.3. 'retailer-notified-failure' – order could not be sent to retailer

(ship-from-warehouse flow) : 3. 'pending-shipped' – awaiting shipment notification from retailer

(ship-from-warehouse flow) : 3.1. 'payment-confirmed-failure' – invoicing did not succeed

(ship-from-warehouse flow) : 3.2 'shipped' – dispatched to customer

(pick-up-in-store flow) : 3. 'ready-for-pick-up' – ready in the store to be collected by customer

(pick-up-in-store flow) : 3.1. 'pick-up-cancelled' – pick up did not proceed

(pick-up-in-store flow) : 3.2 'picked-up' – collected by customer

4. 'refunded-online' – refund has occurred

Allowed Lifecycle Changes for an Order

The following represents the possible statuses that an order can move into from an initial starting status.

  • 'created' > 'pending-retailer-cancellation' OR 'pending-payment-confirmed' OR 'hold' OR 'retailer-notifier-failure
  • 'retailer-notified-failure' > 'created'
  • 'hold' > 'created'
  • 'pending-retailer-cancellation' > 'retailer-cancellation'
  • 'pending-payment-confirmed' > 'pending-shipped' OR 'payment-confirmed-failure' OR 'ready-for-pick-up'
  • 'pending-shipped' > 'shipped' OR 'refunded-online'
  • 'ready-for-pick-up' > 'picked-up' OR 'pick-up-cancelled'
  • 'picked-up' > 'refunded-online'
  • 'shipped' > 'refunded-online'