An order is created when a customer checks out on a site's store, or through the API with Create External Order. It records what was bought, what it cost, how it was paid for, and how it is being delivered.
Every order field is described in the request and response schemas on each endpoint page. This page covers how the parts fit together.
Where an order comes from
source says where the order was created, for example CHECKOUT or EXTERNAL. mode says whether it was placed in TEST or LIVE mode.
status tracks the order as a whole. DISPUTED is deprecated: setting it sets the status to CANCELLED. A cancelled order also has cancelled (the date) and cancellation_reason. To cancel an order, use Cancel order.
What was bought and what it cost
items holds one entry per line item: the product and variation it came from, the quantity, unit_price, and the options and product customizations the customer chose. A line item's total is quantity × unit price.
At the order level, subtotal is the cost before taxes, shipping and other additions, and total is what the customer paid. discounts and taxes list what was applied, and shipping_method holds the method the customer chose and its cost. The currency is on payment.currency.
Payment and refunds
payment holds the payment provider's transaction_id, the payment status, and confirmed_method: the gateway that processed the payment and the method the customer used, such as a card or PayPal.
Refunds are listed in refunds. To issue or look up refunds, use Create Refund, List Refunds and Get Refund.
Fulfillment
A fulfillment records that some or all of an order's line items were delivered. An order can have several, in fulfillments, and unfulfilled_items lists what still needs to be fulfilled.
Each fulfillment has a method:
SHIPMENT: physical items that are marked as shippable and are shipped to the customer.PICKUP: physical items when the customer chose a pickup method at checkout.EMAIL_MESSAGE: digital goods, fulfilled automatically by email.
All items in a fulfillment must use the same method, so physical items and digital goods can't share one. Items that can't be fulfilled, such as paid memberships, never appear in a fulfillment.
Shipment tracking is on each fulfillment, not on the order. tracking (the carrier, tracking number and tracking URL) can only be set when the method is SHIPMENT, and can be updated after the fulfillment is created. Customers see it in emails and in their dashboard.
To manage fulfillments, use Create Order Fulfillment, Update Order Fulfillment, List Order Fulfillments and Get Order Fulfillment.
Custom fields
custom_fields holds the values the customer entered in custom checkout fields, with the field's label, type and the checkout step (zone) it was shown in. A CHECKBOX field the customer didn't check has a null value, and a DATE field's value is an ISO datetime string in UTC.
Example
{
"source": "CHECKOUT",
"mode": "LIVE",
"id": "string",
"external_id": "string",
"status": "IN_PROGRESS",
"email": "string",
"invoice_number": "string",
"items": [
{
"id": "string",
"product_id": "string",
"variation_id": "string",
"external_product_id": "string",
"external_variation_id": "string",
"name": "string",
"image": "string",
"sku": "string",
"options": [
{
"name": "string",
"value": "string"
}
],
"product_customizations": [
{
"type": "string",
"value": "string",
"id": "string",
"name": "string",
"label": "string"
}
],
"quantity": 0,
"shippable": true,
"unit_price": 0,
"unit_weight": 0,
"unit_dimensions": {
"height": 0,
"width": 0,
"length": 0
},
"total": 0,
"combined_weight": 0,
"metadata": "string"
}
],
"billing_address": {
"first_name": "string",
"last_name": "string",
"full_name": "string",
"address_1": "string",
"address_2": "string",
"street_number": "string",
"street_name": "string",
"city": "string",
"sub_locality": "string",
"region": "string",
"country": "string",
"postal_code": "string",
"phone": "string"
},
"shipping_address": {
"first_name": "string",
"last_name": "string",
"full_name": "string",
"address_1": "string",
"address_2": "string",
"street_number": "string",
"street_name": "string",
"city": "string",
"sub_locality": "string",
"region": "string",
"country": "string",
"postal_code": "string",
"phone": "string"
},
"shipping_method": {
"name": "string",
"cost": 0
},
"shipping_instructions": "string",
"discounts": [
{
"id": "string",
"savings": 0,
"name": "string",
"type": "string"
}
],
"taxes": [
{
"name": "string",
"amount": 0,
"rate": 0
}
],
"subtotal": 0,
"total": 0,
"payment": {
"transaction_id": "string",
"status": "PAID",
"currency": "string",
"card_brand": "NULL",
"confirmed_method": {
"gateway": "NONE",
"name": "UNKNOWN",
"display_name": "string",
"icon": "string",
"details": "string",
"instructions": "string"
}
},
"refunds": [
{}
],
"fulfillments": [
{
"id": "fulfill_123",
"order_id": "1234",
"status": "FULFILLED",
"method": "SHIPMENT",
"items": [
{
"id": "item_123",
"quantity": 2
},
{
"id": "item_456",
"quantity": 1
}
],
"tracking": {
"number": "123456",
"url": "https://example.com",
"carrier": "USPS"
},
"created": "2025-05-01T14:52:29.729Z",
"updated": "2025-05-01T14:52:29.729Z"
}
],
"unfulfilled_items": [
{
"id": "item_123",
"quantity": 4,
"method": "SHIPMENT"
},
{
"id": "item_456",
"quantity": 1,
"method": "EMAIL_MESSAGE"
}
],
"custom_fields": [
{
"id": "cf_89c341606fea47f1be19a09106d877c4",
"label": "Do you want to add a gift message with your order?",
"type": "DATE",
"value": "Yes",
"zone": "CONTACT_INFO",
"includes_time": true,
"date_range_policy": "ANY"
}
],
"created": "2023-08-02T14:52:29.729Z",
"user_agent": "string",
"customer_accepts_marketing": true,
"ip_address": "string",
"cancellation_reason": "string",
"cancelled": "2024-12-11T18:28:17.853Z",
"metadata": "string"
}