Commerce API Reference
The Commerce app exposes public HTTP ingresses for cart management and customer order lookup. All endpoints are prefixed with /ingress/commerce/.
TIP
All cart mutation endpoints return the rendered cart on success. Error responses return { error: { code, message } }. The order lookup endpoint returns a customer-facing order representation on success and uses a uniform 404 ORDER_NOT_FOUND response for unknown references and e-mail mismatches.
Create Cart
POST
/ingress/commerce/carts
Creates a new cart with the specified profile and locale. Returns the new cart ID.
Request Body
application/json
JSON "profileKey": "default", "locale": "sv-SE"
{
}
Responses
Cart created successfully.
application/json
JSON "cartId": "string"
{
}
POST
/ingress/commerce/carts
Samples
Get Cart
GET
/ingress/commerce/carts/{cartId}
Returns the fully rendered cart including computed items, totals, shipping, and tax.
Parameters
Path Parameters
cartId*
The cart ID.
Type
Requiredstring
Format
"uuid"Responses
Rendered cart.
application/json
JSON "cartId": "string", "cartNumber": "string", "cartState": "string", "profileKey": "string", "orderId": "string", "orderNumber": "string", "channelKey": "string", "currencyCode": "SEK", "taxIncluded": true, "productTotal": 0, "orderTotal": 0, "orderTaxTotal": 0, "shippingTotal": 0, "locale": "string", "email": "string", "phone": "string", "address": { "name": "string", "careOf": "string", "attention": "string", "addressLine1": "string", "addressLine2": "string", "city": "string", "state": "string", "postalCode": "string", "countryCode": "string" }, "invoiceAddress": { "name": "string", "careOf": "string", "attention": "string", "addressLine1": "string", "addressLine2": "string", "city": "string", "state": "string", "postalCode": "string", "countryCode": "string" }, "coupons": [ "string" ], "fields": { "additionalProperties": "string" }, "items": [ { "cartItemId": "string", "productNumber": "string", "description": "string", "image": "string", "quantity": 0, "unitPrice": 0, "total": 0, "tax": 0, "discount": 0 } ]
{
}
GET
/ingress/commerce/carts/{cartId}
Samples
Cart Events (SSE)
GET
/ingress/commerce/carts/{cartId}/events
Server-Sent Events stream for real-time cart updates. The stream emits the full rendered cart whenever the cart state changes.
Parameters
Path Parameters
cartId*
The cart ID.
Type
Requiredstring
Format
"uuid"Responses
SSE event stream. Each event contains the rendered cart as JSON.
text/event-stream
JSON
"string"
GET
/ingress/commerce/carts/{cartId}/events
Samples
Add Item
POST
/ingress/commerce/carts/{cartId}/add-item
Adds an item to the cart. Validates the item can be added by previewing the cart with the new item before applying.
Parameters
Header Parameters
Idempotency-Key
Optional idempotency key mapped to the item ID. If omitted, a new UUID is generated.
Type
string
Format
"uuid"Path Parameters
cartId*
The cart ID.
Type
Requiredstring
Format
"uuid"Request Body
application/json
JSON "productNumber": "TSHIRT-001", "quantity": 2
{
}
Responses
Item added. Returns the rendered cart.
application/json
JSON "cartId": "string", "cartNumber": "string", "cartState": "string", "profileKey": "string", "orderId": "string", "orderNumber": "string", "channelKey": "string", "currencyCode": "SEK", "taxIncluded": true, "productTotal": 0, "orderTotal": 0, "orderTaxTotal": 0, "shippingTotal": 0, "locale": "string", "email": "string", "phone": "string", "address": { "name": "string", "careOf": "string", "attention": "string", "addressLine1": "string", "addressLine2": "string", "city": "string", "state": "string", "postalCode": "string", "countryCode": "string" }, "invoiceAddress": { "name": "string", "careOf": "string", "attention": "string", "addressLine1": "string", "addressLine2": "string", "city": "string", "state": "string", "postalCode": "string", "countryCode": "string" }, "coupons": [ "string" ], "fields": { "additionalProperties": "string" }, "items": [ { "cartItemId": "string", "productNumber": "string", "description": "string", "image": "string", "quantity": 0, "unitPrice": 0, "total": 0, "tax": 0, "discount": 0 } ]
{
}
POST
/ingress/commerce/carts/{cartId}/add-item
Samples
Remove Item
POST
/ingress/commerce/carts/{cartId}/remove-item
Removes an item from the cart by its cart item ID.
Parameters
Path Parameters
cartId*
Type
Requiredstring
Format
"uuid"Request Body
application/json
JSON "cartItemId": "string"
{
}
Responses
Item removed. Returns the rendered cart.
application/json
JSON "cartId": "string", "cartNumber": "string", "cartState": "string", "profileKey": "string", "orderId": "string", "orderNumber": "string", "channelKey": "string", "currencyCode": "SEK", "taxIncluded": true, "productTotal": 0, "orderTotal": 0, "orderTaxTotal": 0, "shippingTotal": 0, "locale": "string", "email": "string", "phone": "string", "address": { "name": "string", "careOf": "string", "attention": "string", "addressLine1": "string", "addressLine2": "string", "city": "string", "state": "string", "postalCode": "string", "countryCode": "string" }, "invoiceAddress": { "name": "string", "careOf": "string", "attention": "string", "addressLine1": "string", "addressLine2": "string", "city": "string", "state": "string", "postalCode": "string", "countryCode": "string" }, "coupons": [ "string" ], "fields": { "additionalProperties": "string" }, "items": [ { "cartItemId": "string", "productNumber": "string", "description": "string", "image": "string", "quantity": 0, "unitPrice": 0, "total": 0, "tax": 0, "discount": 0 } ]
{
}
POST
/ingress/commerce/carts/{cartId}/remove-item
Samples
Set Item Quantity
POST
/ingress/commerce/carts/{cartId}/set-quantity
Updates the quantity of an existing cart item. Validates the change by previewing the cart before applying.
Parameters
Path Parameters
cartId*
Type
Requiredstring
Format
"uuid"Request Body
application/json
JSON "cartItemId": "string", "quantity": 3
{
}
Responses
Quantity updated. Returns the rendered cart.
application/json
JSON "cartId": "string", "cartNumber": "string", "cartState": "string", "profileKey": "string", "orderId": "string", "orderNumber": "string", "channelKey": "string", "currencyCode": "SEK", "taxIncluded": true, "productTotal": 0, "orderTotal": 0, "orderTaxTotal": 0, "shippingTotal": 0, "locale": "string", "email": "string", "phone": "string", "address": { "name": "string", "careOf": "string", "attention": "string", "addressLine1": "string", "addressLine2": "string", "city": "string", "state": "string", "postalCode": "string", "countryCode": "string" }, "invoiceAddress": { "name": "string", "careOf": "string", "attention": "string", "addressLine1": "string", "addressLine2": "string", "city": "string", "state": "string", "postalCode": "string", "countryCode": "string" }, "coupons": [ "string" ], "fields": { "additionalProperties": "string" }, "items": [ { "cartItemId": "string", "productNumber": "string", "description": "string", "image": "string", "quantity": 0, "unitPrice": 0, "total": 0, "tax": 0, "discount": 0 } ]
{
}
POST
/ingress/commerce/carts/{cartId}/set-quantity
Samples
Set Address
POST
/ingress/commerce/carts/{cartId}/address
Sets the shipping and/or invoice address on the cart. Validates country codes against the cart profile's allowed countries.
Parameters
Path Parameters
cartId*
Type
Requiredstring
Format
"uuid"Request Body
application/json
JSON "address": { "name": "string", "careOf": "string", "attention": "string", "addressLine1": "string", "addressLine2": "string", "city": "string", "state": "string", "postalCode": "string", "countryCode": "string" }, "invoiceAddress": { "name": "string", "careOf": "string", "attention": "string", "addressLine1": "string", "addressLine2": "string", "city": "string", "state": "string", "postalCode": "string", "countryCode": "string" }
{
}
Responses
Address updated. Returns the rendered cart.
application/json
JSON "cartId": "string", "cartNumber": "string", "cartState": "string", "profileKey": "string", "orderId": "string", "orderNumber": "string", "channelKey": "string", "currencyCode": "SEK", "taxIncluded": true, "productTotal": 0, "orderTotal": 0, "orderTaxTotal": 0, "shippingTotal": 0, "locale": "string", "email": "string", "phone": "string", "address": { "name": "string", "careOf": "string", "attention": "string", "addressLine1": "string", "addressLine2": "string", "city": "string", "state": "string", "postalCode": "string", "countryCode": "string" }, "invoiceAddress": { "name": "string", "careOf": "string", "attention": "string", "addressLine1": "string", "addressLine2": "string", "city": "string", "state": "string", "postalCode": "string", "countryCode": "string" }, "coupons": [ "string" ], "fields": { "additionalProperties": "string" }, "items": [ { "cartItemId": "string", "productNumber": "string", "description": "string", "image": "string", "quantity": 0, "unitPrice": 0, "total": 0, "tax": 0, "discount": 0 } ]
{
}
POST
/ingress/commerce/carts/{cartId}/address
Samples
Set Email
POST
/ingress/commerce/carts/{cartId}/email
Sets the email address on the cart. Validates the email format.
Parameters
Path Parameters
cartId*
Type
Requiredstring
Format
"uuid"Request Body
application/json
JSON "email": "customer@example.com"
{
}
Responses
Email updated. Returns the rendered cart.
application/json
JSON "cartId": "string", "cartNumber": "string", "cartState": "string", "profileKey": "string", "orderId": "string", "orderNumber": "string", "channelKey": "string", "currencyCode": "SEK", "taxIncluded": true, "productTotal": 0, "orderTotal": 0, "orderTaxTotal": 0, "shippingTotal": 0, "locale": "string", "email": "string", "phone": "string", "address": { "name": "string", "careOf": "string", "attention": "string", "addressLine1": "string", "addressLine2": "string", "city": "string", "state": "string", "postalCode": "string", "countryCode": "string" }, "invoiceAddress": { "name": "string", "careOf": "string", "attention": "string", "addressLine1": "string", "addressLine2": "string", "city": "string", "state": "string", "postalCode": "string", "countryCode": "string" }, "coupons": [ "string" ], "fields": { "additionalProperties": "string" }, "items": [ { "cartItemId": "string", "productNumber": "string", "description": "string", "image": "string", "quantity": 0, "unitPrice": 0, "total": 0, "tax": 0, "discount": 0 } ]
{
}
POST
/ingress/commerce/carts/{cartId}/email
Samples
Set Phone
POST
/ingress/commerce/carts/{cartId}/phone
Sets the phone number on the cart.
Parameters
Path Parameters
cartId*
Type
Requiredstring
Format
"uuid"Request Body
application/json
JSON "phone": "+46701234567"
{
}
Responses
Phone updated. Returns the rendered cart.
application/json
JSON "cartId": "string", "cartNumber": "string", "cartState": "string", "profileKey": "string", "orderId": "string", "orderNumber": "string", "channelKey": "string", "currencyCode": "SEK", "taxIncluded": true, "productTotal": 0, "orderTotal": 0, "orderTaxTotal": 0, "shippingTotal": 0, "locale": "string", "email": "string", "phone": "string", "address": { "name": "string", "careOf": "string", "attention": "string", "addressLine1": "string", "addressLine2": "string", "city": "string", "state": "string", "postalCode": "string", "countryCode": "string" }, "invoiceAddress": { "name": "string", "careOf": "string", "attention": "string", "addressLine1": "string", "addressLine2": "string", "city": "string", "state": "string", "postalCode": "string", "countryCode": "string" }, "coupons": [ "string" ], "fields": { "additionalProperties": "string" }, "items": [ { "cartItemId": "string", "productNumber": "string", "description": "string", "image": "string", "quantity": 0, "unitPrice": 0, "total": 0, "tax": 0, "discount": 0 } ]
{
}
POST
/ingress/commerce/carts/{cartId}/phone
Samples
Set Custom Field
POST
/ingress/commerce/carts/{cartId}/set-field/{key}
Sets a custom field on the cart. Custom fields are accessible via the fields property in the rendered cart.
Parameters
Path Parameters
cartId*
Type
Requiredstring
Format
"uuid"key*
The field key.
Type
Requiredstring
Example
"giftMessage"Request Body
application/json
JSON "value": "string"
{
}
Responses
Field set. Returns the rendered cart.
application/json
JSON "cartId": "string", "cartNumber": "string", "cartState": "string", "profileKey": "string", "orderId": "string", "orderNumber": "string", "channelKey": "string", "currencyCode": "SEK", "taxIncluded": true, "productTotal": 0, "orderTotal": 0, "orderTaxTotal": 0, "shippingTotal": 0, "locale": "string", "email": "string", "phone": "string", "address": { "name": "string", "careOf": "string", "attention": "string", "addressLine1": "string", "addressLine2": "string", "city": "string", "state": "string", "postalCode": "string", "countryCode": "string" }, "invoiceAddress": { "name": "string", "careOf": "string", "attention": "string", "addressLine1": "string", "addressLine2": "string", "city": "string", "state": "string", "postalCode": "string", "countryCode": "string" }, "coupons": [ "string" ], "fields": { "additionalProperties": "string" }, "items": [ { "cartItemId": "string", "productNumber": "string", "description": "string", "image": "string", "quantity": 0, "unitPrice": 0, "total": 0, "tax": 0, "discount": 0 } ]
{
}
POST
/ingress/commerce/carts/{cartId}/set-field/{key}
Samples
Remove Custom Field
POST
/ingress/commerce/carts/{cartId}/remove-field/{key}
Removes a custom field from the cart.
Parameters
Path Parameters
cartId*
Type
Requiredstring
Format
"uuid"key*
The field key to remove.
Type
Requiredstring
Responses
Field removed. Returns the rendered cart.
application/json
JSON "cartId": "string", "cartNumber": "string", "cartState": "string", "profileKey": "string", "orderId": "string", "orderNumber": "string", "channelKey": "string", "currencyCode": "SEK", "taxIncluded": true, "productTotal": 0, "orderTotal": 0, "orderTaxTotal": 0, "shippingTotal": 0, "locale": "string", "email": "string", "phone": "string", "address": { "name": "string", "careOf": "string", "attention": "string", "addressLine1": "string", "addressLine2": "string", "city": "string", "state": "string", "postalCode": "string", "countryCode": "string" }, "invoiceAddress": { "name": "string", "careOf": "string", "attention": "string", "addressLine1": "string", "addressLine2": "string", "city": "string", "state": "string", "postalCode": "string", "countryCode": "string" }, "coupons": [ "string" ], "fields": { "additionalProperties": "string" }, "items": [ { "cartItemId": "string", "productNumber": "string", "description": "string", "image": "string", "quantity": 0, "unitPrice": 0, "total": 0, "tax": 0, "discount": 0 } ]
{
}
POST
/ingress/commerce/carts/{cartId}/remove-field/{key}
Samples
Add Coupon
POST
/ingress/commerce/carts/{cartId}/add-coupon
Adds a coupon code to the cart.
Parameters
Path Parameters
cartId*
Type
Requiredstring
Format
"uuid"Request Body
application/json
JSON "couponCode": "SUMMER25"
{
}
Responses
Coupon added. Returns the rendered cart.
application/json
JSON "cartId": "string", "cartNumber": "string", "cartState": "string", "profileKey": "string", "orderId": "string", "orderNumber": "string", "channelKey": "string", "currencyCode": "SEK", "taxIncluded": true, "productTotal": 0, "orderTotal": 0, "orderTaxTotal": 0, "shippingTotal": 0, "locale": "string", "email": "string", "phone": "string", "address": { "name": "string", "careOf": "string", "attention": "string", "addressLine1": "string", "addressLine2": "string", "city": "string", "state": "string", "postalCode": "string", "countryCode": "string" }, "invoiceAddress": { "name": "string", "careOf": "string", "attention": "string", "addressLine1": "string", "addressLine2": "string", "city": "string", "state": "string", "postalCode": "string", "countryCode": "string" }, "coupons": [ "string" ], "fields": { "additionalProperties": "string" }, "items": [ { "cartItemId": "string", "productNumber": "string", "description": "string", "image": "string", "quantity": 0, "unitPrice": 0, "total": 0, "tax": 0, "discount": 0 } ]
{
}
POST
/ingress/commerce/carts/{cartId}/add-coupon
Samples
Remove Coupon
POST
/ingress/commerce/carts/{cartId}/remove-coupon
Removes a coupon from the cart.
Parameters
Path Parameters
cartId*
Type
Requiredstring
Format
"uuid"Request Body
application/json
JSON "couponCode": "string"
{
}
Responses
Coupon removed. Returns the rendered cart.
application/json
JSON "cartId": "string", "cartNumber": "string", "cartState": "string", "profileKey": "string", "orderId": "string", "orderNumber": "string", "channelKey": "string", "currencyCode": "SEK", "taxIncluded": true, "productTotal": 0, "orderTotal": 0, "orderTaxTotal": 0, "shippingTotal": 0, "locale": "string", "email": "string", "phone": "string", "address": { "name": "string", "careOf": "string", "attention": "string", "addressLine1": "string", "addressLine2": "string", "city": "string", "state": "string", "postalCode": "string", "countryCode": "string" }, "invoiceAddress": { "name": "string", "careOf": "string", "attention": "string", "addressLine1": "string", "addressLine2": "string", "city": "string", "state": "string", "postalCode": "string", "countryCode": "string" }, "coupons": [ "string" ], "fields": { "additionalProperties": "string" }, "items": [ { "cartItemId": "string", "productNumber": "string", "description": "string", "image": "string", "quantity": 0, "unitPrice": 0, "total": 0, "tax": 0, "discount": 0 } ]
{
}
POST
/ingress/commerce/carts/{cartId}/remove-coupon
Samples
Lookup Order
POST
/ingress/commerce/orders/lookup
Looks up a customer-facing order by a live cart number, order number, or delivery number and a matching e-mail address. E-mail comparison is case-insensitive. A live cart uses its cart e-mail; an order uses its invoice-recipient and delivery-address e-mails. Unknown references, e-mail mismatches, and query failures intentionally return the same ORDER_NOT_FOUND response to prevent reference enumeration. A cart number stops resolving after its cart has been deleted; use an order or delivery number for historical lookup.
Request Body
application/json
JSON "reference": "ORDER-12345", "email": "customer@example.com"
{
}
Responses
Customer-facing order representation. When the originating cart still exists, this is rendered from that cart; otherwise it is rendered from the order and its deliveries.
application/json
JSON "cartId": "string", "cartNumber": "string", "cartState": "string", "profileKey": "string", "orderId": "string", "orderNumber": "string", "channelKey": "string", "currencyCode": "SEK", "taxIncluded": true, "coupons": [ "string" ], "invalidCoupons": [ "string" ], "productTotal": 0, "orderTotal": 0, "orderTaxTotal": 0, "shippingDiscount": 0, "shippingTotal": 0, "shippingTax": 0, "locale": "string", "email": "string", "phone": "string", "address": { "name": "string", "careOf": "string", "attention": "string", "addressLine1": "string", "addressLine2": "string", "city": "string", "state": "string", "postalCode": "string", "countryCode": "string" }, "invoiceRecipient": { "name": "string", "careOf": "string", "attention": "string", "addressLine1": "string", "addressLine2": "string", "city": "string", "state": "string", "postalCode": "string", "countryCode": "string" }, "promotions": [ { "calculatedTotal": 0, "description": "string", "messageRendered": "string", "messageTemplate": "string", "messageType": "string" } ], "payments": [ { "reference": "string", "provider": "string", "amount": 0 } ], "fields": { "additionalProperties": "string" }, "items": [ { "cartItemId": "string", "productNumber": "string", "description": "string", "image": "string", "quantity": 0, "reservedQuantity": 0, "unitPrice": 0, "total": 0, "tax": 0, "discount": 0, "deliveryNumber": "string" } ]
{
}
POST
/ingress/commerce/orders/lookup
Samples
Get Cart Profiles
GET
/ingress/commerce/cart-profiles
Returns the list of configured cart profiles with their settings (currency, allowed countries, etc.).
Responses
List of cart profiles.
application/json
JSON { "key": "string", "currencyCode": "string", "defaultCountryCode": "string", "allowedCountries": [ "string" ] }
[
]
GET
/ingress/commerce/cart-profiles