Orders

Overview

The order resource is a complex resource, typically comprised of a collection of other resources and procedures, rather than a simple operation. At a minimum, an order usually involves the following:

1. Storing the basic order details (order number, customer details, notes, etc.).
2. Collecting the address details (shipping and billing).
3. Storing details of how the order is to be shipped.
4. Adding the desired products to the order.

Similarly, orders can contain a combination of the above resources, and may need to be changed at some point in the order cycle, such as when a customer contacts the business to add an extra item to an order.

The full details and contents of an order are not always known at a singular point in time, and each business tends to handle orders in their own unique fashion. As such, the order resource has been architected to accomodate this.

Architecture

There are two core states for an order to exist in on the platform: committed and uncommitted. By default, when an order is created, it is in the committed state, unless explicitly instructed otherwise.

The two states behave as follows as follows:

An uncommitted order can be thought of as a draft order. Typically an order should be committed at the point it is created (as occurs by default), unless there is a reason not to. Some examples of reasons to create an order in the uncommitted state might be:

• The order has items being shipped to multiple addresses.
• Only part of the order information is known at the point in time when the order is being created.
• The order is likely to be changed before it is fulfilled.

Why are there two different states?

There are several other resources that need to reference an order to function, such as fulfilments. Once these resources reference an order or a part of it, it becomes infeasible to keep track of changes that may be made to the order resource in the resources that reference it, or indeed in any external systems that may also hold a record of it.

Besides the difficulty keeping track of changes, certain data should not be edited, as it may have consequences for auditability and traceability - for example, if the order number could be changed after it was committed, it is possible that the customer would be given an order number that is subsequently changed, and a record of the number originally given to them no longer exists.

Fulfilments and Shipping

In order to create a shipment, orders must be in the committed state. This is because at the point a shipment is created, certain data must remain unchanged, as references are passed to external systems which cannot be updated at a later date.

Attempting to create a fulfilment for an order in the uncommitted state will return an error.

Inventory for an order is only reserved once the order is placed in the committed state. Orders in the uncomitted state are not reflected in the inventory levels.

Creating simple orders

A simple order is an order that has one billing address, one shipping address, and one shipping detail.

If all of the above conditions are met, which will generalyl be the case for the vast majority of orders, an order can be created by submitting a single request to the Create Order endpoint.

The IDs for addresses and shipment details do not need to be specified as described in the section discussing multiple shipping addresses below, they will be auto populated when the order is created.

Orders will also be automatically committed.

In the event that all of the above parameters are not met, automatic assignment of addresses and shipping details will still occur - the details of the first item in each array will be used as the default. If an array is empty, then any fields that would otherwise reference that resource will be null.

When to Create Uncommitted Orders

In the event that an order is complex, it may be that multiple API calls are required to represent the details of the order as desired, such as shipping to multiple addresses.

Incomplete Orders / Partial Orders

In some cases, all the order details may not be known upfront, for example, an order from a procurement department may commit to buy an approximate quantity of products, but the final quantity is subject to minor adjustment, and the invoicing details are to be provided at a later date.

In an instance such as this, it is advised that an order is created in an uncommitted state, as this provides the optionality of being able to update billing addresses, order references, and so on several times before the order is finalised by the customer, at which point final details may be entered, and the order committed.

Shipping to Multiple Addresses

Some marketplaces support shipments to multiple addresses within a single order, the obvious example is Amazon's Deliver to Multiple Addresses feature. In this scenario, an order will have a billing address, and two or more shipping addresses. This order would be created as follows:

1. Call the Create Order endpoint, specifying the request body as usual, and the multiple shipping addresses in the shipping_addresses array, and excluding the shipping_details parameter. The query parameter auto_commit should be set to false to prevent the order being automatically committed.
   
   The response object will contain the created order, with the committed_at field set to null to indicate that the order is uncommitted. The addresses returned in the shipping_addresses field will also each contain a unique ID for the order address that has been created, the IDs of which have the prefix oa.
   
   
2. The client would then retrieve the ID for the relevant shipping address from the response, and make a second request to the Update Order endpoint, specifying the shipping_details parameter, containing the shipping details for each of the shipping addresses, and passing the ID of the relevant shipping address with each shipping detail.
   
   The relevant part of the request will look something like as follows:

{
 ...,
 "shipping_details": [
   {
    "carrier_code": "Amazon",
    "carrier_service_code": "SFP",
    "method_name": "Seller Fulfilled Prime",
    "method_identifier": "AmazonSellerFulfilledPrime",
    "prices": {
        "gross": 0,
        "net": 0,
        "base": 0,
        "tax": 0,
        "tax_rate": 0.2,
        "currency_code": "USD"
    },
    "shipping_address": {
      "id": "oa_2AFvyAr1FRAB2MkC84J8aoyjg0n"
    }
   }
 ],
 ...
}

3. The client would then make an additional request to the Update Line Items endpoint, passing the line items, along with the ID of the shipping detail returned in response to the previous request that corresponds to each line item in the shipping_detail parameter.
   
   For example:

{
  "id": "li_2AFvyEB064DgmpOZ4mbvNygAPGU",
  "shipping_detail": {
      "id": "sd_2AFvyCHxL5J8CdJ7cQeN3QxZ6QA"
  }
}

Order Name / Number Format

When an order is created on the platform as a standalone order (ie. not attached to a marketplace), and no name is supplied, an order number will be automatically generated.

The number will be in a 3-7-7 format (the same format is used for Amazon orders), consist only of numbers, with the first two numbers being 68. Order numbers are pseudo-randomised and non-sequential.

For example: 688-0758679-5104374

This number is guaranteed to be unique within a single organisation, but may not be unique across organisations.

Third party clients that interact with multiple organisations will thus need to ensure that sufficient additional information, such as the organisation ID, is stored alongside the order number to be able to differentiate between possible duplicates.