Orders

Orders get created in a "draft" status and become "pending" when they have a customer and some line items. Draft orders act as shopping carts. Pending orders can be recovered when abandoned. When an order is placed, it can either get "approved" or "canceled". An approved order becomes "fulfilled" when paid and shipped. Canceling an order automatically voids its payment source's authorization.

The order object

An order object is returned as part of the response body of each successful create, list, retrieve or update API call. The following table contains the list of all its fields along with their type, description and example values.
Object fields:
status
string
The order status. One of 'draft' (default), 'pending', 'placed', 'approved' or 'cancelled'
Example:
draft
payment_status
string
The order's payment status. One of 'unpaid' (default), 'authorized', 'paid', 'voided' or 'refunded'
Example:
unpaid
fulfillment_status
string
The order's fulfillment status. One of 'unfulfilled' (default), 'in_progress' or 'fulfilled'
Example:
unfulfilled
guest
boolean
Indicates if the order has been placed as guest.
Example:
true
editable
boolean
Indicates if the order can be edited.
Example:
true
placeable
boolean
Indicates if the order can be placed.
Example:
false
customer_email
string
The email address of the associated customer. When creating or updating an order, this is a shortcut to find or create the associated customer by email.
language_code
string
The preferred language code (ISO 639-1) to be used when communicating with the customer. This can be useful when sending the order to 3rd party marketing tools and CRMs. If the language is supported, the hosted checkout will be localized accordingly.
Example:
it
currency_code
string
The international 3-letter currency code as defined by the ISO 4217 standard, automatically inherited from the order's market.
Example:
EUR
tax_included
boolean
Indicates if taxes are included in the order amounts, automatically inherited from the order's price list.
Example:
true
tax_rate
float
The tax rate for this order (if calculated).
Example:
0.22
freight_taxable
boolean
Indicates if taxes are applied to shipping costs.
Example:
true
country_code
string
The international 2-letter country code as defined by the ISO 3166-1 standard, automatically inherited from the order's shipping address.
Example:
IT
shipping_country_code_lock
string
The country code that you want the shipping address to be locked to. This can be useful to make sure the shipping address belongs to a given shipping country, e.g. the one selected in a country selector page.
Example:
IT
coupon_code
string
The coupon code to be used for the order. If valid, it triggers a promotion adding a discount line item to the order.
Example:
SUMMERDISCOUNT
subtotal_amount_cents
integer
The sum of all the sku line items total amounts, in cents.
Example:
5000
subtotal_amount_float
float
The sum of all the sku line items total amounts, float.
Example:
50.0
formatted_subtotal_amount
string
The sum of all the sku line items total amounts, formatted.
Example:
€50,00
shipping_amount_cents
integer
The sum of all the shipping costs, in cents.
Example:
1200
shipping_amount_float
float
The sum of all the shipping costs, float.
Example:
12.0
formatted_shipping_amount
string
The sum of all the shipping costs, formatted.
Example:
€12,00
payment_method_amount_cents
integer
The sum of all the payment method costs, in cents.
Example:
0
payment_method_amount_float
float
The sum of all the payment method costs, float.
Example:
0.0
formatted_payment_method_amount
string
The sum of all the payment method costs, formatted.
Example:
€0,00
discount_amount_cents
integer
The sum of all the discounts applied to the order, in cents (negative amount).
Example:
-500
discount_amount_float
float
The sum of all the discounts applied to the order, float.
Example:
-5.0
formatted_discount_amount
string
The sum of all the discounts applied to the order, formatted.
Example:
-€5,00
total_tax_amount_cents
integer
The sum of all the taxes applied to the order, in cents.
Example:
1028
total_tax_amount_float
float
The sum of all the taxes applied to the order, float.
Example:
10.28
formatted_total_tax_amount
string
The sum of all the discounts applied to the order, formatted.
Example:
€10,28
subtotal_tax_amount_cents
integer
The taxes applied to the order's subtotal, in cents.
Example:
902
subtotal_tax_amount_float
float
The taxes applied to the order's subtotal, float.
Example:
9.02
formatted_subtotal_tax_amount
string
The sum of all the discounts applied to the order, formatted.
Example:
€9,02
shipping_tax_amount_cents
integer
The taxes applied to the order's shipping costs, in cents.
Example:
216
shipping_tax_amount_float
float
The taxes applied to the order's shipping costs, float.
Example:
2.16
formatted_shipping_tax_amount
string
The taxes applied to the order's shipping costs, formatted.
Example:
€2,16
payment_method_tax_amount_cents
integer
The taxes applied to the order's payment method costs, in cents.
Example:
0
payment_method_tax_amount_float
float
The taxes applied to the order's payment method costs, float.
Example:
0.0
formatted_payment_method_tax_amount
string
The taxes applied to the order's payment method costs, formatted.
Example:
€0,00
discount_tax_amount_cents
integer
The taxes applied to the order's discount, in cents (negative amount).
Example:
-90
discount_tax_amount_float
float
The taxes applied to the order's discount, float.
Example:
-0.9
formatted_discount_tax_amount
string
The taxes applied to the order's discount, formatted.
Example:
-€0,90
total_amount_cents
integer
The order's total amount, in cents.
Example:
5700
total_amount_float
float
The order's total amount, float.
Example:
57.0
formatted_total_amount
string
The order's total amount, formatted.
Example:
€57,00
total_taxable_amount_cents
integer
The order's total taxable amount, in cents (equal to total_amount_cents when prices don't include taxes).
Example:
4672
total_taxable_amount_float
float
The order's total taxable amount, float.
Example:
46.72
formatted_total_taxable_amount
string
The order's total taxable amount, formatted.
Example:
€46,72
subtotal_taxable_amount_cents
integer
The order's subtotal taxable amount, in cents (equal to subtotal_amount_cents when prices don't include taxes).
Example:
4098
subtotal_taxable_amount_float
float
The order's subtotal taxable amount, float.
Example:
40.98
formatted_subtotal_taxable_amount
string
The order's subtotal taxable amount, formatted.
Example:
€40,98
shipping_taxable_amount_cents
integer
The order's shipping taxable amount, in cents (equal to shipping_amount_cents when prices don't include taxes).
Example:
984
shipping_taxable_amount_float
float
The order's shipping taxable amount, float.
Example:
9.84
formatted_shipping_taxable_amount
string
The order's shipping taxable amount, formatted.
Example:
€9,84
payment_method_taxable_amount_cents
integer
The order's payment method taxable amount, in cents (equal to payment_method_amount_cents when prices don't include taxes).
Example:
0
payment_method_taxable_amount_float
float
The order's payment method taxable amount, float.
Example:
0.0
formatted_payment_method_taxable_amount
string
The order's payment method taxable amount, formatted.
Example:
€0,00
discount_taxable_amount_cents
integer
The order's discount taxable amount, in cents (equal to discount_amount_cents when prices don't include taxes).
Example:
-410
discount_taxable_amount_float
float
The order's discount taxable amount, float.
Example:
-4.10
formatted_discount_taxable_amount
string
The order's discount taxable amount, formatted.
Example:
-€4,10
total_amount_with_taxes_cents
integer
The order's total amount (when prices include taxes) or the order's total + taxes amount (when prices don't include taxes, e.g. US Markets or B2B)
Example:
5700
total_amount_with_taxes_float
float
The order's total amount with taxes, float.
Example:
57.00
formatted_total_amount_with_taxes
string
The order's total amount with taxes, formatted.
Example:
€57,00
fees_amount_cents
integer
The fees amount that is applied by Commerce Layer, in cents.
Example:
0
fees_amount_float
float
The fees amount that is applied by Commerce Layer, float.
Example:
0.0
formatted_fees_amount
string
The fees amount that is applied by Commerce Layer, formatted.
Example:
€0,00
skus_count
integer
The total number of skus in the order's line items. This can be useful to display a preview of the customer shopping cart content.
Example:
2
payment_source_details
object
An object that contains the shareable details of the order's payment source.
Example:
null
token
string
A unique token that can be shared more securely instead of the order's id.
Example:
1c0994cc4e996e8c6ee56a2198f66f3c
cart_url
string
The cart url on your site. If present, it will be used on our hosted checkout application.
Example:
https://yourbrand.com/cart
return_url
string
The return url on your site. If present, it will be used on our hosted checkout application.
Example:
https://yourbrand.com/
terms_url
string
The terms and conditions url on your site. If present, it will be used on our hosted checkout application.
Example:
https://yourbrand.com/terms
privacy_url
string
The privacy polivy url on your site. If present, it will be used on our hosted checkout application.
Example:
https://yourbrand.com/privacy
checkout_url
string
The checkout url that was automatically generated for the order. Send the customers to this url to let them checkout the order securely on our hosted checkout application.
Example:
https://commerce.yourbrand.com/checkout/1c0994cc4e996e8c6ee56a2198f66f3c
placed_at
datetime
Time at which the order was placed.
Example:
2018-01-01T12:00:00.000Z
approved_at
datetime
Time at which the order was approved.
Example:
2018-01-01T12:00:00.000Z
cancelled_at
datetime
Time at which the order was cancelled.
Example:
2018-01-01T12:00:00.000Z
payment_updated_at
datetime
Time at which the order's payment status was last updated.
Example:
2018-01-01T12:00:00.000Z
fulfillment_updated_at
datetime
Time at which the order's fulfillment status was last updated.
Example:
2018-01-01T12:00:00.000Z
id
integer
Unique identifier for the resource.
Example:
1234
created_at
datetime
Time at which the resource was created.
Example:
2018-01-01T12:00:00.000Z
updated_at
datetime
Time at which the resource was last updated.
Example:
2018-01-01T12:00:00.000Z
reference
string
A string that you can use to add your own identifier to the resource. This can be useful for intergrating the resource to an external system, like an ERP, a marketing tool or a CRM.
Example:
ANYREFEFERNCE
metadata
object
Set of key-value pairs that you can attach to the resource. This can be useful for storing additional information about the resource in a structured format.
Example:
{"foo":"bar"}
relationship (N:1)
The associated market.
relationship (N:1)
The associated customer.
relationship (N:1)
The customer's shipping address.
relationship (N:1)
The customer's billing address.
relationship (N:1)
The associated payment method.
payment_source
relationship (N:1)
The associated payment source (credit card or paypal payment).
relationship (1:N)
The associated line items.
relationship (1:N)
The associated shipments (automatically generated based on the inventory model).

Create an order

To create a new order, send a POST request to the /api/orders endpoint, passing the resource arguments in the request body. The following table contains the list of all the possible arguments, along with their type, description and examples values. All the arguments marked as required must be present in the request.
Arguments:
guest
optional
Indicates if the order has been placed as guest.
Example:
true
customer_email
optional
The email address of the associated customer. When creating or updating an order, this is a shortcut to find or create the associated customer by email.
customer_password
optional
The password of the associated customer. When creating or updating an order, this is a shortcut to sign up the associated customer.
Example:
secret
language_code
optional, default is 'en'
The preferred language code (ISO 639-1) to be used when communicating with the customer. This can be useful when sending the order to 3rd party marketing tools and CRMs. If the language is supported, the hosted checkout will be localized accordingly.
Example:
it
shipping_country_code_lock
optional
The country code that you want the shipping address to be locked to. This can be useful to make sure the shipping address belongs to a given shipping country, e.g. the one selected in a country selector page.
Example:
IT
coupon_code
optional
The coupon code to be used for the order. If valid, it triggers a promotion adding a discount line item to the order.
Example:
SUMMERDISCOUNT
cart_url
optional
The cart url on your site. If present, it will be used on our hosted checkout application.
Example:
https://yourbrand.com/cart
return_url
optional
The return url on your site. If present, it will be used on our hosted checkout application.
Example:
https://yourbrand.com/
terms_url
optional
The terms and conditions url on your site. If present, it will be used on our hosted checkout application.
Example:
https://yourbrand.com/terms
privacy_url
optional
The privacy polivy url on your site. If present, it will be used on our hosted checkout application.
Example:
https://yourbrand.com/privacy
reference
optional
A string that you can use to add your own identifier to the resource. This can be useful for intergrating the resource to an external system, like an ERP, a marketing tool or a CRM.
Example:
ANYREFEFERNCE
metadata
optional
Set of key-value pairs that you can attach to the resource. This can be useful for storing additional information about the resource in a structured format.
Example:
#
required
The associated market.
optional
The associated customer.
optional
The customer's shipping address.
optional
The customer's billing address.
optional
The associated payment method.
payment_source
optional
The associated payment source (credit card or paypal payment).
Example request:
POST /api/orders HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": {
    "type": "orders",
    "relationships": {
      "market": {
        "data": {
          "type": "markets",
          "id": "1234"
        }
      }
    }
  }
}
Example response: 201 Created
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json

{
  "data": {
    "id": "1234",
    "type": "orders",
    "links": {
      "self": "https://your-brand.commercelayer.io/api/orders/1234"
    },
    "attributes": {
      "status": "draft",
      "payment_status": "unpaid",
      "fulfillment_status": "unfulfilled",
      "guest": "true",
      "editable": "true",
      "placeable": "false",
      "customer_email": "[email protected]",
      "language_code": "it",
      "currency_code": "EUR",
      "tax_included": "true",
      "tax_rate": "0.22",
      "freight_taxable": "true",
      "country_code": "IT",
      "shipping_country_code_lock": "IT",
      "coupon_code": "SUMMERDISCOUNT",
      "subtotal_amount_cents": "5000",
      "subtotal_amount_float": "50.0",
      "formatted_subtotal_amount": "€50,00",
      "shipping_amount_cents": "1200",
      "shipping_amount_float": "12.0",
      "formatted_shipping_amount": "€12,00",
      "payment_method_amount_cents": "0",
      "payment_method_amount_float": "0.0",
      "formatted_payment_method_amount": "€0,00",
      "discount_amount_cents": "-500",
      "discount_amount_float": "-5.0",
      "formatted_discount_amount": "-€5,00",
      "total_tax_amount_cents": "1028",
      "total_tax_amount_float": "10.28",
      "formatted_total_tax_amount": "€10,28",
      "subtotal_tax_amount_cents": "902",
      "subtotal_tax_amount_float": "9.02",
      "formatted_subtotal_tax_amount": "€9,02",
      "shipping_tax_amount_cents": "216",
      "shipping_tax_amount_float": "2.16",
      "formatted_shipping_tax_amount": "€2,16",
      "payment_method_tax_amount_cents": "0",
      "payment_method_tax_amount_float": "0.0",
      "formatted_payment_method_tax_amount": "€0,00",
      "discount_tax_amount_cents": "-90",
      "discount_tax_amount_float": "-0.9",
      "formatted_discount_tax_amount": "-€0,90",
      "total_amount_cents": "5700",
      "total_amount_float": "57.0",
      "formatted_total_amount": "€57,00",
      "total_taxable_amount_cents": "4672",
      "total_taxable_amount_float": "46.72",
      "formatted_total_taxable_amount": "€46,72",
      "subtotal_taxable_amount_cents": "4098",
      "subtotal_taxable_amount_float": "40.98",
      "formatted_subtotal_taxable_amount": "€40,98",
      "shipping_taxable_amount_cents": "984",
      "shipping_taxable_amount_float": "9.84",
      "formatted_shipping_taxable_amount": "€9,84",
      "payment_method_taxable_amount_cents": "0",
      "payment_method_taxable_amount_float": "0.0",
      "formatted_payment_method_taxable_amount": "€0,00",
      "discount_taxable_amount_cents": "-410",
      "discount_taxable_amount_float": "-4.10",
      "formatted_discount_taxable_amount": "-€4,10",
      "total_amount_with_taxes_cents": "5700",
      "total_amount_with_taxes_float": "57.00",
      "formatted_total_amount_with_taxes": "€57,00",
      "fees_amount_cents": "0",
      "fees_amount_float": "0.0",
      "formatted_fees_amount": "€0,00",
      "skus_count": "2",
      "payment_source_details": null,
      "token": "1c0994cc4e996e8c6ee56a2198f66f3c",
      "cart_url": "https://yourbrand.com/cart",
      "return_url": "https://yourbrand.com/",
      "terms_url": "https://yourbrand.com/terms",
      "privacy_url": "https://yourbrand.com/privacy",
      "checkout_url": "https://commerce.yourbrand.com/checkout/1c0994cc4e996e8c6ee56a2198f66f3c",
      "placed_at": "2018-01-01T12:00:00.000Z",
      "approved_at": "2018-01-01T12:00:00.000Z",
      "cancelled_at": "2018-01-01T12:00:00.000Z",
      "payment_updated_at": "2018-01-01T12:00:00.000Z",
      "fulfillment_updated_at": "2018-01-01T12:00:00.000Z",
      "id": "1234",
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": "ANYREFEFERNCE",
      "metadata": {
        "foo": "bar"
      }
    },
    "relationships": {
      "market": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/orders/1234/relationships/market",
          "related": "https://your-brand.commercelayer.io/api/orders/1234/market"
        }
      },
      "customer": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/orders/1234/relationships/customer",
          "related": "https://your-brand.commercelayer.io/api/orders/1234/customer"
        }
      },
      "shipping_address": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/orders/1234/relationships/shipping_address",
          "related": "https://your-brand.commercelayer.io/api/orders/1234/shipping_address"
        }
      },
      "billing_address": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/orders/1234/relationships/billing_address",
          "related": "https://your-brand.commercelayer.io/api/orders/1234/billing_address"
        }
      },
      "payment_method": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/orders/1234/relationships/payment_method",
          "related": "https://your-brand.commercelayer.io/api/orders/1234/payment_method"
        }
      },
      "payment_source": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/orders/1234/relationships/payment_source",
          "related": "https://your-brand.commercelayer.io/api/orders/1234/payment_source"
        }
      },
      "line_items": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/orders/1234/relationships/line_items",
          "related": "https://your-brand.commercelayer.io/api/orders/1234/line_items"
        }
      },
      "shipments": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/orders/1234/relationships/shipments",
          "related": "https://your-brand.commercelayer.io/api/orders/1234/shipments"
        }
      }
    },
    "meta": {
      "mode": "test"
    }
  }
}

List all orders

To fetch a collection of orders, send a GET request to the /api/orders endpoint.

Example request:
GET /api/orders HTTP/1.1
Accept: application/vnd.api+json
Example response: 200 OK
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": [
    {
      "id": "1234",
      "type": "orders",
      "links": {
        "self": "https://your-brand.commercelayer.io/api/orders/1234"
      },
      "attributes": {
        "status": "draft",
        "payment_status": "unpaid",
        "fulfillment_status": "unfulfilled",
        "guest": "true",
        "editable": "true",
        "placeable": "false",
        "customer_email": "[email protected]",
        "language_code": "it",
        "currency_code": "EUR",
        "tax_included": "true",
        "tax_rate": "0.22",
        "freight_taxable": "true",
        "country_code": "IT",
        "shipping_country_code_lock": "IT",
        "coupon_code": "SUMMERDISCOUNT",
        "subtotal_amount_cents": "5000",
        "subtotal_amount_float": "50.0",
        "formatted_subtotal_amount": "€50,00",
        "shipping_amount_cents": "1200",
        "shipping_amount_float": "12.0",
        "formatted_shipping_amount": "€12,00",
        "payment_method_amount_cents": "0",
        "payment_method_amount_float": "0.0",
        "formatted_payment_method_amount": "€0,00",
        "discount_amount_cents": "-500",
        "discount_amount_float": "-5.0",
        "formatted_discount_amount": "-€5,00",
        "total_tax_amount_cents": "1028",
        "total_tax_amount_float": "10.28",
        "formatted_total_tax_amount": "€10,28",
        "subtotal_tax_amount_cents": "902",
        "subtotal_tax_amount_float": "9.02",
        "formatted_subtotal_tax_amount": "€9,02",
        "shipping_tax_amount_cents": "216",
        "shipping_tax_amount_float": "2.16",
        "formatted_shipping_tax_amount": "€2,16",
        "payment_method_tax_amount_cents": "0",
        "payment_method_tax_amount_float": "0.0",
        "formatted_payment_method_tax_amount": "€0,00",
        "discount_tax_amount_cents": "-90",
        "discount_tax_amount_float": "-0.9",
        "formatted_discount_tax_amount": "-€0,90",
        "total_amount_cents": "5700",
        "total_amount_float": "57.0",
        "formatted_total_amount": "€57,00",
        "total_taxable_amount_cents": "4672",
        "total_taxable_amount_float": "46.72",
        "formatted_total_taxable_amount": "€46,72",
        "subtotal_taxable_amount_cents": "4098",
        "subtotal_taxable_amount_float": "40.98",
        "formatted_subtotal_taxable_amount": "€40,98",
        "shipping_taxable_amount_cents": "984",
        "shipping_taxable_amount_float": "9.84",
        "formatted_shipping_taxable_amount": "€9,84",
        "payment_method_taxable_amount_cents": "0",
        "payment_method_taxable_amount_float": "0.0",
        "formatted_payment_method_taxable_amount": "€0,00",
        "discount_taxable_amount_cents": "-410",
        "discount_taxable_amount_float": "-4.10",
        "formatted_discount_taxable_amount": "-€4,10",
        "total_amount_with_taxes_cents": "5700",
        "total_amount_with_taxes_float": "57.00",
        "formatted_total_amount_with_taxes": "€57,00",
        "fees_amount_cents": "0",
        "fees_amount_float": "0.0",
        "formatted_fees_amount": "€0,00",
        "skus_count": "2",
        "payment_source_details": null,
        "token": "1c0994cc4e996e8c6ee56a2198f66f3c",
        "cart_url": "https://yourbrand.com/cart",
        "return_url": "https://yourbrand.com/",
        "terms_url": "https://yourbrand.com/terms",
        "privacy_url": "https://yourbrand.com/privacy",
        "checkout_url": "https://commerce.yourbrand.com/checkout/1c0994cc4e996e8c6ee56a2198f66f3c",
        "placed_at": "2018-01-01T12:00:00.000Z",
        "approved_at": "2018-01-01T12:00:00.000Z",
        "cancelled_at": "2018-01-01T12:00:00.000Z",
        "payment_updated_at": "2018-01-01T12:00:00.000Z",
        "fulfillment_updated_at": "2018-01-01T12:00:00.000Z",
        "id": "1234",
        "created_at": "2018-01-01T12:00:00.000Z",
        "updated_at": "2018-01-01T12:00:00.000Z",
        "reference": "ANYREFEFERNCE",
        "metadata": {
          "foo": "bar"
        }
      },
      "relationships": {
        "market": {
          "links": {
            "self": "https://your-brand.commercelayer.io/api/orders/1234/relationships/market",
            "related": "https://your-brand.commercelayer.io/api/orders/1234/market"
          }
        },
        "customer": {
          "links": {
            "self": "https://your-brand.commercelayer.io/api/orders/1234/relationships/customer",
            "related": "https://your-brand.commercelayer.io/api/orders/1234/customer"
          }
        },
        "shipping_address": {
          "links": {
            "self": "https://your-brand.commercelayer.io/api/orders/1234/relationships/shipping_address",
            "related": "https://your-brand.commercelayer.io/api/orders/1234/shipping_address"
          }
        },
        "billing_address": {
          "links": {
            "self": "https://your-brand.commercelayer.io/api/orders/1234/relationships/billing_address",
            "related": "https://your-brand.commercelayer.io/api/orders/1234/billing_address"
          }
        },
        "payment_method": {
          "links": {
            "self": "https://your-brand.commercelayer.io/api/orders/1234/relationships/payment_method",
            "related": "https://your-brand.commercelayer.io/api/orders/1234/payment_method"
          }
        },
        "payment_source": {
          "links": {
            "self": "https://your-brand.commercelayer.io/api/orders/1234/relationships/payment_source",
            "related": "https://your-brand.commercelayer.io/api/orders/1234/payment_source"
          }
        },
        "line_items": {
          "links": {
            "self": "https://your-brand.commercelayer.io/api/orders/1234/relationships/line_items",
            "related": "https://your-brand.commercelayer.io/api/orders/1234/line_items"
          }
        },
        "shipments": {
          "links": {
            "self": "https://your-brand.commercelayer.io/api/orders/1234/relationships/shipments",
            "related": "https://your-brand.commercelayer.io/api/orders/1234/shipments"
          }
        }
      },
      "meta": {
        "mode": "test"
      }
    },
    {
      "other": "... 24 orders (first page)"
    }
  ],
  "meta": {
    "record_count": 125,
    "page_count": 5
  },
  "links": {
    "first": "/api/orders?page[number]=1&page[size]=25",
    "prev": "/api/orders?page[number]=2&page[size]=25",
    "next": "/api/orders?page[number]=4&page[size]=25",
    "last": "/api/orders?page[number]=5&page[size]=25"
  }
}
Available filters
idstatuspayment_statusfulfillment_statustokenplaced_atapproved_atcancelled_atpayment_updated_atfulfillment_updated_atreferencemarket_idcustomer_idpayment_method_ididsplaced_at_fromplaced_at_toapproved_at_fromapproved_at_tocancelled_at_fromcancelled_at_topayment_updated_at_frompayment_updated_at_tofulfillment_updated_at_fromfulfillment_updated_at_tocreated_at_fromcreated_at_toupdated_at_fromupdated_at_to
Sortable attributes
statuspayment_statusfulfillment_statusplaced_atapproved_atcancelled_atpayment_updated_atfulfillment_updated_atidcreated_atupdated_atreference

Retrieve an order

To fetch a single order, send a GET request to the /api/orders/{{id}} endpoint, where {{id}} is the id of the resource that you want to retrieve.
Example request:
GET /api/orders/1234 HTTP/1.1
Accept: application/vnd.api+json
Example response: 200 OK
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": {
    "id": "1234",
    "type": "orders",
    "links": {
      "self": "https://your-brand.commercelayer.io/api/orders/1234"
    },
    "attributes": {
      "status": "draft",
      "payment_status": "unpaid",
      "fulfillment_status": "unfulfilled",
      "guest": "true",
      "editable": "true",
      "placeable": "false",
      "customer_email": "[email protected]",
      "language_code": "it",
      "currency_code": "EUR",
      "tax_included": "true",
      "tax_rate": "0.22",
      "freight_taxable": "true",
      "country_code": "IT",
      "shipping_country_code_lock": "IT",
      "coupon_code": "SUMMERDISCOUNT",
      "subtotal_amount_cents": "5000",
      "subtotal_amount_float": "50.0",
      "formatted_subtotal_amount": "€50,00",
      "shipping_amount_cents": "1200",
      "shipping_amount_float": "12.0",
      "formatted_shipping_amount": "€12,00",
      "payment_method_amount_cents": "0",
      "payment_method_amount_float": "0.0",
      "formatted_payment_method_amount": "€0,00",
      "discount_amount_cents": "-500",
      "discount_amount_float": "-5.0",
      "formatted_discount_amount": "-€5,00",
      "total_tax_amount_cents": "1028",
      "total_tax_amount_float": "10.28",
      "formatted_total_tax_amount": "€10,28",
      "subtotal_tax_amount_cents": "902",
      "subtotal_tax_amount_float": "9.02",
      "formatted_subtotal_tax_amount": "€9,02",
      "shipping_tax_amount_cents": "216",
      "shipping_tax_amount_float": "2.16",
      "formatted_shipping_tax_amount": "€2,16",
      "payment_method_tax_amount_cents": "0",
      "payment_method_tax_amount_float": "0.0",
      "formatted_payment_method_tax_amount": "€0,00",
      "discount_tax_amount_cents": "-90",
      "discount_tax_amount_float": "-0.9",
      "formatted_discount_tax_amount": "-€0,90",
      "total_amount_cents": "5700",
      "total_amount_float": "57.0",
      "formatted_total_amount": "€57,00",
      "total_taxable_amount_cents": "4672",
      "total_taxable_amount_float": "46.72",
      "formatted_total_taxable_amount": "€46,72",
      "subtotal_taxable_amount_cents": "4098",
      "subtotal_taxable_amount_float": "40.98",
      "formatted_subtotal_taxable_amount": "€40,98",
      "shipping_taxable_amount_cents": "984",
      "shipping_taxable_amount_float": "9.84",
      "formatted_shipping_taxable_amount": "€9,84",
      "payment_method_taxable_amount_cents": "0",
      "payment_method_taxable_amount_float": "0.0",
      "formatted_payment_method_taxable_amount": "€0,00",
      "discount_taxable_amount_cents": "-410",
      "discount_taxable_amount_float": "-4.10",
      "formatted_discount_taxable_amount": "-€4,10",
      "total_amount_with_taxes_cents": "5700",
      "total_amount_with_taxes_float": "57.00",
      "formatted_total_amount_with_taxes": "€57,00",
      "fees_amount_cents": "0",
      "fees_amount_float": "0.0",
      "formatted_fees_amount": "€0,00",
      "skus_count": "2",
      "payment_source_details": null,
      "token": "1c0994cc4e996e8c6ee56a2198f66f3c",
      "cart_url": "https://yourbrand.com/cart",
      "return_url": "https://yourbrand.com/",
      "terms_url": "https://yourbrand.com/terms",
      "privacy_url": "https://yourbrand.com/privacy",
      "checkout_url": "https://commerce.yourbrand.com/checkout/1c0994cc4e996e8c6ee56a2198f66f3c",
      "placed_at": "2018-01-01T12:00:00.000Z",
      "approved_at": "2018-01-01T12:00:00.000Z",
      "cancelled_at": "2018-01-01T12:00:00.000Z",
      "payment_updated_at": "2018-01-01T12:00:00.000Z",
      "fulfillment_updated_at": "2018-01-01T12:00:00.000Z",
      "id": "1234",
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": "ANYREFEFERNCE",
      "metadata": {
        "foo": "bar"
      }
    },
    "relationships": {
      "market": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/orders/1234/relationships/market",
          "related": "https://your-brand.commercelayer.io/api/orders/1234/market"
        }
      },
      "customer": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/orders/1234/relationships/customer",
          "related": "https://your-brand.commercelayer.io/api/orders/1234/customer"
        }
      },
      "shipping_address": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/orders/1234/relationships/shipping_address",
          "related": "https://your-brand.commercelayer.io/api/orders/1234/shipping_address"
        }
      },
      "billing_address": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/orders/1234/relationships/billing_address",
          "related": "https://your-brand.commercelayer.io/api/orders/1234/billing_address"
        }
      },
      "payment_method": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/orders/1234/relationships/payment_method",
          "related": "https://your-brand.commercelayer.io/api/orders/1234/payment_method"
        }
      },
      "payment_source": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/orders/1234/relationships/payment_source",
          "related": "https://your-brand.commercelayer.io/api/orders/1234/payment_source"
        }
      },
      "line_items": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/orders/1234/relationships/line_items",
          "related": "https://your-brand.commercelayer.io/api/orders/1234/line_items"
        }
      },
      "shipments": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/orders/1234/relationships/shipments",
          "related": "https://your-brand.commercelayer.io/api/orders/1234/shipments"
        }
      }
    },
    "meta": {
      "mode": "test"
    }
  }
}

Update an order

To update an existing order, send a PATCH request to the /api/orders/{{id}} endpoint, where {{id}} is the id of the resource that you want to update. The following table contains the list of all the possible arguments that you can pass with the request body, along with their type, description and examples values. Please note that all arguments are optional.
Arguments:
guest
optional
Indicates if the order has been placed as guest.
Example:
true
customer_email
optional
The email address of the associated customer. When creating or updating an order, this is a shortcut to find or create the associated customer by email.
customer_password
optional
The password of the associated customer. When creating or updating an order, this is a shortcut to sign up the associated customer.
Example:
secret
language_code
optional
The preferred language code (ISO 639-1) to be used when communicating with the customer. This can be useful when sending the order to 3rd party marketing tools and CRMs. If the language is supported, the hosted checkout will be localized accordingly.
Example:
it
shipping_country_code_lock
optional
The country code that you want the shipping address to be locked to. This can be useful to make sure the shipping address belongs to a given shipping country, e.g. the one selected in a country selector page.
Example:
IT
coupon_code
optional
The coupon code to be used for the order. If valid, it triggers a promotion adding a discount line item to the order.
Example:
SUMMERDISCOUNT
cart_url
optional
The cart url on your site. If present, it will be used on our hosted checkout application.
Example:
https://yourbrand.com/cart
return_url
optional
The return url on your site. If present, it will be used on our hosted checkout application.
Example:
https://yourbrand.com/
terms_url
optional
The terms and conditions url on your site. If present, it will be used on our hosted checkout application.
Example:
https://yourbrand.com/terms
privacy_url
optional
The privacy polivy url on your site. If present, it will be used on our hosted checkout application.
Example:
https://yourbrand.com/privacy
_place
optional
Send this attribute if you want to place the order.
Example:
1
_cancel
optional
Send this attribute if you want to cancel a placed order. The order's authorization will be automatically voided.
Example:
1
_approve
optional
Send this attribute if you want to approve a placed order.
Example:
1
_update_taxes
optional
Send this attribute if you want to calculate taxes for this order (a tax calculator must be associated to the order's market).
Example:
1
_billing_address_clone_id
optional
The id of the address that you want to clone to create the order's billing address.
Example:
1234
_shipping_address_clone_id
optional
The id of the address that you want to clone to create the order's shipping address.
Example:
1234
_customer_payment_source_id
optional
The id of the customer payment source (i.e. credit card) that you want to use as the order's payment source.
Example:
1234
_shipping_address_same_as_billing
optional
Send this attribute if you want the shipping address to be cloned from the order's billing address.
Example:
1
_billing_address_same_as_shipping
optional
Send this attribute if you want the billing address to be cloned from the order's shipping address.
Example:
1
_save_payment_source_to_customer_wallet
optional
Send this attribute if you want the order's payment source to be saved in the customer's wallet as a customer payment source.
Example:
1
_save_shipping_address_to_customer_address_book
optional
Send this attribute if you want the order's shipping address to saved in the customer's address book as a customer address.
Example:
1
_save_billing_address_to_customer_address_book
optional
Send this attribute if you want the order's billing address to saved in the customer's address book as a customer address.
Example:
1
_refresh
optional
Send this attribute if you want to refresh an order.
Example:
1
reference
optional
A string that you can use to add your own identifier to the resource. This can be useful for intergrating the resource to an external system, like an ERP, a marketing tool or a CRM.
Example:
ANYREFEFERNCE
metadata
optional
Set of key-value pairs that you can attach to the resource. This can be useful for storing additional information about the resource in a structured format.
Example:
#
optional
The associated market.
optional
The associated customer.
optional
The customer's shipping address.
optional
The customer's billing address.
optional
The associated payment method.
payment_source
optional
The associated payment source (credit card or paypal payment).
Example request:
PATCH /api/orders/1234 HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": {
    "type": "orders",
    "id": 1234,
    "attributes": {
      "guest": "true"
    },
    "relationships": {
    }
  }
}
Example response: 200 OK
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": {
    "id": "1234",
    "type": "orders",
    "links": {
      "self": "https://your-brand.commercelayer.io/api/orders/1234"
    },
    "attributes": {
      "status": "draft",
      "payment_status": "unpaid",
      "fulfillment_status": "unfulfilled",
      "guest": "true",
      "editable": "true",
      "placeable": "false",
      "customer_email": "[email protected]",
      "language_code": "it",
      "currency_code": "EUR",
      "tax_included": "true",
      "tax_rate": "0.22",
      "freight_taxable": "true",
      "country_code": "IT",
      "shipping_country_code_lock": "IT",
      "coupon_code": "SUMMERDISCOUNT",
      "subtotal_amount_cents": "5000",
      "subtotal_amount_float": "50.0",
      "formatted_subtotal_amount": "€50,00",
      "shipping_amount_cents": "1200",
      "shipping_amount_float": "12.0",
      "formatted_shipping_amount": "€12,00",
      "payment_method_amount_cents": "0",
      "payment_method_amount_float": "0.0",
      "formatted_payment_method_amount": "€0,00",
      "discount_amount_cents": "-500",
      "discount_amount_float": "-5.0",
      "formatted_discount_amount": "-€5,00",
      "total_tax_amount_cents": "1028",
      "total_tax_amount_float": "10.28",
      "formatted_total_tax_amount": "€10,28",
      "subtotal_tax_amount_cents": "902",
      "subtotal_tax_amount_float": "9.02",
      "formatted_subtotal_tax_amount": "€9,02",
      "shipping_tax_amount_cents": "216",
      "shipping_tax_amount_float": "2.16",
      "formatted_shipping_tax_amount": "€2,16",
      "payment_method_tax_amount_cents": "0",
      "payment_method_tax_amount_float": "0.0",
      "formatted_payment_method_tax_amount": "€0,00",
      "discount_tax_amount_cents": "-90",
      "discount_tax_amount_float": "-0.9",
      "formatted_discount_tax_amount": "-€0,90",
      "total_amount_cents": "5700",
      "total_amount_float": "57.0",
      "formatted_total_amount": "€57,00",
      "total_taxable_amount_cents": "4672",
      "total_taxable_amount_float": "46.72",
      "formatted_total_taxable_amount": "€46,72",
      "subtotal_taxable_amount_cents": "4098",
      "subtotal_taxable_amount_float": "40.98",
      "formatted_subtotal_taxable_amount": "€40,98",
      "shipping_taxable_amount_cents": "984",
      "shipping_taxable_amount_float": "9.84",
      "formatted_shipping_taxable_amount": "€9,84",
      "payment_method_taxable_amount_cents": "0",
      "payment_method_taxable_amount_float": "0.0",
      "formatted_payment_method_taxable_amount": "€0,00",
      "discount_taxable_amount_cents": "-410",
      "discount_taxable_amount_float": "-4.10",
      "formatted_discount_taxable_amount": "-€4,10",
      "total_amount_with_taxes_cents": "5700",
      "total_amount_with_taxes_float": "57.00",
      "formatted_total_amount_with_taxes": "€57,00",
      "fees_amount_cents": "0",
      "fees_amount_float": "0.0",
      "formatted_fees_amount": "€0,00",
      "skus_count": "2",
      "payment_source_details": null,
      "token": "1c0994cc4e996e8c6ee56a2198f66f3c",
      "cart_url": "https://yourbrand.com/cart",
      "return_url": "https://yourbrand.com/",
      "terms_url": "https://yourbrand.com/terms",
      "privacy_url": "https://yourbrand.com/privacy",
      "checkout_url": "https://commerce.yourbrand.com/checkout/1c0994cc4e996e8c6ee56a2198f66f3c",
      "placed_at": "2018-01-01T12:00:00.000Z",
      "approved_at": "2018-01-01T12:00:00.000Z",
      "cancelled_at": "2018-01-01T12:00:00.000Z",
      "payment_updated_at": "2018-01-01T12:00:00.000Z",
      "fulfillment_updated_at": "2018-01-01T12:00:00.000Z",
      "id": "1234",
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": "ANYREFEFERNCE",
      "metadata": {
        "foo": "bar"
      }
    },
    "relationships": {
      "market": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/orders/1234/relationships/market",
          "related": "https://your-brand.commercelayer.io/api/orders/1234/market"
        }
      },
      "customer": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/orders/1234/relationships/customer",
          "related": "https://your-brand.commercelayer.io/api/orders/1234/customer"
        }
      },
      "shipping_address": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/orders/1234/relationships/shipping_address",
          "related": "https://your-brand.commercelayer.io/api/orders/1234/shipping_address"
        }
      },
      "billing_address": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/orders/1234/relationships/billing_address",
          "related": "https://your-brand.commercelayer.io/api/orders/1234/billing_address"
        }
      },
      "payment_method": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/orders/1234/relationships/payment_method",
          "related": "https://your-brand.commercelayer.io/api/orders/1234/payment_method"
        }
      },
      "payment_source": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/orders/1234/relationships/payment_source",
          "related": "https://your-brand.commercelayer.io/api/orders/1234/payment_source"
        }
      },
      "line_items": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/orders/1234/relationships/line_items",
          "related": "https://your-brand.commercelayer.io/api/orders/1234/line_items"
        }
      },
      "shipments": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/orders/1234/relationships/shipments",
          "related": "https://your-brand.commercelayer.io/api/orders/1234/shipments"
        }
      }
    },
    "meta": {
      "mode": "test"
    }
  }
}

Delete an order

To delete a order, send a DELETE request to the /api/orders/{{id}} endpoint, where {{id}} is the id of the resource that you want to delete.
Example request:
DELETE /api/orders/1234 HTTP/1.1
Accept: application/vnd.api+json
Example response: 204 No Content
HTTP/1.1 204 No Content

Get our machine-readable JSON schema that follows the OpenAPI Specification (formerly Swagger).

Get our Postman collection in one click and start making real calls to Commerce Layer API in minutes.

Get in touch with our support team if you have any questions or want to learn more about Commerce Layer.