Cart Service

Download OpenAPI specification:Download

E-mail: documentation@emporix.com

High performance, extensible cart that holds products for a later checkout.

Key Features:

Authenticated user cart
Merging of carts
Single cart across sites or individual cart per site
Persistent for later checkout
Add, remove, modify, and delete cart entries
Support for products with unknown weight at checkout
Calculates prices with high precision of up to 16 digits, which is a range from 1 quadrillion (1,000,000,000,000,000) to 0.000000000000001 (scale of 15)
Multi-currency support with appropriate format (no fractions, ISO standard defined fractions or custom fractions)
Support for promotions, discounts
Support for coupons
Deposit / fee handling
Net / gross price support
High-performance, auto-scaling

Key Benefits:

Ready to use cart implementation
Guaranteed response times, high availability
Support for web, native/reactive mobile, gaming consoles and other IoT devices.

Carts

Manage Carts

Creating a new cart

Creates a new cart. When a cart is created, its status is set to open.

Note: There can be only one open cart per customer. If another cart needs to be created for a specific customer, you need to update the existing cart's status to closed.

Required scopes

cart.cart_manage

Note: This scope is only required for OAuth2 authorization method to authorize the request with the access_token. Use when you want to create a cart for a logged in customer.

SecurityCustomerAccessToken or OAuth2

Request

path Parameters

tenant

required

string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

header Parameters

session-id	string Anonymous customer's unique session identifier. Note: The `session-id` is only required if you want to create a cart for an anonymous customer.
saas-token	string Customer’s `saasToken` generated when the customer token is generated. Note: The `saas-token` is only required if you want to create a cart for a logged in customer.

Request Body schema: application/json

customerId	string <= 200 characters Customer’s unique identifier generated when a customer’s account is created through the Customer Service.
currency required	string = 3 characters [A-Z]{3} Three-letter currency code, compliant with the ISO 4217 standard.
legalEntityId	string Id of the legal entity to which customer is assigned.
deliveryWindowId	string Delivery window's unique identifier, as defined in the Shipping Service.
	object (deliveryWindow)
siteCode	string Default: "default" Site’s unique identifier. A site is a specific shop. If the tenant owns only one shop, the value should be set to `main`.
type	string Cart type. You can use this field if your store offers different types of carts, such as shopping carts and wishlists.
	object (channel) Channel through which the cart was created.
	object (metadataRequest)
mixins	object
sessionValidated	boolean Default: false If set to `true`, endpoints will validate whether the `session-id` used to create the cart matches the `session-id` passed in the request header. Note: The `sessionValidated` parameter only applies to anonymous customers’ carts.

Responses

201

The request was successful. Cart details are returned.

400

The request was syntactically incorrect. Details will be provided in the response payload.

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

409

The request could not be completed due to a conflict with the current state of the target resource.

500

Some server-side error occurred. Details will be provided in the response payload.

post/{tenant}/carts

Request samples

application/json

{"siteCode": "main",
"currency": "EUR",
"type": "shopping",
"channel": {"name": "storefront",
"source": "https://your-storefront.com/"
},
"sessionValidated": true
}

Response samples

application/json

{"cartId": "65141d687308095e25ca0671",
"yrn": "urn:yaas:hybris:cart:cart-item:saastest2;65141d687308095e25ca0671"
}

Retrieving a cart's details by criteria

Retrieves a cart's details based on the store's site code and criteria such as session ID or customer ID.

Required scopes

cart.cart_manage

Note: This scope is only required for OAuth2 authorization method to authorize the request with the access_token.

SecurityCustomerAccessToken or OAuth2

Request

path Parameters

tenant

required

string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

query Parameters

sessionId	string Customer's unique session identifier. Note: The `sessionId` is only required if you want to retrieve an anonymous customer's cart.
customerId	string Customer’s unique identifier generated when a customer’s account is created. Note: The `customerId` is only required if you want to create a cart for a logged in customer.
siteCode required	string Site’s unique identifier. A site is a specific shop. If the tenant owns only one shop, the value should be set to `main`.
legalEntityId	string Id of the legal entity to which customer is assigned. Should not be provided for B2C business model.
create	boolean If set to `true` and no cart exists for the specified criteria, a new cart will be created.
type	string Type of the cart
zipCode	string [ 1 .. 9 ] characters Zip code for cart filtering
countryCode	string = 2 characters Country code for cart filtering

Responses

200

The request was successful. Cart details are returned.

400

The request was syntactically incorrect. Details will be provided in the response payload.

401

Given request is unauthorized - the authorization token is invalid or has expired.

Details will be provided in the response payload.

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

404

The requested resource does not exist.

500

Some server-side error occurred. Details will be provided in the response payload.

get/{tenant}/carts

Request samples

Response samples

application/json

{"id": "612c9ae63cff1d66f699b691",
"yrn": "urn:yaas:hybris:cart:cart:saastest2;612c9ae63cff1d66f699b691",
"customerId": "87413250",
"currency": "EUR",
"siteCode": "main",
"sessionId": "YxXRjn9zSFM7gMq5dtNKarX7xYkIMV",
"metadata": {"createdAt": "2021-08-30T08:46:30.780Z",
"modifiedAt": "2021-08-30T08:46:30.786Z",
"version": 1
},
"leadTime": 0,
"nonDelivery": ["5",
"6"
]
}

Retrieving a cart's details by ID

Retrieves a specified cart's details.

Required scopes

cart.cart_manage

Note: This scope is only required for OAuth2 authorization method to authorize the request with the access_token.

SecurityOAuth2 or CustomerAccessToken

Request

path Parameters

cartId required	string Cart’s unique identifier generated when a cart is created.
tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: The tenant should always be written in lowercase.

query Parameters

expandCalculation	boolean Default: true If set to `true`, a fully calculated cart is returned.
zipCode	string [ 1 .. 9 ] characters Zip code for cart filtering
countryCode	string = 2 characters Country code for cart filtering

Responses

200

The request was successful. Cart details are returned.

400

The request was syntactically incorrect. Details will be provided in the response payload.

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

404

The requested resource does not exist.

500

Some server-side error occurred. Details will be provided in the response payload.

get/{tenant}/carts/{cartId}

Request samples

Response samples

application/json

{"id": "6128cf97330cc7035fa1484c",
"yrn": "urn:yaas:hybris:cart:cart:saastest2;6128cf97330cc7035fa1484c",
"currency": "EUR",
"siteCode": "main",
"items": [{"id": "0",
"itemYrn": "urn:yaas:saasag:caasproduct:product:saastest2;5c3351aea9812100098ffc60",
"quantity": 6,
"effectiveQuantity": 6,
"price": {"priceId": "5f5a3ce5fb29e20020be99c8",
"originalAmount": 4.99,
"effectiveAmount": 4.99,
"currency": "EUR"
}
}
],
"sessionId": "YxXRjn9zSFM7gMq5dtNKarX7xYkIMV",
"metadata": {"createdAt": "2021-08-27T11:42:15.709Z",
"modifiedAt": "2021-08-30T10:32:46.711Z",
"version": 1
},
"leadTime": 0,
"nonDelivery": ["5",
"6"
]
}

Updating a cart

Updates a specified cart's details.

Required scopes

cart.cart_manage

Note: This scope is only required for OAuth2 authorization method to authorize the request with the access_token.

SecurityOAuth2 or CustomerAccessToken

Request

path Parameters

cartId required	string Cart’s unique identifier generated when a cart is created.
tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: The tenant should always be written in lowercase.

Request Body schema: application/json

customerId	string Customer’s unique identifier generated when a customer’s account is created through the Customer Service.
currency	string = 3 characters [A-Z]{3} Three-letter currency code, compliant with the ISO 4217 standard.
legalEntityId	string Id of the legal entity to which customer is assigned.
deliveryWindowId	string Delivery window''s unique identifier, as defined in the Shipping Service.
	object (deliveryWindow)
type	string Cart type. You can use this field if your store offers different types of carts, such as shopping carts and wishlists.
zipCode	string <= 9 characters Customer's address - zip code.
countryCode	string = 2 characters [a-zA-Z]{2} Two-letter country code, compliant with the ISO 3166 standard.
orderId	string Order’s unique identifier generated when a checkout is triggered through the Checkout Service.
status	string Cart status. Enum: "OPEN" "CLOSED"
	object (channel) Channel through which the cart was created.
	object (metadataRequest)
mixins	object

Responses

204

The request was successful. The cart has been updated.

400

The request was syntactically incorrect. Details will be provided in the response payload.

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

404

The requested resource does not exist.

409

The request could not be completed due to a conflict with the current state of the target resource.

500

Some server-side error occurred. Details will be provided in the response payload.

put/{tenant}/carts/{cartId}

Request samples

application/json

{"customerId": "87413250",
"currency": "EUR",
"deliveryWindowId": "60006da77ec20a807cd6f065",
"type": "wishlist",
"zipCode": "10115",
"countryCode": "DE",
"status": "OPEN",
"deliveryWindow": {"id": "5b5572a61cf31a000f31eee4",
"deliveryDate": "2023-06-06T12:00:00.000Z",
"slotId": "5678-8756-3321-1234"
},
"channel": {"name": "storefront",
"source": "https://your-storefront.com/"
},
"metadata": {"mixins": {"generalAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/schemata/orderGeneralAttributesMixIn.v9.json",
"deliveryTime": "https://res.cloudinary.com/saas-ag/raw/upload/schemata/deliveryTimeMixIn.v2.json"
}
},
"mixins": {"deliveryTime": {"deliveryDate": "2021-06-08T12:00:00.000Z",
"deliveryTimeId": "5f5a3da02d48b9000d39798c"
}
}
}

Response samples

application/json

{"code": 400,
"status": "BAD_REQUEST",
"message": "There are validation problems, see details section for more information"
}

Deleting a cart

Deletes a specified cart.

Required scopes

cart.cart_manage

Note: This scope is only required for OAuth2 authorization method to authorize the request with the access_token.

SecurityOAuth2 or CustomerAccessToken

Request

path Parameters

cartId required	string Cart’s unique identifier generated when a cart is created.
tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: The tenant should always be written in lowercase.

Responses

204

The request was successful. The cart has been deleted.

400

The request was syntactically incorrect. Details will be provided in the response payload.

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

404

The requested resource does not exist.

500

Some server-side error occurred. Details will be provided in the response payload.

delete/{tenant}/carts/{cartId}

Request samples

Response samples

application/json

{"code": 400,
"status": "BAD_REQUEST",
"message": "There are validation problems, see details section for more information"
}

Refreshing a cart

Refreshes a specified cart and their items. In case the prices assigned to cart's items have been changed then these changes are recognized and reassigned to the cart.

Required scopes

cart.cart_manage

Note: This scope is only required for OAuth2 authorization method to authorize the request with the access_token.

SecurityOAuth2 or CustomerAccessToken

Request

path Parameters

cartId required	string Cart’s unique identifier generated when a cart is created.
tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: The tenant should always be written in lowercase.

Responses

204

The request was successful. The cart has been refreshed.

400

The request was syntactically incorrect. Details will be provided in the response payload.

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

404

The requested resource does not exist.

409

The request could not be completed due to a conflict with the current state of the target resource.

500

Some server-side error occurred. Details will be provided in the response payload.

put/{tenant}/carts/{cartId}/refresh

Request samples

Response samples

application/json

{"code": 400,
"status": "BAD_REQUEST",
"message": "There are validation problems, see details section for more information"
}

Changing a cart's site

Changes a specified cart's site. The following cart settings are changed according to the new site:

Language
Currency
Shipment
Tax
Payment

In case the new site uses a different currency, the endpoint sends a price match request to the Price Service. This ensures that items in cart display correct prices in the new site's currency.

Required scopes

cart.cart_manage

Note: This scope is only required for OAuth2 authorization method to authorize the request with the access_token.

SecurityOAuth2 or CustomerAccessToken

Request

path Parameters

cartId required	string Cart’s unique identifier generated when a cart is created.
tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: The tenant should always be written in lowercase.

header Parameters

Accept-Language	string List of natural languages acceptable for the response.
Content-Language	string List of acceptable natural languages of the customers.
languages	string You can use the `languages` header to apply the request to carts for which a particular localization attribute (language) has been specified. You can specify multiple languages by separating them with commas.

Request Body schema: application/json

siteCode

required

string

Site’s unique identifier. A site is a specific shop.

Responses

200

All item's currencies are updated.

400

The request was syntactically incorrect. Details will be provided in the response payload.

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

404

The requested resource does not exist.

500

Some server-side error occurred. Details will be provided in the response payload.

post/{tenant}/carts/{cartId}/changeSite

Request samples

application/json

{"siteCode": "USA"
}

Response samples

application/json

{"code": 400,
"status": "BAD_REQUEST",
"message": "There are validation problems, see details section for more information"
}

Changing a cart's currency

Changes a specified cart's currency. The endpoint sends a price match request to the Price Service. This ensures that items in cart display correct prices in the new currency.

Required scopes

cart.cart_manage

Note: This scope is only required for OAuth2 authorization method to authorize the request with the access_token.

SecurityOAuth2 or CustomerAccessToken

Request

path Parameters

cartId required	string Cart’s unique identifier generated when a cart is created.
tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: The tenant should always be written in lowercase.

header Parameters

Accept-Language	string List of natural languages acceptable for the response.
Content-Language	string List of acceptable natural languages of the customers.
languages	string You can use the `languages` header to apply the request to carts for which a particular localization attribute (language) has been specified. You can specify multiple languages by separating them with commas.

Request Body schema: application/json

currency

string

Responses

200

All item's currencies are updated.

400

The request was syntactically incorrect. Details will be provided in the response payload.

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

404

The requested resource does not exist.

500

Some server-side error occurred. Details will be provided in the response payload.

post/{tenant}/carts/{cartId}/changeCurrency

Request samples

application/json

{"currency": "USD"
}

Response samples

application/json

{"code": 400,
"status": "BAD_REQUEST",
"message": "There are validation problems, see details section for more information"
}

Merging carts

Merges a list of anonymous carts with the specified customer cart.

Note: The cart specified in the path parameter must belong to a logged in customer. Carts listed in the request body must belong to anonymous customers.

Required scopes

cart.cart_manage

Note: This scope is only required for OAuth2 authorization method to authorize the request with the access_token.

SecurityOAuth2 or CustomerAccessToken

Request

path Parameters

cartId required	string Cart’s unique identifier generated when a cart is created.
tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: The tenant should always be written in lowercase.

header Parameters

Accept-Language	string List of natural languages acceptable for the response.
Content-Language	string List of acceptable natural languages of the customers.
languages	string You can use the `languages` header to apply the request to carts for which a particular localization attribute (language) has been specified. You can specify multiple languages by separating them with commas.

Request Body schema: application/json

carts

required

Array of strings non-empty

List of anonymous carts to merge with the customer cart.

Responses

200

The request was successful. Carts have been merged.

400

The request was syntactically incorrect. Details will be provided in the response payload.

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

404

The requested resource does not exist.

500

Some server-side error occurred. Details will be provided in the response payload.

post/{tenant}/carts/{cartId}/merge

Request samples

application/json

{"carts": ["60effb93e5545f246574fde2"
]
}

Response samples

application/json

{"code": 400,
"status": "BAD_REQUEST",
"message": "There are validation problems, see details section for more information"
}

Retrieving lead time and non-delivery times for a cart

Retrieves the lead time and non-delivery times for a specified cart.

Required scopes

cart.cart_manage

Note: This scope is only required for OAuth2 authorization method to authorize the request with the access_token.

SecurityOAuth2 or CustomerAccessToken

Request

path Parameters

cartId required	string Cart’s unique identifier generated when a cart is created.
tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: The tenant should always be written in lowercase.

Responses

200

The request was successful. Cart lead time and non delivery times are returned.

400

The request was syntactically incorrect. Details will be provided in the response payload.

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

404

The requested resource does not exist.

500

Some server-side error occurred. Details will be provided in the response payload.

get/{tenant}/carts/{cartId}/dtRestrictions

Request samples

Response samples

application/json

{"leadTime": 10,
"nonDelivery": ["1",
"3",
"5"
]
}

Cart items

Manage Cart items

Adding multiple products to cart

Adds multiple products to the specified cart and creates cart items.

Required scopes

cart.cart_manage

Note: This scope is only required for OAuth2 authorization method to authorize the request with the access_token.

SecurityOAuth2 or CustomerAccessToken

Request

path Parameters

cartId required	string Cart’s unique identifier generated when a cart is created.
tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: The tenant should always be written in lowercase.

Request Body schema: application/json

Array

id	string Cart item's unique identifier.
	object Product details.
itemYrn	string (YRN) non-empty A unique identifier of a global resource, which stores information about the resource, such as its type, ID or name of the tenant.
	Array of objects (externalFee)
itemType	string Optional field which allows fetching external prices if set to EXTERNAL. Enum: "EXTERNAL" "INTERNAL"
taxCode	string Tax code. Tax indicated in this field overrides the site's default tax value.
quantity required	number <double> >= 0 Quantity of the product added to cart.
required	object (priceRowItem) Price details.
	object Tax information per unit. This field is only required when itemType is EXTERNAL and request contains external price.
	object (metadataRequest)
mixins	object
weightDependent	boolean If set to `true`, the storefront displays a hint that the total price of the product may vary depending on the product’s actual weight.

Responses

200

The request was successful. Items have been added to the cart.

400

The request was syntactically incorrect. Details will be provided in the response payload.

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

404

The requested resource does not exist.

500

Some server-side error occurred. Details will be provided in the response payload.

post/{tenant}/carts/{cartId}/itemsBatch

Request samples

application/json

[{"product": {"id": "5f5a3ce35bac380024b93cff",
"yrn": "{productYrn}",
"name": "Cherry Tomatoes",
"description": "Guaranteed to be the sweetest tomato you have ever tasted! This super sweet bite sized tomato is juicy and bursting with flavor. They are great for snacking and in salads. Kids love them too!",
"images": [{"id": "dbf2f8a4-1ff6-40a9-982f-1485ddb602e0",
"url": "https://res.cloudinary.com/saas-ag/image/upload/v1599749351/{tenant}/products/dbf2f8a4-1ff6-40a9-982f-1485ddb602e0.jpg"
}
]
},
"quantity": 100,
"price": {"priceId": "5f5a3ce5fb29e20020be99c8",
"yrn": "{priceYrn}",
"originalAmount": 4.99,
"effectiveAmount": 4.99,
"currency": "EUR",
"measurementUnit": {"quantity": 100,
"unitCode": "GRM"
}
},
"weightDependent": true
},
{"product": {"id": "5f5a3b435bac380024b93c88",
"yrn": "{productYrn}",
"name": "Black Tea",
"description": "A pack of high-quality black tea to drink with your guests.",
"images": [{"id": "4b4addad-9272-4435-83a0-4b5f1621208d",
"url": "https://res.cloudinary.com/saas-ag/image/upload/v1599749351/{tenant}/products/4b4addad-9272-4435-83a0-4b5f1621208d.jpg"
}
]
},
"quantity": 1,
"price": {"priceId": "5f5a3b45fb29e20020be9976",
"yrn": "{priceYrn}",
"originalAmount": 2.29,
"effectiveAmount": 2.29,
"currency": "EUR",
"measurementUnit": {"quantity": 1,
"unitCode": "H87"
}
},
"weightDependent": false
}
]

Response samples

application/json

[{"status": 201,
"id": "1",
"headers": {"location": "/carts/612cc4783cff1d66f699b6a1/items/1"
},
"yrn": "urn:yaas:saasag:caasproduct:product:saastest2;5c3351aea9812100098ffc60"
},
{"status": 201,
"id": "2",
"headers": {"location": "/carts/612cc4783cff1d66f699b6a1/items/2"
},
"yrn": "urn:yaas:saasag:caasproduct:product:saastest2;5c3351aea9812100098ffc61"
}
]

Retrieving all products added to a cart

Retrieves all items added to the specified cart.

Required scopes

cart.cart_manage

Note: This scope is only required for OAuth2 authorization method to authorize the request with the access_token.

SecurityOAuth2 or CustomerAccessToken

Request

path Parameters

cartId required	string Cart’s unique identifier generated when a cart is created.
tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: The tenant should always be written in lowercase.

Responses

200

The request was successful. Cart items are returned.

400

The request was syntactically incorrect. Details will be provided in the response payload.

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

404

The requested resource does not exist.

500

Some server-side error occurred. Details will be provided in the response payload.

get/{tenant}/carts/{cartId}/items

Request samples

Response samples

application/json

[{"id": "0",
"yrn": "urn:yaas:saasag:caasproduct:product:saastest2;5c3351aea9812100098ffc60",
"itemYrn": "{productYrn}",
"quantity": 6,
"effectiveQuantity": 6,
"price": {"priceId": "5f5a3b45fb29e20020be9976",
"originalAmount": 2.29,
"effectiveAmount": 2.29,
"currency": "EUR"
}
},
{"id": "1",
"yrn": "urn:yaas:saasag:caasproduct:product:saastest2;5c3351aea9812100098ffc60",
"itemYrn": "{productYrn}",
"quantity": 2,
"effectiveQuantity": 2,
"price": {"priceId": "5f59fe70fb29e20020be8f12",
"originalAmount": 9.49,
"effectiveAmount": 9.49,
"currency": "EUR"
}
}
]

Adding a product to cart

Adds a product to the specified cart and creates a cart item.

Required scopes

cart.cart_manage

Note: This scope is only required for OAuth2 authorization method to authorize the request with the access_token.
cart.cart_manage_external_prices

Note: This scope is used to manage external prices, products and fees. It's required only when an external price, product or fee is provided.

SecurityCustomerAccessToken or OAuth2

Request

path Parameters

cartId required	string Cart’s unique identifier generated when a cart is created.
tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: The tenant should always be written in lowercase.

query Parameters

siteCode

required

string

Site’s unique identifier. A site is a specific shop.

If the tenant owns only one shop, the value should be set to main.

Request Body schema: application/json

id	string Cart item's unique identifier.
	object Product details.
itemYrn	string (YRN) non-empty A unique identifier of a global resource, which stores information about the resource, such as its type, ID or name of the tenant.
	Array of objects (externalFee)
itemType	string Optional field which allows fetching external prices if set to EXTERNAL. Enum: "EXTERNAL" "INTERNAL"
taxCode	string Tax code. Tax indicated in this field overrides the site's default tax value.
quantity required	number <double> >= 0 Quantity of the product added to cart.
required	object (priceRowItem) Price details.
	object Tax information per unit. This field is only required when itemType is EXTERNAL and request contains external price.
	object (metadataRequest)
mixins	object
weightDependent	boolean If set to `true`, the storefront displays a hint that the total price of the product may vary depending on the product’s actual weight.

Responses

201

The request was successful. The product has been added to the cart.

400

The request was syntactically incorrect. Details will be provided in the response payload.

401

Given request is unauthorized - the authorization token is invalid or has expired.

Details will be provided in the response payload.

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

404

The requested resource does not exist.

409

The request could not be completed due to a conflict with the current state of the target resource.

500

Some server-side error occurred. Details will be provided in the response payload.

post/{tenant}/carts/{cartId}/items

Request samples

application/json

{"itemYrn": "{productYrn}",
"price": {"priceId": "{priceId}",
"effectiveAmount": 0.3582,
"originalAmount": 0.3582,
"currency": "EUR"
},
"quantity": 6
}

Response samples

application/json

{"itemId": "5c3351aea9812100098ffc60",
"yrn": "urn:yaas:saasag:caasproduct:product:saastest2;5c3351aea9812100098ffc60"
}

Deleting all products added to a cart

Removes all products from the specified cart and deletes the cart items.

Required scopes

cart.cart_manage

Note: This scope is only required for OAuth2 authorization method to authorize the request with the access_token.

SecurityOAuth2 or CustomerAccessToken

Request

path Parameters

cartId required	string Cart’s unique identifier generated when a cart is created.
tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: The tenant should always be written in lowercase.

Responses

204

The request was successful. Products have been deleted from the cart.

400

The request was syntactically incorrect. Details will be provided in the response payload.

401

Given request is unauthorized - the authorization token is invalid or has expired.

Details will be provided in the response payload.

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

404

The requested resource does not exist.

500

Some server-side error occurred. Details will be provided in the response payload.

delete/{tenant}/carts/{cartId}/items

Request samples

Response samples

application/json

{"code": 400,
"status": "BAD_REQUEST",
"message": "There are validation problems, see details section for more information"
}

Retrieving a cart item

Retrieves a specified cart item's details.

Required scopes

cart.cart_manage

Note: This scope is only required for OAuth2 authorization method to authorize the request with the access_token.

SecurityOAuth2 or CustomerAccessToken

Request

path Parameters

itemId required	string Cart item's unique identifier generated when the product is added to the cart.
cartId required	string Cart’s unique identifier generated when a cart is created.
tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: The tenant should always be written in lowercase.

Responses

200

The request was successful. Cart item details are returned.

400

The request was syntactically incorrect. Details will be provided in the response payload.

401

Given request is unauthorized - the authorization token is invalid or has expired.

Details will be provided in the response payload.

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

404

The requested resource does not exist.

500

Some server-side error occurred. Details will be provided in the response payload.

get/{tenant}/carts/{cartId}/items/{itemId}

Request samples

Response samples

application/json

{"id": "0",
"yrn": "urn:yaas:saasag:caasproduct:product:saastest2;5c3351aea9812100098ffc60",
"itemYrn": "{productYrn}",
"quantity": 2,
"effectiveQuantity": 2,
"price": {"priceId": "5f59fe70fb29e20020be8f12",
"originalAmount": 9.49,
"effectiveAmount": 9.49,
"currency": "EUR"
}
}

Updating a cart item

Updates a specified cart item.

Required scopes

cart.cart_manage

Note: This scope is only required for OAuth2 authorization method to authorize the request with the access_token.

SecurityOAuth2 or CustomerAccessToken

Request

path Parameters

itemId required	string Cart item's unique identifier generated when the product is added to the cart.
cartId required	string Cart’s unique identifier generated when a cart is created.
tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: The tenant should always be written in lowercase.

query Parameters

partial

boolean

Default: false

Option	Description
`true`	A partial product update will be performed.
`false`	A full product replacement will be performed.

Request Body schema: application/json

	Array of objects (externalFee)
	object (updateProduct)
itemYrn	string (YRN) non-empty A unique identifier of a global resource, which stores information about the resource, such as its type, ID or name of the tenant.
itemType	string Optional field which allows fetching external prices if set to EXTERNAL. Enum: "EXTERNAL" "INTERNAL"
quantity	number <double> >= 0 Quantity of the product added to cart.
taxCode	string Tax code. Tax indicated in this field overrides the site's default tax value.
	object Tax information per unit. This field is only required when itemType is EXTERNAL and request contains external price.
	object (priceRowItem) Price details.
	object (metadataRequest)
mixins	object

Responses

204

The request was successful. The cart item has been updated.

400

The request was syntactically incorrect. Details will be provided in the response payload.

401

Given request is unauthorized - the authorization token is invalid or has expired.

Details will be provided in the response payload.

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

404

The requested resource does not exist.

409

The request could not be completed due to a conflict with the current state of the target resource.

500

Some server-side error occurred. Details will be provided in the response payload.

put/{tenant}/carts/{cartId}/items/{itemId}

Request samples

application/json

{"itemYrn": "{productYrn}",
"quantity": 5,
"price": {"priceId": "5f59fe70fb29e20020be8f12",
"originalAmount": 9.49,
"effectiveAmount": 9.49,
"currency": "EUR",
"measurementUnit": {"quantity": 1,
"unitCode": "H87"
}
}
}

Response samples

application/json

{"code": 400,
"status": "BAD_REQUEST",
"message": "There are validation problems, see details section for more information"
}

Removing an item from cart

Removes a specified product from cart and deletes the cart item.

Required scopes

cart.cart_manage

Note: This scope is only required for OAuth2 authorization method to authorize the request with the access_token.

SecurityOAuth2 or CustomerAccessToken

Request

path Parameters

itemId required	string Cart item's unique identifier generated when the product is added to the cart.
cartId required	string Cart’s unique identifier generated when a cart is created.
tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: The tenant should always be written in lowercase.

Responses

204

The request was successful. The item has been removed from cart.

400

The request was syntactically incorrect. Details will be provided in the response payload.

401

Given request is unauthorized - the authorization token is invalid or has expired.

Details will be provided in the response payload.

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

404

The requested resource does not exist.

500

Some server-side error occurred. Details will be provided in the response payload.

delete/{tenant}/carts/{cartId}/items/{itemId}

Request samples

Response samples

application/json

{"code": 400,
"status": "BAD_REQUEST",
"message": "There are validation problems, see details section for more information"
}

Discounts

Manage Discounts

Applying a discount to cart

Applies a discount on the specified cart. Multiple discount coupons can be applied to cart, but you need to send a separate request for each discount coupon.

Required scopes

cart.cart_manage

Note: This scope is only required for OAuth2 authorization method to authorize the request with the access_token.

SecurityOAuth2 or CustomerAccessToken

Request

path Parameters

cartId required	string Cart’s unique identifier generated when a cart is created.
tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: The tenant should always be written in lowercase.

Request Body schema: application/json

id	string Discount's unique identifier.
couponYrn	string (YRN) non-empty A unique identifier of a global resource, which stores information about the resource, such as its type, ID or name of the tenant.
code required	string [ 1 .. 150 ] characters Discount code generated when a discount coupon is created through the Coupon Service.
currency	string = 3 characters [A-Z]{3} Three-letter currency code, compliant with the ISO 4217 standard.
amount	number <double> >= 0 Discount expressed as fixed amount.
name	string <= 150 characters Discount's displayed name.
discountRate	number <double> >= 0 Discount expressed as a percentage of the price.
calculationType	string <= 30 characters Default: "ApplyDiscountBeforeTax" Calculation type specifies how the discount should be calculated. Can be set to one of the following: `ApplyDiscountBeforeTax` `ApplyDiscountAfterTax` Enum: "ApplyDiscountBeforeTax" "ApplyDiscountAfterTax"
discountCalculationType	string Default: "SUBTOTAL" Determines whether the coupon is applied to the total or subtotal value of the order. Enum: "SUBTOTAL" "TOTAL"
	Array of objects (link) >= 2 items Links to Coupon Service endpoints used to validate and redeem the discount.

Responses

201

The request was successful. The discount has been applied to cart.

400

The request was syntactically incorrect. Details will be provided in the response payload.

401

Given request is unauthorized - the authorization token is invalid or has expired.

Details will be provided in the response payload.

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

404

The requested resource does not exist.

409

The request could not be completed due to a conflict with the current state of the target resource.

500

Internal Server Error

post/{tenant}/carts/{cartId}/discounts

Request samples

application/json

{"code": "DEVIZU",
"amount": 10,
"currency": "EUR",
"name": "Thanksgiving coupon for all orders",
"calculationType": "ApplyDiscountBeforeTax",
"links": [{"title": "THANKSGIVING10",
"rel": "validate",
"type": "application/json",
"href": "https://api.emporix.io/coupon/{tenant}/coupons/THANKSGIVING10"
},
{"title": "THANKSGIVING10 redeem",
"rel": "redeem",
"type": "application/json",
"href": "https://api.emporix.io/coupon/{tenant}/coupons/THANKSGIVING10/redemptions"
}
]
}

Response samples

application/json

{"yrn": "{discountYrn}",
"discountId": "1",
"discountIndex": 0
}

Removing all discounts from cart

Removes all discounts applied to the specified cart.

Required scopes

cart.cart_manage

Note: This scope is only required for OAuth2 authorization method to authorize the request with the access_token.

SecurityOAuth2 or CustomerAccessToken

Request

path Parameters

cartId required	string Cart’s unique identifier generated when a cart is created.
tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: The tenant should always be written in lowercase.

query Parameters

codes

string

Discount codes, listed with commas, specify the discounts slated for deletion. If no codes are provided, all discounts will be removed.

Example: codes=code1,code2

Responses

204

The request was successful. Discounts have been removed.

400

The request was syntactically incorrect. Details will be provided in the response payload.

401

Given request is unauthorized - the authorization token is invalid or has expired.

Details will be provided in the response payload.

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

404

The requested resource does not exist.

500

Some server-side error occurred. Details will be provided in the response payload.

delete/{tenant}/carts/{cartId}/discounts

Request samples

Response samples

application/json

{"code": 400,
"status": "BAD_REQUEST",
"message": "There are validation problems, see details section for more information"
}

Returning all discounts from the cart

Returns all discounts of the specified cart.

Required scopes

cart.cart_manage

Note: This scope is only required for OAuth2 authorization method to authorize the request with the access_token.

SecurityOAuth2

Request

path Parameters

cartId required	string Cart’s unique identifier generated when a cart is created.
tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: The tenant should always be written in lowercase.

Responses

200

The request was successful. Cart discounts items are returned.

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

404

The requested resource does not exist.

500

Some server-side error occurred. Details will be provided in the response payload.

get/{tenant}/carts/{cartId}/discounts

Request samples

Response samples

application/json

[{"id": "string",
"yrn": "string",
"couponYrn": "string",
"code": "string",
"amount": 0,
"currency": "str",
"discountRate": 0,
"name": "string",
"calculationType": "ApplyDiscountBeforeTax",
"discountCalculationType": "SUBTOTAL",
"valid": true,
"links": [{"rel": "validate",
"title": "string",
"href": "string",
"type": "application/json"
},
{"rel": "validate",
"title": "string",
"href": "string",
"type": "application/json"
}
],
"discountValidationDetails": {"message": "string",
"details": ["string"
]
},
"discountIndex": 0
}
]

Removing a discount from cart

Delete the discount in the cart by the provided discount Index.

Required scopes

cart.cart_manage

Note: This scope is only required for OAuth2 authorization method to authorize the request with the access_token.

SecurityOAuth2 or CustomerAccessToken

Request

path Parameters

cartId required	string Cart’s unique identifier generated when a cart is created.
discountIndex required	string
tenant required	string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$ Your Emporix tenant's name. Note: The tenant should always be written in lowercase.

Responses

204

The request was successful. The discount has been removed from cart.

400

The request was syntactically incorrect. Details will be provided in the response payload.

401

Given request is unauthorized - the authorization token is invalid or has expired.

Details will be provided in the response payload.

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

404

The requested resource does not exist.

500

Internal server error.

delete/{tenant}/carts/{cartId}/discounts/{discountIndex}

Request samples

Response samples

application/json

{"code": 400,
"status": "BAD_REQUEST",
"message": "There are validation problems, see details section for more information"
}