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
    }
}