This use case describes how to interact with the cart, which stores details about the product you configure from the catalog, including options, attributes, and pricing configuration. Implementation teams can use these APIs to build a cart as necessary to prepare a product configuration by providing relevant details. These APIs also enable actions on the cart to activate and price the product configuration.

Retrieving a List of Carts

You can retrieve all carts with their details where the requester is the creator, owner of, or has access to the cart. Retrieving carts helps you explore the carts before you check them out. This API retrieves the following details:

  • Cart name
  • Effective date of the cart

Method: GET
Endpoint: /carts

You can use the query parameters available in the API to sort or filter carts based on specific requirements. For example, you have access to 1000 carts and retrieve them as follows.

APIPurpose

GET/carts?Page=1&limit=20&sort=asc(Name)

Retrieves only the first 2 carts sorted alphabetically based on cart names.

GET/carts?Page=1&limit=30&sort=desc(EffectiveDate)

Retrieves only the first 2 carts sorted based on the effective dates of carts in descending order.

For the following values:

ParametersValue
page1
limit2
sortdesc(EffectiveDate)

The below is the request URL and after executing that:

Request

'GET' \'https://<URL_of_the_Instance>/api/cart/v1/carts?sort=asc%28Name%29&page=1&limit=2' \
CODE

You get the following response:

Response

[
  {
    "Account": {
      "Id": "d80484e9-6a11-4019-8bab-7733726f068a",
      "Name": "Auto_IncStartAndEndDateCR_Account001"
    },
    "Ancestor": null,
    "ApprovalStatus": null,
    "BaseRelationCount": null,
    "BillingPreference": null,
    "BillToAccount": null,
    "BusinessObjectId": null,
    "BusinessObjectProfile": "Regular",
    "BusinessObjectRefId": null,
    "BusinessObjectType": "Agreement",
    "Comments": null,
    "ContractNumbers": null,
    "CostRollupInfo": null,
    "CouponCodes": null,
    "CurrentUser": null,
    "Description": "Cart1 Created with automation script",
    "EffectiveDate": "2023-06-30T00:00:00",
    "EffectivePriceList": {
      "Id": "ca40ab42-1756-4047-851e-29ca7568ed80",
      "Name": "Auto_IncStartAndEndDateCR_PL001"
    },
    "ExpectedEndDate": null,
    "ExpectedStartDate": null,
    "FinalizedDate": null,
    "Intent": null,
    "IsPricePending": false,
    "IsTaskPending": false,
    "IsTransient": false,
    "IsValidationPending": false,
    "LineItemsAwaitingPrice": null,
    "LegalEntity": null,
    "Location": null,
    "NumberOfItems": 0,
    "Order": null,
    "ParentConfiguration": null,
    "PaymentTerm": null,
    "PriceList": {
      "Id": "ca40ab42-1756-4047-851e-29ca7568ed80",
      "Name": "Auto_IncStartAndEndDateCR_PL001"
    },
    "PricingDate": "2023-06-30T00:00:00",
    "Primordial": null,
    "PurchaseId": null,
    "RenewalAdjustmentAmount": null,
    "RenewalAdjustmentType": null,
    "ShipToAccount": null,
    "SplitCriteriaKey": null,
    "Status": "New",
    "SummaryGroupType": "Category",
    "TaskCompletedDate": null,
    "UseType": "Main",
    "VersionNumber": null,
    "ActivationDate": null,
    "Id": "e42d09d9-6498-4b5b-8529-54a8826ab341",
    "Name": "Auto_IncStartAndEndDateCR_Cart001",
    "CreatedBy": {
      "Id": "27634e3f-904a-4321-9ce5-c2edbe181d90",
      "Name": "Test User"
    },
    "CreatedDate": "2022-11-16T01:09:06",
    "ModifiedBy": {
      "Id": "27634e3f-904a-4321-9ce5-c2edbe181d90",
      "Name": "Test User"
    },
    "ModifiedDate": "2022-11-16T01:09:06",
    "ExternalId": null,
    "PDTest_CustomField_c": "Custom Field Default Value",
    "ActivationDate_c": null
  },
  {
    "Account": {
      "Id": "c8a3e8e3-ceba-46a9-9dae-84058e8dd4a2",
      "Name": "Auto_IncStartAndEndDateCR_Account001"
    },
    "Ancestor": null,
    "ApprovalStatus": null,
    "BaseRelationCount": null,
    "BillingPreference": null,
    "BillToAccount": null,
    "BusinessObjectId": null,
    "BusinessObjectProfile": "Regular",
    "BusinessObjectRefId": null,
    "BusinessObjectType": "Agreement",
    "Comments": null,
    "ContractNumbers": null,
    "CostRollupInfo": null,
    "CouponCodes": null,
    "CurrentUser": null,
    "Description": "Cart1 Created with automation script",
    "EffectiveDate": "2023-06-30T00:00:00",
    "EffectivePriceList": {
      "Id": "8f58849c-ae90-4040-865d-8c67432e0ae1",
      "Name": "Auto_IncStartAndEndDateCR_PL001"
    },
    "ExpectedEndDate": null,
    "ExpectedStartDate": null,
    "FinalizedDate": null,
    "Intent": null,
    "IsPricePending": false,
    "IsTaskPending": false,
    "IsTransient": false,
    "IsValidationPending": false,
    "LineItemsAwaitingPrice": null,
    "LegalEntity": null,
    "Location": null,
    "NumberOfItems": 0,
    "Order": null,
    "ParentConfiguration": null,
    "PaymentTerm": null,
    "PriceList": {
      "Id": "8f58849c-ae90-4040-865d-8c67432e0ae1",
      "Name": "Auto_IncStartAndEndDateCR_PL001"
    },
    "PricingDate": "2023-06-30T00:00:00",
    "Primordial": null,
    "PurchaseId": null,
    "RenewalAdjustmentAmount": null,
    "RenewalAdjustmentType": null,
    "ShipToAccount": null,
    "SplitCriteriaKey": null,
    "Status": "New",
    "SummaryGroupType": "Category",
    "TaskCompletedDate": null,
    "UseType": "Main",
    "VersionNumber": null,
    "ActivationDate": null,
    "Id": "72da7e2d-0fb5-49c3-9124-effc819ee424",
    "Name": "Auto_IncStartAndEndDateCR_Cart001",
    "CreatedBy": {
      "Id": "27634e3f-904a-4321-9ce5-c2edbe181d90",
      "Name": "Test User"
    },
    "CreatedDate": "2022-11-15T14:48:59",
    "ModifiedBy": {
      "Id": "27634e3f-904a-4321-9ce5-c2edbe181d90",
      "Name": "Test User"
    },
    "ModifiedDate": "2022-11-15T14:48:59",
    "ExternalId": null,
    "PDTest_CustomField_c": "Custom Field Default Value",
    "ActivationDate_c": null
  }
]
CODE


Activating a Cart

Of all carts, only one cart can be active. You can activate a cart that is in the "New" status only. You cannot activate a cart in other statuses such as Finalized, Superseded, Suspended, Abandoned, or Deleted. Activating a cart does not change anything on the cart, except marking the cart as "Active". This API allows you to work on any existing cart that is not checked out yet.

Method: POST
Endpoint: /carts/{CartId}/activate

For example, you want to activate a cart with the cart ID b6c8762a-2c14-49b0-9a46-bebe4044c919. Execute the following API:

POST/carts/b6c8762a-2c14-49b0-9a46-bebe4044c919/activate
CODE

Retrieving Cart Details (Header Information)

You can retrieve the header details of a cart. This API retrieves the following details among others:

  • Cart name
  • Price list
  • Account
  • Effective date
  • Link to the business object if the cart is finalized

Method: GET
Endpoint: /carts/{cartId}

For example, the following sample code enables you to get the header details of a cart with the cart ID e42d09d9-6498-4b5b-8529-54a8826ab34. 

Request

'GET' \ 'https://<URL_of_the_Instance>/api/cart/v1/carts/e42d09d9-6498-4b5b-8529-54a8826ab341' \
CODE

You get the following response:

Response

{
  "Account": {
    "Id": "d80484e9-6a11-4019-8bab-7733726f068a",
    "Name": "Auto_IncStartAndEndDateCR_Account001"
  },
  "Ancestor": null,
  "ApprovalStatus": null,
  "BaseRelationCount": null,
  "BillingPreference": null,
  "BillToAccount": null,
  "BusinessObjectId": null,
  "BusinessObjectProfile": "Regular",
  "BusinessObjectRefId": null,
  "BusinessObjectType": "Agreement",
  "Comments": null,
  "ContractNumbers": null,
  "CostRollupInfo": null,
  "CouponCodes": null,
  "CurrentUser": null,
  "Description": "Cart1 Created with automation script",
  "EffectiveDate": "2023-06-30T00:00:00",
  "EffectivePriceList": {
    "Id": "ca40ab42-1756-4047-851e-29ca7568ed80",
    "Name": "Auto_IncStartAndEndDateCR_PL001"
  },
  "ExpectedEndDate": null,
  "ExpectedStartDate": null,
  "FinalizedDate": null,
  "Intent": null,
  "IsPricePending": false,
  "IsTaskPending": false,
  "IsTransient": false,
  "IsValidationPending": false,
  "LineItemsAwaitingPrice": null,
  "LegalEntity": null,
  "Location": null,
  "NumberOfItems": 0,
  "Order": null,
  "ParentConfiguration": null,
  "PaymentTerm": null,
  "PriceList": {
    "Id": "ca40ab42-1756-4047-851e-29ca7568ed80",
    "Name": "Auto_IncStartAndEndDateCR_PL001"
  },
  "PricingDate": "2023-06-30T00:00:00",
  "Primordial": null,
  "PurchaseId": null,
  "RenewalAdjustmentAmount": null,
  "RenewalAdjustmentType": null,
  "ShipToAccount": null,
  "SplitCriteriaKey": null,
  "Status": "New",
  "SummaryGroupType": "Category",
  "TaskCompletedDate": null,
  "UseType": "Main",
  "VersionNumber": null,
  "ActivationDate": null,
  "Id": "e42d09d9-6498-4b5b-8529-54a8826ab341",
  "Name": "Auto_IncStartAndEndDateCR_Cart001",
  "CreatedBy": {
    "Id": "27634e3f-904a-4321-9ce5-c2edbe181d90",
    "Name": "Test User"
  },
  "CreatedDate": "2022-11-16T01:09:06",
  "ModifiedBy": {
    "Id": "27634e3f-904a-4321-9ce5-c2edbe181d90",
    "Name": "Test User"
  },
  "ModifiedDate": "2022-11-16T01:09:06",
  "ExternalId": null,
  "PDTest_CustomField_c": "Custom Field Default Value",
  "ActivationDate_c": null
}
CODE


Retrieving Line Items of the Cart

You can retrieve all line items in a cart, with their details. The API retrieves the following details:

  • Cart header fields
  • Primary line items
  • Secondary line items associated with the primary line items such as options and charge types

Method: GET
Endpoint: /carts/{cartId}/items

For example, you want to get the details of all line items in a cart with the cart ID e42d09d9-6498-4b5b-8529-54a8826ab341. Execute the following API:

Request

'GET' \'https://<URL_of_the_Instance>/api/cart/v1/carts/e42d09d9-6498-4b5b-8529-54a8826ab341/items'
CODE

You can use the query parameters available in the API to sort or filter cart line items based on specific requirements. For example, a cart with the cart ID b6c8762a-2c14-49b0-9a46-bebe4044c919 has 1000 cart line items and you retrieve them as follows.

APIPurpose

GET/carts/{b6c8762a-2c14-49b0-9a46-bebe4044c919}/items&page=1&limit=20&sort=asc(Name)

Retrieves only the first 20 cart line items sorted alphabetically based on their names.

Adding Line Items to the Cart

You can add one or more standalone, bundle, and option products to the cart. You can add bundle line items with the default or modified configuration. You cannot add products to a cart in the Finalized, Superseded, or Deleted status.

Method: POST
Endpoint: /carts/{cartId}/items

For example, you want to add line items to a cart with the cart ID b6c8762a-2c14-49b0-9a46-bebe4044c919. Execute the following API:

POST/carts/b6c8762a-2c14-49b0-9a46-bebe4044c919/items
CODE

You must pass the product ID in the request body to add the product to the cart. You can add products with different field values.

Scenarios

  • In the following example, you add multiple standalone products with different field values. You pass the following parameters in the request body:

    Request Body

    [
   
    {
        "ProductId": "fd1f08e0-e557-445b-bdfa-ff39acf09b13",
        "Quantity":3,
        "SellingTerm":5,
        "StartDate": "2021-03-30",
        "EndDate": "2022-03-30"
    },
   {
        "ProductId": "fd1f08e0-e557-445b-bdfa-ff39acf09b13",
        "Quantity":5.5,
        "SellingTerm":5,
        "EndDate": "2022-03-30"
    },
 
   {
        "ProductId": "fd1f08e0-e557-445b-bdfa-ff39acf09b13",
        "Quantity":5,
        "SellingTerm":5.5,
        "StartDate": "2021-03-30"
    },
 
    {
        "ProductId": "fd1f08e0-e557-445b-bdfa-ff39acf09b13",
        "Quantity":5
    }
]
    CODE

  • In the following example, you add option to the Bundle products. You pass the following parameters in the request body:

    [
    {
        "ProductId": "8d30309c-089b-4f66-babb-50192177d9ce",
        "PrimaryTxnLineNumber": "1",
        "LineType": "Product/Service",
        "PricingStatus": "Pending",
        "ExternalId": "Bundle",
        "SellingTerm": 6.5
    },
    {
        "TxnParentBundleNumber": 1,
        "PrimaryTxnLineNumber": 2,
        "ProductId": "8d30309c-089b-4f66-babb-50192177d9ce",
        "OptionId": "5312f96e-0677-47c8-be55-5cf6b54fe44a",
        "ExternalId": "Prod-4",
        "LineType": "Option",
        "PricingStatus": "Pending",
        "IsPrimaryLine": true
    },

    {
        "ProductId": "8d30309c-089b-4f66-babb-50192177d9ce",
        "PrimaryTxnLineNumber": "1",
        "LineType": "Product/Service",
        "PricingStatus": "Pending",
        "ExternalId": "Bundle",
        "SellingTerm": 6.5
    },
    {
        "TxnParentBundleNumber": 1,
        "PrimaryTxnLineNumber": 2,
        "ProductId": "8d30309c-089b-4f66-babb-50192177d9ce",
        "OptionId": "5312f96e-0677-47c8-be55-5cf6b54fe44a",
        "ExternalId": "Prod-4",
        "LineType": "Option",
        "PricingStatus": "Pending",
        "IsPrimaryLine": true
    },
    {
        "PrimaryTxnLineNumber": 3,
        "ProductId": "8d30309c-089b-4f66-babb-50192177d9ce",
        "OptionId": "5312f96e-0677-47c8-be55-5cf6b54fe44a",
        "ExternalId": "Prod-5",
        "TxnParentBundleNumber": 1,
        "LineType": "Option",
        "PricingStatus": "Pending",
        "IsPrimaryLine": true
    },
    {
        "PrimaryTxnLineNumber": 4,
        "ProductId": "8d30309c-089b-4f66-babb-50192177d9ce",
        "OptionId": "5312f96e-0677-47c8-be55-5cf6b54fe44a",
        "ExternalId": "Prod-6",
        "TxnParentBundleNumber": 1,
        "LineType": "Option",
        "PricingStatus": "Pending",
        "IsPrimaryLine": true
    },
    {
        "PrimaryTxnLineNumber": 5,
        "ProductId": "8d30309c-089b-4f66-babb-50192177d9ce",
        "OptionId": "5312f96e-0677-47c8-be55-5cf6b54fe44a",
        "ExternalId": "Prod-7",
        "TxnParentBundleNumber": 1,
        "LineType": "Option",
        "PricingStatus": "Pending",
        "IsPrimaryLine": true
    }
]
    CODE

Updating an Existing Cart Item

You can update one or more existing cart line items by providing details of the following fields in the request body:

  • Quantity
  • Selling Term
  • Start Date
  • End Date
  • Adjustment Amount
  • Adjustment Type

You cannot update custom fields. You cannot update line items in a cart in the Finalized, Superseded, or Deleted status.

Method: PATCH
Endpoint: /carts/{cartId}/items

For example, you want to update line items in a cart with the cart ID b6c8762a-2c14-49b0-9a46-bebe4044c919. Execute the following API:

PATCH/carts/b6c8762a-2c14-49b0-9a46-bebe4044c919/items
CODE

In the request body, you must pass the product ID and the required fields with values to update the cart line items.

Scenarios

  • In the following example, you update the quantity of an existing cart line item.

    [
    {
        "PrimaryTxnLineNumber": "1",
        "ProductId": "6e6619b8-8d2e-4686-af69-b16e683b98f9",
        "LineType": "Product/Service",
        "LineNumber" : 1,
        "PrimaryLineNumber" :1,
        "PricingStatus": "Pending",
        "Id": "494f0297-d63a-46b1-a71a-689ad5409a3f",
        "Quantity": 10,
        "ExternalId": "Standalone"
    }
]
    CODE

  • In the following example, you update the selling term of an existing cart line item:

    [
    {
        "PrimaryTxnLineNumber": "1",
        "ProductId": "6e6619b8-8d2e-4686-af69-b16e683b98f9",
        "LineType": "Product/Service",
        "LineNumber": 1,
        "PrimaryLineNumber": 1,
        "PricingStatus": "Pending",
        "Id": "494f0297-d63a-46b1-a71a-689ad5409a3f",
        "Quantity": 10,
        "ExternalId": "Standalone",
        "SellingTerm" : 5
    }
]
    CODE

Removing Line Items from the Cart

You can remove one or more line items from the cart. You cannot remove line items from a cart in the Finalized, Superseded, or Deleted status.

Method: DELETE
Endpoint: /carts/{cartId}/items

For example, you want to remove line items from a cart with the cart ID b6c8762a-2c14-49b0-9a46-bebe4044c919. Execute the following API:

DELETE/carts/b6c8762a-2c14-49b0-9a46-bebe4044c919/items
CODE

In the request body, you provide IDs of cart line items to remove the associated records from the cart.

Scenario

In the following example, you remove one cart line item.

[
  {
    "LineNumber": 0
  },
  {
    "CartItemId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
]
CODE

Run Pricing on the Cart

You must calculate pricing on the cart whenever you add any product(s) to the cart and/or configure products from the catalog. CPQ does not run pricing on the cart by default, so you must do it explicitly. Following are some of the scenarios to call this API:

  • Adding a standalone product to the cart
  • Adding a bundle product and configuring its options
  • Selecting different charge types
  • Configuring product attributes or modifying them
  • Changing the default quantity (that is 1) on the Catalog page while adding/configuring the products
  • Deselecting an added product from the catalog

You must also perform repricing of the cart whenever you update the cart. Following are some of the scenarios to reprice the cart:

  • Changing any cart line item fields such as Quantity, Selling Term, Start Date, End Date, Base Price
  • Applying any kind of adjustments on any cart line item
  • Performing actions such Mass Update
  • Adding or removing any line item
  • Configuring any line item for options, attributes, or other parameters

Method: POST
Endpoint: /carts/{cartId}/price

For example, you want to price or reprice a cart with the cart ID b6c8762a-2c14-49b0-9a46-bebe4044c919. Execute the following API:

POST/carts/b6c8762a-2c14-49b0-9a46-bebe4044c919/price
CODE

Deleting a Cart

You can delete a cart when it is no longer required. A deleted cart record is not stored so you cannot access it after deletion.

Method: DELETE
Endpoint: /carts/{cartId}

For example, you want to delete a cart with the cart ID b6c8762a-2c14-49b0-9a46-bebe4044c919. Execute the following API:

DELETE/carts/b6c8762a-2c14-49b0-9a46-bebe4044c919
CODE