Create Marketplace Order
As a Marketplace, create an Order from the given Marketplace
Note: Retailers do have access to this endpoint, but there is no use case for this usage.
Endpoint: POST /v2/retailer/$retailerCode/marketplace/$marketplaceCode/order/create
Update Marketplace Order
As a Retailer or Marketplace Integrator, update an Order from the given Marketplace
Note: The general usage is that Retailers will update the status of the Order when it's shipped and provide tracking information (optional).
Endpoint: POST /v2/retailer/$retailerCode/marketplace/$marketplaceCode/order/update
The following sections detail how an order is managed through its lifecycle by the Retailer via the Omnivore APIs. There are a number of order lifecycle paths that an order can take depending on how the Retailer's order management system treats orders. The most common lifecycle for an order is as follows, note the use of the Pending Retailer Confirmation status to 'park' orders that are awaiting download. This allows the Retailer to poll for all orders with this status and, providing the downloaded orders are acknowledged and moved to Pending Shipped, ensures that orders are never downloaded more than once.
| Starting state | Transition to state | Notes |
| [Start] | Created | Order is built inside Omnivore from data downloaded from Marketplace. Note that this may be done in several stages, depending on the Marketplace, but will always result in an order with status 'Created' |
| Created | Pending Retailer Confirmation | Omnivore internal transition, signalling that an order is now ready for the Retailer to download |
| Pending Retailer Confirmation | Pending Shipped | Retailer initiated: order acknowledgement, signalling that Retailer has imported the order successfully |
| Pending Shipped | Shipped | Retailer initiated: shipment, supplying carrier and shipment tracking data, signalling that the order has been dispatched to the buyer. This is a valid end-state for an order |
Common scenarios
1. Order acknowledgement
For the purpose of the update api, the order is identified by the marketplace and order number.
The order_number comes in the json payload, the marketplace_code should come in the url and optional in the json payload.
These 2 fields are optional: "retailer_order_id" and "retailer_order_number". They help the retailer find the order more easily when using the Omnivore GUI.
For some ecommerce integrations it also provides a link directly to the ecommerce order page.
Example JSON payload for updating the order status
{
"marketplace_code": "ebay",
"order_number": "12345678901234567890",
"retailer_order_number": "12345-ABC",
"status": "pending-shipped",
}Example response
[Updated order data]
2. Order shipment
Same as above plus the "shipping" and optional a list of "line_Items".
This is required and important. Most marketplaces strongly insist on providing tracking codes too.
If the line_items is not provided or is empty, the all items in the order are marked as shipped and the whole order is set to "shipped".
In the example below, all line items in the order are shipped in this one single shipment.
Example JSON payload for updating the order status and providing shipping info:
{
"marketplace_code": "ebay",
"order_number": "12345678901234567890",
"retailer_order_number": "12345-ABC",
"status": "shipped",
"shipping":
{
"carrier": "Australia Post",
"tracking_code": "1234567890"
}
}Example response
[Updated order data]
It optionally can also contain the quantites of each line item that have been shipped. These quantites are used to decrement the unshipped quantity counts in the order in Omnivore; once all line items are fully shipped, then the order will finally transition to 'shipped' status. The line item quantity can be decremented via multiple calls until the unshipped amount finally reaches zero. Specifying a quantity to be shipped that is greater than the unshipped amount for a line item will result in an error.
Example JSON payload for partially shipped order:
{
"marketplace_code": "ebay",
"order_number": "12345678901234567890",
"retailer_order_number": "12345-ABC",
"status": "shipped",
"shipping":
{
"carrier": "Australia Post",
"tracking_code": "1234567890"
},
"line_items": [
{
"product_sku": "5235AF",
"variant_sku": "5235AF-RED-XL",
"quantityShipped": 2
},
{
"product_sku": "5235AF",
"variant_sku": "5235AF-BLUE-XL",
"quantityShipped": 1
}
]
}Example response
[Updated order data]
3. Order refund
The payload for order refund requires the 'refund' element, which provides the refund reference and option refund reason. It optionally can also contain the quantites of each line item that have been refunded. These quantities are decremented in Omnivore, and can happen regardless of whether or not the line item has been shipped since it is possible to refund the customer before the item has been shipped. The line item quantity can be decremented via multiple calls until the refunded quantity equals the line item quantity. Specifying a quantity to be refunded that is greater than the total quantity for a line item will result in an error.
If the call omits line item information, it will be assumed that the entire order has been refunded and the order will be transitioned immediately to 'refunded-online' status.
Example request
{
"marketplace_code": "ebay",
"order_number": "12345678901234567890",
"retailer_order_number": "12345-ABC",
"status": "refunded-online",
"refund": {
"reason": "Damaged goods",
"reference": "33WDL500722366600655001"
}
"line_items": [
{
"product_sku": "5235AF",
"variant_sku": "5235AF-RED-XL",
"quantityRefunded": 2
},
{
"product_sku": "5235AF",
"variant_sku": "5235AF-BLUE-XL",
"quantityRefunded": 1
}
]
}Example response
[Updated order data]