Managing Carts of Registered Users

The Carts API provides access to management of customers' shopping carts. Carts come in two different forms: carts for registered customers and carts for guests. In your development, the resources provided by the API can support you in the development of shopping cart functionality.

The following document covers the APIs for carts for registered customers only. If you want to know how to access carts of unregistered users, see Managing Guest Carts.

Installation

For detailed information on the modules that provide the API functionality and related installation instructions, see Carts API.

Guest Carts and Carts of Registered Users

Access to carts for registered users is provided by the /carts resource. Before accessing the resource, you need to authenticate a user first. For more details, see Authentication and Authorization.

Unlike guest carts, carts of registered users have an unlimited lifetime. Also, if the multiple carts feature is integrated into your project and Glue is enabled for multi-cart operations, registered users can have as many carts as they want. In the B2B scenario, this allows for creating different carts for different purposes. For instance, registered users can have a cart for daily purchases and one more for purchases made once a month.

Owned and Shared Carts

Registered users can share carts they own. Thus, a registered user can access both their personal carts and carts shared with them by other users. This feature allows company users to collaborate on company purchases as a team.

To be able to share carts, as well as access carts shared with them, customers need to authenticate as Company User Accounts. Each such account is a member of a certain Business Unit, and carts can be shared only among members of the same Unit. On the other hand, customers have the ability to impersonate as different Company Accounts depending on the job tasks they want to perform. Such accounts can belong to different Business Units, which means that any specific customer can have access to a different set of shared carts depending on the Company Account they impersonate as.

To use a Company Account, a customer needs to retrieve a bearer token for the account. The token is valid for a specific combination of an authenticated user and Company Account. It provides access to:

  • the carts owned by the user;
  • the carts shared with the Company Account.

For details on how to receive the token, see Logging In as Company User.

To be able to access shared carts, the API client needs to access the endpoints provided by the Carts API using the token received when impersonating as the Company Account. Doing so provides access to management of both the user's own carts and the carts shared with the current Company Account based on the bearer token presented.

Shared carts can be accessed and manipulated the same as regular carts. The only difference is that the list of actions that a user can perform on a shared cart depends on the permissions granted to them.

By default, there are 2 levels of permissions for shared carts: read-only and full access. If a user attempts to perform an unauthorized action on a shared cart, the API will respond with the 403 Forbidden status code.

For more details, see section Retrieving Cart Permission Groups in Sharing Company User Carts.

To distinguish whether a specific cart is owned by a user directly or shared with them, you need to extend the responses of the endpoints with the cart-permission-groups resource relationship. For example, if you want to get all carts available to a company user and distinguish which of them are shared, send the following request: GET http://glue.mysprykershop.com/carts?include=cart-permission-groups. If a cart is shared with the user, it will contain the relationship, while if a cart is owned by the user directly, the relationship will not be present.

For details on using the endpoint, see section Retrieving Carts.

The following example represents 2 carts available to a user, where:

  • My Cart is owned by the user;
  • Shared Cart is shared.

For more details on card sharing via Glue, see Sharing Company User Carts.

Creating Carts

To create a cart for a registered user, send a POST request to the following endpoint:

/carts

Request

Sample request: POST http://glue.mysprykershop.com/carts

Carts created via Glue API are always set as the default carts for the user.

Attributes:

Attribute
Type Required Description
name String

Sets the cart name.

This field can be set only if you are using the multiple carts feature. If you are operating in a single-cart environment, an attempt to set the value will result in an error with the 422 Unprocessable Entry status code.

priceMode Enum

Sets the price mode to be used for the cart. Possible values:

  • GROSS_MODE - prices after tax;
  • NET_MODE - prices before tax.

For details, see Net & Gross Prices.

currency String Sets the cart currency.
store String Sets the name of the store where to create the cart.

Authentication
To use this endpoint, customers need to authenticate first. For details, see Authentication and Authorization.

Sample Request Body:

{
   "data":{
      "type":"carts",
      "attributes":{
         "name":"My Cart",
         "priceMode":"GROSS_MODE",
         "currency":"EUR",
         "store":"DE"
      }
   }
}

You can also use the Accept-Language header to specify the locale.
Sample header:
[{"key":"Accept-Language","value":"de, en;q=0.9"}]
where de and en are the locales; q=0.9 is the user's preference for a specific locale. For details, see 14.4 Accept-Language.

Response

If a request was successful and a cart was created, the endpoint responds with a RestCartsResponse containing information about the new cart.

The response contains a unique identifier returned in the id attribute and a self link that can be used to access the cart in the future.

Possible Errors

Status Reason
422

Failed to create a cart.

In a single cart environment, this error can occur when attempting to create a cart for a customer who already has a cart.

401 The access token is invalid.
403 The access token is missing.

Retrieving Carts

Request

To access all available carts, send a GET request to the following endpoint:

/carts

Sample request: GET http://glue.mysprykershop.com/carts

To get a specific cart by ID, use the following endpoint:

/carts/{{cartId}}

Sample request: GET http://glue.mysprykershop.com/carts/4741fc84-2b9b-59da-bb8d-f4afab5be054

where 4741fc84-2b9b-59da-bb8d-f4afab5be054 is the ID of the cart you need.

Authentication
To use this endpoint, customers need to authenticate first. For details, see Authentication and Authorization.

You can also use the Accept-Language header to specify the locale.
Sample header:
[{"key":"Accept-Language","value":"de, en;q=0.9"}]
where de and en are the locales; q=0.9 is the user's preference for a specific locale. For details, see 14.4 Accept-Language.

Response

No matter which of the 2 endpoints you use, the response will consist of a single or multiple RestCartsResponse objects containing the requested cart(s).

To find out which products are placed in the cart, you can extend the response of the endpoint with the items and concrete-products resource relationships. The first relationship provides information on the items placed in the cart and their quantity, and the second one provides detailed information on the products.

Apart from that, you can identify permissions granted to users for each cart shared with them. To do so, extend the response with the cart-permission-groups resource relationship.

Sample request: GET http://glue.mysprykershop.com/carts?include=items,concrete-products,cart-permission-groups

The response will include the following additional attributes:

Possible Errors

Status Reason
401 The access token is invalid.
403 The access token is missing.
404 A cart with the specified ID was not found.

Adding Items

To add items to a cart, send a POST request to the following endpoint:

/carts/{{cartId}}/items

Request

Sample request: POST http://glue.mysprykershop.com/carts/4741fc84-2b9b-59da-bb8d-f4afab5be054/items

where 4741fc84-2b9b-59da-bb8d-f4afab5be054 is the ID of the cart you need.

Authentication
To use this endpoint, customers need to authenticate first. For details, see Authentication and Authorization.

You can also use the Accept-Language header to specify the locale.
Sample header:
[{"key":"Accept-Language","value":"de, en;q=0.9"}]
where de and en are the locales; q=0.9 is the user's preference for a specific locale. For details, see 14.4 Accept-Language.

Attributes:

Attribute Type Required Description
sku String Specifies the SKU part number of the item to add to the cart.
quantity String Specifies the quantity of items to add.

You can add concrete products only.

Sample Request Body:

{
    "data": {
        "type": "items",
        "attributes": {
            "sku": "209_12554247",
            "quantity": 10
        }
    }
}

Response

In case of a successful update, the endpoint will respond with a RestCartsResponse containing the new items. For details of the response, see section Response in Retrieving Carts.

Possible Errors

Status Reason
400 Cart ID is missing.
401 The access token is invalid.
403 The access token is missing or the user is not allowed to perform the operation.
404 A cart with the specified ID was not found.
422 Failed to add an item.

Removing Items

To remove an item from a cart, send a DELETE request to the following endpoint:

/carts/{{cartId}}/items/{{concrete_product_sku}}

Request

Sample request: DELETE http://mysprykershop.com/carts/4741fc84-2b9b-59da-bb8d-f4afab5be054/items/177_25913296

where 4741fc84-2b9b-59da-bb8d-f4afab5be054 is the ID of the cart you need and 177_25913296 is the SKU of the concrete product you want to remove.

Authentication
To use this endpoint, customers need to authenticate first. For details, see Authentication and Authorization.

Response

If the item was deleted successfully, the endpoint will respond with a 204 No Content status code.

Possible Errors

Status Reason
400 Cart ID and/or item ID is missing.
401 The access token is invalid.
403 The access token is missing or the user is not allowed to perform the operation.
404 A cart or item with the specified ID was not found.
422 Failed to delete an item.

Changing Item Quantity

To change the quantity of certain items in a cart, use the following endpoint with the PATCH method:

/carts/{{cartId}}/items/{{concrete_product_sku}}

Request

Sample request: PATCH http://mysprykershop.com/carts/4741fc84-2b9b-59da-bb8d-f4afab5be054/items/177_25913296

where 4741fc84-2b9b-59da-bb8d-f4afab5be054 is the ID of the cart you need and 177_25913296 is the SKU of the concrete product for which to change the quantity.

Authentication
To use this endpoint, customers need to authenticate first. For details, see Authentication and Authorization.

Attributes:

Attribute Type Required Description
quantity String Specifies the new quantity of the items.

Sample Request Body:

{
    "data": {
        "type": "items",
        "attributes": {
            "quantity": 10
        }
    }
}

Response

In case of a successful update, the endpoint will respond with a RestCartsResponse with updated quantity. For details of the response, see section Response in Retrieving Carts.

Possible Errors

Status Reason
400 Cart ID is missing.
401 The access token is invalid.
403 The access token is missing or the user is not allowed to perform the operation.
404 A cart with the specified ID was not found.
422 Failed to update an item.

Deleting Registered User's Cart

To delete a cart of a registered user, send a DELETE request to the following endpoint::

/carts/{{cartId}}

You cannot delete a cart if it is the customer's only cart. If you attempt to delete a customer's last cart, the endpoint responds with the 422 Unprocessable Entry status code.
If you delete the default cart of a customer, another cart will be assigned as default automatically.

Request

Sample request: DELETE http://glue.mysprykershop.com/carts/4741fc84-2b9b-59da-bb8d-f4afab5be054

where 4741fc84-2b9b-59da-bb8d-f4afab5be054 is the ID of the cart you want to delete.

Authentication
To use this endpoint, customers need to authenticate first. For details, see Authentication and Authorization.

Response

If the cart was deleted successfully, the endpoint will respond with a 204 No Content status code.

Possible Errors

Status Reason
400 Cart ID is missing.
401 The access token is invalid.
403 The access token is missing or the user is not allowed to perform the operation.
404 A cart with the specified ID was not found.
422 Failed to delete a cart.

See also:

Last review date: July 15, 2019