Orders

Order Index Endpoint

Structure

See View Order Endpoint for the structure of the order payload inside the data array.

Scopes

Name
 Description
 Example
visible Only return visible orders (those which have been ordered) ?scope=visible
outstanding Only return outstanding orders ?scope=outstanding
completed Only return completed orders ?scope=completed
incomplete Only return incomplete orders ?scope=incomplete
express Only return express orders ?scope=express
standard Only return standard orders ?scope=standard

Filters

Name
 Description
 Example
reference Only return orders with specific references ?references=ABC123,DEF456
statuses Only return orders with specific status ids or names ?statuses=1,On Hold
states Only return orders with specific states ?states=dispatched,returned
customers Only return orders with specific customers (by id or email) ?customers=1,test@gmail.com
emails Only return orders for specific emails ?emails=test@gmail.com
channels Only return orders for specific channels ?channels=web,api
flags Only return orders for specific flags (by id, name, or name|value) ?flags=1,abc,def|123 
GET /api/orders?per_page=2&min_ordered_at=2023-08-30%2010:36:23
{
    "current_page": 1,
    "data": [
      //...
    ],
    "first_page_url": "http://aero.test/api/orders?page=1",
    "from": 1,
    "last_page": 3,
    "last_page_url": "http://aero.test/api/orders?page=3",
    "next_page_url": "http://aero.test/api/orders?page=2",
    "path": "http://aero.test/api/orders",
    "per_page": 2,
    "prev_page_url": null,
    "to": 2,
    "total": 5
}

See View Order Endpoint for the structure of the order payload inside the data array.

View Order Endpoint

Structure

Order

Name
 Type
 Description
reference string The unique reference for the order
status object The Order Status of the order (null if none)
customer object The Customer of the order (null if none)
email string The email of the customer that placed the order
subtotal.amount float The subtotal of the order excluding tax
subtotal.tax float The subtotal tax for the order
shipping.amount float The shipping of the order excluding tax
shipping.tax float The shipping tax for the order
discount.amount float The discount of the order excluding tax
discount.tax float The discount tax for the order
surcharge.amount float The surcharge of the order excluding tax
surcharge.tax float The surcharge tax for the order
currency string The currency code of the order
shipping_method object The Shipping Method of the order (null if none)
shipping_address object The Shipping Address of the order (null if none)
billing_address object The Billing Address of the order (null if none)
ordered_at timestamp When the order was ordered
deliver_on timestamp When the order should be delivered
items array An array of Order Item objects
payments array An array of Payment objects
fulfillments array An array of Fulfillment objects
returns array An array of Return objects
comments array An array of Comment objects
additional_attributes array An array of Additional Attribute objects

Order Status

Name
 Type
 Description
id int The id of the order status
name string The name of the order status
state string The state of the order status

Valid states: cancelled, on_hold, successful, complete, processing, closed, partially_dispatched, dispatched, partially_returned, returned

Customer

Name
 Type
 Description
id int The id of the customer
name string The name of the customer
email string The email of the customer

Shipping Method

Name
 Type
 Description
id int The id of the shipping method
name string The name of the shipping method

Shipping Address

Name
 Type
 Description
first_name string The first name for the shipping address
last_name string The last name for the shipping address
company string The company for the shipping address
mobile string The mobile number for the shipping address
phone string The phone number for the shipping address
line_1 string The first line for the shipping address
line_2 string The second line for the shipping address
city string The city for the shipping address
county string The county for the shipping address
zone string The zone code for the shipping address
postcode string The postcode for the shipping address
country string The country code for the shipping address
reference string The unique reference for the shipping address
eori_number string The EORI number for the shipping address

Billing Address

Name
 Type
 Description
first_name string The first name for the billing address
last_name string The last name for the billing address
company string The company for the billing address
mobile string The mobile number for the billing address
phone string The phone number for the billing address
line_1 string The first line for the billing address
line_2 string The second line for the billing address
city string The city for the billing address
county string The county for the billing address
zone string The zone code for the billing address
postcode string The postcode for the billing address
country string The country code for the billing address
reference string The unique reference for the billing address
eori_number string The EORI number for the billing address

Order Item

Name
 Type
 Description
id int The id of the order item
variant_id int The variant id of the buyable (not set if the buyable is not a variant)
product_id int The product id of the buyable
buyable_type string The buyable type of the order item
buyable_id int The buyable id of the order item
name string The name for the order item
url string The url for the order item
sku string The sku for the order item
reference string The unique reference for the order item
manufacturer object The Manufacturer for the order item (null if none)
image.url string The image url for the order item
shippable boolean Whether the order item is shippable
quantity int The quantity for the order item
returned_quantity int The quantity returned for the order item
price.amount float The unit price of the order item excluding tax
price.tax float The unit tax for the order item
discount.amount float The total discount of the order item excluding tax
discount.tax float The total discount tax for the order item
full_price.amount float The unit full price (including extras) of the order item excluding tax
full_price.tax float The unit full tax (including extras) for the order item
cost_price.amount float The unit cost price of the order item excluding tax
cost_price.currency string The currency code for the cost price
weight float The weight for the order item
weight_unit float The weight unit for the order item, defaults to stores normalized
weight unit
volume float The volume for the order item
volume_unit float The volume unit for the order item, defaults to stores normalized
volume unit
hs string The HS code for the order item
origin_country string The origin country code for the order item
goods_description string The goods description for the order item

Manufacturer

Name
 Type
 Description
id int The id of the manufacturer
name string The name of the manufacturer

Payment

Name
 Type
 Description
id int The id of the payment
method object The Payment Method for the payment
reference string The reference for the payment
state string The state of the payment
amount float The total amount for the payment
currency string The currency code for the payment
captured_at timestamp The date the payment was captured

Payment Method

Name
 Type
 Description
id int The id of the payment method
name string The name of the payment method
driver string The driver of the payment method

Fulfillment

Name
 Type
 Description
id int The id of the order return
method object The Fulfillment Method for the fulfillment
reference string The reference of the fulfillment
state string The state of the fulfillment
mobile string The mobile number for the fulfillment
phone string The phone number for the fulfillment
tracking_code string The tracking code for the fulfillment
tracking_url string The tracking url for the fulfillment
weight float The weight for the fulfillment
weight_unit string The weight unit for the fulfillment, defaults to stores normalized
weight unit
volume float The volume for the order item
volume_unit string The volume unit for the fulfillment, defaults to stores normalized
volume unit
delivery_note string The delivery note for the fulfillment
created_at timestamp The date the fulfillment was made
items array An array of Fulfillment Items objects

Fulfillment Method

Name
 Type
 Description
id int The id of the fulfillment method
name string The name of the fulfillment method
driver string The driver of the fulfillment method

Fulfillment Items

Name
 Type
 Description
id int The id of the order item that was fulfilled
quantity int The quantity of the order item that was fulfilled

Return

Name
 Type
 Description
id int The id of the order return
reason string The reason for the return - null if no reason given
created_at timestamp The date the return was made
items array An array of Return Item objects

Return Item

Name
 Type
 Description
id int The id of the order item that was returned
quantity int The quantity of the order item that was returned
exchanged_for_id int The id of the order item that the item was returned for (null if the item was not exchanged)

Comment

Name
 Type
 Description
admin object The Admin who commented
message string The comment message
customer_facing boolean Whether the comment is customer facing
created_at timestamp The date the comment was created

Admin

Name
 Type
 Description
id int The id of the admin
name string The name of the admin
email string The email of the admin

Additional Attribute

Name
 Type
 Description
key string The key of the additional attribute
value string The value of the additional attribute

Examples

Unfulfilled & Unreturned Order
Request
GET /api/orders/{id|reference}
Response
{
    "id": 1,
    "reference": "ABC123",
    "email": "testing@gmail.com",
    "subtotal": {
        "amount": 84166.67,
        "tax": 16833.33
    },
    "shipping": {
        "amount": 83.33,
        "tax": 16.67
    },
    "discount": {
        "amount": 8416.67,
        "tax": 1683.33
    },
    "surcharge": {
        "amount": 0,
        "tax": 0
    },
    "ordered_at": "2023-09-01T09:29:41.000000Z",
    "deliver_on": null,
    "currency": "GBP",
    "status": {
        "id": 3,
        "name": "Successful",
        "state": "successful"
    },
    "customer": {
        "id": 1,
        "name": "Test",
        "email": "test@gmail.com"
    },
    "shipping_method": {
        "id": 1,
        "name": "Standard"
    },
    "billing_address": {
        "id": 1,
        "first_name": "Aero",
        "last_name": "Commerce",
        "company": "Aero Commerce",
        "mobile": null,
        "phone": null,
        "line_1": "28-32 Albert Rd",
        "line_2": null,
        "city": "Middlesbrough",
        "zone": null,
        "postcode": "TS1 1QD",
        "reference": null,
        "country": "GB",
        "eori_number": null
    },
    "shipping_address": {
        "id": 1,
        "first_name": "Aero",
        "last_name": "Commerce",
        "company": "Aero Commerce",
        "mobile": null,
        "phone": null,
        "line_1": "28-32 Albert Rd",
        "line_2": null,
        "city": "Middlesbrough",
        "zone": null,
        "postcode": "TS1 1QD",
        "reference": null,
        "country": "GB",
        "eori_number": null
    },
    "items": [
        {
            "id": 148,
            "name": "Sandro Paris Checked Trench Coat",
            "sku": "SHPMA00148-M",
            "product_id": 4,
            "variant_id": 14,
            "shippable": true,
            "quantity": 2,
            "price": {
                "amount": 42083.33,
                "tax": 8416.67
            },
            "discount": {
                "amount": 8416.67,
                "tax": 1683.33
            },
            "full_price": {
                "amount": 42083.33,
                "tax": 8416.67
            },
            "weight": 0,
            "volume": 0
        }
    ],
    "payments": [
        {
            "id": "a53c31f9-43bd-4fc4-b308-cded0b533a2c",
            "method": {
                "id": 1,
                "name": "Cash",
                "driver": "cash"
            },
            "reference": "a53c31f9-43bd-4fc4-b308-cded0b533a2c",
            "amount": 91000,
            "currency": "GBP",
            "captured_at": "2023-09-12T10:17:03.000000Z"
        }
    ],
    "fulfillments": [],
    "returns": [],
    "comments": [
        {
            "admin": {
                "id": 1,
                "name": "Admin",
                "email": "admin@example.com"
            },
            "message": "This is an API message",
            "customer_facing": true,
            "created_at": "2025-09-01 09:29:41"
        }
    ]
}
Fulfilled Order
Request
GET /api/orders/{id|reference}
Response
{
    "id": 1,
    "reference": "ABC123",
    "email": "testing@gmail.com",
    "subtotal": {
        "amount": 84166.67,
        "tax": 16833.33
    },
    "shipping": {
        "amount": 83.33,
        "tax": 16.67
    },
    "discount": {
        "amount": 8416.67,
        "tax": 1683.33
    },
    "surcharge": {
        "amount": 0,
        "tax": 0
    },
    "currency": "GBP",
    "ordered_at": "2023-09-01T08:29:41.000000Z",
    "deliver_on": null,
    "status": {
        "id": 6,
        "name": "Dispatched",
        "state": "dispatched"
    },
    "customer": {
        "id": 1,
        "name": "Test",
        "email": "test@gmail.com"
    },
    "shipping_method": {
        "id": 1,
        "name": "Standard"
    },
    "billing_address": {
        "id": 1,
        "first_name": "Aero",
        "last_name": "Commerce",
        "company": "Aero Commerce",
        "mobile": null,
        "phone": null,
        "line_1": "28-32 Albert Rd",
        "line_2": null,
        "city": "Middlesbrough",
        "zone": null,
        "postcode": "TS1 1QD",
        "country": "GB",
        "eori_number": null
    },
    "shipping_address": {
        "id": 1,
        "first_name": "Aero",
        "last_name": "Commerce",
        "company": "Aero Commerce",
        "mobile": null,
        "phone": null,
        "line_1": "28-32 Albert Rd",
        "line_2": null,
        "city": "Middlesbrough",
        "zone": null,
        "postcode": "TS1 1QD",
        "country": "GB",
        "eori_number": null
    },
    "items": [
        {
            "id": 26,
            "name": "Sandro Paris Checked Trench Coat",
            "url": "/product/sandro-paris-checked-trench-coat-4?variant=2",
            "sku": "SHPMA00148-M",
            "reference": null,
            "manufacturer": {
                "id": 2,
                "name": "Sandro Paris"
            },
            "image": {
                "url": "http://l9.test/storage/images/products/uaaVbTbqbZxs1FH3N28Tw0a7dc6I7Xd08DiyPAG6.jpg"
            },
            "product_id": 4,
            "variant_id": 14,
            "buyable_type": "variant",
            "buyable_id": 14,
            "shippable": true,
            "quantity": 2,
            "returned_quantity": 0,
            "price": {
                "amount": 42083.33,
                "tax": 8416.67
            },
            "discount": {
                "amount": 8416.67,
                "tax": 1683.33
            },
            "full_price": {
                "amount": 42083.33,
                "tax": 8416.67
            },
            "weight": 0,
            "volume": 0,
            "cost_price": {
                "amount": null,
                "currency": null
            },
            "hs": null,
            "origin_country": null,
            "goods_description": null
        }
    ],
    "flags": [],
    "payments": [
        {
            "id": "a53c31f9-43bd-4fc4-b308-cded0b533a2c",
            "method": {
                "id": 1,
                "name": "Cash",
                "driver": "cash"
            },
            "reference": "a53c31f9-43bd-4fc4-b308-cded0b533a2c",
            "state": "captured",
            "amount": 91000,
            "currency": "GBP",
            "captured_at": "2023-09-12T10:17:03.000000ZZ",
            "refunds": []
        }
    ],
    "fulfillments": [
        {
            "id": 3,
            "method": {
                "id": 1,
                "name": "Manual Fulfillment",
                "driver": "manual"
            },
            "address": {
                "id": 3,
                "first_name": "Aero",
                "last_name": "Commerce",
                "company": "Aero Commerce",
                "mobile": null,
                "phone": null,
                "line_1": "28-32 Albert Rd",
                "line_2": null,
                "city": "Middlesbrough",
                "zone": null,
                "postcode": "TS1 1QD",
                "country": "GB",
                "eori_number": null
            },
            "reference": "F3-128",
            "state": "successful",
            "mobile": null,
            "email": "testing@gmail.com",
            "tracking_code": "test tracking code",
            "tracking_url": null,
            "weight": 0,
            "weight_unit": null,
            "volume": 0,
            "volume_unit": "cm^3",
            "delivery_note": "test delivery note",
            "created_at": "2023-09-12T10:17:03.000000Z",
            "items": [
                {
                    "id": 26,
                    "quantity": 2
                }
            ]
        }
    ],
    "returns": [],
    "comments": []
}
Returned Order (Exchange)
Request
GET /api/orders/{id|reference}
Response
{
    "id": 1,
    "reference": "ABC123",
    "email": "testing@gmail.com",
    "subtotal": {
        "amount": 84166.67,
        "tax": 16833.33
    },
    "shipping": {
        "amount": 83.33,
        "tax": 16.67
    },
    "discount": {
        "amount": 8416.67,
        "tax": 1683.33
    },
    "surcharge": {
        "amount": 0,
        "tax": 0
    },
    "currency": "GBP",
    "ordered_at": "2023-09-01T08:29:41.000000Z",
    "deliver_on": null,
    "status": {
        "id": 7,
        "name": "Partially Returned",
        "state": "partially_returned"
    },
    "customer": {
        "id": 1,
        "name": "Test",
        "email": "test@gmail.com"
    },
    "shipping_method": {
        "id": 1,
        "name": "Standard"
    },
    "billing_address": {
        "id": 1,
        "first_name": "Aero",
        "last_name": "Commerce",
        "company": "Aero Commerce",
        "mobile": null,
        "phone": null,
        "line_1": "28-32 Albert Rd",
        "line_2": null,
        "city": "Middlesbrough",
        "zone": null,
        "postcode": "TS1 1QD",
        "country": "GB",
        "eori_number": null
    },
    "shipping_address": {
        "id": 1,
        "first_name": "Aero",
        "last_name": "Commerce",
        "company": "Aero Commerce",
        "mobile": null,
        "phone": null,
        "line_1": "28-32 Albert Rd",
        "line_2": null,
        "city": "Middlesbrough",
        "zone": null,
        "postcode": "TS1 1QD",
        "country": "GB",
        "eori_number": null
    },
    "items": [
        {
            "id": 26,
            "name": "Sandro Paris Checked Trench Coat",
            "url": "/product/sandro-paris-checked-trench-coat-4?variant=2",
            "sku": "SHPMA00148-M",
            "reference": null,
            "manufacturer": {
                "id": 2,
                "name": "Sandro Paris"
            },
            "image": {
                "url": "http://l9.test/storage/images/products/uaaVbTbqbZxs1FH3N28Tw0a7dc6I7Xd08DiyPAG6.jpg"
            },
            "product_id": 4,
            "variant_id": 14,
            "buyable_type": "variant",
            "buyable_id": 14,
            "shippable": true,
            "quantity": 2,
            "returned_quantity": 0,
            "price": {
                "amount": 42083.33,
                "tax": 8416.67
            },
            "discount": {
                "amount": 8416.67,
                "tax": 1683.33
            },
            "full_price": {
                "amount": 42083.33,
                "tax": 8416.67
            },
            "weight": 0,
            "volume": 0,
            "cost_price": {
                "amount": null,
                "currency": null
            },
            "hs": null,
            "origin_country": null,
            "goods_description": null
        }
    ],
    "flags": [],
    "payments": [
        {
            "id": "a53c31f9-43bd-4fc4-b308-cded0b533a2c",
            "method": {
                "id": 1,
                "name": "Cash",
                "driver": "cash"
            },
            "reference": "a53c31f9-43bd-4fc4-b308-cded0b533a2c",
            "state": "captured",
            "amount": 91000,
            "currency": "GBP",
            "captured_at": "2023-09-12T10:17:03.000000ZZ",
            "refunds": []
        }
    ],
    "fulfillments": [],
    "returns": [
        {
            "id": 1,
            "reason": "Test Reason",
            "created_at": "2023-09-12T10:17:03.000000ZZ",
            "items": [
                {
                    "id": 26,
                    "quantity": 2,
                    "exchanged_for_id": 27
                }
            ]
        }
    ],
    "comments": []
}
Returned Order (Refund)
Request
GET /api/orders/{id|reference}
Response
{
    "id": 1,
    "reference": "ABC123",
    "email": "testing@gmail.com",
    "subtotal": {
        "amount": 84166.67,
        "tax": 16833.33
    },
    "shipping": {
        "amount": 83.33,
        "tax": 16.67
    },
    "discount": {
        "amount": 8416.67,
        "tax": 1683.33
    },
    "surcharge": {
        "amount": 0,
        "tax": 0
    },
    "currency": "GBP",
    "ordered_at": "2023-09-01T08:29:41.000000Z",
    "deliver_on": null,
    "status": {
        "id": 8,
        "name": "Returned",
        "state": "returned"
    },
    "customer": {
        "id": 1,
        "name": "Test",
        "email": "test@gmail.com"
    },
    "shipping_method": {
        "id": 1,
        "name": "Standard"
    },
    "billing_address": {
        "id": 1,
        "first_name": "Aero",
        "last_name": "Commerce",
        "company": "Aero Commerce",
        "mobile": null,
        "phone": null,
        "line_1": "28-32 Albert Rd",
        "line_2": null,
        "city": "Middlesbrough",
        "zone": null,
        "postcode": "TS1 1QD",
        "country": "GB",
        "eori_number": null
    },
    "shipping_address": {
        "id": 1,
        "first_name": "Aero",
        "last_name": "Commerce",
        "company": "Aero Commerce",
        "mobile": null,
        "phone": null,
        "line_1": "28-32 Albert Rd",
        "line_2": null,
        "city": "Middlesbrough",
        "zone": null,
        "postcode": "TS1 1QD",
        "country": "GB",
        "eori_number": null
    },
    "items": [
        {
            "id": 26,
            "name": "Sandro Paris Checked Trench Coat",
            "url": "/product/sandro-paris-checked-trench-coat-4?variant=2",
            "sku": "SHPMA00148-M",
            "reference": null,
            "manufacturer": {
                "id": 2,
                "name": "Sandro Paris"
            },
            "image": {
                "url": "http://l9.test/storage/images/products/uaaVbTbqbZxs1FH3N28Tw0a7dc6I7Xd08DiyPAG6.jpg"
            },
            "product_id": 4,
            "variant_id": 14,
            "buyable_type": "variant",
            "buyable_id": 14,
            "shippable": true,
            "quantity": 2,
            "returned_quantity": 0,
            "price": {
                "amount": 42083.33,
                "tax": 8416.67
            },
            "discount": {
                "amount": 8416.67,
                "tax": 1683.33
            },
            "full_price": {
                "amount": 42083.33,
                "tax": 8416.67
            },
            "weight": 0,
            "volume": 0,
            "cost_price": {
                "amount": null,
                "currency": null
            },
            "hs": null,
            "origin_country": null,
            "goods_description": null
        }
    ],
    "flags": [],
    "payments": [
        {
            "id": "a53c31f9-43bd-4fc4-b308-cded0b533a2c",
            "method": {
                "id": 1,
                "name": "Cash",
                "driver": "cash"
            },
            "reference": "a53c31f9-43bd-4fc4-b308-cded0b533a2c",
            "state": "captured",
            "amount": 91000,
            "currency": "GBP",
            "captured_at": "2023-09-12T10:17:03.000000ZZ",
            "refunds": [
                {
                    "id": 1,
                    "amount": 91000,
                    "created_at": "2025-09-16T07:40:22.000000Z"
                }
            ]
        }
    ],
    "fulfillments": [],
    "returns": [
        {
            "id": 1,
            "reason": "Test reason",
            "created_at": "2025-09-16T07:40:22.000000Z",
            "items": [
                {
                    "id": 28,
                    "quantity": 2,
                    "exchanged_for_id": null
                }
            ]
        }
    ],
    "comments": []
}

Create Order Endpoint

Structure

Order

Name
 Type
 Description
 Required
id int The id for the order No
reference string The unique reference for the order Yes
status_id int The status id of the order, can also be resolved from state If ordered_at is not null
state string Alternative to passing status_id, resolves the first status with the specified state No
customer_id int The id of the customer that placed the order No
email string The email of the customer that placed the order No
subtotal.amount float The subtotal of the order excluding tax (in pence not pounds) No
subtotal.tax float The subtotal tax for the order (in pence not pounds) No
shipping.amount float The shipping of the order excluding tax (in pence not pounds) No
shipping.tax float The shipping tax for the order (in pence not pounds) No
discount.amount float The discount of the order excluding tax (in pence not pounds) No
discount.tax float The discount tax for the order (in pence not pounds) No
surcharge.amount float The surcharge of the order excluding tax (in pence not pounds) No
surcharge.tax float The surcharge tax for the order (in pence not pounds) No
shipping_method_id int The shipping method id of the order No
currency string The currency of the order, (defaults to store default if not provided) No
exchange_rate float The exchange rate of the order (derives from currency if not supplied) No
shipping_address object The Shipping Address for the order No
billing_address object The Billing Address for the order No
ip string The ip of the order No
channel string The channel of the order No
subscription_id int The subscription id of the order No
notify boolean Whether the order notifications are activated (defaults to true) No
buy_items boolean Whether the order items stock should be mutated. If false then OrderItemBought event will not be emit (defaults to true) No
ordered_at timestamp When the order was ordered No
deliver_on timestamp When the order should be delivered No
items array An array of Order Item objects Yes
payments array An array of Payment objects No
fulfillments array An array of Fulfillment objects No
comments array An array of Comment objects No
additional_attributes array An array of Additional Attribute objects No

If no subtotal.amount or subtotal.tax is passed their values will be set to the sum of the items price.amount * quantity & price.tax * quantity respectively.

If no discount.amount or discount.tax is passed their values will be set to the sum of the items discount.amount & discount.tax respectively.

Shipping Address

Name
 Type
 Description
 Required
first_name string The first name for the shipping address Yes
last_name string The last name for the shipping address Yes
company string The company for the shipping address No
mobile string The mobile number for the shipping address No
phone string The phone number for the shipping address No
line_1 string The first line for the shipping address Yes
line_2 string The second line for the shipping address No
city string The city for the shipping address Yes
zone string The zone code for the shipping address No
postcode string The postcode for the shipping address Yes
country string The country code for the shipping address No
reference string The unique reference for the shipping address No
eori_number string The EORI number for the shipping address No

Billing Address

Name
 Type
 Description
 Required
first_name string The first name for the billing address Yes
last_name string The last name for the billing address Yes
company string The company for the billing address No
mobile string The mobile number for the billing address No
phone string The phone number for the billing address No
line_1 string The first line for the billing address Yes
line_2 string The second line for the billing address No
city string The city for the billing address Yes
zone string The zone code for the billing address No
postcode string The postcode for the billing address Yes
country string The country code for the billing address No
reference string The unique reference for the billing address No
eori_number string The EORI number for the billing address No

Order Item

Name
 Type
 Description
 Required
key string The unique key for the order item No
variant_id int The variant id of the buyable No
product_id string The product id of the buyable (resolves first variant unless variant_id is provided) No
buyable_type string The buyable type of the order item Not required if any of:
sku/variant_id/product_id are provided
buyable_id int The buyable id of the order item Not required if any of:
sku/variant_id/product_id are provided
name string The name for the order item Conditional *
url string The url for the order item No
sku string The sku for the order item, can be used to resolve buyable Conditional *
reference string The unique reference for the order item No
manufacturer_id int The manufacturer id for the order item No
image string The image for the order item No
options array The options for the order item No
shippable boolean Whether the order item is shippable No
quantity int The quantity for the order item Yes
price.amount float The unit price of the order item excluding tax (in pence not pounds) Yes
price.tax float The unit tax for the order item (in pence not pounds) Yes
discount.amount float The total discount of the order item excluding tax (in pence not pounds) No
discount.tax float The total discount tax for the order item (in pence not pounds) No
full_price.amount float The unit full price (including extras) of the order item excluding tax (in pence not pounds) No
full_price.tax float The unit full tax (including extras) for the order item (in pence not pounds) No
cost_price.amount float The unit cost price of the order item excluding tax (in pence not pounds) No
cost_price.currency string The currency code for the cost price No
weight float The weight for the order item No
weight_unit float The weight unit for the order item, defaults to stores normalized
weight unit if not passed		 No
volume float The volume for the order item No
volume_unit float The volume unit for the order item, defaults to stores normalized
volume unit if not passed		 No
tag_ids array The tag ids for the order item No
hs string The HS code for the order item No
origin_country string The origin country code for the order item No
subscription_plan_id int The subscription plan id for the order item No
goods_description string The goods description for the order item No

* If no buyable can be resolved from the given data, the sku is required - as is the name.

price, discount & full_price all support an un-nested price including tax being passed, see Price Conventions.

Payment

Name
 Type
 Description
 Required
method_id int The payment method id of the payment Not required if driver is passed
driver string Payment driver used to resolve method_id No
reference string The reference for the payment, if not specified a uuid will be generated No
state string The state for the payment, if not specified the captured state will be used No
amount float The total amount for the payment Yes

Valid states: failed, pending, authorized, partially captured, captured, partially refunded, refunded, canceled, errored

Fulfillment

Name
 Type
 Description
 Required
id int The id for the fulfillment No
reference string The reference for the fulfillment No
state string The state of the fulfillment (defaults to method's default if not passed) No
method int| string The fulfillment method's id, name or driver (defaults to orders' default if not passed) No
tracking_code string The tracking code for the fulfillment No
tracking_url url The tracking url for the fulfillment No
weight float The total weight of the fulfillment (calculated from items if not passed) No
weight_unit string The weight unit (defaults to store's default if not provided) No
volume float The total volume of the fulfillment (calculated from items if not passed) No
volume_unit string The volume unit (defaults to store's default if not provided) No
delivery_note string The delivery note for the fulfillment No
notify boolean Whether the fulfillment notifications are activated (defaults to true) No
dispatched_at timestamp The dispatched at of the fulfillment No
items array An array of Fullfillment Item objects (if not passed every fulfillable item is fulfilled) No

Fulfillment Item

Name
 Type
 Description
 Required
sku string The sku of the order item to be fulfilled Yes
quantity int The quantity to be fulfilled (defaults to max possible) No
weight float The weight of the item (uses order item's weight if not passed) No
weight_unit string The weight unit (defaults to store's default if not provided) No
volume float The volume of the fulfillment (uses order item's volume if not passed) No
volume_unit string The volume unit (defaults to store's default if not provided) No

Comment

Name
 Type
 Description
 Required
id int The id for the comment No
admin int|string The id or email of the admin No
message string The comment message Yes
customer_facing boolean Whether the comment is customer facing (default: false) No
created_at timestamp The date the comment was created (defaults to now) No

Additional Attribute

Name
 Type
 Description
 Required
key string The key of the additional attribute Yes
value string The value of the additional attribute Yes

Example Request

POST /api/orders
{
    "reference": "ABC123",
    "email": "testing@gmail.com",
    "subtotal": {
        "amount": 84166.67,
        "tax": 16833.33
    },
    "shipping": {
        "amount": 83.33,
        "tax": 16.67
    },
    "discount": {
        "amount": 8416.67,
        "tax": 1683.33
    },
    "ordered_at": "2023-09-01T09:29:41.000000Z",
    "currency": "GBP", 
    "status_id": 3, 
    "customer_id": 1, 
    "shipping_method_id": 1, 
    "notify": true, 
    "billing_address": { 
        "first_name": "Aero",
        "last_name": "Commerce",
        "company": "Aero Commerce", 
        "mobile": null, 
        "phone": null, 
        "line_1": "28-32 Albert Rd",
        "line_2": null, 
        "city": "Middlesbrough",
        "zone": null, 
        "postcode": "TS1 1QD",
        "reference": null, 
        "country": "GB", 
        "eori_number": null 
    },
    "shipping_address": {
        "first_name": "Aero",
        "last_name": "Commerce",
        "company": "Aero Commerce", 
        "mobile": null, 
        "phone": null, 
        "line_1": "28-32 Albert Rd",
        "line_2": null, 
        "city": "Middlesbrough",
        "zone": null, 
        "postcode": "TS1 1QD",
        "reference": null, 
        "country": "GB", 
        "eori_number": null 
    },
    "items": [
        {
            "variant_id": 1,
            "shippable": true,
            "quantity": 2,
            "price": {
                "amount": 42083.33,
                "tax": 8416.67
            },
            "discount": {
                "amount": 8416.67,
                "tax": 1683.33
            }
        }
    ],
    "payments": [
        {
            "driver": "cash",
            "amount": 91000
        }
    ],
    "comments": [
        {
            "admin": "admin@example.com",
            "message": "This is an API message",
            "created_at": "2025-09-01 09:29:41",
            "customer_facing": true
        }
    ]
}

Example Response

{
    "order": {
        "id": 1
    }
}

Flag Order Endpoints

Examples

Adding a Flag
Request
POST /api/orders/{id|reference}/flags/{id|name}
Response
{
    "order": {
        "id": 1
    },
    "flag": {
        "id": 1
    }
}
Removing a Flag
Request
DELETE /api/orders/{id|reference}/flags/{id|name}
Response
204 No Content

Order Comments Endpoint

Structure

Name
 Type
 Description
 Required
id int The id for the comment No
admin int|string The id or email of the admin No
message string The comment message Yes
customer_facing boolean Whether the comment is customer facing (default: false) No
created_at timestamp The date the comment was created (defaults to now) No

If no admin is supplied then the API Token name will be displayed for the comment in the Admin.

Example Request

POST /api/orders/{id|reference}/comments
{
    "admin": "admin@example.com",
    "message": "This is an API message",
    "customer_facing": true,
    "created_at": "2025-09-01 09:29:41"
}

Example Response

{
    "order": {
        "id": 1
    },
    "comment": {
        "id": 1
    }
}