Webhook: Order v1
Order webhooks are fired around lifecycle events on an Order - for example the initial creation, through successful fraud checks, financial processing, good despatch, refunds and more.
order_create
Description
This webhook is fired whenever an order is created. It contains the state of the order when placed. It could be possible that order_create and order_update webhooks might be fired in quick succession and arrive out of sequence. We would always recommend explicitly handling a mis-sequencing of these hooks.
Payload Format
| Attribute | Type | Description |
|---|---|---|
| id | String | The identifier of this Order |
| store_id | String | The identifier of the Store this Order was placed through |
| currency | String | The transaction currency of this Order |
| lines | Array | Deprecated, use consignments instead |
| consignments | Array | Consignments for this order, see additional types for details |
| shipments | Array | Shipments for this order, see additional types for details |
| test | Boolean | Was this order placed using a Sandbox gateway |
| gateway | String | The payment gateway processing this Order |
| billing_address | Address | The billing address of this order, see additional types for details |
| shipping_address | Address | The shipping address of this order, see additional types for details |
| customer | Customer | The Customer purchasing this Order, see additional types for details |
| updated_at | DateTime | An ISO8601 format timestamp for the last update to this record |
| created_at | DateTime | An ISO8601 format timestamp for the creation time of this record |
order_update
Description
This webhook is fired whenever an order is updated. This could be due to dispatch of some components of the order, or changes of address, or possibly even cancellations. We do not guarantee sequence of delivery for webhooks so you should always compare the updated_at attribute of this update with the timestamp of the last update you received to ensure you’re not acting upon stale information.
If you receive an order_update webhook for an order you have not seen before you can either:
- treat it as an upsertable event and handle it with an implicit creation
- reject it with an error status code and await the
order_createevent to arrive. We will reattempt delivery a number of times and you can accept this webhook on a later delivery.
Payload Format
| Attribute | Type | Description |
|---|---|---|
| id | String | The identifier of this Order |
| store_id | String | The identifier of the Store this Order was placed through |
| currency | String | The transaction currency of this Order |
| lines | Array | Deprecated, use consignments instead |
| consignments | Array | Consignments for this order, see additional types for details |
| shipments | Array | Shipments for this order, see additional types for details |
| test | Boolean | Was this order placed using a Sandbox gateway |
| gateway | String | The payment gateway processing this Order |
| billing_address | Address | The billing address of this order, see additional types for details |
| shipping_address | Address | The shipping address of this order, see additional types for details |
| customer | Customer | The Customer purchasing this Order, see additional types for details |
| updated_at | DateTime | An ISO8601 format timestamp for the last update to this record |
| created_at | DateTime | An ISO8601 format timestamp for the creation time of this record |
Additional Data Types
Customer
A Customer who has purchased the goods within this Order
| Attribute | Type | Description |
|---|---|---|
| id | String | The identifier of this Customer |
| String | The email address of this Customer | |
| first_name | String | The first name of this Customer |
| last_name | String | The last name of this Customer |
| orders_count | Integer | The count of orders this Customer has placed, at the point of placing this order, inclusive of this order |
| created_at | DateTime | The timestamp of when this Customer was added or created |
| updated_at | DateTime | The timestamp of the last update to this Customer |
Address
A physical address. Used for Billing or Shipping purposes
| Attribute | Type | Description |
|---|---|---|
| name | String | A name for this Address |
| address1 | String | The first line of this Address |
| address2 | String | The second line of this Address |
| company | String | An optional company name at this Address |
| city | String | The postal city for this Address |
| state | String | The State, Region or County of this Address |
| zip | String | The ZIP or Postal Code of this Address |
| country | String | The country of this Address |
| phone | String | A contact phone number for this Address |
Fulfiller
A Fulfiller is the party responsible for the despatch of the items within the order
| Attribute | Type | Description |
|---|---|---|
| id | String | The identifier of this Fulfiller |
| name | String | The name of the Fulfiller |
OrderLine
An OrderLine is a list of Purchases
| Attribute | Type | Description |
|---|---|---|
| id | String | The identifier of this Fulfiller |
| purchases | Array | The Purchases on this OrderLine |
Purchase
An item purchased within this Order
| Attribute | Type | Description |
|---|---|---|
| id | String | The identifier of this Purchase |
| product_id | String | The identifier of the Product being bought |
| variant_id | String | The identifier of the Variant of the Product being bought - e.g. a Red version |
| vendor_id | String | The identifier of the Vendor - the party who has sold the Product |
| status | String | The status of this Purchase - e.g. Shipped, or Pending |
| financial_status | String | The financial status of this Purchase - e.g. Authorized or Captured |
| sku | String | The SKU of the Variant being bought |
| released_at | DateTime | An optional timestamp of the release date if this purchase is for a pre-order item |
| list_price | Money | The advertised price of this Purchase, this could have been discounted - check sale_price for the price paid |
| sale_price | Money | The actual price paid for this item, including discounts |
| tax | Money | The sales tax paid on this item |
| discount | Money | The amount of discount applied to this item |
| shipment_id | String | The identifier of the Shipment this item was dispatched within, if present |
| consignment_id | String | The identifier of the Consignment this item is awaiting dispatch within, if present |
Consignment
A container of Purchases which are awaiting Shipment by the Fulfiller
| Attribute | Type | Description |
|---|---|---|
| id | String | The identifier of this Consignment |
| numeric_id | Integer | A Fulfiller-scoped sequential ID for systems that require it |
| fulfiller | Fulfiller | This fulfiller of this Consignment |
| purchases | Array | A list of Purchases contained within this Consignment |
Shipment
A group of Purchase which have been dispatched by the Fulfiller to the Customer
| Attribute | Type | Description |
|---|---|---|
| id | String | The identifier of this Shipment |
| fulfiller | Fulfiller | The Fulfiller of this Shipment |
| purchases | Array | A list of Purchase that are included in this Shipment |
| shipped_at | DateTime | The timestamp this Shipment was dispatched at |
| tracking | TrackingData | Tracking data for this Shipment |
TrackingData
Tracking information for a Shipment
| Attribute | Type | Description |
|---|---|---|
| carrier | String | The carrier this has been dispatched using |
| method | String | The name of the shipping method |
| code | String | The tracking code, if present |
| url | String | A URL to view tracking information, if present |
| additional_codes | Array | Some complex cross-border transactions or multiple-box shipments require multiple tracking codes, these will be included here if present |