Introduction

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.

order_flow

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

http://api.omnivore.com.au/v1/retailers/fresh-beach-club/orders?ordersSince=1514614-3462677&status=shipped

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>