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).


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 stateTransition to stateNotes
[Start]CreatedOrder 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'
CreatedPending Retailer ConfirmationOmnivore internal transition, signalling that an order is now ready for the Retailer to download
Pending Retailer ConfirmationPending ShippedRetailer initiated: order acknowledgement, signalling that Retailer has imported the order successfully
Pending ShippedShippedRetailer 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


Order acknowledgement


Endpoint: POST /v2/retailer/$retailerCode/marketplace/$marketplaceCode/order/update


Example request

{
  "order_number": "153805092910-1978256051005",
  "status": "pending-shipped"
}

Example response


[Updated order data]


Order shipment


Endpoint: POST /v2/retailer/$retailerCode/marketplace/$marketplaceCode/order/update


The payload for order shipment requires the 'shipping' element, which provides the carrier and tracking code. 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.


If the call omits line item information, it will be assumed that the entire order has now been shipped and the order will be transitioned immediately to 'shipped' status.


Example request

{
  "order_number": "153805066610-1978256051005",
  "status": "shipped",
  "shipping": {
    "carrier": "Australia Post",
    "tracking_code": "33WDL500722366600655001"
  }
  "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]