Backend API: Retrieve orders

Last updated:
Edit on GitHub

The orders resource of the Backend API lets Back Office integrations read placed sales orders—everything an operator sees on the order screens, without driving the UI. This document describes how to retrieve a paginated order collection and a single order with its line items.

Installation

The endpoints are provided by the OrderExperienceManagement module, which projects existing order data from the Sales module rather than reimplementing it. For details on installing it, see Install the Orders Backend API feature.

Retrieve orders

To retrieve a paginated collection of orders, send the request:

GET /orders

Request

HEADER KEY HEADER VALUE REQUIRED DESCRIPTION
Authorization string ✓ Alphanumeric string that authorizes the Back Office user to send requests to protected resources. Get it by authenticating as a Back Office user.
QUERY PARAMETER DESCRIPTION EXEMPLARY VALUES
page[limit] Number of orders per page. Default: 25, maximum: 100. A higher value is reduced to the maximum. page[limit]=50
page[offset] Number of orders to skip. Default: 0. page[offset]=50
sort Sorts the collection by a field. Prefix the field with - for descending order. The only supported field is createdAt; an unrecognized field is ignored rather than causing an error. sort=createdAt
sort=-createdAt
filter[orders.orderReference] Returns the orders with the specified reference. Comma-separate to look up several orders in one call. filter[orders.orderReference]=DE--1234
filter[orders.orderReference]=DE--1234,DE--1235
filter[orders.customerReference] Returns every order belonging to the specified customer. Comma-separate for several customers. filter[orders.customerReference]=DE--6
filter[orders.storeName] Returns only orders placed in the specified store. filter[orders.storeName]=DE
filter[orders.itemState] Returns orders with at least one item in the specified OMS state. Comma-separate to match any of several states. Items advance independently, so an order reports the set of states in itemStates rather than one state of its own. An unknown state name matches nothing. filter[orders.itemState]=shipped
filter[orders.itemState]=shipped,delivered
filter[orders.createdAtFrom] Returns orders created at or after this timestamp (inclusive). filter[orders.createdAtFrom]=2026-01-01 00:00:00
filter[orders.createdAtTo] Returns orders created at or before this timestamp (inclusive). filter[orders.createdAtTo]=2026-12-31 23:59:59

All filters are optional and AND-combined.

Filtering follows the JSON:API filter[orders.<property>] form. A key inside filter[] that doesn’t follow that form, or that names a property other than the ones listed above, is rejected with a 400. A bare query parameter outside filter[]—for example, ?orderReference=DE--1234—is not a filter at all: it’s ignored, and the request returns the unfiltered collection.

REQUEST USAGE
GET https://glue-backend.mysprykershop.com/orders Retrieve the first page of the order collection.
GET https://glue-backend.mysprykershop.com/orders?page[limit]=10&page[offset]=10 Retrieve the second page of the collection with 10 orders per page.
GET https://glue-backend.mysprykershop.com/orders?sort=-createdAt Retrieve orders sorted by creation date, newest first.
GET https://glue-backend.mysprykershop.com/orders?filter[orders.customerReference]=DE--6 Retrieve every order belonging to customer DE--6.
GET https://glue-backend.mysprykershop.com/orders?filter[orders.itemState]=shipped,delivered Retrieve orders that have at least one item in the shipped or delivered state.
GET https://glue-backend.mysprykershop.com/orders?filter[orders.createdAtFrom]=2026-01-01 00:00:00&filter[orders.createdAtTo]=2026-01-31 23:59:59 Retrieve orders placed in January 2026.

Response

The pagination summary is returned in the top-level meta.pagination object, and the pagination links in the top-level links object.

The collection response omits items and comments—items would add many lines per order, and comments cost a query each. Both are present on retrieving a single order. Use itemsCount to see how many lines an order has without reading them.

Response sample: retrieve orders 
{
    "links": {
        "self": "https://glue-backend.mysprykershop.com/orders?page[limit]=1&page[offset]=0",
        "first": "https://glue-backend.mysprykershop.com/orders?page[limit]=1&page[offset]=0",
        "last": "https://glue-backend.mysprykershop.com/orders?page[limit]=1&page[offset]=41",
        "next": "https://glue-backend.mysprykershop.com/orders?page[limit]=1&page[offset]=1"
    },
    "meta": {
        "pagination": {
            "numFound": 42,
            "currentPage": 1,
            "maxPage": 42,
            "currentItemsPerPage": 1
        }
    },
    "data": [
        {
            "id": "DE--1234",
            "type": "orders",
            "attributes": {
                "orderReference": "DE--1234",
                "customerReference": "DE--6",
                "store": "DE",
                "currency": "EUR",
                "createdAt": "2026-08-27 11:04:52",
                "priceMode": "GROSS_MODE",
                "itemsCount": 3,
                "itemStates": ["paid", "shipped"],
                "availableEvents": ["ship", "cancel"],
                "customer": {
                    "email": "[email protected]",
                    "salutation": "Ms",
                    "firstName": "Ada",
                    "lastName": "Lovelace"
                },
                "totals": {
                    "subtotal": 43322,
                    "expenseTotal": 490,
                    "discountTotal": 0,
                    "taxTotal": 4980,
                    "taxBreakdown": [],
                    "grandTotal": 31192,
                    "canceledTotal": 0,
                    "refundableTotal": 31192,
                    "remunerationTotal": 0
                },
                "expenses": [
                    {
                        "type": "SHIPMENT_EXPENSE_TYPE",
                        "name": "Standard",
                        "sumPrice": 490,
                        "taxRate": 19,
                        "sumTaxAmount": 78,
                        "sumDiscountAmountAggregation": 0,
                        "sumPriceToPayAggregation": 490,
                        "canceledAmount": 0
                    }
                ],
                "calculatedDiscounts": [],
                "payments": [
                    {
                        "paymentProvider": "DummyPayment",
                        "paymentMethod": "dummyPaymentInvoice",
                        "amount": 31192,
                        "meta": {}
                    }
                ]
            },
            "links": {
                "self": "https://glue-backend.mysprykershop.com/orders/DE--1234"
            }
        }
    ]
}
ATTRIBUTE TYPE DESCRIPTION
orderReference String Sales order reference. Identifies the order everywhere—for example, GET /orders/{orderReference}—and is also the resource id.
customerReference String Reference of the customer the order belongs to.
store String Store the order was placed in.
currency String ISO 4217 currency code.
createdAt String ISO 8601 creation timestamp.
orderCustomReference String The caller’s own reference for the order, if one was supplied at creation—for example, a purchase-order number. Shown in the Back Office.
companyBusinessUnitUuid String Business unit the order was placed for, if any.
companyUuid String Company the order was placed for. Derived from companyBusinessUnitUuid at placement; absent for an order placed by a customer with no company user.
priceMode String Whether the order’s unit prices are gross or net: GROSS_MODE or NET_MODE.
locale String Locale the order was placed in—for example, de_DE.
itemsCount Integer Number of line items on the order (line count, not ordered units). Always present, even when items itself is omitted.
itemStates Array Distinct OMS state names currently held by the order’s items. An order has no state of its own—its items advance independently.
availableEvents Array OMS events an operator can currently trigger on the order—the union over its line items. items[].availableEvents says which lines each one applies to. Empty when every item is in a terminal state.
customer Object Read-only snapshot of the buyer, taken when the order was placed—not a live customer lookup.
customer.email String Email recorded on the order.
customer.salutation String Salutation recorded on the order: Mr, Mrs, Dr, Ms, or n/a.
customer.firstName String First name recorded on the order.
customer.lastName String Last name recorded on the order.
totals Object Order totals, in cents, using the same keys as the Storefront orders API.
totals.subtotal Integer Sum of item prices before discounts, expenses, or tax, in cents.
totals.expenseTotal Integer Total expenses (shipment, order-threshold surcharges), in cents. See expenses for the breakdown.
totals.discountTotal Integer Total discount applied across the order, in cents. See calculatedDiscounts for the breakdown.
totals.taxTotal Integer Total tax across the order, in cents. See totals.taxBreakdown for the per-rate detail.
totals.taxBreakdown Array taxTotal split by rate, since an order can mix rates. Empty on the response to POST /orders; present once the order is read back.
totals.taxBreakdown.taxRate Number The rate, in percent.
totals.taxBreakdown.taxAmount Integer Tax charged at this rate across the whole order, in cents.
totals.grandTotal Integer subtotal - discountTotal + expenseTotal + tax. What the order was placed at, in cents.
totals.canceledTotal Integer Value of the order’s canceled items, in cents.
totals.refundableTotal Integer Amount still refundable on the order, in cents—not what has already been refunded. Starts at the grand total and falls as parts of the order are canceled.
totals.remunerationTotal Integer Amount settled by remuneration rather than payment, in cents.
expenses Array Shipment and surcharge lines that make up totals.expenseTotal.
expenses.type String Expense type—for example, SHIPMENT_EXPENSE_TYPE.
expenses.name String Display name—for example, the shipment method name.
expenses.sumPrice Integer Expense price in cents before discounts.
expenses.taxRate Number Tax rate applied to the expense, in percent.
expenses.sumTaxAmount Integer Tax charged on the expense, in cents.
expenses.sumDiscountAmountAggregation Integer Discount applied to the expense, in cents—a free-delivery rule shows here.
expenses.sumPriceToPayAggregation Integer What the expense actually costs after discounts, in cents.
expenses.canceledAmount Integer Canceled portion of the expense, in cents.
calculatedDiscounts Array Rules and vouchers applied to the order, one entry per discount with its total across the order. Per-line amounts are on items[].calculatedDiscounts.
calculatedDiscounts.displayName String Name of the discount as configured. Entries sharing a display name are grouped into one.
calculatedDiscounts.description String Description of the discount as configured.
calculatedDiscounts.voucherCode String The voucher code that triggered the discount. null for a cart rule. On a grouped entry, reflects only one of the merged discounts.
calculatedDiscounts.quantity Integer Ordered units the discount applied to, totaled across every line it applied to.
calculatedDiscounts.sumAmount Integer Discount total across the order, in cents, including any part applied to shipping or product options.
payments Array How the order was actually charged, one row per payment method used.
payments.paymentProvider String Payment provider key—for example, DummyPayment or GiftCard.
payments.paymentMethod String Payment method key—for example, dummyPaymentInvoice or GiftCard.
payments.amount Integer Amount charged to this payment method, in cents.
payments.meta Object Free-form, method-specific data for this payment—for example, giftCard carrying the redeemed code and its value. Only properties actually populated for this payment appear.
comments Array Back Office comments on the order, oldest first—the same thread retrieved and appended to via the order-comments resource. Included only on the single-order response; omitted from the order collection response.

Retrieve an order

To retrieve a single order with its line items, send the request:

GET /orders/{{orderReference}}

PATH PARAMETER DESCRIPTION
{{orderReference}} Reference of the order to retrieve. To get it, retrieve orders.

Request

HEADER KEY HEADER VALUE REQUIRED DESCRIPTION
Authorization string ✓ Alphanumeric string that authorizes the Back Office user to send requests to protected resources. Get it by authenticating as a Back Office user.

Request sample: retrieve an order

GET https://glue-backend.mysprykershop.com/orders/DE--1234

Response

The single-order response includes items and comments, which the collection response omits.

Response sample: retrieve an order 
{
    "data": {
        "id": "DE--1234",
        "type": "orders",
        "attributes": {
            "orderReference": "DE--1234",
            "customerReference": "DE--6",
            "store": "DE",
            "currency": "EUR",
            "createdAt": "2026-08-27 11:04:52",
            "priceMode": "GROSS_MODE",
            "itemsCount": 1,
            "itemStates": ["shipped"],
            "availableEvents": ["cancel"],
            "customer": {
                "email": "[email protected]",
                "salutation": "Ms",
                "firstName": "Ada",
                "lastName": "Lovelace"
            },
            "totals": {
                "subtotal": 34500,
                "expenseTotal": 490,
                "discountTotal": 0,
                "taxTotal": 4658,
                "taxBreakdown": [
                    {
                        "taxRate": 19,
                        "taxAmount": 4658
                    }
                ],
                "grandTotal": 29176,
                "canceledTotal": 0,
                "refundableTotal": 29176,
                "remunerationTotal": 0
            },
            "expenses": [
                {
                    "type": "SHIPMENT_EXPENSE_TYPE",
                    "name": "Standard",
                    "sumPrice": 490,
                    "taxRate": 19,
                    "sumTaxAmount": 78,
                    "sumDiscountAmountAggregation": 0,
                    "sumPriceToPayAggregation": 490,
                    "canceledAmount": 0
                }
            ],
            "calculatedDiscounts": [],
            "payments": [
                {
                    "paymentProvider": "DummyPayment",
                    "paymentMethod": "dummyPaymentInvoice",
                    "amount": 29176,
                    "meta": {}
                }
            ],
            "items": [
                {
                    "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
                    "sku": "001_25904006",
                    "name": "Canon PowerShot SC620",
                    "quantity": 1,
                    "unitPrice": 34500,
                    "sumPrice": 34500,
                    "taxRate": 19,
                    "sumTaxAmount": 4658,
                    "refundableAmount": 29176,
                    "canceledAmount": 0,
                    "calculatedDiscounts": [],
                    "sumSubtotalAggregation": 34500,
                    "sumDiscountAmountFullAggregation": 0,
                    "sumPriceToPayAggregation": 29176,
                    "state": "shipped",
                    "availableEvents": ["cancel"]
                }
            ],
            "comments": [
                {
                    "message": "Customer asked to hold the shipment until Friday.",
                    "username": "Admin Spryker",
                    "createdAt": "2026-08-27 15:12:03.000000",
                    "updatedAt": "2026-08-27 15:12:03.000000"
                }
            ]
        },
        "links": {
            "self": "https://glue-backend.mysprykershop.com/orders/DE--1234"
        }
    }
}
ATTRIBUTE TYPE DESCRIPTION
orderReference String Sales order reference. Identifies the order everywhere—for example, GET /orders/{orderReference}—and is also the resource id.
customerReference String Reference of the customer the order belongs to.
store String Store the order was placed in.
currency String ISO 4217 currency code.
createdAt String ISO 8601 creation timestamp.
orderCustomReference String The caller’s own reference for the order, if one was supplied at creation—for example, a purchase-order number. Shown in the Back Office.
companyBusinessUnitUuid String Business unit the order was placed for, if any.
companyUuid String Company the order was placed for. Derived from companyBusinessUnitUuid at placement; absent for an order placed by a customer with no company user.
priceMode String Whether the order’s unit prices are gross or net: GROSS_MODE or NET_MODE.
locale String Locale the order was placed in—for example, de_DE.
itemsCount Integer Number of line items on the order (line count, not ordered units). Always present, even when items itself is omitted.
itemStates Array Distinct OMS state names currently held by the order’s items. An order has no state of its own—its items advance independently.
availableEvents Array OMS events an operator can currently trigger on the order—the union over its line items. items[].availableEvents says which lines each one applies to. Empty when every item is in a terminal state.
customer Object Read-only snapshot of the buyer, taken when the order was placed—not a live customer lookup.
customer.email String Email recorded on the order.
customer.salutation String Salutation recorded on the order: Mr, Mrs, Dr, Ms, or n/a.
customer.firstName String First name recorded on the order.
customer.lastName String Last name recorded on the order.
totals Object Order totals, in cents, using the same keys as the Storefront orders API.
totals.subtotal Integer Sum of item prices before discounts, expenses, or tax, in cents.
totals.expenseTotal Integer Total expenses (shipment, order-threshold surcharges), in cents. See expenses for the breakdown.
totals.discountTotal Integer Total discount applied across the order, in cents. See calculatedDiscounts for the breakdown.
totals.taxTotal Integer Total tax across the order, in cents. See totals.taxBreakdown for the per-rate detail.
totals.taxBreakdown Array taxTotal split by rate, since an order can mix rates. Empty on the response to POST /orders; present once the order is read back.
totals.taxBreakdown.taxRate Number The rate, in percent.
totals.taxBreakdown.taxAmount Integer Tax charged at this rate across the whole order, in cents.
totals.grandTotal Integer subtotal - discountTotal + expenseTotal + tax. What the order was placed at, in cents.
totals.canceledTotal Integer Value of the order’s canceled items, in cents.
totals.refundableTotal Integer Amount still refundable on the order, in cents—not what has already been refunded. Starts at the grand total and falls as parts of the order are canceled.
totals.remunerationTotal Integer Amount settled by remuneration rather than payment, in cents.
expenses Array Shipment and surcharge lines that make up totals.expenseTotal.
expenses.type String Expense type—for example, SHIPMENT_EXPENSE_TYPE.
expenses.name String Display name—for example, the shipment method name.
expenses.sumPrice Integer Expense price in cents before discounts.
expenses.taxRate Number Tax rate applied to the expense, in percent.
expenses.sumTaxAmount Integer Tax charged on the expense, in cents.
expenses.sumDiscountAmountAggregation Integer Discount applied to the expense, in cents—a free-delivery rule shows here.
expenses.sumPriceToPayAggregation Integer What the expense actually costs after discounts, in cents.
expenses.canceledAmount Integer Canceled portion of the expense, in cents.
calculatedDiscounts Array Rules and vouchers applied to the order, one entry per discount with its total across the order. Per-line amounts are on items[].calculatedDiscounts.
calculatedDiscounts.displayName String Name of the discount as configured. Entries sharing a display name are grouped into one.
calculatedDiscounts.description String Description of the discount as configured.
calculatedDiscounts.voucherCode String The voucher code that triggered the discount. null for a cart rule. On a grouped entry, reflects only one of the merged discounts.
calculatedDiscounts.quantity Integer Ordered units the discount applied to, totaled across every line it applied to.
calculatedDiscounts.sumAmount Integer Discount total across the order, in cents, including any part applied to shipping or product options.
payments Array How the order was actually charged, one row per payment method used.
payments.paymentProvider String Payment provider key—for example, DummyPayment or GiftCard.
payments.paymentMethod String Payment method key—for example, dummyPaymentInvoice or GiftCard.
payments.amount Integer Amount charged to this payment method, in cents.
payments.meta Object Free-form, method-specific data for this payment—for example, giftCard carrying the redeemed code and its value. Only properties actually populated for this payment appear.
comments Array Back Office comments on the order, oldest first—the same thread retrieved and appended to via the order-comments resource. Included only on the single-order response; omitted from the order collection response.
ATTRIBUTE TYPE DESCRIPTION
items.uuid String Public identifier of the line item, and the value every other endpoint addresses a line by—for example, itemUuids on firing an OMS event. The internal ID is never exposed.
items.sku String Concrete product SKU.
items.name String Product name, snapshotted onto the line at order time.
items.quantity Integer Ordered quantity, in the product’s base measurement unit.
items.salesUnit Object The measurement unit the line is ordered in—for example, “2 metres” rather than “200 base units”. Absent for a product sold in base units.
items.salesUnit.code String Measurement unit code—for example, METR, KILO.
items.salesUnit.amount Number How many of code are ordered.
items.salesUnit.name String Measurement unit name, snapshotted onto the line at order time.
items.salesUnit.baseUnitName String Name of the base unit quantity is expressed in.
items.salesUnit.conversion Number Base units per one code. quantity = amount * conversion.
items.salesUnit.precision Integer Smallest fraction of code that can be ordered, as a divisor.
items.unitPrice Integer Unit price actually charged, in cents.
items.merchantReference String Merchant fulfilling the line, for a marketplace line.
items.productOfferReference String The specific offer the line was bought from, if the merchant holds several offers for the SKU.
items.cartNote String Free-text note carried on the line.
items.packagingAmount Object For a product sold as a package, how much of the contained product the line’s packages hold. Absent for a product that is not sold as a package.
items.packagingAmount.amount Number Amount per package, not for the whole line—3 boxes of 250 is quantity: 3 with amount: 250.
items.packagingAmount.salesUnitCode String Measurement unit the amount is expressed in—a unit of the contained product, not of the package itself.
items.packagingAmount.salesUnitName String Name of the unit the amount is expressed in.
items.packagingAmount.leadProductSku String SKU of the product contained in the package.
items.productOptions Array Product options selected for the line.
items.productOptions.groupName String Option group name, snapshotted onto the line at order time.
items.productOptions.value String The selected option value, snapshotted at order time.
items.productOptions.unitPrice Integer Option surcharge per unit, in cents.
items.productOptions.sumPrice Integer Option surcharge across all units of the line, in cents. Included in items.sumSubtotalAggregation.
items.productOptions.taxRate Number Tax rate applied to the option, in percent.
items.shipment Object Per-line delivery override. Falls back to the order-level shipment when absent.
items.shipment.shipmentMethod String Shipment method name for the line.
items.shipment.shippingAddress Object Delivery address for the line. Same shape as the order-level shipment.shippingAddress.
items.shipment.requestedDeliveryDate String Requested delivery date for the line.
items.sumPrice Integer Line price in cents before discounts.
items.taxRate Number Tax rate applied to the line, in percent.
items.sumTaxAmount Integer Tax charged on the line, in cents.
items.refundableAmount Integer Amount still refundable on the line, in cents.
items.canceledAmount Integer Canceled portion of the line, in cents.
items.calculatedDiscounts Array Rules and vouchers applied to the line. The order-level calculatedDiscounts reports the same discounts totaled per discount.
items.calculatedDiscounts.displayName String Name of the discount as configured.
items.calculatedDiscounts.voucherCode String The voucher code that triggered the discount. null for a cart rule.
items.calculatedDiscounts.unitAmount Integer Discount per unit, in cents. Rounded for display—use sumAmount for any calculation.
items.calculatedDiscounts.sumAmount Integer Discount for the line, in cents.
items.sumSubtotalAggregation Integer Line subtotal in cents.
items.sumDiscountAmountFullAggregation Integer Discount applied to the line, in cents.
items.sumPriceToPayAggregation Integer What the line actually costs after discounts, in cents.
items.state String Current OMS state of the item.
items.availableEvents Array Events an operator can currently trigger on this line item. This is the per-line detail behind the order-level availableEvents, which reports the union over all lines. Empty when the item sits in a terminal state. Returned only by retrieving a single order—the collection endpoint omits items entirely.

Possible errors

STATUS CODE REASON
404 N/A The order with the specified orderReference doesn’t exist.
401 N/A The Authorization header is missing, or the access token is invalid or expired.
403 N/A The authenticated Back Office user is not allowed to access the orders resource.

To view generic errors and status codes of the Backend API, see Backend API request and response reference.