Overview
The Cart service is used to manage the cart and the items within the cart. The service enables you to:
- Create a new cart.
- Add items to an existing cart.
- Retrieve the details of the items in the cart.
- Update the cart information, such as customer information, item quantity, item price, and cart status.
- Remove items from a cart.
- Merge an anonymous cart with a registered cart.
- Change the site that the cart belongs to.
- Validate the discount before applying it to the cart.
- Calculate the cart's total.
- Create and use mixins.
A cart must be created before a customer can begin adding items to the cart. When the cart is created, it has an open status. While the cart is open, you can perform any of the functions listed above. When a cart is closed, it no longer exists, and you must create a new cart so that the customer can continue shopping. The customer can shop as an anonymous user or log in if they have an account.
If tax is applicable, you can configure which tax provider (Tax or Avalara Tax) to use in the Site service. The tax or shipping provider you select determines how taxes and shipping costs (either by estimation or quotation) are calculated for the cart. Once the customer is ready to proceed to checkout, the cart details are passed to the Checkout service using the access token.
API Reference
/{tenant}/carts
This resourceType defines the GET, POST, DELETE methods and their responses for a collection resource.
/{tenant}/carts
Get cart by criteria. The criteria can have customerId or sessionId. The search will be executed by customerId if available otherwise with sessionId. If the zipCode and countryCode are provided as query parameters then the taxes are applied on cart. The zipCode and countryCode must either be provided both or none. The caller must have the hybris.cart_manage scope assigned when retrieving a cart on behalf of the customer.
Create a cart. The caller must have the hybris.cart_manage scope assigned when creating a cart on behalf of the customer.
/{tenant}/carts/{cartId}
This resource type defines the GET, PUT, DELETE methods and their responses for a single element resource.
Get a specific cart by ID. If the zipCode and countryCode are provided as query parameters then the taxes are applied on the cart. You can either get a basic cart with items or the complete calculated cart using the expand query parameter. The caller must have the hybris.cart_manage scope assigned when retrieving a cart on behalf of the customer.
Modify a specific cart by cartId. The caller must have the hybris.cart_manage scope assigned when updating a cart on behalf of the customer.
Delete the cart. The caller must have the hybris.cart_manage scope assigned when deleting a cart on behalf of the customer.
/{tenant}/carts/{cartId}/changeSite
Change site changes the cart’s language, currency, shipment, tax, and payment settings. It uses the match currency request in Price service to ensure that the items in the cart have a corresponding price in the currency of the new site.
/{tenant}/carts/{cartId}/merge
Merge some other carts to the current cart.
/{tenant}/carts/{cartId}/itemsBatch
Create multiple items to one specific cart with a single call.
/{tenant}/carts/{cartId}/items
This resourceType defines the GET, POST, DELETE methods and their responses for a collection resource.
Retrieve all items in the cart.
Create a cart item.
Delete all the items in the cart.
/{tenant}/carts/{cartId}/items/{itemId}
This resource type defines the GET, PUT, DELETE methods and their responses for a single element resource.
Get the item in the cart.
Update the cart item state.
Delete the item in the cart.
/{tenant}/carts/{cartId}/discounts
Apply discount on cart.
Delete all the discounts in the cart.
/{tenant}/carts/{cartId}/discounts/{discountId}
Delete the discount in the cart.
Cart Creation
Before the customer can add items to the cart, a cart must exist. A unique cart ID needs to be created for:
- A registered user: A user logged in with an account
- An anonymous user: A user not logged in with an account
When a cart is created, its status is open. If a new cart is needed, the current cart status can be updated to closed. A Cart service consumer can only have one open cart at a time. The cart uniqueness is identified in two different ways, depending on whether the user is logged in or if the user is anonymous:
- Logged in users: The Cart service allows only one
opencart perhybris-user/customer ID, per site. - Anonymous users: The Cart service allows only one
opencart perhybris-session-id/session ID.
The customer ID is the equivalent of the hybris-user that is passed through the token. The session ID is the equivalent of the hybris-session-id that is passed through the token. For more information, see Request Headers.
To support customers shopping on various channels (for example, YaaS Storefront, Twitter, Pinterest, etc.), the channel information is received by the Cart service from the client application when the cart is created.
Create a cart for a registered user
To create a cart for a user who already has an account, you need the customer ID and currency attributes. The site code attribute is optional. The following are a few considerations in this scenario:
- The Customer service creates the customer ID when the user creates their account for the site. For more information about creating accounts, see Creating a New Account.
- The customer ID cannot be passed directly unless the request has the hybris.cart_manage scope associated with the token.
- When the token passed in the request does not have the hybris.cart_manage scope, the value of the header hybris-user is assigned to the cart's customer ID.
- The currency is determined by the user when they select a country of origin to enter the site.
- You have the option to provide the site code attribute with the specific site code.
- If you don't provide the site code, then the site named default is used.
- You can have multiple open carts depending on the different sites you have set up in the Site service.
- Passing this site code ensures that the correct site configurations are used.
Create a cart for an anonymous user
If the customer does not have an account, the customer is considered an anonymous user and the session ID and currency attributes are needed to create an anonymous cart.
The session ID, which is the equivalent of the customer ID for users who have an account, can be created in the following ways:
- By the SessionIdGeneratorSvc factory.
- By the Customer Login service.
- Your own implementation.
The currency attribute value is determined by the customer when they select a country of origin to enter the site. You have the option to provide the site code attribute with the specific site code. If you don't provide the site code, then the site named default is used.
Session ID generate by the SessionIdGeneratorSvc factory
When the client side SessionIdGeneratorSvc factory generates the session ID, it is used along with the client ID and Hybris tenant to generate the access token. This session ID is then persisted in the session-id cookie for 20 years from the date of creation. This ensures that the same ID is used each time the customer shops on the same device. The session ID is passed to the Cart service, through the proxy, and is used in the header to create the cart ID. Once the cart is created, the session ID is persisted in the cart. If the customer checks out, meaning the cart status is changed to closed, but then decides to continue shopping, another cart ID is created with the same session ID.
Session ID created by the Customer Login service
If you choose to not send the session ID when generating the access token, the Customer Login service will generate a session ID for the anonymous user. The difference between a server-generated session ID and one generated by the client is its active lifecycle. This session ID is only active for an hour (the same as the access token). This can cause an issue for carts that are open for more than an hour. If the session ID has expired, the cart is only retrievable by the cart ID and not by the session ID. If the customer checks out, meaning the cart status is changed to closed, but then decides to continue shopping, another cart ID is created and the session ID persisted with this new cart depends on whether the previous session ID is still valid.
Anonymous cart security enhancement
To enhance the security on an anonymous cart, the client application can send the optional sessionValidated attribute to the Cart service when the cart is created. By default, the value is set to false, which means any request can be executed on the cart without validating the session ID. If set to true, the Cart service needs to validate that the session ID persisted during the cart creation matches the session ID used to perform any other action on the cart.
Merge Carts
If the customer does not log in to a site, they are shopping as an anonymous user, and therefore the cart ID is associated with their session ID. Once the customer logs in to their account, they are then shopping with their customer ID, and a new cart ID is automatically created. To make sure that the items in the anonymous cart are not lost, the merge functionality is used to merge the two carts together, and the registered user's cart ID is used from then on. After the merge, the anonymous cart ID is deleted.
The following guidelines specify what the merge cart functionality can and cannot do.
- You can merge an anonymous cart with a registered cart, but you cannot merge a registered cart with an anonymous cart.
- You can merge a non-empty anonymous cart with a non-empty registered cart.
- If the same item is in the anonymous cart and the registered cart, the quantities are added together when the two carts are merged.
- If the same item, one with an itemYrn is in the anonymous cart and the other with a product object is in the registered cart, the items are added as separate entries when two carts are merged. The quantities are not added together.
- You can merge two empty carts with different currencies. When the two carts are merged, the new cart assumes the currency of the registered cart.
- You can merge two non-empty carts with different currencies even if the items in the anonymous cart does not have prices in the currency of the registered cart.
- You can merge two carts if the price of the item in the cart has been updated.
- You can merge two carts if an item in the cart is currently out of stock, but this will prevent the customer from proceeding to checkout. If the customer attempts to perform a checkout, an error message displays prompting the customer to remove that item from their cart.
- You can merge two carts if the price for an item in the cart has been deleted, but this will prevent the customer from proceeding to checkout. If the customer attempts to perform a checkout, an error message displays prompting the customer that the price of the product does not exist.
- If there are different mixins in each cart, the mixins will be consolidated once the two carts are merged.
- If the same mixin appears in both carts, once the carts are merged it will keep the value of the anonymous cart mixin.
Discounts
All discounts added to the cart are validated by a call made to the Coupon service. This call checks that the discount exists and is valid based on the cart's subtotal. The discount is only applied when you retrieve or checkout a cart because that is when the cart calculation is executed. It is always applied on the cart's subtotal (in orther words, the sum of the cart items) and never on the shipping cost.
The following guidelines specify what the discount functionality can and cannot do.
- You can add multiple discounts consisting of both dollar amounts and percentages to the cart.
- The currency of the discount must be equal to the currency of the cart.
- You can add discounts to both anonymous and registered carts.
- Discounts can remain on an empty cart.
Discount attributes
The discount object has these attributes:
- ID
- Code
- Currency
- Amount/discount rate
- Name
- Sequence ID
- Calculation type
- Links
To add a discount to the cart, the request must contain the discount amount or discount rate, currency, links, and code attributes.
The sequence ID attribute (sequenceId) is optional. You can use the sequence ID to determine the order of the discounts when multiple discounts are applied to the cart. These are guidelines for this attribute:
- If you choose not to use this attribute, the discounts are applied on a first added, first applied basis.
- If you choose to use this attribute, the discounts are applied to the cart based on the value of the sequence ID.
The calculation type attribute (calculationType) is also optional. This determines whether the discount is added to the cart before the tax (ApplyDiscountBeforeTax) or after the tax (ApplyDiscountAfterTax). By default, the calculationType is set to ApplyDiscountBeforeTax.
Error messages
An error code of 400 business error and a corresponding message is sent to the customer in these scenarios:
- The request body is missing any of these mandatory attributes: the discount code, the currency, the discount amount or discount rate and the links.
- The discount value is equal to or less than zero.
- The discount has the same code as one that already exists in the cart. A discount cannot be added to the cart twice.
- The amount and discountRate attributes have both been assigned a value for a single discount.
Extend Cart Information
Each cart contains a set of properties that uniquely identify and define it. For example, the cart id identifies each particular cart instance, and the siteCode identifies the site that the cart belongs to.
However, there are not many properties defined by the cart schema. The properties that are defined by the cart schema are common to all items of the cart type. But what if you could have a flexible and adjustable set of properties that vary from cart to cart, each one extending the information about the cart? What if you could only define such properties once and then reuse these properties in many different carts?
The mixin feature lets you define a set of properties once and reuse them in different carts. You can assign one mixin to many carts, but you can also use many mixins in one cart. This approach supports flexibility, re-usability, and structural consistency among all your carts.
To use mixins you need to first create the mixin schema in the Schema service and then apply it by referring to the URL or phrase of the mixin. Another way you can add mixins is by adding it to the service request call. For information on how to create a mixin, see Mixin Schema. For information on using a mixin, see Use the Mixin Schema.
Mixin schema
To create a mixin, you can define the mixin in a schema within the Schema service or you can create the mixin inside the service request. If you create the mixin in the Schema service you only have to call the mixin URL (or phrase) and assign a value to the mixin within the request. If you create the mixin directly in the request call (inline schema), you need to enter the same properties each time you want to add that specific mixin to the cart.
The following is an example of the mixin structure for either method:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"instruction": {
"type": "string"
}
}
}
The mixin declares the properties and data types of those properties. This example has an instruction property and it accepts a string value.
With the mixin in the Schema service, you can use it to extend the cart with this new additional property. These properties are not part of the Cart schema; they are part of the mixin schema. For more information on how to create and retrieve a mixin schema, see Create and Retrieve Schema.
Use the mixin schema
Once you have created your mixin schema, you can add the mixin to the cart configuration when you create a new cart or update an existing cart, or if you add or update items to your cart. The mixin can be applied at the cart, cart item, and product (within cart item) level.
The following example shows a mixin schema added to the cart level.
{
"customerId": "536cd455cb4e6cc7d8f50165",
"currency": "CAD",
"siteCode": "canada",
"mixins":{
"additionalCode": {
"code": "ABC"
}
},
"metadata": {
"mixins": {
"additionalCode": "https://api.beta.yaas.io/hybris/schema/v1/kiwistest/example-schema.json"
}
}
}
When you add a new cart item or update an existing cart item, you can add the mixin-based properties to the cart item or product level. The following example shows mixins added to the cart item and product level.
{
"price": {
"originalAmount": 55.55,
"effectiveAmount": 55.55,
"currency": "CAD",
"priceId": "558c3ddf294eb05a5ed0c972"
},
"quantity": 1,
"product": {
"id": "sku1",
"yrn": "urn:yaas:hybris:product:product:myshop;sku1",
"sku": "sku1",
"name": "sku1",
"description": "sku1",
"metadata": {
"mixins": {
"inventory": "https://api.beta.yaas.io/hybris/schema/b2/hybriscommerce/inventorySchema-v1"
}
},
"mixins": {
"inventory": {
"inStock": true
}
},
"images": [
{
"id":"image001",
"url": "http://localhost/img01sku1.png"
}
]
}
},
"metadata": {
"mixins": {
"additionalCode": {
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema",
"properties": {
"version": {
"type": "integer",
"minimum": 1
}
}
}
}
},
"mixins":{
"additionalCode": {
"version": 2
}
}
}
For tutorials on how to add mixins to a cart or cart item, see Create Cart with Mixins and Update Cart with Mixins.
Create a Cart
Before a customer can add items to their cart, a cart needs to be created.
The following example shows how a cart is created for a registered user.
Request
- Method: POST
- Request URL:
https://api.beta.yaas.io/hybris/cart/v1/{tenant}/carts - Body: The request body must contain the customer ID (customerId) and currency (currency) attributes.
{ "type": "object", "$schema": "http://json-schema.org/draft-04/schema", "required": "true", "properties": { "customerId": { "type": "string", "required": "true", "maxLength": "200" }, "currency": { "type": "string", "required": true, "pattern" : "[A-Z]{3}" }, "siteCode": { "type": "string", "required": false }, "channel": { "type": "object" } } } - Example:
{ "customerId": "536cd455cb4e6cc7d8f50165", "currency": "CAD", "siteCode": "canada", "channel": { "name": "Pinterest", "source": "http://pinterest.com/pin/1/te/2/rest/3" } }
Response
- Status Code:
201 - Body: The response body contains the cart ID (cartId) and YRN. This ID is used to:
- Add items to the cart.
- Update cart details.
- Retrieve cart details.
- Delete items from the cart.
{ "type": "object", "$schema": "http://json-schema.org/draft-04/schema", "required": false, "properties": { "cartId": { "type": "string", "required": true }, "yrn": { "type": "string" } } }
- Example:
{ "cartId": "54219416ad0eeed77130bad8", "yrn": "urn:yaas:hybris:cart:cart:myshop;54219416ad0eeed77130bad8" }
This example shows how a cart is created for an anonymous user.
Request
- Method: POST
- Request URL:
https://api.beta.yaas.io/hybris/cart/v1/{tenant}/carts - Example:Do not include the customerId in the request body for an anonymous customer.
{ "currency": "CAD", "siteCode": "canada", "channel": { "name": "yaas-storefront", "source": "http://shops.yaas.io/" } }
Response
- Status Code:
201 - Example:
{ "cartId": "542c56cbfa2e6c54c67d6850", "cartId": "54219416ad0eeed77130bad8", "yrn": "urn:yaas:hybris:cart:cartId:myshop;542c56cbfa2e6c54c67d6850" }
Create Cart with Mixins
When you create a cart, you have the option to include additional attributes to the cart. These attributes are added by using mixins. For information on how to create a mixin, see the Mixin schema section in the Extend Cart Information page.
You can add mixins to the cart by using:
- The Schema service: This method uses an existing schema that has been published on a server and placed in the metadata.
- The inline schema in the metadata: This creates a mixin with an inline schema.
Create a cart with an existing schema mixin
Once you have a mixin created in the Schema service, you can add the property to the cart when you create the cart.
Request
- Method: POST
- Request URL:
https://api.beta.yaas.io/hybris/cart/v1/{tenant}/carts - Body: The request body must contain the customer ID (customerId), currency (currency) site code (siteCode), metadata and mixins attributes.
{ "customerId": "536cd455cb4e6cc7d8f50165", "currency": "CAD", "siteCode": "canada", "mixins":{ "cartInstructions":{ "instruction": "It would be nice if you deliver the order after 5 PM." } } "metadata": { "mixins":{ "cartInstructions":"existingCartInstructionsSchemaUri" } } }
Response
- Status Code:
201 - Example:
{ "cartId": "542c56cbfa2e6c54c67d6850", "yrn": "urn:yaas:hybris:cart:cart:myshop;542c56cbfa2e6c54c67d6850" }
Create a cart with an inline schema
The inline schema enables you to define the schema definition inside the metadata attribute. This example shows you how to create a mixin as you create your cart.
Request
- Method: POST
- Request URL:
https://api.beta.yaas.io/hybris/cart/v1/{tenant}/carts - Body: The request body must contain the customer ID (customerId), currency (currency), site code (siteCode), metadata, and mixins attributes. The metadata.mixins.cartInstructions attribute contains the inline schema definition.
{ "customerId": "536cd455cb4e6cc7d8f50165", "currency": "CAD", "siteCode": "canada", "metadata": { "mixins": { "additionalCode": { "type": "object", "$schema": "http://json-schema.org/draft-04/schema", "properties": { "version": { "type": "integer", "minimum": 1 } } } } }, "mixins": { "additionalCode": { "version": 12 } } }
Response
- Status Code:
201 - Example:
{ "cartId": "542c56cbfa2e6c54c67d6850", "yrn": "urn:yaas:hybris:cart:cart:myshop;542c56cbfa2e6c54c67d6850" }
Add Item to the Cart
When you create a cart ID, the customer can begin to add items to the cart.
Request
- Method: POST
- Request URL:
https://api.beta.yaas.io/hybris/cart/v1/{tenant}/carts/{cartId}/items - Header: The hybris-resource-version is an optional optimistic locking header and begins with the value 1. It increments by one each time a POST or a PUT operation is performed on the cart. If you specify the version number, make sure you know what the most current version of the cart is before performing a POST or PUT. To determine the current cart version number, you need to retrieve the cart details. For more information, see Retrieve Cart Details.
Body: The request body must contain the cart item information as shown in this schema. The quantity, price, and product object or itemYrn attribute are mandatory. If a product has a specific tax code associated to it, the taxCode attribute must also be included in the schema. If the product price is based on a unit of measurement, then the measurementUnit attribute needs to be included in the price attribute. You can also add mixins to the item or product.
{ "type": "object", "$schema": "http://json-schema.org/draft-04/schema", "required": true, "properties": { "id": { "type": "string" }, "product": { "type": "object", "$ref": "product.json" }, "itemYrn": { "description": "The global resource identifier", "type": "string" }, "taxCode": { "description": "The tax code used to override the default site's tax value in tax calculation.", "type": "string" }, "quantity": { "type": "number", "minimum": 0 }, "price": { "description": "The price for the item.", "type": "object", "$ref": "priceRow.json" }, "metadata": { "type": "object", "$ref": "metadataRequest.json" }, "mixins": { "type": "object" } }, "required":["quantity", "price"] }Example:
{ "product": { "id": "pr0001abcdefghjk12340001", "yrn": "urn:yaas:hybris:product:product:myshop;pr0001abcdefghjk12340001", "description": "pr0001abcdefghjk12340001", "name": "pr0001abcdefghjk12340001", "images": [ { "url": "http://www.ystore.com/img001/pr0001abcdefghjk12340001.png" } ], "sku": "pr0001abcdefghjk12340001", "metadata": { "mixins": { "inventory": "https://api.beta.yaas.io/hybris/schema/b2/hybriscommerce/inventorySchema-v1" } }, "mixins": { "inventory": { "inStock": true } } }, "taxCode": "TaxCodeXYZ", "price": { "originalAmount": 10.0, "effectiveAmount": 10.0, "currency": "CAD", "priceId": "54f50fef620e7f00c2178f5c", "yrn":"urn:yaas:hybris:price:price:myshop;54f50fef620e7f00c2178f5c" "measurementUnit": { "unit":"kg", "quantity":"1" } }, "quantity": 1, "metadata": { "mixins": { "additionalCode": "https://api.beta.yaas.io/hybris/schema/v1/kiwistest/example-schema.json" } }, "mixins": { "additionalCode": { "code": "ABC" } } }
Response
- Status Code:
201 - Body:
{ "type": "object", "$schema": "http://json-schema.org/draft-04/schema", "required": false, "properties": { "itemId": { "type": "string", "required": "true" }, "yrn": { "type": "string", } } } Example: The response body contains the cart item ID (itemId) and YRN. You can use these IDs to update or delete the item from the cart. The first item added to the cart receives an item ID of "0". The second item receives an ID of "1", the third item receives a "2", and so on. The item IDs are not reassigned when an item is deleted from the cart.
{ "itemId": "0", "yrn": urn:yaas:hybris:cart:cart-item:myshop;57695027450dc3001d60e884;0" }
Add Multiple Items to the Cart in a Single Call
The add item in batch feature lets customers add multiple products to their cart in a single call. This feature is handy to have if you are a regular customer and you always have the same items on your shopping list. It saves the customer the hassle of finding each item on their list and adding it to their cart one at a time.
This feature is implemented using the batch processing API best practices. For more information, see Batch Processing.
Request
- Method: POST
- Request URL:
https://api.beta.yaas.io/hybris/cart/v1/{tenant}/carts/{cartId}/itemsBatch - Body: The request body must contain an array of cart item information. The quantity, price and product or itemYrn are mandatory. If a product has a specific tax code associated to it, the taxCode attribute must also be included in the schema. If the product price is based on a unit of measurement, then the measurementUnit attribute needs to be included in the price attribute. You can also add mixins to the item or product.
- Example:
[ { "product": { "id": "0001", "yrn": "urn:yaas:hybris:product:product-variant:myshop;0001;red", "description": "0001", "name": "0001", "images": [ { "url": "http://www.ystore.com/img001/0001.png" } ], "sku": "0001" }, "taxCode": "TaxCode001", "price": { "originalAmount": 10.0, "effectiveAmount": 10.0, "currency": "CAD", "priceId": "0001", "yrn":"urn:yaas:hybris:price:price:myshop;0001" }, "quantity": 1, "metadata": { "mixins": { "additionalCode": "https://api.beta.yaas.io/hybris/schema/v1/kiwistest/example-schema.json" } }, "mixins": { "additionalCode": { "code": "ABC" } } }, { "price": { "originalAmount": 55.55, "effectiveAmount": 55.55, "currency": "CAD", "priceId": "558c3ddf294eb05a5ed0c980", "yrn": "urn:yaas:hybris:price:price:myshop;558c3ddf294eb05a5ed0c980" }, "quantity": 5, "itemYrn": "urn:yaas:hybris:product:product-variant:myshop;productId004;red" }, { "price": { "originalAmount": 10.00, "effectiveAmount": 10.00, "currency": "CAD", "priceId": "0001", "yrn":"urn:yaas:hybris:price:id:myshop;0001" }, "taxCode": "TaxCode001", "quantity": 5, "itemYrn": "urn:yaas:hybris:product:product-variant:myshop;0001;red" } ]
Response
If all of the items were successfully added to the cart, the response includes a 200 status code, the identifier ID for each item, YRN for each item, and the location of the created resource.
- Status Code:
200 - Example: The response body contains the details for every batch item.
[ { "status": 200, "id": "0", "headers": { "location": "/carts/57ac9229381456001d80f5c7/items/0" } }, { "status": 200, "id": "1", "headers": { "location": "/carts/57ac9229381456001d80f5c7/items/1" } }, { "status": 200, "id": "2", "headers": { "location": "/carts/57ac9229381456001d80f5c7/items/2" } } ]
If all of the items were not successfully added to the cart, you will receive an overall 400 status code. For every successful item added to the cart, you will receive an identifier ID and the location of the created resource, and for every item that was not added to the cart, you will receive an error description (as shown below).
- Status Code:
400 - Example: The response body contains the details for each single batch item.
[ { "status": 200, "id": "0", "yrn": urn:yaas:hybris:cart:cart-item:myshop;57695027450dc3001d60e884;0" "headers": { "location": "/carts/0001/items/0" } }, { "status": 400, "errorMessage": "The item can not be added, the currency of the cart (USD) is not the same as the item (CAD)" }, { "status": 400, "errorMessage": "Only one of the following can be provided product information or itemYrn." }, { "status": 400, "errorMessage": "You must provide at least one of the two following information itemYrn or the product." } ]
Add Discount to Cart
A discount can be applied to the cart either as a dollar value discount (such as $10 off), or as a percentage discount (such as 10% off). The discount is always applied to the subtotal of the cart, but you can choose to apply the discount before or after the tax has been applied. When a discount is added to the cart, a call is made to the Coupon service to validate the discount. For more details about the discount feature, its attributes, and how it is applied to the cart, see Discounts.
In this example, a dollar value discount is added to the cart. You can apply a percentage discount to the cart in the same manner.
Request
- Method: POST
- Request URL:
https://api.beta.yaas.io/hybris/cart/v1/{tenant}/carts/{cartId}/discounts - Body: The request body must contain these attributes:
- Discount code (code)
- Discount amount (amount) or discount rate (discountRate)
- Currency (currency)
- The sequenceId attribute is optional. It is only necessary if there are multiple discounts that must be applied in a specific order.
{ "$schema": "http://json-schema.org/schema#", "description": "Discount applied to the cart or cart item.", "type": "object", "properties": { "id": { "required": false, "type": "string" }, "couponYrn": { "type": "string" }, "code": { "type": "string", "description":"The discount code.", "required": true, "maxLength" : "150" }, "amount": { "type": "number", "description":"The fixed price of the discount.", "minimum" : 0 }, "currency": { "description": "The currency code following the ISO 4217 standard.", "type": "string", "required": true, "pattern" : "[A-Z]{3}" }, "name": { "type": "string", "description":"The discount display name.", "maxLength" : "150" }, "discountRate": { "type": "number", "description":"The percentage value of the discount.", "minimum" : 0 }, "sequenceId": { "type": "integer", "description":"The sequence of this discount to be applied to cart.", "default":1 }, "calculationType": { "type": "string", "description":"Possible Values are ApplyDiscountBeforeTax, ApplyDiscountAfterTax. The calculation type to be applied while calculating the discounts.", "maxLength" : "30", "default": "ApplyDiscountBeforeTax" }, "links": { "type": "array", "items": { "$ref": "link" }, "minItems" : "2" } } }
- Example:
{ "amount": 10.0, "code": "DISC1", "couponYrn":"urn:yaas:hybris:coupon:couponCode:myshop;DISC1", "currency": "CAD", "links": [ { "rel": "validate", "href": "http://www.ystore.com/coupons/123", "type": "application/json", "title": "Discounts" }, { "rel": "redeem", "href": "http://www.ystore.com/coupons/123/redemptions", "type": "application/json", "title": "DiscountsRedeem" } ], "sequenceId": 1 }
Response
- Status Code:
201 Body: The response body returns the discount ID (discountId) and YRN. Each discount you add receives its own discount ID. This ID is used to remove the discount from the cart, if necessary.
{ "type": "object", "$schema": "http://json-schema.org/draft-04/schema", "required": false, "properties": { "discountId": { "type": "string", "required": true }, "yrn": { "type": "string" } } }- Example:
{ "discountId": "0", "yrn": "urn:yaas:hybris:cart:cart-discount:myshop;57695027450dc3001d60e884;0" }
Update Cart with Mixins
For an existing cart, you can add mixins to the cart or update existing mixins you had already added to your cart. The mixins can be added to the cart, cart item, or product (within the cart item) level. To add or update a mixin, you can use the existing schema method or the inline schema method. For more information about mixins the existing and inline schemas, see Extend Cart Information.
When you update the mixins in your cart, you can do a partial or a full update. A partial update will add the new mixin or update the value of the existing mixin in the cart. A full update would update the entire cart with the values sent in the request.
The following example shows you how to add a mixin (using the inline schema method) when you update a cart.
Request
- Method: PUT
- Request URL:
https://api.beta.yaas.io/hybris/cart/v1/{tenant}/carts/{cartId} - Body:
{ "metadata": { "mixins": { "additionalCode": { "type": "object", "$schema": "http://json-schema.org/draft-04/schema", "properties": { "version": { "type": "integer", "minimum": 1 } } } } }, "mixins":{ "additionalCode": { "version": 2 } } }
Response
- Status Code:
204
Update an Item's Quantity
You can update the quantity of a single product or multiple products in the cart. There are two ways you can update the quantity of an item that already exists in the cart:
- The customer adds the same item that already exists in the cart.
- The customer updates the quantity of the existing item in the cart.
Add the same item that already exists in the cart
If an item is already in the cart, you can increase the quantity of that item by selecting the item again and adding it to the cart. The result of this request is that the quantity of the selected item is added to the existing quantity. However, if your item is defined by an itemYrn and the same item in the cart is defined by a product object, then the quantity of the items will not be added together. Instead the item with an itemYrn will be added as the second item to the cart.
Request
- Method: POST
- Request URL:
https://api.beta.yaas.io/hybris/cart/v1/{tenant}/carts/{cartId}/items - Header: The hybris-resource-version header is an optional optimistic locking header that is only required if you have previously used it for other POST or PUT cart requests. Make sure you know what the current version number is by performing a request to retrieve cart details.
- Body: The request body must contain the information about the item in the cart whose quantity is to be incremented (by one). The product, quantity, and price attributes are required:
{ "type": "object", "$schema": "http://json-schema.org/draft-04/schema", "required": true, "properties": { "id": { "required": false, "type": "string" }, "product": { "type": "object", "required": "true", "$ref": "product" }, "quantity": { "type": "number", "required": "true", "minimum": "0" }, "price": { "description": "The price for the item.", "type": "object", "required": "true", "$ref": "priceRow" }, "totalItemPrice": { "description": "cartItem totalPrice is calculated by multiplying the quantity by the item’s unit price", "$ref": "price", "required": false } } } Example:
{ "product": { "id": "pr0001abcdefghjk12340001", "yrn": "urn:yaas:hybris:product:product:myshop;pr0001abcdefghjk12340001", "description": "pr0001abcdefghjk12340001", "name": "pr0001abcdefghjk12340001", "images": [ { "url": "http://www.ystore.com/img001/pr0001abcdefghjk12340001.png" } ], "sku": "pr0001abcdefghjk12340001" }, "price": { "originalAmount": 60.0, "effectiveAmount": 55.5, "currency": "CAD", "priceId": "54f50fef620e7f00c2178f5c", "yrn":"urn:yaas:hybris:price:price:myshop;54f50fef620e7f00c2178f5c", }, "quantity": 1 }
Response
- Status Code:
201 - Body:
{ "type": "object", "$schema": "http://json-schema.org/draft-04/schema", "required": false, "properties": { "itemId": { "type": "string", "required": "true" } } } - Example: The response body returns the cart item ID (itemId) of the item that already exists in the cart.
{ "itemId": "0" }
Update a cart item quantity
You can increase or decrease the quantity of each item in the cart.
Request
- Method: PUT
- Request URL:
https://api.beta.yaas.io/hybris/cart/v1/{tenant}/carts/{cartId}/items/{itemId}
ORhttps://api.beta.yaas.io/hybris/cart/v1/{tenant}/carts/{cartId}/items/{itemId}?partial=trueFor doing a partial update on a cart item and not sending all the information again. - Headers: The hybris-resource-version header is an optional optimistic locking header and is only mandatory if you have previously used it for other POST or PUT cart requests. Make sure you know what the current version number is by performing a retrieve cart details request.
- Example: The request body may contain all the information about the item in the cart whose quantity is to be modified, or only the quantity attribute if the request is to do a partial update:
{
"quantity": 5
}
Response
- Status Code:
204
Update Cart Item Price
Updating a product's price on the website does not automatically update the item's price if it is already in a customer's cart. To ensure that the item's price is also updated in the cart, you must perform this request.
Request
- Method: PUT
- Request URL:
https://api.beta.yaas.io/hybris/cart/v1/{tenant}/carts/{cartId}/{itemId}ORhttps://api.beta.yaas.io/hybris/cart/v1/{tenant}/carts/{cartId}/{itemId}?partial=true(to perform a partial update on cart item and not sending all the information again) - Header: The hybris-resource-version header is an optional optimistic locking header that is only required if you have previously used it for other POST or PUT cart requests. Make sure you know what the current version number is by performing a request to retrieve the cart details.
- Body: The request body may contain all the information about the item in the cart whose price is to be modified, or only the price attribute if the request is to do a partial update. If it contains all the information, you can add mixins as you update the price.
- Example:
{ "product": { "id": "pr0001abcdefghjk12340002", "yrn": "urn:yaas:hybris:product:product:myshop;pr0001abcdefghjk12340002", "description": "pr0001abcdefghjk12340002", "name": "pr0001abcdefghjk12340002", "metadata": { "mixins": { "inventory": "https://api.beta.yaas.io/hybris/schema/b2/hybriscommerce/inventorySchema-v1" } }, "mixins": { "inventory": { "inStock": true } }, "images": [ { "url": "http://www.ystore.com/img001/pr0001abcdefghjk12340002.png" } ], "sku": "pr0001abcdefghjk12340002" }, "price": { "originalAmount": 60.0, "effectiveAmount": 55.5, "currency": "CAD", "priceId": "54f50fef620e7f00c2178f5c", "yrn":"urn:yaas:hybris:price:price:myshop;54f50fef620e7f00c2178f5c", "measurementUnit":{ "unit":"kg", "quantity":"1" } }, "quantity": 5, "metadata": { "mixins": { "additionalCode": "https://api.beta.yaas.io/hybris/schema/v1/kiwistest/example-schema.json" } }, "mixins": { "additionalCode": { "code": "ABC" } } }
Response
- Status Code:
204
Update the Cart's Customer Information
A situation can arise where the customer's ID (either customer ID or session ID) is no longer valid and a new ID is created. If this occurs while the customer is shopping, the ID needs to be updated to make sure the customer does not lose their cart.
To update a customer ID or a session ID you need to have administrative rights. That means you need to use the hybris.cart_manage scope to perform this action.
Update the cart's customer ID
The customer ID is the identifier of a user who has a registered account on that site. This request demonstrates how an administrator updates the customer ID assigned to a cart.
Request
- Method: PUT
- Request URL:
https://api.beta.yaas.io/hybris/cart/v1/{tenant}/carts/{cartId} - Header: The hybris-resource-version header is an optional optimistic locking header that is only required if you have previously used it for other POST or PUT cart requests. Make sure you know what the current version number is by performing a request to retrieve the cart details.
- Example:
{ "customerId": "123dc455cb4e6cc7d8f57493" }
Response
- Status Code:
204
Update the cart's session ID
If a customer does not sign in to an account when they enter a site, they are seen as an anonymous user, and a session ID is assigned. The session ID is created by the Account service and then passed to the Cart service when a cart is created. This request demonstrates how an administrator can update the session ID.
Request
- Method: PUT
- Request URL:
https://api.beta.yaas.io/hybris/cart/v1/{tenant}/carts/{cartId} Header: The hybris-resource-version header is an optional optimistic locking header that is only required if you have previously used it for other POST or PUT cart requests. Make sure you know what the current version number is by performing a request to retrieve the cart details.
Example:
{ "sessionId": "Sap1412193542932" }
Response
- Status Code:
204
Update the Cart Status
A cart can be associated with only two status values: open or closed.
- When a cart is created, it is automatically associated with status
open. - When a cart is
open, you can add, update, retrieve, or delete items in the cart. - When a cart is successfully checked out by a customer or an anonymous user, the status of the cart automatically gets updated to
closed. - The status of an open cart can be updated to
closed, as shown in the example below. However, the status of a closed cart cannot be updated toopen. - Once a cart is
closed, the cart can no longer be accessed. If the customer or anonymous user wants to continue shopping, a new cart must be created.
Request
- Method: PUT
- Request URL:
https://api.beta.yaas.io/hybris/cart/v1/{tenant}/carts/{cartId} - Header: The hybris-resource-version is an optional optimistic locking header that is only required if you have previously used it for other POST or PUT cart requests. Make sure you know what the most current version number is by performing a request to retrieve cart details.
- Example:
{ "status": "CLOSED" }
Response
- Status Code:
204
Update the Cart Information
After a cart is created, you can update these cart attributes:
- Customer ID
- Currency
- Status
- Channel
- mixins (if applicable)
- ZIP Code (if applicable)
- Country code (if applicable)
The ZIP Code and country code attributes are needed if you plan on using the Avalara Tax service for your tax calculation. (These attributes are not needed if you are using the Tax service.) Be aware that you need to use both the ZIP Code and country code attributes for the tax calculation to be successful.
Request
- Method: PUT
- Request URL:
https://api.beta.yaas.io/hybris/cart/v1/{tenant}/carts/{cartId} - Header: The hybris-resource-version header is an optional optimistic locking header that is only required if you have previously used it for other POST or PUT cart requests. Make sure you know what the current version number is by performing a request to retrieve cart details.
- Example:
{ "zipCode": "J3E1L4", "countryCode": "CA", "channel": { "name": "yaas-storefront", "source": "http://shops.yaas.io/" } }
Response
- Status Code:
204
Update the Cart Item Information
After an item is added to the cart, you can update these cart item attributes:
- Product object or itemYrn
- Quantity
- TaxCode
- Price object
- Cart item mixins (if applicable)
- Metadata object
You can do both a partial as well as a full update of the cart item's itemYrn attribute value. However, in order to successfully update the cart item's itemYrn attribute to a product object, you have to perform a full update of the cart item.
Request
- Method: PUT
- Request URL:
https://api.beta.yaas.io/hybris/cart/v1/{tenant}/carts/{cartId}/items/{itemId}?partial=true - Header: The hybris-resource-version header is an optional optimistic locking header that is only required if you have previously used it for other POST or PUT cart requests. Make sure you know what the current version number is by performing a request to retrieve cart details.
- Example:
{ "itemYrn": "urn:yaas:hybris:product:product-variant:myshop;productId008;white" }
Response
- Status Code:
204
Change Cart Site
You can use the cart's siteCode attribute to change the site to which the cart is assigned. This feature ensures items in the cart are not lost when you change the site. The customer can initially shop on one site (for example, Canada), add items to their cart, and then change their site to another (like the United States). Another example of how you can use this feature is to have the customer shop on one site as an anonymous user and then when they log in, the site changes to their registered site. When you change a cart's site, you are changing the language, currency, shipping zone, tax, and payment settings. For more information on the site settings, see Site.
When you execute a change site request and there are items in the cart, the match currency request in the Price service is automatically triggered. The match currency request ensures that the items in the cart have a corresponding price in the new currency of the new site. If there isn't a price in the currency of the new site, the change cart site request fails and an error is returned. If the match currency request is successful, the cart's site is changed and the prices of the items in the cart are updated.
If you change the cart site of an empty cart, the match currency request is not triggered and the site code of the cart is updated.
Request
- Method: POST
- Request URL:
https://api.beta.yaas.io/hybris/cart/v1/{tenant}/carts/{cartId}/changeSite - Header: The hybris-resource-version is an optional optimistic locking header. It is only required if you have previously used it for other POST or PUT cart requests. Make sure you know what the most current version number is by performing a request to retrieve the cart details.
- Example:
{ "siteCode": "canada" }
Response
- Status Code:
200
Merge an Anonymous Cart with a Registered Cart
A customer can begin shopping on a site without having to sign in first. If the customer decides to create or sign in to an account while they are shopping, you can use the merge carts functionality to ensure that the items in their anonymous cart are moved to their registered cart.
The merge carts functionality combines the items in an anonymous cart with the items in a registered cart that belong to the same customer. The merged cart has the cart ID associated with the registered customer. The anonymous cart ID is deleted. After the two carts are merged, the customer can continue to perform tasks such as adding, deleting, or modifying items in the cart until checkout.
The URL contains the tenant ID as well as the cart ID of the registered cart. The request body contains the anonymous cart ID. For more information, see Merge Carts.
Request
- Method: POST
- Request URL:
https://api.beta.yaas.io/hybris/cart/v1/{tenant}/carts/{cartId}/merge - Header: The hybris-resource-version is an optional optimistic locking header that is only required if you have previously used it for other POST or PUT cart requests. Make sure you know what the most current version number is by performing a request to retrieve cart details.
- Example:
{ "carts": [ "54736692e34ed3e05160ef8c" ] }
Response
- Status Code:
200
Retrieve Item Details From the Cart
You can retrieve the details of a single item or all the items in a cart.
Retrieve all the items in a cart
This information is returned for each item when retrieving the details of all the items in the cart:
- Resource version number (if applicable)
- Item ID
- Item ID yrn (yrn attribute)
- Item product details or itemYrn
- Item quantity
- Item price (measurementUnit attribute is optional)
- Item tax code (if applicable)
- Item/product mixin (if applicable)
- Item fee(s) (if applicable)
Request
- Method: GET
- Request URL:
https://api.beta.yaas.io/hybris/cart/v1/{tenant}/carts/{cartId}/items
Response
- Status Code:
200 - Example:
[ { "id": "0", "product": { "description": "sku3", "id": "sku3", "yrn": "urn:yaas:hybris:product:product:myshop;sku3", "sku": "sku3", "name": "sku3" }, "quantity": 1.0, "taxCode": "A400", "itemPrice": { "amount": 55.55, "currency": "CAD" }, "itemTaxInfo": [ { "rate": 10.0, "name": "tax override off 10%", "value": { "amount": 5.55 } } ], "price": { "effectiveAmount": 55.55, "priceId": "558c3db209eeea511e089251", "yrn":"urn:yaas:hybris:price:price:myshop;558c3db209eeea511e089251", "originalAmount": 55.55, "currency": "CAD" "measurementUnit":{ "unit":"kg", "quantity":1 } } }, { "id": "1", "itemYrn": "urn:yaas:hybris:product:product:myshop;sku4", "quantity": 3.0, "itemPrice": { "amount": 166.65, "currency": "CAD" }, "itemTaxInfo": [ { "name":"GST/PST", "rate": 15.0, "value": { "amount": 25.0 } } ], "price": { "effectiveAmount": 55.55, "priceId": "558c3db2918e6f965584833c", "yrn":"urn:yaas:hybris:price:price:myshop;558c3db2918e6f965584833c", "originalAmount": 55.55, "currency": "CAD" }, "fees": { "elements": [ { "yrn": "urn:yaas:saas-ag:fee:id:myshop;581b6655f36281001da5d079", "taxCode": "A400", "total": { "subTotal": 10, "totalTax": 1.00, "total": 11.00 }, "taxValues": [ { "name": "tax override off 10%", "value": { "amount": 1.0 }, "rate": 10.0 } ] }, { "yrn": "urn:yaas:saas-ag:fee:id:myshop;581b6655f36281001da5d079", "taxCode": "A400", "total": { "subTotal": 45.00, "totalTax": 4.50, "total": 49.50 }, "taxValues": [ { "name": "tax override off 10%", "value": { "amount": 4.5 }, "rate": 10.0 } ] } ], "total": { "subTotal": 55.00, "totalTax": 5.50, "total": 60.50 } } } ]
Retrieve details for a single item in the cart
This request retrieves the details for a single item in the cart. For this request, you need the cart ID and item ID.
This information is returned when retrieving the details of a single item in the cart:
- Item ID
- Item ID yrn (yrn attribute)
- Item product details or itemYrn
- Item quantity
- Item price (measurementUnit attribute is optional)
- Item tax code (if applicable)
- Item/product mixin (if applicable)
Request
- Method: GET
- Request URL:
https://api.beta.yaas.io/hybris/cart/v1/{tenant}/carts/{cartId}/items/{itemId}
Response
- Status Code:
200 - Example:
{ "id": "1", "itemYrn": "urn:yaas:hybris:product:product:myshop;sku4", "quantity": 3.0, "itemPrice": { "amount": 166.65, "currency": "CAD" }, "itemTaxInfo": [ { "name":"GST/PST", "rate": 15.0, "value": { "amount": 25.0 } } ], "price": { "effectiveAmount": 55.55, "priceId": "558c3db2918e6f965584833c", "yrn":"urn:yaas:hybris:price:price:myshop;558c3db2918e6f965584833c", "originalAmount": 55.55, "currency": "CAD" }, "fees": { "elements": [ { "yrn": "urn:yaas:saas-ag:fee:id:myshop;581b6655f36281001da5d079", "taxCode": "A400", "total": { "subTotal": 10, "totalTax": 1.00, "total": 11.00 }, "taxValues": [ { "name": "tax override off 10%", "value": { "amount": 1.0 }, "rate": 10.0 } ] }, { "yrn": "urn:yaas:saas-ag:fee:id:myshop;581b6655f36281001da5d079", "taxCode": "A400", "total": { "subTotal": 45.00, "totalTax": 4.50, "total": 49.50 }, "taxValues": [ { "name": "tax override off 10%", "value": { "amount": 4.5 }, "rate": 10.0 } ] } ], "total": { "subTotal": 55.00, "totalTax": 5.50, "total": 60.50 } } }
Retrieve Cart Details by ID
You can retrieve the cart details by performing a request with:
- the cart ID (you can retrieve both the cart and calculation details or only the cart details),
- the Hybris user header (for a registered user), or the session ID header (for an anonymous user), or
- the customer ID
The difference between retrieving the item details and retrieving the cart details is that the cart details provide you with all the item details, as well as these calculation fields:
- Total price for each item
- Cart subtotal
- Total units in the cart
- Total cart price
- Tax for each item (optional)
- Total tax (optional)
- Shipping method fee (optional)
- Discount (optional)
- Total, subtotal, and tax total for each item fee in the cart (optional)
- Total, subtotal, and tax total of the sum of the item fees for an item (optional)
- Total, subtotal, and tax total of the sum of each item fee for all the items (optional)
- Fee aggregate for each fee YRN in the cart (optional)
The item tax and the total tax are both optional fields and are only returned if you have either the Tax service or the Avalara Tax service configured. For more information about tax configuration, see Tax and Avalara Tax.
If you have the Avalara Tax service configured, the tax fields are only returned if you update the cart with these two attributes:
- countryCode: The country code to be considered in the tax service (such as
CA). - zipCode: The ZIP Code for the desired country.
Similarly, the Shipping service information must be configured for the shipping method fee to appear in the cart details. For details about managing shipping configurations and setting up zones and shipping method fees for a given site and tenant, see Site and Shipping.
The discount field is optional and is only returned if an existing discount in the Coupon service is added to the cart. For more details about discounts, see Discounts.
The values of these fields are calculated when you perform a retrieve cart request. To understand how the cart is calculated, see the Cart Calculation Process page.
Retrieve cart and calculation details by cart ID
When you retrieve a cart ID, you can select whether to retrieve the cart and calculation details or only the cart details. The following request retrieves both the cart and calculation details.
Request
- Method: GET
- Request URL:
https://api.beta.yaas.io/hybris/cart/v1/{tenant}/cart/{cartId}
Response
- Status Code:
200 - Example:
{ "metadata": { "createdAt":"2015-01-02T10:12:40", "modifiedAt":"2015-01-02T10:12:40", "version": 1, "mixins":{ "commentMixin":"commentSchemaUri" } }, "id": "558c3dad54ce90d486a0eca4", "yrn": "urn:yaas:hybris:cart:cart:myshop;558c3dad54ce90d486a0eca4", "customerId": "C1435254189557", "currency": "CAD", "siteCode": "canada", "channel": { "name": "yaas-storefront", "source": "http://shops.yaas.io/" }, "zipCode": "J3E1L4", "countryCode": "CA", "subTotalPrice": { "amount": 222.2, "currency": "CAD" }, "shipping": { "fee": { "amount":100.00, "currency":"CAD" } }, "totalUnitsCount": 4.0, "totalTax": { "amount": 51.05, "currency": "CAD" }, "totalDiscount": { "amount": 0, "currency": "CAD" }, "totalPrice": { "amount": 428.25, "currency": "CAD" }, "items": [ { "id": "0", "product": { "description": "sku3", "id": "sku3", "yrn": "urn:yaas:hybris:product:product:myshop;sku3", "sku": "sku3", "name": "sku3" }, "quantity": 1.0, "taxCode": "A400", "itemPrice": { "amount": 55.55, "currency": "CAD" }, "itemTaxInfo": [ { "rate": 10.0, "name": "tax override off 10%", "value": { "amount": 5.55 } } ], "price": { "effectiveAmount": 55.55, "priceId": "558c3db209eeea511e089251", "yrn":"urn:yaas:hybris:price:price:myshop;558c3db209eeea511e089251", "originalAmount": 55.55, "currency": "CAD" "measurementUnit":{ "unit":"kg", "quantity":1 } } }, { "id": "1", "itemYrn": "urn:yaas:hybris:product:product:myshop;sku4", "quantity": 3.0, "itemPrice": { "amount": 166.65, "currency": "CAD" }, "itemTaxInfo": [ { "name":"GST/PST", "rate": 15.0, "value": { "amount": 25.0 } } ], "price": { "effectiveAmount": 55.55, "priceId": "558c3db2918e6f965584833c", "yrn":"urn:yaas:hybris:price:price:myshop;558c3db2918e6f965584833c", "originalAmount": 55.55, "currency": "CAD" }, "fees": { "elements": [ { "yrn": "urn:yaas:saas-ag:fee:id:myshop;581b6655f36281001da5d079", "taxCode": "A400", "total": { "subTotal": 10, "totalTax": 1.00, "total": 11.00 }, "taxValues": [ { "name": "tax override off 10%", "value": { "amount": 1.0 }, "rate": 10.0 } ] }, { "yrn": "urn:yaas:saas-ag:fee:id:myshop;581b6655f36281001da5d079", "taxCode": "A400", "total": { "subTotal": 45.00, "totalTax": 4.50, "total": 49.50 }, "taxValues": [ { "name": "tax override off 10%", "value": { "amount": 4.5 }, "rate": 10.0 } ] } ], "total": { "subTotal": 55.00, "totalTax": 5.50, "total": 60.50 } } } ], "itemFeesTotal": { "subTotal": 55.00, "totalTax": 5.50, "total": 60.50 }, "paymentFeesTotal": { "subTotal": 0.0, "totalTax": 0.0, "total": 0.0 }, "mixins":{ "commentMixin":{ "cartComment": "Comment1" } }, "taxAggregate" : { "lines": [ { "name": "GST/PST", "rate": 15.0, "amount": 40.0, "taxable" : 266.65 }, { "name": "tax override off 10%", "rate": 10.0, "amount": 11.05, "taxable" : 105.05 } ] } }
Retrieve only the cart details by cart ID
By default, the expandCalculation query parameter is set to true which retrieves both the cart and calculation details. If the query parameter is set to false, then the response only contains the cart details. The following request retrieves only the cart details.
Request
- Method: GET
- Request URL:
https://api.beta.yaas.io/hybris/cart/v1/{tenant}/cart/{cartId}?expandCalculation=false
Response
- Status Code:
200 - Example:
{ "id": "565dd286462e8ad5f54dae6c", "yrn": "urn:yaas:hybris:cart:cart:myshop;57695027450dc3001d60e884", "customerId": "priceless@hybristest.com", "currency": "CAD", "siteCode": "default", "items": [ { "id": "0", "product": { "id": "SKU0011448989367603", "yrn": "urn:yaas:hybris:product:product:myshop;SKU0011448989367603", "sku": "SKU0011448989367603", "name": "SKU0011448989367603", "description": "SKU0011448989367603", "images": [ { "id": "abc123", "url": "http://localhost/img01SKU0011448989367603.png" } ] }, "quantity": 2.0, "price": { "priceId": "price11448989336042", "originalAmount": 55.5, "effectiveAmount": 55.5, "currency": "CAD" } }, { "id": "1", "product": { "id": "SKU0021448989367888", "yrn": "urn:yaas:hybris:product:product:myshop;SKU0021448989367888", "sku": "SKU0021448989367888", "name": "SKU0021448989367888", "description": "SKU0021448989367888", "images": [ { "id": "abc123", "url": "http://localhost/img01SKU0021448989367888.png" } ] }, "quantity": 2.0, "price": { "priceId": "price21448989336042", "originalAmount": 55.5, "effectiveAmount": 55.5, "currency": "CAD" } } ], "sessionId": "2345-6789-0908-7654-3212-0001", "metadata": { "createdAt": "2015-12-01T17:01:58.430Z", "modifiedAt": "2015-12-01T17:02:32.472Z", "version": 3 } }
Retrieve cart details by header ID
This request is used by the customer to retrieve their cart. The same request URL can be used by both a registered and an anonymous customer. The header (hybris-user or hybris-session-id) is the identifier of the account/anonymous user and is provided automatically when the request passes through the proxy.
The following example shows the retrieval of a registered user's cart.
Request
- Method: GET
- Request URL:
https://api.beta.yaas.io/hybris/cart/v1/{tenant}/carts?siteCode={siteCode} - Header:
- hybris-user: 123dc455cb4e6cc7d8f57493
- hybris-user: 123dc455cb4e6cc7d8f57493
The site code is an optional attribute used to ensure that the correct cart is retrieved. If a site code was used to create the cart, you need to include the site code in order to retrieve it. If you don't provide the site code, then the site code named 'default' will be used.
Response
- Status Code:
200 - Example:
{ "metadata": { "createdAt":"2015-01-02T10:12:40", "modifiedAt":"2015-01-02T10:12:40", "version": 1, "mixins":{ "commentMixin":"commentSchemaUri" } }, "id": "558c3dad54ce90d486a0eca4", "yrn": "urn:yaas:hybris:cart:cart:myshop;558c3dad54ce90d486a0eca4", "customerId": "C1435254189557", "currency": "CAD", "siteCode": "canada", "channel": { "name": "yaas-storefront", "source": "http://shops.yaas.io/" }, "zipCode": "J3E1L4", "countryCode": "CA", "subTotalPrice": { "amount": 222.2, "currency": "CAD" }, "shipping": { "fee": { "amount":100.00, "currency":"CAD" } }, "totalUnitsCount": 4.0, "totalTax": { "amount": 51.05, "currency": "CAD" }, "totalDiscount": { "amount": 0, "currency": "CAD" }, "totalPrice": { "amount": 428.25, "currency": "CAD" }, "items": [ { "id": "0", "product": { "description": "sku3", "id": "sku3", "yrn": "urn:yaas:hybris:product:product:myshop;sku3", "sku": "sku3", "name": "sku3" }, "quantity": 1.0, "taxCode": "A400", "itemPrice": { "amount": 55.55, "currency": "CAD" }, "itemTaxInfo": [ { "rate": 10.0, "name": "tax override off 10%", "value": { "amount": 5.55 } } ], "price": { "effectiveAmount": 55.55, "priceId": "558c3db209eeea511e089251", "yrn":"urn:yaas:hybris:price:price:myshop;558c3db209eeea511e089251", "originalAmount": 55.55, "currency": "CAD" "measurementUnit":{ "unit":"kg", "quantity":1 } } }, { "id": "1", "itemYrn": "urn:yaas:hybris:product:product:myshop;sku4", "quantity": 3.0, "itemPrice": { "amount": 166.65, "currency": "CAD" }, "itemTaxInfo": [ { "name":"GST/PST", "rate": 15.0, "value": { "amount": 25.0 } } ], "price": { "effectiveAmount": 55.55, "priceId": "558c3db2918e6f965584833c", "yrn":"urn:yaas:hybris:price:price:myshop;558c3db2918e6f965584833c", "originalAmount": 55.55, "currency": "CAD" }, "fees": { "elements": [ { "yrn": "urn:yaas:saas-ag:fee:id:myshop;581b6655f36281001da5d079", "taxCode": "A400", "total": { "subTotal": 10, "totalTax": 1.00, "total": 11.00 }, "taxValues": [ { "name": "tax override off 10%", "value": { "amount": 1.0 }, "rate": 10.0 } ] }, { "yrn": "urn:yaas:saas-ag:fee:id:myshop;581b6655f36281001da5d079", "taxCode": "A400", "total": { "subTotal": 45.00, "totalTax": 4.50, "total": 49.50 }, "taxValues": [ { "name": "tax override off 10%", "value": { "amount": 4.5 }, "rate": 10.0 } ] } ], "total": { "subTotal": 55.00, "totalTax": 5.50, "total": 60.50 } } } ], "itemFeesTotal": { "subTotal": 55.00, "totalTax": 5.50, "total": 60.50 }, "paymentFeesTotal": { "subTotal": 0.0, "totalTax": 0.0, "total": 0.0 }, "mixins":{ "commentMixin":{ "cartComment": "Comment1" } }, "taxAggregate" : { "lines": [ { "name": "GST/PST", "rate": 15.0, "amount": 40.0, "taxable" : 266.65 }, { "name": "tax override off 10%", "rate": 10.0, "amount": 11.05, "taxable" : 105.05 } ] } }
Retrieve cart details by customer ID
Retrieving the cart details by using the customer ID can only be executed by the administrator as it needs the hybris.cart_manage scope.
Request
- Method: GET
- Request URL:
https://api.beta.yaas.io/hybris/cart/v1/{tenant}/carts?customerId={customerId}&siteCode={siteCode} - Header:
- hybris-scopes: hybris.cart_manage
The site code is an optional attribute used to ensure that the correct cart is retrieved. If a site code was used to create the cart, you need to include the site code in order to retrieve it. If you don't provide the site code, then the site code named 'default' will be used.
Response
- Status Code:
200 - Example:
{ "metadata": { "createdAt":"2015-01-02T10:12:40", "modifiedAt":"2015-01-02T10:12:40", "version": 1, "mixins":{ "commentMixin":"commentSchemaUri" } }, "id": "558c3dad54ce90d486a0eca4", "yrn": "urn:yaas:hybris:cart:cart:myshop;558c3dad54ce90d486a0eca4", "customerId": "C1435254189557", "currency": "CAD", "siteCode": "canada", "channel": { "name": "yaas-storefront", "source": "http://shops.yaas.io/" }, "zipCode": "J3E1L4", "countryCode": "CA", "subTotalPrice": { "amount": 222.2, "currency": "CAD" }, "shipping": { "fee": { "amount":100.00, "currency":"CAD" } }, "totalUnitsCount": 4.0, "totalTax": { "amount": 51.05, "currency": "CAD" }, "totalDiscount": { "amount": 0, "currency": "CAD" }, "totalPrice": { "amount": 428.25, "currency": "CAD" }, "items": [ { "id": "0", "product": { "description": "sku3", "id": "sku3", "yrn": "urn:yaas:hybris:product:product:myshop;sku3", "sku": "sku3", "name": "sku3" }, "quantity": 1.0, "taxCode": "A400", "itemPrice": { "amount": 55.55, "currency": "CAD" }, "itemTaxInfo": [ { "rate": 10.0, "name": "tax override off 10%", "value": { "amount": 5.55 } } ], "price": { "effectiveAmount": 55.55, "priceId": "558c3db209eeea511e089251", "yrn":"urn:yaas:hybris:price:price:myshop;558c3db209eeea511e089251", "originalAmount": 55.55, "currency": "CAD" "measurementUnit":{ "unit":"kg", "quantity":1 } } }, { "id": "1", "itemYrn": "urn:yaas:hybris:product:product:myshop;sku4", "quantity": 3.0, "itemPrice": { "amount": 166.65, "currency": "CAD" }, "itemTaxInfo": [ { "name":"GST/PST", "rate": 15.0, "value": { "amount": 25.0 } } ], "price": { "effectiveAmount": 55.55, "priceId": "558c3db2918e6f965584833c", "yrn":"urn:yaas:hybris:price:price:myshop;558c3db2918e6f965584833c", "originalAmount": 55.55, "currency": "CAD" }, "fees": { "elements": [ { "yrn": "urn:yaas:saas-ag:fee:id:myshop;581b6655f36281001da5d079", "taxCode": "A400", "total": { "subTotal": 10, "totalTax": 1.00, "total": 11.00 }, "taxValues": [ { "name": "tax override off 10%", "value": { "amount": 1.0 }, "rate": 10.0 } ] }, { "yrn": "urn:yaas:saas-ag:fee:id:myshop;581b6655f36281001da5d079", "taxCode": "A400", "total": { "subTotal": 45.00, "totalTax": 4.50, "total": 49.50 }, "taxValues": [ { "name": "tax override off 10%", "value": { "amount": 4.5 }, "rate": 10.0 } ] } ], "total": { "subTotal": 55.00, "totalTax": 5.50, "total": 60.50 } } } ], "itemFeesTotal": { "subTotal": 55.00, "totalTax": 5.50, "total": 60.50 }, "paymentFeesTotal": { "subTotal": 0.0, "totalTax": 0.0, "total": 0.0 }, "mixins":{ "commentMixin":{ "cartComment": "Comment1" } }, "taxAggregate" : { "lines": [ { "name": "GST/PST", "rate": 15.0, "amount": 40.0, "taxable" : 266.65 }, { "name": "tax override off 10%", "rate": 10.0, "amount": 11.05, "taxable" : 105.05 } ] } }
Delete Items From the Cart
You can remove a single item or all the items from the cart.
Delete all items from the cart.
You can use this request to delete all the items from a cart. You need the cart ID (cartId) to perform this request. Deleting all the items from the cart does not delete the cart itself. To delete the cart, you must delete the cart ID.
Request
- Method: DELETE
- Request URL:
https://api.beta.yaas.io/hybris/cart/v1/{tenant}/carts/{cartId}/items
Response
- Status Code:
204
Delete a specific item from the cart
You can use this request to delete a specific item from a cart. You need the cart ID (cartId) and item ID (itemId) to perform this request.
Request
- Method: DELETE
- Request URL:
https://api.beta.yaas.io/hybris/cart/v1/{tenant}/carts/{cartId}/items/{itemId}
Response
- Status Code:
204
Remove Discount from Cart
If the discount is no longer valid or the customer chooses to save their coupon for another shopping experience, you can remove the coupon from the cart. To remove the discount, you need the discount ID (discountId) that was created when you added the discount to the cart. For more information about the discount ID, see Add Discount to Cart.
Request
- Method: DELETE
- Request URL:
https://api.beta.yaas.io/hybris/cart/v1/{tenant}/carts/{cartId}/discounts/{discountId}
Response
- Status Code:
204
Delete the Cart
You can delete a cart, which removes the cart and all the items in the cart from the system. You need the cart ID to perform this action.
Request
- Method: DELETE
- Request URL:
https://api.beta.yaas.io/hybris/cart/v1/{tenant}/carts/{cartId}
Response
- Status Code:
204
Error Codes
For more information about error codes, see the API Reference.
Glossary
| Term | Description |
|---|---|
| anonymous cart | A cart that belongs to an anonymous customer. This cart ID is associated with the customer"s session ID. |
| anonymous user | A customer without an account, or a customer who is shopping on the site and has not logged into their account. |
| closed cart | A cart ID that no longer exists. You cannot perform any functionality (add, update, retrieve, remove, or merge) to that cart. |
| country code | A code used to designate a particular country or region. |
| discount | A percentage or dollar amount that is subtracted from the product"s original price or from the cart"s total. |
| item | An object that is in the cart. |
| merge carts | When an anonymous customer"s cart ID is merged with a registered cart ID after the customer logs in to their account. |
| mixin | Customizable definition of additional properties for the service. One service definition can use many mixins, and one mixin can be used by many service definitions. |
| open cart | An active cart ID where you can perform an add, update, retrieve, remove, or merge functionality. |
| product | An object that belongs to the store. |
| registered cart | A cart that belongs to a registered customer. This cart ID is associated with the customer ID. |
| registered user | A customer who has signed in or registered for an account to shop on the site. |
| site code | A code you assign to represent a specific site, such as "US" for the United States. The site code is configured in the Site service. |
| tax code | A code created in the Tax service that is then assigned to a product. |
| VAT | A Value Added Tax added to a product"s price. This tax is included in the product"s sale price. |
| ZIP Code | A group of numbers (and letters) that are added to an address to assist in the sorting of mail. |
If you find any information that is unclear or incorrect, please let us know so that we can improve the Dev Portal content.
Use our private help channel. Receive updates over email and contact our specialists directly.
If you need more information about this topic, visit hybris Experts to post your own question and interact with our community and experts.