Cart Service

Download OpenAPI specification:Download

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.

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": {},
  • "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.

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": {
    },
  • "leadTime": 0,
  • "nonDelivery": [
    ]
}

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": [
    ],
  • "sessionId": "YxXRjn9zSFM7gMq5dtNKarX7xYkIMV",
  • "metadata": {
    },
  • "leadTime": 0,
  • "nonDelivery": [
    ]
}

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.

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
{}
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": [
    ]
}
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": [
    ]
}

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
[
  • {
    },
  • {}
]
Response samples
application/json
[
  • {
    },
  • {
    }
]

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
[
  • {
    },
  • {
    }
]

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": {
    },
  • "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": {
    }
}

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": {
    }
}
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
{}
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
[
  • {
    }
]

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"
}