search
CommunitySupport PortalYouTubeFree trialSign Up!

Carts

Manage Carts

hashtag
Retrieving cart details by criteria

get

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

As a response only one cart is returned, so all required criteria needs to be provided to fetch the unique cart. Uniqueness of the cart is defined by combination of siteCode, type, legalEntityId and (sessionId or customerId)

hashtag
Required scopes

  • cart.cart_manage

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

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
tenantstring · min: 3 · max: 16Required

Your Emporix tenant name.

Note: The tenant should always be written in lowercase.

Pattern: ^[a-z][a-z0-9]+$
Query parameters
sessionIdstringOptional

Customer unique session identifier.

Note: The sessionId is only required if you want to retrieve an anonymous customer cart.

customerIdstringOptional

Customer unique identifier generated when a customer account is created.

Note: The customerId is only required if you want to create a cart for a logged in customer.

siteCodestringRequired

Site unique identifier. A site is a specific shop.

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

legalEntityIdstringOptional

ID of the legal entity to which customer is assigned. Should not be provided for B2C business model.

Note: The query param is optional, but if not provided, the cart without legalEntity assigned is returned.

createbooleanOptional

If set to true and no cart exists for the specified criteria, a new cart will be created.

typestringOptional

Type of the cart.

Note: The query param is optional, but if not provided then only cart without type is returned.

zipCodestring · min: 1 · max: 9Optional

The zip code of the shipping address, used for tax calculations, shipping cost estimations, and pricing. Must be provided together with countryCode if either of the parameters is specified. If the cart already has both (zipCode and countyCode) address values, the request parameters are ignored. If the cart is missing either value, request parameters are used to fill the missing one.

countryCodestring · min: 2 · max: 2Optional

The country code of the shipping address, used for tax calculations, shipping cost estimations, and pricing. Must be provided together with zipCode if either of the parameters is specified. If the cart already has both (zipCode and countyCode) address values, the request parameters are ignored. If the cart is missing either value, request parameters are used to fill the missing one.

Responses
chevron-right
200

The request was successful. Cart details are returned.

application/json
get
/cart/{tenant}/carts

hashtag
Creating a new cart

post

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

Note: A customer can have multiple carts opened, but they have to be of a different type. The cart type is specified in the payload in the type property. It allows for different types of carts, such as shopping carts and wishlists.

hashtag
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.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
tenantstring · min: 3 · max: 16Required

Your Emporix tenant name.

Note: The tenant should always be written in lowercase.

Pattern: ^[a-z][a-z0-9]+$
Header parameters
session-idstringOptional

Anonymous customer unique session identifier.

Note: The session-id is only required if you want to create a cart for an anonymous customer.

saas-tokenstringOptional

Customer 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.

Body
customerIdstring · max: 200Optional

Customer unique identifier generated when a customer account is created through the Customer Service.

currencystring · min: 3 · max: 3Required

Three-letter currency code, compliant with the ISO 4217 standard.

Pattern: [A-Z]{3}
legalEntityIdstringOptional

ID of the legal entity to which customer is assigned.

deliveryWindowIdstringOptional

Delivery window unique identifier, as defined in the Shipping Service.

siteCodestringOptional

Site unique identifier. A site is a specific shop.

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

Default: default
typestringOptional

Cart type. You can use this field if your store offers different types of carts, such as shopping carts and wishlists.

sessionValidatedbooleanOptional

If set to true, endpoints 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 customer carts.

Default: false
Responses
post
/cart/{tenant}/carts

hashtag
Searching for carts

post

Returns all carts that match provided criteria.

hashtag
Required scopes

  • cart.cart_manage

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

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
tenantstring · min: 3 · max: 16Required

Your Emporix tenant name.

Note: The tenant should always be written in lowercase.

Pattern: ^[a-z][a-z0-9]+$
Query parameters
pageSizestringOptional

The number of documents to be retrieved per page.

pageNumberstringOptional

The page number to be retrieved. The size of the pages should be specified by the pageSize parameter.

sortstringOptional

List of properties used to sort the results, separated by colons.

fieldsstringOptional

Fields to be returned in the response.

Header parameters
X-Total-CountbooleanOptional

Flag indicating whether the total number of retrieved results should be returned.

Body
qstringOptional

A standard query parameter is used to search for specific values.

See: Standard practises - Query parameter

Responses
chevron-right
200

The request was successful. Carts are returned.

application/json
post
/cart/{tenant}/carts/search

hashtag
Retrieving cart details by ID

get

Retrieves specified cart details.

hashtag
Required scopes

  • cart.cart_manage

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

Authorizations
OAuth2clientCredentialsRequired
Token URL:
Available scopes:
  • : Needed to manage carts.
Path parameters
cartIdstringRequired

Cart unique identifier generated when a cart is created.

tenantstring · min: 3 · max: 16Required

Your Emporix tenant name.

Note: The tenant should always be written in lowercase.

Pattern: ^[a-z][a-z0-9]+$
Query parameters
expandCalculationbooleanOptional

If set to true, a fully calculated cart is returned.

Default: true
zipCodestring · min: 1 · max: 9Optional

The zip code of the shipping address, used for tax calculations, shipping cost estimations, and pricing. Must be provided together with countryCode if either of the parameters is specified. If the cart already has both (zipCode and countryCode) address values, the request parameters are ignored. If the cart is missing either value, request parameters are used to fill the missing one.

countryCodestring · min: 2 · max: 2Optional

The country code of the shipping address, used for tax calculations, shipping cost estimations, and pricing. Must be provided together with zipCode if either of the parameters is specified. If the cart already has both (zipCode and countryCode) address values, the request parameters are ignored. If the cart is missing either value, request parameters are used to fill the missing one.

Responses
chevron-right
200

The request was successful. Cart details are returned.

application/json
get
/cart/{tenant}/carts/{cartId}

hashtag
Updating a cart

put

Updates specified cart details.

hashtag
Required scopes

  • cart.cart_manage

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

Authorizations
OAuth2clientCredentialsRequired
Token URL:
Available scopes:
  • : Needed to manage carts.
Path parameters
cartIdstringRequired

Cart unique identifier generated when a cart is created.

tenantstring · min: 3 · max: 16Required

Your Emporix tenant name.

Note: The tenant should always be written in lowercase.

Pattern: ^[a-z][a-z0-9]+$
Body
customerIdstringOptional

Customer unique identifier generated when a customer account is created through the Customer Service.

currencystring · min: 3 · max: 3Optional

Three-letter currency code, compliant with the ISO 4217 standard.

Pattern: [A-Z]{3}
legalEntityIdstringOptional

ID of the legal entity to which customer is assigned.

deliveryWindowIdstringOptional

Delivery window unique identifier, as defined in the Shipping Service.

typestringOptional

Cart type. You can use this field if your store offers different types of carts, such as shopping carts and wishlists.

zipCodestring · max: 9Optional

Customer address - zip code.

countryCodestring · min: 2 · max: 2Optional

Two-letter country code, compliant with the ISO 3166 standard.

Pattern: [a-zA-Z]{2}
orderIdstringOptional

Order unique identifier generated when a checkout is triggered through the Checkout Service.

quoteIdstringOptional

Quote unique identifier generated when a quote is created through the Quote Service out of a cart.

statusstring · enumOptional

Cart status.

Possible values:
Responses
put
/cart/{tenant}/carts/{cartId}
No content

hashtag
Deleting a cart

delete

Deletes a specified cart.

hashtag
Required scopes

  • cart.cart_manage

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

Authorizations
OAuth2clientCredentialsRequired
Token URL:
Available scopes:
  • : Needed to manage carts.
Path parameters
cartIdstringRequired

Cart unique identifier generated when a cart is created.

tenantstring · min: 3 · max: 16Required

Your Emporix tenant name.

Note: The tenant should always be written in lowercase.

Pattern: ^[a-z][a-z0-9]+$
Responses
delete
/cart/{tenant}/carts/{cartId}
No content

hashtag
Refreshing a cart

put

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

hashtag
Required scopes

  • cart.cart_manage

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

Authorizations
OAuth2clientCredentialsRequired
Token URL:
Available scopes:
  • : Needed to manage carts.
Path parameters
cartIdstringRequired

Cart unique identifier generated when a cart is created.

tenantstring · min: 3 · max: 16Required

Your Emporix tenant name.

Note: The tenant should always be written in lowercase.

Pattern: ^[a-z][a-z0-9]+$
Responses
put
/cart/{tenant}/carts/{cartId}/refresh
No content

hashtag
Changing a cart site

post

Changes a specified cart 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.

hashtag
Required scopes

  • cart.cart_manage

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

Authorizations
OAuth2clientCredentialsRequired
Token URL:
Available scopes:
  • : Needed to manage carts.
Path parameters
cartIdstringRequired

Cart unique identifier generated when a cart is created.

tenantstring · min: 3 · max: 16Required

Your Emporix tenant name.

Note: The tenant should always be written in lowercase.

Pattern: ^[a-z][a-z0-9]+$
Header parameters
Accept-LanguagestringOptional

List of natural languages acceptable for the response.

Content-LanguagestringOptional

List of acceptable natural languages of the customers.

languagesstringOptional

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.

Body
siteCodestringRequired

Site unique identifier. A site is a specific shop.

Responses
chevron-right
200

All item's currencies are updated.

No content
post
/cart/{tenant}/carts/{cartId}/changeSite
No content

hashtag
Changing a cart currency

post

Changes a specified cart 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.

hashtag
Required scopes

  • cart.cart_manage

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

Authorizations
OAuth2clientCredentialsRequired
Token URL:
Available scopes:
  • : Needed to manage carts.
Path parameters
cartIdstringRequired

Cart unique identifier generated when a cart is created.

tenantstring · min: 3 · max: 16Required

Your Emporix tenant name.

Note: The tenant should always be written in lowercase.

Pattern: ^[a-z][a-z0-9]+$
Header parameters
Accept-LanguagestringOptional

List of natural languages acceptable for the response.

Content-LanguagestringOptional

List of acceptable natural languages of the customers.

languagesstringOptional

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.

Body
currencystringOptional
Responses
chevron-right
200

All item's currencies are updated.

No content
post
/cart/{tenant}/carts/{cartId}/changeCurrency
No content

hashtag
Merging carts

post

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.

hashtag
Required scopes

  • cart.cart_manage

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

Authorizations
OAuth2clientCredentialsRequired
Token URL:
Available scopes:
  • : Needed to manage carts.
Path parameters
cartIdstringRequired

Cart unique identifier generated when a cart is created.

tenantstring · min: 3 · max: 16Required

Your Emporix tenant name.

Note: The tenant should always be written in lowercase.

Pattern: ^[a-z][a-z0-9]+$
Header parameters
Accept-LanguagestringOptional

List of natural languages acceptable for the response.

Content-LanguagestringOptional

List of acceptable natural languages of the customers.

languagesstringOptional

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.

Body
cartsstring[] · min: 1Required

List of anonymous carts to merge with the customer cart.

Responses
chevron-right
200

The request was successful. Carts have been merged.

No content
post
/cart/{tenant}/carts/{cartId}/merge
No content

hashtag
Retrieving lead time and non-delivery times for a cart

get

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

hashtag
Required scopes

  • cart.cart_manage

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

Authorizations
OAuth2clientCredentialsRequired
Token URL:
Available scopes:
  • : Needed to manage carts.
Path parameters
cartIdstringRequired

Cart unique identifier generated when a cart is created.

tenantstring · min: 3 · max: 16Required

Your Emporix tenant name.

Note: The tenant should always be written in lowercase.

Pattern: ^[a-z][a-z0-9]+$
Responses
chevron-right
200

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

application/json
get
/cart/{tenant}/carts/{cartId}/dtRestrictions

hashtag
Validating cart items

get

Validates the cart items, checking for pricing issues and other potential problems.

The endpoint checks for two specific validation issues:

  1. CART-ITEM-UNIT-PRICE-100001 - Returns this error when a cart contains a price that is no longer valid or not found in the price match.

  2. CART-ITEM-UNIT-PRICE-100002 - Returns this error when there are duplicated prices for the same product in the cart.

hashtag
Required scopes

  • cart.cart_manage

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

Authorizations
OAuth2clientCredentialsRequired
Token URL:
Available scopes:
  • : Needed to manage carts.
Path parameters
cartIdstringRequired

Cart unique identifier generated when a cart is created.

tenantstring · min: 3 · max: 16Required

Your Emporix tenant name.

Note: The tenant should always be written in lowercase.

Pattern: ^[a-z][a-z0-9]+$
Responses
chevron-right
200

The request was successful. Returns the validation status of the cart.

application/json
get
/cart/{tenant}/carts/{cartId}/validate
PreviousAPI ReferenceNextCart items

Last updated

Was this helpful?