This resource is for existing V1 API customers, if you're not using our APIs yet, please use the Omnivore V2 APIs.
The Order API has the ability interact with retailers systems at several key points in the order process. For example you can use the API to retrieve customer orders, the order number, and details of the order (containing customer information and the items requested).
The Order API helps you perform the following tasks:
- Get Retailer orders, filtered by date, last order, marketplace, number of orders to be retrieved
- Get confirmation of payments for orders
- Return order response or yes/no and submit a retailer internal purchase order/reference number back to the originating Marketplace
- Return a shipping/tracking i.d. response
Order Lifecycle Management
Retailer Order state changes are made through submitting an XML object to the Retailer Order resource. 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’
Retailer notification
In the sections below, some status changes may require the retailer to be notified. Note that the notification is via a POST of the Retailer Order to the retailer’s order endpoint. The system will assume that the notification was successful if it received a HTTP 200 response code, regardless of content also returned in the body of the HTTP response.
The APIs for the shipped and refunded status change as well as the ready for pick up and picked up status changes are detailed below.
pending shipped
Trigger: retailer action (but see note). Once order has been accepted and processed by the retailer, a confirmation is sent back containing the retailer’s order reference ID. This signals that the order has been received by the retailer successfully, and to wait for shipping confirmation. NOTE: depending on the retailer integration (and therefore the order delivery method) this step may not be necessary, e.g. if the retailer is able to produce an order ID synchronously in the response of the original order notification sent by Omnivore to the retailer’s system.
Request info: The following REST interface is used:
<?xml version="1.0" encoding="utf-8"?> <confirmation> <external_order_ref>73457245757</external_order_ref> </confirmation>
Success/error responses:
- 200 – Ok: operation was successful
- 400 – Bad request: the XML was malformed or the contents of one or more fields failed validation tests
- 403 – Forbidden: you do not have the right to invoke this operation on this resource, for example: you are attempting to access an order from another retailer
- 404 – Not found: retailer order not found
- 409 – Conflict: this action cannot be done with retailer order at this time
- 503 – Service unavailable: transient failure of the service
Resulting system state:
- Retailer Order has status ‘pending-shipped’
- Retailer Order has external_order_ref set to the external order reference
shipped
(See also Bulk Shipping below)
Trigger: retailer action. Once payment is successful the retailer will ship the order, providing the tracking/shipping reference at the same time.
Request info: The following REST interface is used:
<?xml version="1.0" encoding="utf-8"?> <delivery> <shipper>ZippyCouriers</shipper> <tracking_code>RT44FF1</tracking_code> <products> <product> <retailer_ref>agf1037724-Multi-6</retailer_ref> <sku>agf1037724</sku> <quantity>1</quantity> </product> </products> </delivery>
products - optional element. If included, product (and therefore retailer_ref, sku and quantity) is mandatory within the element.
Success/error responses:
The products element allows the user to specify which products in the order have changed status. In the above example, only 1 of the products under SKU agf1037724 in this order has changed state. NOTE: <quantity> shows the number of items for that SKU that have changed state in this call, NOT total quantity changed so far. So, if the order contains 3 items for SKU agf1037724 and 2 had already changed state in a previous call, the above would change the 3rd item’s state and trigger the entire order to change state to ‘shipped’.
If <products> is omitted, it is assumed that the entire order is being changed, e.g. all products in the order have been shipped in a single delivery.
- 200 – Ok: operation was successful
- 400 – Bad request: the XML was malformed or the contents of one or more fields failed validation tests
- 403 – Forbidden: you do not have the right to invoke this operation on this resource, for example: you are attempting to access an order from another retailer
- 404 – Not found: retailer order not found
- 409 – Conflict: this action cannot be done with retailer order at this time
- 503 – Service unavailable: transient failure of the service
Resulting system state:
- Retailer Order has status ‘shipped’ (if product quantities are specified, order will remain in ‘pending-shipped’ until all items have been shipped, even if that requires multiple calls)
- Retailer Order has external_tracking_ref set to the external tracking reference
ready for pick up
Trigger: retailer action. Once order has been allocated to a store, a notification is sent back containing the retailer’s (optional) pick up instructions and (optional) store pick-up code; this code will be used by the customer at pick up to verify that they are the intended recipient of the goods.
Request info: The following REST interface is used:
<?xml version="1.0" encoding="utf-8"?> <readyforpickup> <pickup_note>please go to the customer service desk on ground floor</pickup_note> <pickup_code>100001</pickup_code> <products> <product> <retailer_ref>agf1037724-Multi-6</retailer_ref> <sku>agf1037724</sku> <quantity>1</quantity> </product> </products> </readyforpickup> products - optional element. If included, product (and therefore retailer_ref, sku and quantity) is mandatory within the element. pickup_note - (optional field) pick up instructions to send to the customer pickup_code - (optional field) code to identify the customer to the pick-up point
Success/error responses:
The products element allows the user to specify which products in the order have changed status. In the above example, only 1 of the products under SKU agf1037724 in this order has changed state. NOTE: <quantity> shows the number of items for that SKU that have changed state in this call, NOT total quantity changed so far. So, if the order contains 3 items for SKU agf1037724 and 2 had already changed state in a previous call, the above would change the 3rd item’s state and trigger the entire order to change state to ‘ready-for-pick-up’.
If <products> is omitted, it is assumed that the entire order is being changed, e.g. all products in the order are now ready for pick up at once.
- 200 – Ok: operation was successful
- 400 – Bad request: the XML was malformed or the contents of one or more fields failed validation tests
- 403 – Forbidden: you do not have the right to invoke this operation on this resource, for example: you are attempting to access an order from another retailer, or you are trying to set status on an order that is NOT ship to store
- 404 – Not found: retailer order not found
- 409 – Conflict: this action cannot be done with retailer order at this time
- 503 – Service unavailable: transient failure of the service
Resulting system state:
- Retailer Order has status ‘ready-for-pick-up’ (if product quantities are specified, order will remain in its previous state until all items have been marked as ready for pick up, even if that requires multiple calls)
- Marketplace is notified that order is ready for pick up and the marketplace notification email has been sent to the customer
picked up
Trigger: retailer action. The customer has collected in-store.
Request info: The following REST interface is used:
<?xml version="1.0" encoding="utf-8"?> <pickedup> <pickup_note>please go to the customer service desk on ground floor</pickup_note> <products> <product> <retailer_ref>agf1037724-Multi-6</retailer_ref> <sku>agf1037724</sku> <quantity>1</quantity> </product> </products> </pickedup>
products - optional element. If included, product (and therefore retailer_ref, sku and quantity) is mandatory within the element. pickup_note - (optional field) pick up notes to add to the order's audit log
Success/error responses:
The product elements allow the user to specify which products in the order have changed status. In the above example, only 1 of the products under SKU agf1037724 in this order has changed state. NOTE: <quantity> shows the number of items for that SKU that have changed state in this call, NOT total quantity changed so far. So, if the order contains 3 items for SKU agf1037724 and 2 had already changed state in a previous call, the above would change the 3rd item’s state and trigger the entire order to change state to ‘picked-up’.
If <products> is omitted, it is assumed that the entire order is being changed, e.g. all products in the order have been picked up in a single delivery.
- 200 – Ok: operation was successful
- 400 – Bad request: the XML was malformed or the contents of one or more fields failed validation tests
- 403 – Forbidden: you do not have the right to invoke this operation on this resource, for example: you are attempting to access an order from another retailer, or you are trying to set status on an order that is NOT ship to store
- 404 – Not found: retailer order not found
- 409 – Conflict: this action cannot be done with retailer order at this time
- 503 – Service unavailable: transient failure of the service
Resulting system state:
- Retailer Order has status ‘picked up’ (if product quantities are specified, order will remain in ‘ready-for-pick-up’ state until all items have been picked up, even if that requires multiple calls)
Non-happy-day Lifecycle States
pick up cancelled
Trigger: retailer action. The order has been marked as ready for pick up but now needs to be cancelled, e.g. due to a customer no-show. This is an end state and all products in the order are marked as cancelled.
Request info: The following REST interface is used:
<?xml version="1.0" encoding="utf-8"?> <cancelpickup> <reason>did not arrive in time</reason> <cancellation_code>BUYER_NO_SHOW</cancellation_code> </cancelpickup> reason - (optional field) Human-readable reason for the cancellation cancellation_code- (mandatory field) Must be one of: BUYER_NO_SHOW, NO_STOCK
Success/error responses:
- 200 – Ok: operation was successful
- 400 – Bad request: the XML was malformed or the contents of one or more fields failed validation tests
- 403 – Forbidden: you do not have the right to invoke this operation on this resource, for example: you are attempting to access an order from another retailer
- 404 – Not found: retailer order not found
- 409 – Conflict: this action cannot be done with retailer order at this time, for example: calling payment confirmed a second time on a retailer order, since the order is no longer in the pending state and able to process ‘payment confirmed’
- 503 – Service unavailable: transient failure of the service
Resulting system state:
- Retailer Order is set to status ‘pick up cancelled’.
refunded online
Trigger: the retailer has requested an online (as opposed to in-store) refund after processing a return. The shopper is notified via email by the system. This is an end state.
The retailer may elect to refund the full price of all items in the order with or without the shipping amount back to the customer’s credit card via this API. The refund of the commission back to the retailer is triggered.
Request info: The following REST interface is used:
<?xml version="1.0" encoding="utf-8"?> <refund> <reason>did not arrive in time</reason> <refund_ref>2456247hf</refund_ref> <products> <product> <retailer_ref>agf1037724-Multi-6</retailer_ref> <sku>agf1037724</sku> <quantity>1</quantity> </product> </products> </refund>
Success/error responses:
- 200 – Ok: operation was successful
- 400 – Bad request: the XML was malformed or the contents of one or more fields failed validation tests
- 403 – Forbidden: you do not have the right to invoke this operation on this resource, for example: you are attempting to access an order from another retailer
- 404 – Not found: retailer order not found
- 409 – Conflict: this action cannot be done with retailer order at this time, for example: calling payment confirmed a second time on a retailer order, since the order is no longer in the pending state and able to process ‘payment confirmed’
- 503 – Service unavailable: transient failure of the service
Resulting system state:
- Retailer Order is set to status ‘refunded online’. Note: depending on marketplace, the order may or MAY NOT be able to be refunded in that marketplace without manual intervention
Bulk Batch Order Status Updating
Shipped status update
POST to /v1/retailers/$id/orders/shipment_csv
Allow bulk update of orders to the Shipped state. Orders are specified one per row. There is no heading row.
Example CSV format:
[order id], [shipped date], [shipping carrier], [tracking number]
e.g.:
“1234567890-0987654321”, “9-JUN-14”, “FedEx”, “5667656af”
Fields:
order id – eBay order IDshipped date – date shipped
shipping carrier – Courier company identifier
tracking number – Courier shipment/tracking number
Success/error responses:
- 200 – Ok: operation was successful
- 400 – Bad request: the data was malformed or the contents of one or more fields failed validation tests
- 403 – Forbidden: you do not have the right to invoke this operation on this resource, for example: you are attempting to access an order from another retailer
- 404 – Not found: retailer order not found
- 409 – Conflict: this action cannot be done with retailer order at this time, for example: calling payment confirmed a second time on a retailer order, since the order is no longer in the pending state and able to process ‘payment confirmed’
- 503 – Service unavailable: transient failure of the service
Resulting system state:
- Retailer Order is set to status ‘shipped’.
Ready to Pick Up status update
POST to /v1/retailers/$id/orders/ready_for_pick_up_csv
Allow bulk update of orders to the Ready For Pick Up state. Orders are specified one per row. There is no heading row.
Example CSV format:
[order id], [ready to pick up date], [pick up id], [customer note]
e.g.:
“1234567890-0987654321”, “9-JUN-14”, “74748”, “Go to the service desk on arrival”
Fields:
order id – eBay order ID
ready to pick up date – date order became ready to pick up
pick up id – Order identifier for customer to quote to store personnel to verify and identify the order to be collected, e.g. retailer order ID
customer note – (Optional, may be blank) Special instructions to the customer for pick up
Success/error responses:
- 200 – Ok: operation was successful
- 400 – Bad request: the data was malformed or the contents of one or more fields failed validation tests
- 403 – Forbidden: you do not have the right to invoke this operation on this resource, for example: you are attempting to access an order from another retailer, or you are trying to set status on an order that is NOT ship to store
- 404 – Not found: retailer order not found
- 409 – Conflict: this action cannot be done with retailer order at this time, for example: calling payment confirmed a second time on a retailer order, since the order is no longer in the pending state and able to process ‘payment confirmed’
- 503 – Service unavailable: transient failure of the service
Resulting system state:
- Retailer Order is set to status ‘ready for pick up’.
Picked Up status update
POST to /v1/retailers/$id/orders/picked_up_csv
Allow bulk update of orders to the Picked Up state. Orders are specified one per row. There is no heading row.
Example CSV format:
[order id], [picked up date], [picked up note]
e.g.:
“1234567890-0987654321”, “9-JUN-14”, “Picked up a red one rather than blue”
Fields:
order id – eBay order ID
picked up date – date order was picked up
picked up note – (Optional, may be blank) Notes entered during pick up
Success/error responses:
- 200 – Ok: operation was successful
- 400 – Bad request: the data was malformed or the contents of one or more fields failed validation tests
- 403 – Forbidden: you do not have the right to invoke this operation on this resource, for example: you are attempting to access an order from another retailer, or you are trying to set status on an order that is NOT ship to store
- 404 – Not found: retailer order not found
- 409 – Conflict: this action cannot be done with retailer order at this time, for example: calling payment confirmed a second time on a retailer order, since the order is no longer in the pending state and able to process ‘payment confirmed’
- 503 – Service unavailable: transient failure of the service
Resulting system state:
- Retailer Order is set to status ‘ready for pick up’.
Retrieving Orders
/v1/retailers/$id/orders?type=$type&ordersSince=$order_ref&status=$status&limit=$limit&fromDate=$from_date&toDate=$to_date
Download the latest product feed for the specified retailer and marketplace.
Request
Parameters
$id – unique retailer ID
$order_ref – (optional) order reference ID, to retrieve all orders created after this one
$from_date – (optional) date in the format yyyy-MM-dd (e.g. 2014-02-28), to retrieve all orders created after this date. For example, 2014-02-08 corresponds to 00:00h 8th Feb 2014 in the GMT timezone. NOTE: mutually exclusive with ordersSince – if both are specified, ordersSince will be used and fromDate will be ignored
$to_date – (optional) date in the format yyyy-MM-dd (e.g. 2014-02-28), to retrieve all orders created to this date. For example, 2014-02-08 corresponds to 00:00h 8th Feb 2014 in the GMT timezone. NOTE: must be used in conjunction with fromDate; also, it is mutually exclusive with ordersSince – if both are specified, ordersSince will be used and toDate will be ignored
$type – (optional) format of response, one of: ‘xml’, ‘csv’, if missing defaults to ‘xml’
$status – (optional) only retrieve orders with the specified order lifecycle status
$limit – (optional) number of orders to retrieve, defaults to 100
Example request
Not applicable
Example URL
Response
Permitted response codes
GET: 200 OK, 404 Not found (e.g. bad retailer ID)
POST: 405 Method Not Allowed
PUT: 405 Method Not Allowed
DELETE: 405 Method Not Allowed
Example response
See Order payload
/v1/retailers/$id/orders/$order_ref?type=$type
Download the latest product feed for the specified retailer and marketplace.
Request
Parameters
$id – unique retailer ID
$order_ref – unique reference ID for the order
$type – (optional) format of response, one of: ‘xml’, ‘csv’, if missing defaults to ‘xml’
Example request
Not applicable
Example URL
http://api.omnivore.com.au/v1/retailers/fresh-beach-club/orders/1514614-3462677
Response
Permitted response codes
GET: 200 OK, 404 Not found (e.g. bad retailer ID)
POST: 405 Method Not Allowed
PUT: 405 Method Not Allowed
DELETE: 405 Method Not Allowed
Example response
See Order payload
Order Payload
<?xml version="1.0"?> <retailer_order id="723484"> <products> <product> <retailer_ref>agf1037724-Multi-6</retailer_ref> <sku>agf1037724</sku> <quantity>1</quantity> <price currency="AUD"> <amount>11900</amount> <sell_amount>11900</sell_amount> <tax>1081</tax> </price> </product> </products> <status>authorised</status> <payment_transactions> <payment_transaction> <transaction_id>723484_20121204172551</transaction_id> <currency>AUD</currency> <amount>13000</amount> <status>authorised</status> <response_code>APPROVED</response_code> <payment_method id="132816" type="credit_card"> <billing_address> <address_line_1>85 George St</address_line_1> <suburb>Sydney</suburb> <state>NSW</state> <postcode>2000</postcode> <country>Australia</country> </billing_address> <card_type>MC</card_type> <masked_number>555555xxxxxx5555</masked_number> <name_on_card>Mrs Ann Person</name_on_card> <expiry_month>03</expiry_month> <expiry_year>15</expiry_year> </payment_method> </payment_transaction> </payment_transactions> <created_date>2012-12-04T17:25:51+11:00</created_date> <customer id="3594172"> <first_name>Ann</first_name> <last_name>Person</last_name> <phone_number>0299999999</phone_number> <email_address>aperson@test.com</email_address> <shipping_address> <address_line_1>85 George St</address_line_1> <suburb>Sydney</suburb> <state>NSW</state> <postcode>2000</postcode> </shipping_address> </customer> <delivery currency_code="AUD"> <method>Standard</method> <charge>1100</charge> <tax>100</tax> </delivery> <order_number>467-127-671-533-3499-1</order_number> <currency_code>AUD</currency_code> <grand_total> <amount>13000</amount> <tax>1181</tax> </grand_total> </retailer_order>
Creating Orders
POST: /v1/retailers/$id/orders/marketplaces/$marketplaceCode
Upload an order XML payload to create orders in Omnivore for the specified retailer and marketplace.
Request
Parameters
$id – unique retailer ID
$marketplaceCode – ID of the marketplace
Example URL
http://api.omnivore.com.au/v1/retailers/fresh-beach-club/orders/marketplaces/ebay
Response
Permitted response codes
GET: 405 Method Not Allowed
POST: 200 OK, 403 Forbidden (marketplace does not allow order creation), 404 Not found (e.g. bad retailer ID, bad marketplace ID)
PUT: 405 Method Not Allowed
DELETE: 405 Method Not Allowed
Example order payload
<?xml version="1.0"?> <retailer_order id="723484"> <products> <product> <retailer_ref>agf1037724-Multi-6</retailer_ref> <sku>agf1037724</sku> <quantity>1</quantity> <price currency="AUD"> <amount>11900</amount> <sell_amount>11900</sell_amount> <tax>1081</tax> </price> </product> </products> <status>authorised</status> <payment_transactions> <payment_transaction> <transaction_id>723484_20121204172551</transaction_id> <currency>AUD</currency> <amount>13000</amount> <status>authorised</status> <response_code>APPROVED</response_code> <payment_method id="132816" type="credit_card"> <billing_address> <address_line_1>85 George St</address_line_1> <suburb>Sydney</suburb> <state>NSW</state> <postcode>2000</postcode> <country>Australia</country> </billing_address> <card_type>MC</card_type> <masked_number>555555xxxxxx5555</masked_number> <name_on_card>Mrs Ann Person</name_on_card> <expiry_month>03</expiry_month> <expiry_year>15</expiry_year> </payment_method> </payment_transaction> </payment_transactions> <created_date>2012-12-04T17:25:51+11:00</created_date> <customer id="3594172"> <first_name>Ann</first_name> <last_name>Person</last_name> <phone_number>0299999999</phone_number> <email_address>aperson@test.com</email_address> <shipping_address> <address_line_1>85 George St</address_line_1> <suburb>Sydney</suburb> <state>NSW</state> <postcode>2000</postcode> </shipping_address> </customer> <delivery currency_code="AUD"> <method>Standard</method> <charge>1100</charge> <tax>100</tax> </delivery> <order_number>467-127-671-533-3499-1</order_number> <currency_code>AUD</currency_code> <grand_total> <amount>13000</amount> <tax>1181</tax> </grand_total> </retailer_order>