commercetools-commerce-patterns

Approval Rules

Overview

Core Concepts

Approval Rules Are Predicates

Common predicate fields include:

Approvers

• All required approvers in a tier must act before the next tier is evaluated.
• An Approval Rule can have multiple tiers to model multi-level approval chains (e.g. line manager → finance director).

Requesters

Rules can also restrict which associate roles the rule applies to (i.e. which buyers' orders are subject to the rule). This allows different rules for different buyer roles within the same BU.

Approval Flow State Machine

Order created → Pending
                  │
          ┌───────┴───────┐
          │               │
       Approved        Rejected
          │
       Order confirmed / fulfilment continues

Evaluation at Order Creation

1. Buyer places an order.
2. The platform evaluates all active Approval Rules on the buyer's Business Unit (and inherited from parent BUs).
3. If any rule's predicate matches the order, an Approval Flow is created and the Order is placed in Pending state.
4. If no rule matches, the Order is confirmed immediately.

Rules from parent BUs are inherited by child BUs unless overridden.

Key API Resources

Implementation Notes

• Only associates with an approveOrder permission can call approve/reject actions.
• An order can match multiple Approval Rules simultaneously; the platform creates one Approval Flow that merges all required approver tiers.
• Approval Rules are managed by associates with the updateApprovalRules permission (typically a BU admin).
• Approval Rule predicates are validated at creation time — an invalid predicate is rejected with a 400 error.

As-Associate API

Overview

The API Chain Pattern

The TypeScript SDK exposes the As-Associate API through a fluent builder chain:

apiRoot
  .asAssociate()
  .withAssociateIdValue({ associateId: "customer-id-here" })
  .inBusinessUnitKeyWithBusinessUnitKeyValue({ businessUnitKey: "bu-key-here" })
  .<resource>()
  .<action>()
  .execute();

Breaking Down the Chain

Example: Create a Cart as an Associate

const cart = await apiRoot
  .asAssociate()
  .withAssociateIdValue({ associateId: customerId })
  .inBusinessUnitKeyWithBusinessUnitKeyValue({ businessUnitKey: "acme-uk" })
  .carts()
  .post({
    body: {
      currency: "GBP",
      country: "GB",
      businessUnit: { key: "acme-uk", typeId: "business-unit" },
      store: { key: "acme-uk-store", typeId: "store" },
    },
  })
  .execute();

Example: Place an Order as an Associate

const order = await apiRoot
  .asAssociate()
  .withAssociateIdValue({ associateId: customerId })
  .inBusinessUnitKeyWithBusinessUnitKeyValue({ businessUnitKey: "acme-uk" })
  .orders()
  .post({
    body: {
      cart: { id: cart.body.id, typeId: "cart" },
      version: cart.body.version,
    },
  })
  .execute();

Why the As-Associate Path Is Required

Platform Permission Enforcement

1. Verifies the associateId is an active associate of the named Business Unit.
2. Checks whether that associate holds the required associateRole permission for the requested operation (e.g. createMyCarts, createOrders, viewOrders, updateApprovalFlows).
3. Rejects the request with an AssociateMissingPermissionError (an HTTP 403-class error) if the permission is absent.

• A buyer could see or modify another BU's data if project scopes are broad.
• Approval rule enforcement is bypassed.
• Audit trail (who did what, in which BU) is lost.

Operations Covered

The as-associate path supports the following resource types (non-exhaustive):

REST Equivalent

The SDK chain maps to the following REST path structure:

POST /as-associate/{associateId}/in-business-unit/key={businessUnitKey}/carts
GET  /as-associate/{associateId}/in-business-unit/key={businessUnitKey}/orders
POST /as-associate/{associateId}/in-business-unit/key={businessUnitKey}/orders
POST /as-associate/{associateId}/in-business-unit/key={businessUnitKey}/quote-requests
POST /as-associate/{associateId}/in-business-unit/key={businessUnitKey}/orders/quotes

Common Mistakes

OAuth Scope

The OAuth token used in as-associate requests should carry:

• manage_my_orders:{projectKey} or manage_orders:{projectKey} (depending on whether you use customer tokens or merchant tokens acting on behalf of a customer).
• For customer-token flows (recommended for buyer-facing apps): use the customer OAuth flow so the token is bound to the specific customer, and the platform cross-checks associateId against the token's subject.

B2B Customer Group Pricing

Overview

Price Selection Parameters

commercetools uses a combination of the following parameters to select a price from the variant's embedded price array:

How Price Selection Works

1. Product Projection Search

2. Cart Line Items

• The relevant price selection parameters must be set on the cart before or at the time line items are added.
• The Customer Group is typically derived from the customer's profile and propagated to the cart automatically, but it can also be set explicitly.

3. Fallback / Default Price

Customer Group Constraints and Limitations

Deletion Constraint

"Can not delete a source while it is referenced from at least one 'product'."

1. Create the new Customer Group.
2. Update all product prices (and any discounts referencing the old group) to reference the new Customer Group.
3. Delete the old Customer Group once no pricing entries reference it.

Multiple Groups Per Customer

B2B Recommendations

• Segment pricing tiers using Customer Groups (e.g. tier-bronze, tier-silver, tier-gold, distributor, reseller).
• Always define a base/default price to avoid null prices for customers not assigned to any group.
• Use Channel + Customer Group together when pricing also varies by distribution channel (e.g. online vs. in-store B2B).
• Automate group assignment as part of the customer onboarding or account management workflow so carts always carry the correct Customer Group from the start.

BOPIS Pattern Using Multiple Shipping Methods

Overview

High Level Flow

1. Set the shippingMode on the Cart to Multiple
2. Add item shipping addresses (store pickup address + customer delivery address)
3. Query shipping methods and evaluate predicates to determine eligibles
4. Add selected shipping methods to the cart
5. Set lineItemShippingDetails on each line item
6. Create the order

Step 1: Set the shippingMode on the Cart

If a customer later decides to use multiple fulfillment methods in the cart's life cycle, you can:

• Create a new cart with shippingMode set to Multiple.
• Copy over the line items and discount codes from the original cart to the new one using the addLineItem & addDiscountCode Update Cart actions.
  • This will be your cart going forward.
  • The redundant cart with shippingMode Single may be abandoned and would get deleted based on the lastModifiedAt datetime value, or you may choose to delete this yourself using the Delete Cart by ID operation.

{
    "key": "example-cart-key",
    "currency": "USD",
    "country": "US",
    "ShippingMode": "Multiple",
    "lineItems": [
      // ...
    ]
  }

Step 2: Add the itemShippingAddress

{
    "version": {{cart-version}},
    "actions": [
        {
            "action" : "addItemShippingAddress",
            "address" : {
              "key" : "pickup-store-address",
              "firstName" : "My Store",
              "lastName" : "Store 140",
              "streetName" : "Commerce Blvd",
              "streetNumber" : "1701",
              "postalCode" : "90210",
              "city" : "Los Angeles",
              "state" : "NC",
              "country" : "US"
            }
        },
        {
            "action" : "addItemShippingAddress",
            "address" : {
              "key" : "customer-shipping-address",
              // ...
            }
          }
    ]
}

Step 3: Query shippingMethods to determine eligibles

Once item shipping addresses are added, determine the eligible shipping methods for the cart.

Important: The shipping-methods/matching-cart API does not support carts with shippingMode set to Multiple.

query {
  shippingMethods {
    results {
      id
      predicate
    }
  }
}

{
  "data": {
    "shippingMethods": {
      "results": [
        {
          "id": "17fa25a7-6d70-4c98-8610-1cd04ad87450",
          "predicate": "<predicate-string>"
        },
        {
          "id": "b47f7f2d-a0e3-48d3-88df-4da3b99e34b9",
          "predicate": "<predicate-string>"
        }
      ]
    }
  }
}

Step 4: Add the selected shippingMethod to the cart

Example payload:

{
    "version": {{cart-version}},
    "actions": [
        {
            "action" : "addShippingMethod",
            "shippingKey" : "in-store-pickup",
            "shippingMethod" : {
              "id" : "{{shipping-method-id}}",
              "typeId" : "shipping-method"
            },
            "shippingAddress" : {
              "key" : "pickup-store-address",
              "streetName" : "Commerce Blvd",
              "streetNumber" : "1701",
              "postalCode" : "90210",
              "city" : "Los Angeles",
              "state" : "NC",
              "country" : "US"
            }
          },
          {
            "action" : "addShippingMethod",
            "shippingKey" : "customer-delivery",
            "shippingMethod" : {
              "id" : "{{shipping-method-id}}",
              "typeId" : "shipping-method"
            },
            "shippingAddress" : {
              "key" : "customer-delivery-address",
              // ...
            }
          }
    ]
}

Step 5: Setting the lineItemShippingDetails on each line item

{
    "version": {{cart-version}},
    "actions": [
        {
            "action" : "setLineItemShippingDetails",
            "lineItemId" : "{{lineItemId}}",
            "shippingDetails" : {
              "targets" : [ {
                "addressKey" : "my-store-address",
                "shippingMethodKey": "in-store-pickup",
                "quantity" : 1
              } ]
            }
          }
    ]
}

Conclusion

Once all line items are associated with shipping details, you can proceed to create an order from the cart.

Key Rules and Gotchas

• shippingMode must be set at cart creation time — it cannot be changed later.
• The shipping-methods/matching-cart API does not work for Multiple shippingMode carts. Use the generic Query shipping-methods endpoint and evaluate predicates client-side.
• Each addShippingMethod action in Multiple mode requires its own shippingAddress.
• Use meaningful key values for both itemShippingAddresses and shipping methods (shippingKey) since these keys link addresses to line items.
• If starting with a Single mode cart and needing to switch: create a new Multiple mode cart and copy over lineItems and discountCodes; abandon the old cart.

Bundle Discounting Pattern Using 'Buy Get Cart Discount'

The discount will apply only when all targeted SKUs in a bundle are present in a customer's cart. These discounts can be either absolute ($ off) or relative (% off). Since there are no predefined product types representing bundles, the setup leverages the flexibility of the Buy/Get Cart Discount feature to achieve this goal.

Key Requirements

• Bundle Criteria: Discounts trigger only when all SKUs in the specified bundle are in the cart.
• Discount Type: Support for both absolute ($ off) and relative (% off) discounts.
• SKU-Based Trigger: The discount applies based on the presence of specific SKUs.

Solution Overview

The Buy/Get Cart Discount feature allows for setting conditions and outcomes for discounts, making it ideal for implementing bundle-based promotions. Here's how to set it up:

Define the Trigger

Using the Merchant Center, specify the Variant ID (SKU) required for the discount. For example, if SKUs LPC-09, ADPC-09 & LPC-011 form the bundle:

"triggerPattern": [
    {
        "type": "CountOnLineItemUnits",
        "predicate": "sku = \"LPC-09\"",
        "minCount": 1,
        "maxCount": 1
    },
    {
        "type": "CountOnLineItemUnits",
        "predicate": "sku = \"ADPC-09\"",
        "minCount": 1,
        "maxCount": 1
    },
    {
        "type": "CountOnLineItemUnits",
        "predicate": "sku = \"LPC-011\"",
        "minCount": 1,
        "maxCount": 1
    }
]

Set the Discount Target

"targetPattern": [
    {
        "type": "CountOnLineItemUnits",
        "predicate": "sku = \"LPC-09\"",
        "minCount": 1,
        "maxCount": 1,
        "excludeCount": 0
    },
    {
        "type": "CountOnLineItemUnits",
        "predicate": "sku = \"ADPC-09\"",
        "minCount": 1,
        "maxCount": 1,
        "excludeCount": 0
    },
    {
        "type": "CountOnLineItemUnits",
        "predicate": "sku = \"LPC-011\"",
        "minCount": 1,
        "maxCount": 1,
        "excludeCount": 0
    }
]

Set Discount Value and Distribution

Discount of this type may be absolute ($ off) or relative (% off), and you can decide if the discount should be:

• Distributed evenly across all eligible items
• Applied individually to each eligible item
• Distributed proportionately across all eligible items

Example discount value configuration (absolute, even distribution):

"value": {
    "type": "absolute",
    "money": [
        {
            "type": "centPrecision",
            "currencyCode": "EUR",
            "centAmount": 1000,
            "fractionDigits": 2
        },
        {
            "type": "centPrecision",
            "currencyCode": "GBP",
            "centAmount": 1000,
            "fractionDigits": 2
        },
        {
            "type": "centPrecision",
            "currencyCode": "USD",
            "centAmount": 1000,
            "fractionDigits": 2
        }
    ],
    "applicationMode": "EvenDistribution"

Distribution Modes for Relative (%) Discounts in Buy & Get

With proportional distribution, the 50% discount is spread across all qualifying items rather than applied entirely to the cheapest one.

Benefits of This Approach

• Flexibility: Supports a wide range of discount configurations (absolute or relative, distribution rules).
• Precision: Ensures discounts apply only when all bundle SKUs are present.
• Efficiency: Eliminates the need for manual bundle definitions by leveraging the Buy/Get Cart Discount functionality.

Bundle Modeling

Part 1: Pattern for Static Bundle Pricing

The Recommended Approach: Creating Bundles with Product Data Modeling & Line Item Customizations

Solution Overview: Product Modeling

This approach works well for many use cases, such as offering a special bundle price for a "shirt and trousers bundle," where customers can choose specific variants (e.g., size and color) at the time of purchase. In such cases, the bundle references the product as a whole, allowing flexibility in variant selection.

Solution Overview: LineItem Flow

When a customer adds a bundle to their cart, your backend-for-frontend (BFF) service should handle the following:

• Add the bundle product to the cart: Include the bundle as the parent item.
• Add associated child items to the cart: Represent the bundle components as lineItems.
• Link child items to the parent item: Establish relationships between child and parent lineItems using custom fields.
• Ensure a fixed bundle price: Set the price of the child lineItems to $0 using externalPrice.

Additional constraints may include:

• Prevent modifications to child items: Restrict direct changes to child lineItems in the cart.
• Propagate changes from parent to children: Ensure updates to the bundle, such as quantity adjustments, are applied to the child lineItems.

Defining the Bundle ProductType

{
  "name" : "my-store-bundle",
  "description" : "my-store-bundle",
  "attributes" : [ {
    "type" : {
      "name" : "set",
       "elementType": {
                "name": "text"
            }
    },
    "isSearchable" : true,
    "name" : "bundleContents",
    "label" : {
      "en" : "bundleContents"
    },
    "isRequired" : true,
     "attributeConstraint": "Unique"
  }]
}

Creating the Bundle Product

{
  // generic product info e.g. name, description, productTypeReference, slug and etc.
  // ...
  "masterVariant": {
    "name": {
    "en": "ivory-dinner-bundle"
  },
    "sku": "IDIN-01",
    "attributes": [
      {
        "name": "bundleContents",
        "value": ["ISP-01", "SPOO-094", "SGB-01"]
      }
    ],
    "prices": [
                    {
                        "id": "<id>",
                        "value": {
                            "type": "centPrecision",
                            "currencyCode": "USD",
                            "centAmount": 1999,
                            "fractionDigits": 2
                        }
                    },
                    // ...
                ]
  }
}

{
  // generic product info e.g. name, description, productTypeReference, slug and etc.
  // ...
  "masterVariant": {
    "name": {
    "en": "ivory-dinner-bundle"
  },
    "sku": "IDIN-01",
    "attributes": [
                    {
                        "name": "child-items",
                        "value": [
                            {
                                "typeId": "product",
                                "id": "<referenced-product-id>"
                            },
                            {
                                "typeId": "product",
                                "id": "<referenced-product-id>"
                            }
                        ]
                    }
                ],
    "prices": [
                    {
                        "id": "<id>",
                        "value": {
                            "type": "centPrecision",
                            "currencyCode": "USD",
                            "centAmount": 1999,
                            "fractionDigits": 2
                        }
                    }
                ]
  }
}

Extending the lineItem Object for Bundle-Child Relationships

{
  "key": "parent-lineitem-id",
  "name": {
    "en": "parentLineItemId"
  },
  "description": {
    "en": "Custom type for child lineitems that are part of a bundle"
  },
  "resourceTypeIds": [
    "line-item"
  ],
  "fieldDefinitions": [
    {
      "name": "parentLineItemId",
      "label": {
        "en": "LineItem ID of the parent, bundle item"
      },
      "required": false,
      "type": {
        "name": "String"
      }
    }
  ]
}

Orchestration Logic for Adding Bundles to Carts

With the foundational setup complete, implement orchestration logic to automatically add child items when a bundle is added to the cart.

1. Detect if the item is a bundle product: Check if the ProductVariant being added references a bundle-specific ProductType.
2. Validate and extract bundle contents: Perform validations (e.g., inventory checks) and retrieve bundleContents to get the child ProductVariants.
3. Add the bundle item to the cart: Use the AddLineItem action to add the bundle as a parent item.
4. Add child items: Add each child ProductVariant to the cart with matching quantities using the AddLineItem action.
5. Set child item properties: Assign an externalPrice of $0 and populate parentLineItemId to establish linkage to the parent (bundle lineItem).
6. Handle updates and removals: Ensure bundle quantity changes or removals propagate to child lineItems.

UI Considerations

• Hide child lineItems in the cart UI to reduce clutter — unless your use case requires the customer to select specific product variants to be part of a bundle.
• Prevent direct modifications or removals to child lineItems to preserve bundle integrity.

Other Considerations

• Inventory Tracking: Does inventory need to be tracked at the child lineItem level?
• Reporting Needs: Are separate reports required for the child items within the bundle?

Concluding Thoughts

This approach treats bundles as distinct items, offering significant benefits for categorization and search functionality on your storefront. For example:

• Customers can search for bundles just like any other product.
• You can classify bundles into different categories, making them easier to discover.
• Each bundle can have its own unique images, descriptions, and search slugs, providing flexibility in how bundles are presented to customers.

Additional considerations may be needed such as changes to BFF, orchestration logic, etc.

Part 2: Bundles Hands-On (Implementation Example)

Bundle ProductType that References ProductVariants

Creating the Bundle ProductType

{
            "name": "bundle-type-1",
            "description": "bundle-type-1",
            "classifier": "Complex",
            "attributes": [
                {
                    "name": "bundle-content-skus",
                    "label": {
                        "en-US": "bundle-content-skus"
                        // other languages
                    },
                    "isRequired": false,
                    "type": {
                        "name": "set",
                        "elementType": {
                            "name": "text"
                        }
                    },
                    "attributeConstraint": "None",
                    "isSearchable": false,
                    "inputHint": "SingleLine",
                    "displayGroup": "Other"
                }
            ],
            "key": "bundle-type-1"
        }

Creating the Bundle Product & ProductVariant

{
    "id": "<id>",
    "version": 2,
    "productType": {
        "typeId": "product-type",
        "id": "<referenced-product-id>"
    },
    "masterData": {
        "current": {
            // generic product info e.g. name, description, productTypeReference, slug and etc.
            // ...
            "masterVariant": {
                // variant info
                // ...
                "attributes": [
                    {
                        "name": "bundle-content-skus",
                        "value": [
                            "LCP-02,HP-01,RB-01"
                        ]
                    }
                ],
                "assets": []
            },
            "variants": []
        }
    },
    "key": "slate-and-stone-bundle",
    "taxCategory": {
        "typeId": "tax-category",
        "id": "<id>"
    },
    "priceMode": "Standalone",
    "lastVariantId": 1
}

Setting the Bundle ProductVariant Inventory

The inventory for the bundle SKU (SAS-01) is managed separately from the inventories of its individual items. However, there is a method to reduce the inventory of the bundle's components when a bundle is sold (discussed later).

Set the inventory of the bundle SKU SAS-01:

curl --location 'https://api.us-central1.gcp.commercetools.com/{your-project-key}/inventory' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer' \
--data '{
  "sku" : "SAS-01",
  "quantityOnStock" : 10,
  "availableQuantity" : 10
}'

{"id":"<id>","version":1,"sku":"SAS-01","quantityOnStock":10,"availableQuantity":10,"reservations":[]}

Setting the Bundle ProductVariant Price

The price for the bundle SKU (SAS-01) is managed independently from the prices of its individual products. Generally, the price of the bundle item is typically lower than the sum of the prices of the individual participating items.

You can choose to use either embedded or standalone pricing. In this example, standalone pricing is used:

curl --location 'https://api.us-central1.gcp.commercetools.com/{your-project-key}/standalone-prices' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer' \
--data '{
  "sku" : "SAS-01",
  "value" : {
    "currencyCode" : "USD",
    "centAmount" : 1599
  }
}'

{
    "id": "<id>",
    "version": 1,
    "sku": "SAS-01",
    "value": {
        "type": "centPrecision",
        "currencyCode": "USD",
        "centAmount": 1599,
        "fractionDigits": 2
    },
    "active": true
}

Creating Required CustomField

curl --location 'https://api.us-central1.gcp.commercetools.com/{your-project-key}/types' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer' \
--data '{
  "key": "parent-lineitem-id",
  "name": {
    "en": "parentLineItemId"
  },
  "description": {
    "en": "Custom type for child lineitems that are part of a bundle"
  },
  "resourceTypeIds": [
    "line-item"
  ],
  "fieldDefinitions": [
    {
      "name": "parentLineItemId",
      "label": {
        "en": "LineItem ID of the parent, bundle item"
      },
      "required": false,
      "type": {
        "name": "String"
      }
    }
  ]
}'

Adding a Bundle Item to a Cart

curl --location 'https://api.us-central1.gcp.commercetools.com/{your-project-key}/carts' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer' \
--data '{
    "key": "example-order-key",
    "currency": "USD",
    "country": "US",
    "shippingMode": "Single",
    "shippingAddress": {...},
    "inventoryMode":"ReserveOnOrder",
    "lineItems": [
      {
        "sku": "SAS-01",
        "quantity": 1}
    ]
  }
  '

• Set LineItemPriceMode to ExternalPrice with a value of $0 for all child line items.
• Set the CustomField parentLineItemId on the child line items to match the bundle product's lineItem ID.

curl --location 'https://api.us-central1.gcp.commercetools.com/{your-project-key}/carts/{cart-id}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer' \
--data '{
    "version": 5,
    "actions": [
        {
            "action" : "addLineItem",
            "sku" : "LCP-02",
            "quantity" : 1,
            "externalPrice":{
                "currencyCode":"USD",
                "centAmount":0
            },
            "custom":{
                "type":{
                    "key":"parent-lineitem-id",
                    "type":"line-item"
                },
                "fields":{
                    "parentLineItemId":"<actual-parent-lineitem-id>"
                }
            }
        },
        {
            "action" : "addLineItem",
            "sku" : "HP-01",
            "quantity" : 1,
            "externalPrice":{
                "currencyCode":"USD",
                "centAmount":0
            },
            "custom":{
              // same as the above child lineitem 
            }
        },
        {
            "action" : "addLineItem",
            "sku" : "RB-01",
            "quantity" : 1,
            "externalPrice":{
                "currencyCode":"USD",
                "centAmount":0
            },
            "custom":{
                // same as the above child lineitem 
            }
        }
    ]
}'

Performing the above actions ensures that inventory is reduced for the child items that comprise the bundle, along with reducing the inventory of the bundle item.

Special Considerations

Product Discounts

• Given that the child items are added to the cart with an external price of $0, product discounts should not impact these items.
• Product discounts on the bundle items will apply as usual.

Cart Discounts

• It is recommended to build cart discount predicates to exclude lineItems where the CustomField parentLineItemId is defined.

Multi-quantity Purchases

• If a customer purchases multiple quantities of bundle items, the corresponding number of child items will need to be added to the Cart by the BFF layer.

Lineitem Edits

• Custom UI logic may be necessary to either not show the child line items on the website's UI, or to prevent end-users from editing the child lineItem details.

Removing the Bundle Item from the Cart

• Custom BFF logic needs to be added to auto-remove the child lineItems when the bundle item is removed from the Cart.

Handling "OutOfStock" Errors

• If the platform returns an OutOfStock error for the bundle item or any of the child lineItems, the BFF layer needs to handle this as one single entity and prevent the sale of the bundle product.

Part 3: Reference Option Decision Guide

Import-order Risk with Hard References

If bundle creation is automated (Import API), a bundle product cannot be created if any of its referenced component products do not yet exist in CT. Mitigation: use the Import API with a dependency-aware ordering, or accept a 48-hour eventual-consistency window (Import API creates missing dependencies within that window). For large catalog imports, this dependency tracking adds significant orchestration complexity — prefer soft references.

Bidirectional bundleId + parentId Pattern

• bundleId — set on the bundle (parent) line item with a unique identifier for that bundle instance in the cart
• parentId — set on each child line item, pointing to the parent's bundleId

1. Cart replication works correctly. When a cart is replicated (re-order, quote request creation), new line item IDs are generated. A parentLineItemId pointing to the old line item ID breaks. bundleId/parentId use a stable business identifier — the link survives replication.
2. Dynamic/configurable bundles. For build-to-order bundles where the customer assembles a configuration on the PDP, the bundleId can encode the configuration (e.g., a hash of selected options). This lets you determine whether an add-to-cart should create a new bundle line item or increment the quantity of an existing one.
3. Bidirectional traversal. Finding all children of a bundle: lineItems.filter(li => li.custom.parentId === bundleId). Finding the parent of a child: lineItems.find(li => li.custom.bundleId === childParentId).

Dynamic and Configurable Bundles

Static bundles have fixed components. Two more patterns exist:

Business Unit Hierarchy

Overview

The Business Unit (BU) hierarchy is the structural backbone of commercetools B2B. It models the real-world organisational structure of a buying company — from the top-level corporate entity down through divisions, subsidiaries, and teams — and controls how associates, stores, and permissions are scoped.

Conceptual Hierarchy

Organization (top-level Company BU)
└── Division / Region (Division BU)
    └── Team / Department (Division BU)
        └── Individual Buyer Account (Division BU)

Key Concepts

Stores and Business Units

• Stores are assigned to a Business Unit via the stores array on the BU resource.
• A Store on a BU scopes all carts and orders created within that BU to that Store's catalogue, price, and inventory scope.
• A BU can reference multiple Stores; a Store can be linked to multiple BUs.
• Associates can only act on carts/orders belonging to the BUs they are explicitly assigned to, even if the same Store is linked to another BU.

Associate Roles and Inheritance

• Associates are linked to a BU via the associates array, which specifies which associateRoles they hold within that BU.
• Role inheritance flows downward: roles granted on a parent BU are inherited by all descendant BUs, unless explicitly overridden.
• This allows centralised role management at high levels of the hierarchy while still supporting fine-grained overrides at lower levels.

Store Inheritance

• When a BU has storeMode: FromParent, it inherits the store assignments of its nearest ancestor that explicitly defines stores.
• When storeMode: Explicit, the BU uses only the stores listed on its own stores array.

Common B2B Hierarchy Patterns

Flat (single-level)

Company BU
├── Buyer Account A
├── Buyer Account B
└── Buyer Account C

Suitable for simple B2B portals where all buyer accounts are peers.

Regional / Divisional

Company BU  (global)
├── Division BU  (EMEA)
│   ├── Division BU  (Germany)
│   └── Division BU  (France)
└── Division BU  (APAC)
    └── Division BU  (Australia)

Useful when pricing, catalogues, or associates are region-specific.

Cost-Centre / Department

Company BU  (Enterprise Customer)
└── Division BU  (Procurement Department)
    ├── Division BU  (IT Budget)
    └── Division BU  (Facilities Budget)

Enables spend controls and approval rules at the department level.

API Resource Summary

• Create BU: POST /business-units
• Get BU: GET /business-units/{id} or GET /business-units/key={key}
• Get BU tree: Use GET /business-units with predicate topLevelUnit(id="{companyId}") to retrieve all descendants.
• As-Associate context: All buyer-facing mutations must go through the asAssociate API path to enforce permission checks (see as-associate-api.md).

Customer Groups on Business Units (Multi-Group Pricing)

• cart.businessUnit — the cart must be associated with a Business Unit
• businessUnit.customerGroupAssignments — the BU must have at least one Customer Group assigned

Price selection evaluates all assigned Customer Groups and resolves the cheapest matching price.

Bulk Import of Business Units

Project-Level Defaults for Self-Service B2B Onboarding

Two project-level defaults affect self-service B2B onboarding design:

• Default Business Unit Status: Configurable in MC. When the default is Active, BUs created via self-registration are active immediately and require no explicit activation step. If you configure the default to Inactive, design your onboarding flow to handle the activation step.
• Default Associate Role: A default role assigned automatically to the creating Associate when a new BU is created via the me endpoint. Eliminates the need for a post-creation role assignment step in self-service flows.

Limitations

Cart Discount Scenarios — Concrete Configurations

A scenario cookbook for common cart discount requirements. Each scenario includes the business intent, the key structural choices, and the JSON that implements it.

Item Discount Distribution Modes

Note — applicationMode availability: The applicationMode field is available on both absolute/fixed cart discount values (CartDiscountValueAbsoluteDraft) and relative (percentage-based) cart discount values (CartDiscountValueRelativeDraft). The three modes apply identically regardless of value type:

• ProportionateDistribution (default): Distributes the discount proportionally across matched line items by their price
• EvenDistribution: Distributes the discount evenly across matched line items regardless of price
• IndividualApplication: Applies the full discount amount to each matched line item independently

This matters for Buy and Get and Discount Bundles scenarios with relative values where you want to control how the percentage discount is spread — for example, distributing a 50% discount proportionately across trigger + target items rather than applying the full percentage to each item individually.

Proportional Distribution in Buy & Get

• The discount is still calculated based on the target item's price
• But the discounted amount is prorated across all involved line items (trigger + target)
• Return scenarios are simpler: each line item carries its proportional discount, derivable without manual recalculation

Configure in MC: Buy and Get discount → "distributed proportionately across all involved items" (not "only applied to the discounted items").

Buy and Get — Apply On Parameter

• Cheapest items — sort eligible items low-to-high, apply discount starting from the least expensive
• Most expensive items — sort eligible items high-to-low, apply discount starting from the most expensive

• "Cheapest" = Cheapest items
• "MostExpensive" = Most expensive items

Buy and Get — Multiple Applications Parameter

Controls how many times a Buy and Get discount can fire per cart:

Core Structural Concepts

Buy and Get vs Discount Bundles

selectionMode

• "Cheapest" — discounts the least expensive qualifying items (protects margin on high-value items)
• "MostExpensive" — discounts the most expensive qualifying items (greater perceived value for the customer)

maxOccurrence

categories.key vs categoriesWithAncestors.key

• categories.key = "beds" — matches only items directly assigned to a category with key "beds"
• categoriesWithAncestors.key contains "beds" — matches items in "beds" AND any subcategory of "beds"

value types

• "relative" with permyriad — percentage discount (10000 = 100%, 5000 = 50%, 2500 = 25%)
• "absolute" with money array — fixed amount off (in centAmount)
• "fixed" with money array — set the total price of the targeted items to this amount (e.g., "3 items for $15 total")

Buy X Get Y Scenarios

Scenario 1: Buy 2+ of product A, get 1 of product B free

{
  "value": { "type": "relative", "permyriad": 10000 },
  "cartPredicate": "1 = 1",
  "target": {
    "type": "pattern",
    "triggerPattern": [
      {
        "type": "CountOnLineItemUnits",
        "predicate": "product.key = \"large-ceramic-plate\"",
        "minCount": 2
      }
    ],
    "targetPattern": [
      {
        "type": "CountOnLineItemUnits",
        "predicate": "product.key = \"classic-beer-mug\"",
        "minCount": 1,
        "maxCount": 1
      }
    ],
    "maxOccurrence": 1,
    "selectionMode": "Cheapest"
  }
}

Key notes:

• Trigger has no maxCount — 2 or more plates qualify.
• Target maxCount: 1 ensures only 1 beer mug is made free.
• maxOccurrence: 1 — the free mug is given once per cart regardless of plate quantity.
• permyriad: 10000 = 100% off the target item.

Scenario 2: Spend $100+ on item from category A, get $25 off an item from category B

{
  "value": {
    "type": "absolute",
    "money": [{ "currencyCode": "USD", "centAmount": 2500, "fractionDigits": 2 }],
    "applicationMode": "ProportionateDistribution"
  },
  "cartPredicate": "1 = 1",
  "target": {
    "type": "pattern",
    "triggerPattern": [
      {
        "type": "CountOnLineItemUnits",
        "predicate": "categories.key contains \"furniture\" and price.centAmount > 10000",
        "minCount": 1,
        "maxCount": 1
      }
    ],
    "targetPattern": [
      {
        "type": "CountOnLineItemUnits",
        "predicate": "categories.key contains \"home-decor\"",
        "minCount": 1,
        "maxCount": 1
      }
    ],
    "selectionMode": "Cheapest"
  }
}

Key notes:

• price.centAmount > 10000 inside the trigger predicate filters on per-item price (centAmount 10000 = $100.00), not cart total. This is a CountOnLineItemUnits predicate — it can combine category and price conditions on the line item.
• Use lineItemGrossTotal in cartPredicate instead if you need a category spend threshold (see Scenario 5).

Scenario 3: Buy N of category A, get M of category B for a fixed price

{
  "value": {
    "type": "fixed",
    "money": [{ "currencyCode": "USD", "centAmount": 7500, "fractionDigits": 2 }],
    "applicationMode": "ProportionateDistribution"
  },
  "cartPredicate": "1 = 1",
  "target": {
    "type": "pattern",
    "triggerPattern": [
      {
        "type": "CountOnLineItemUnits",
        "predicate": "categories.key contains \"beds\"",
        "minCount": 3
      }
    ],
    "targetPattern": [
      {
        "type": "CountOnLineItemUnits",
        "predicate": "categories.key contains \"rugs\"",
        "minCount": 2,
        "maxCount": 2
      }
    ],
    "maxOccurrence": 1,
    "selectionMode": "Cheapest"
  }
}

Key notes:

• value.type: "fixed" sets the total price of the 2 target items to $75, distributed proportionately across both.
• maxCount: 2 in target — exactly 2 rugs receive the fixed price.

Scenario 4: Cart contains item from category A AND category B → $100 off order total

{
  "value": {
    "type": "absolute",
    "money": [{ "currencyCode": "USD", "centAmount": 10000, "fractionDigits": 2 }],
    "applicationMode": "ProportionateDistribution"
  },
  "cartPredicate": "lineItemExists(categories.id contains \"<bedroom-category-id>\") = true and lineItemExists(categories.id contains \"<living-room-category-id>\") = true",
  "target": { "type": "totalPrice" },
  "references": [
    { "typeId": "category", "id": "<bedroom-category-id>" },
    { "typeId": "category", "id": "<living-room-category-id>" }
  ]
}

Key notes:

• lineItemExists AND compound — the only way to express "cart must contain at least one item from category A AND at least one from category B" in a cart predicate. Each lineItemExists clause is a separate condition.
• Uses category IDs, not keys. IDs are resolved via the references array on the cart discount (shown in MC as "Category" reference picker).
• target.type: "totalPrice" — discount applies to the overall cart total, not specific line items.
• This is a Total Price discount effect in MC, not a Buy and Get or Discount Bundles effect.

Scenario 5: Spend $500+ on category A items → percentage off a specific product

{
  "value": { "type": "relative", "permyriad": 2500 },
  "cartPredicate": "lineItemGrossTotal(categories.key = (\"furniture\")) >= \"500.00 USD\"",
  "target": {
    "type": "lineItems",
    "predicate": "product.key = \"classic-beer-mug\""
  }
}

Key notes:

• lineItemGrossTotal(categories.key = (...)) >= "X.XX USD" — the only predicate function for "spend threshold on a specific category." Takes the sum of gross prices for all matching line items. Currency must be included in the string value.
• target.type: "lineItems" with a predicate — a simpler target form that applies to all matching line items (not capped by maxCount).
• This is an Item discount effect in MC, combined with a cart predicate.

Discount Bundles Scenarios

Scenario 6: N items for the price of M (percentage-based)

{
  "value": { "type": "relative", "permyriad": 4000 },
  "cartPredicate": "1 = 1",
  "target": {
    "type": "pattern",
    "triggerPattern": [],
    "targetPattern": [
      {
        "type": "CountOnLineItemUnits",
        "predicate": "product.key = \"large-ceramic-plate\"",
        "minCount": 5,
        "maxCount": 5
      }
    ],
    "selectionMode": "Cheapest"
  }
}

Key notes:

• Empty triggerPattern: [] — this is a Discount Bundles effect, not Buy and Get.
• minCount: 5, maxCount: 5 — the discount applies to exactly a set of 5. A second set of 5 would also qualify (unlimited occurrence).
• N for price of M formula: permyriad = ((N - M) / N) * 10000. For 5 for 3: (2/5) * 10000 = 4000.

Scenario 7: BOGO 50% (buy 1 get 1 at half price)

{
  "value": { "type": "relative", "permyriad": 2500 },
  "cartPredicate": "1 = 1",
  "target": {
    "type": "pattern",
    "triggerPattern": [],
    "targetPattern": [
      {
        "type": "CountOnLineItemUnits",
        "predicate": "categories.key = (\"furniture\")",
        "minCount": 2,
        "maxCount": 2
      }
    ],
    "selectionMode": "MostExpensive"
  }
}

Key notes:

• permyriad: 2500 = 25% off each of 2 items = financially equivalent to 50% off 1 item.
• selectionMode: "MostExpensive" — discounts the 2 most expensive furniture items (maximizes customer's perceived value).
• No maxOccurrence → applies to every pair of qualifying items in the cart. Add maxOccurrence: 1 to cap at one BOGO per cart.
• BOGO 50% permyriad formula: permyriad = (discount_percent / 2) * 100. For 50% off one: (50/2) * 100 = 2500.

Scenario 8: Fixed price for up to N items

{
  "value": {
    "type": "fixed",
    "money": [{ "currencyCode": "USD", "centAmount": 1500, "fractionDigits": 2 }],
    "applicationMode": "ProportionateDistribution"
  },
  "cartPredicate": "1 = 1",
  "target": {
    "type": "pattern",
    "triggerPattern": [],
    "targetPattern": [
      {
        "type": "CountOnLineItemUnits",
        "predicate": "product.key = \"classic-beer-mug\"",
        "minCount": 1,
        "maxCount": 3
      }
    ],
    "maxOccurrence": 1,
    "selectionMode": "Cheapest"
  }
}

Key notes:

• minCount: 1, maxCount: 3 — the $15 fixed price applies to 1, 2, or 3 mugs (whichever are in the cart, up to 3).
• applicationMode: "ProportionateDistribution" splits the $15 across the selected items proportionally.
• maxOccurrence: 1 — the $15 deal fires only once per cart.

Scenario 9: Category quantity threshold → fixed amount off

{
  "value": {
    "type": "absolute",
    "money": [{ "currencyCode": "USD", "centAmount": 15000, "fractionDigits": 2 }],
    "applicationMode": "ProportionateDistribution"
  },
  "cartPredicate": "1 = 1",
  "target": {
    "type": "pattern",
    "triggerPattern": [],
    "targetPattern": [
      {
        "type": "CountOnLineItemUnits",
        "predicate": "categories.key contains \"beds\"",
        "minCount": 3
      }
    ],
    "maxOccurrence": 1,
    "selectionMode": "MostExpensive"
  }
}

Key notes:

• No maxCount on the target — the $150 is distributed across all 3+ qualifying bed items.
• selectionMode: "MostExpensive" — the 3 most expensive beds are selected for discount attribution.
• maxOccurrence: 1 — $150 off is applied once even if the cart has 6+ beds.

Scenario 10: First item in a category is free (including subcategories)

{
  "value": { "type": "relative", "permyriad": 10000 },
  "cartPredicate": "1 = 1",
  "target": {
    "type": "pattern",
    "triggerPattern": [],
    "targetPattern": [
      {
        "type": "CountOnLineItemUnits",
        "predicate": "categoriesWithAncestors.key contains \"beds\"",
        "minCount": 1,
        "maxCount": 1
      }
    ],
    "maxOccurrence": 1,
    "selectionMode": "Cheapest"
  }
}

Key notes:

• categoriesWithAncestors.key contains "beds" instead of categories.key contains "beds" — this is the only way to include products assigned to subcategories of "beds" (e.g., "king-beds", "bunk-beds"). Use categoriesWithAncestors whenever the category hierarchy matters.
• maxCount: 1 + maxOccurrence: 1 = exactly one free item per cart, choosing the cheapest.

Scenario 11b: Buy 2 of the same item at a fixed price, limit 5 applications per order

MC configuration:

• Effect type: Discount bundles
• Count: is equal to 2, Item Criteria: category key includes "candle-holders"
• Apply On: Cheapest items
• Multiple applications: Enabled, specify 5 times
• Discount type: Fixed price
• Discount value: EUR 5.00

API JSON:

{
  "value": {
    "type": "fixed",
    "money": [{ "currencyCode": "EUR", "centAmount": 500, "fractionDigits": 2 }],
    "applicationMode": "ProportionateDistribution"
  },
  "cartPredicate": "1 = 1",
  "target": {
    "type": "pattern",
    "triggerPattern": [],
    "targetPattern": [
      {
        "type": "CountOnLineItemUnits",
        "predicate": "categories.key contains \"candle-holders\"",
        "minCount": 2,
        "maxCount": 2
      }
    ],
    "maxOccurrence": 5,
    "selectionMode": "Cheapest"
  }
}

Key notes:

• maxOccurrence: 5 caps the number of qualifying pairs — a cart with 12 candle holders gets the deal on 5 pairs (10 items), 2 items at full price.
• Fixed price type distributes the total proportionately across both items in the pair.

Scenario 11c: Buy 3 of an item, get the next 2 at half-price

This uses Buy and Get: trigger on 3+ items, target up to 2 items at 50% off.

MC configuration:

• Trigger: "Each time the cart contains" — count is at least 3, category key includes "candle-holders"
• Target: "Apply Discount on" — count is up to 2, category key includes "candle-holders"
• Apply On: Cheapest items
• Multiple applications: Disabled (fires once per pattern match)
• Discount type: Percentage off, 50

API JSON:

{
  "value": { "type": "relative", "permyriad": 5000 },
  "cartPredicate": "1 = 1",
  "target": {
    "type": "pattern",
    "triggerPattern": [
      {
        "type": "CountOnLineItemUnits",
        "predicate": "categories.key contains \"candle-holders\"",
        "minCount": 3
      }
    ],
    "targetPattern": [
      {
        "type": "CountOnLineItemUnits",
        "predicate": "categories.key contains \"candle-holders\"",
        "minCount": 1,
        "maxCount": 2
      }
    ],
    "selectionMode": "Cheapest"
  }
}

Key notes:

• The trigger and target reference the same category — this is valid. CT handles the deduplication.
• maxCount: 2 on target — at most 2 items receive the half-price discount per trigger occurrence.
• No maxOccurrence — if the cart has 9 candle holders, the pattern fires 3 times (3 trigger → 2 discounted, 3 trigger → 2 discounted, 3 trigger → 2 discounted).

Gift Line Item and Shipping Scenarios

Scenario 11: Spend $100, get a free gift item

{
  "value": {
    "type": "giftLineItem",
    "product": { "typeId": "product", "id": "<gift-product-id>" },
    "variantId": 1
  },
  "cartPredicate": "cartNetTotal >= \"100.00 USD\""
}

Key notes:

• Use value.type: "giftLineItem" — the dedicated gift value type. When the cartPredicate evaluates true, commercetools automatically adds the referenced product variant to the cart as a gift; you do not pre-add it and do not set a target. The gift product variant must have a price that can be selected for the cart (add supplyChannel/distributionChannel to the value if channel-specific price selection is needed).
• In the cart response, the gifted line item has "lineItemMode": "GiftLineItem", quantity: 1, and totalPrice.centAmount: 0. This mode is what distinguishes gift items from regular purchased items.
• A 100% relative discount on a normal line item does not produce a GiftLineItem — the line item keeps lineItemMode: Standard and is merely discounted to zero. Use giftLineItem for a true auto-added gift.
• Only one item can be added per gift line item discount; for "customer's choice of gift from N items," let the customer add their chosen product and price it to zero with a separate relative/absolute discount instead.
• The cart predicate uses cartNetTotal (excludes shipping and tax). Use totalPrice to include shipping in the threshold calculation.

Scenario 12: Free shipping when cart total ≥ $35

{
  "value": { "type": "relative", "permyriad": 10000 },
  "cartPredicate": "cartNetTotal >= \"35.00 USD\"",
  "target": { "type": "shipping" }
}

Key notes:

• target.type: "shipping" — applies the discount to the cart's shipping cost. This is distinct from the lineItems and totalPrice targets.
• permyriad: 10000 = 100% off shipping. For partial shipping discounts (e.g., "$5 off shipping"), use "type": "absolute" with a money array instead.
• In the cart response, shippingInfo.price.centAmount will show the original shipping rate, while shippingInfo.discountedPrice.centAmount will show 0.
• Shipping discounts can also be configured three ways: via shipping methods in Project Settings, as a cart discount targeting shipping, or through discount codes. The cart discount approach shown here is the most flexible for conditional free-shipping campaigns.
• The cartNetTotal predicate computes the sum of all line item prices before shipping and tax. This ensures the threshold is based on product spend only, not the shipping cost itself.

Promotion Prioritization — Product Discounts vs Cart Discounts

Discount Codes — Key Limits and Store-Specific Behavior

Usage limits

Capacity limits

• One discount code can reference up to 10 cart discounts
• A cart can have up to 10 discount codes applied simultaneously

Store-specific discount codes

• No additional implementation required — link the discount code to a cart discount that has stores set
• The code automatically inherits the store context from the cart discount
• The stores field on a cart discount is an array — one discount can apply across multiple stores
• A cart discount can be associated with up to 500 stores; a discount code reaches stores indirectly through the cart discount(s) it references
• Feature activates implicitly when you associate a code with a store-specific cart discount — no project-level toggle

Custom Associate Roles

Overview

commercetools B2B supports fully customisable associate roles. Roles are the primary mechanism for grouping permissions and assigning them to associates within a Business Unit. The platform ships with a set of predefined roles, but projects may create, edit, and delete roles to match their own permission model.

Frequently Asked Questions

How do you create custom roles in commercetools?

Can roles be grouped above the role level (e.g. "role groups" containing 30+ users)?

No. commercetools does not provide a native concept of "role groups" that sit above individual roles within a Business Unit. Roles themselves group permissions. If a higher-level grouping is needed (e.g. to manage 30+ users uniformly), that logic must be built in a custom service layer that assigns users to BUs with the appropriate roles.

Can B2B roles be customised from the out-of-the-box set?

Yes. Projects may:

• Create new roles with any combination of permissions.
• Edit existing roles to add or remove permissions.
• Delete roles that are no longer needed.

Can a user hold multiple roles?

Yes. An associate can be assigned multiple roles within a Business Unit. There is currently no hard platform limit on the number of roles per associate, unless the project reaches edge-case scale (thousands of roles for a single user).

Business Unit Hierarchy and Role Inheritance

Can Business Units have a parent–child hierarchy?

Can properties and roles/permissions be inherited from parent Business Units?

Yes. Roles and permissions configured on a parent Business Unit are inherited by its child Business Units, allowing centralised permission management.

What are the hierarchy depth limitations?

• Maximum 5 levels deep.
• Each BU can have only one parent.

Stores and Business Units

How are Stores related to Business Units? Is there data segregation?

When a Store is linked to a Business Unit, carts and orders created within that context are scoped to that Store. The practical implications are:

• Permissions granted to an associate on a BU control visibility of carts and orders for the Stores listed under that BU.
• An associate cannot act on behalf of a BU they are not assigned to, even if the same Store is linked to that BU.
• This provides a clear data segregation boundary: Store-scoped data is only accessible through the BU–Associate relationship.

Customer Groups Based Pricing

Customer groups are typically used in conjunction with Currency Code, Country and Channel to define a rich set of price rules. These are price selection parameters.

• CurrencyCode
• Country
• Customer Group (single group; on Product Projection search / price selection, the parameter is priceCustomerGroup)
• Customer Group Assignments (multi-group resolution; on Product Projection search / price selection, the parameter is priceCustomerGroupAssignments)
• Channel
• PriceDate (represented as validFrom and validTo)

1. If price currency and additional price selection parameters are included in product projection search, the platform will use price selection logic to return the matching price to the customer.

   • Reference: https://docs.commercetools.com/api/projects/products#price-selection
2. When adding lineItems to carts, the platform will use the currency and additional price selection parameters to select the same price. In order for price selection to work when calling addLineItem, the price selection parameters (i.e. currencyCode, country, customerGroup...) must be present on the cart. See: https://docs.commercetools.com/api/projects/carts

3. When defining pricing that includes price selection criteria, it is recommended to include a default price within the variant pricing model that can be used as a fall back.

Customer Group associated with a price

"Can not delete a source while it is referenced from at least one 'product'."

In this situation, it would be required to first create the new customer group, modify all discounts referencing the existing customer group and then delete the existing customer group from the platform.

Discount Code Usage

How to retrieve discount code usage / application counts.

Option 1: Via GraphQL Query

{
  discountCodes {
    results {
      id
      applicationCount
    }
  }
}

Option 2: Via CSV Export from Merchant Center

Discount Fundamentals

Part 1: Discounts Topics

Use of "Price - Customer group ID" on product discounts

It is a little bit confusing: If "Price - Customer group ID" is used in a product discount predicate; the product discount is applied to prices defined for a specific customer group. If a customer that belongs to the group but the price is a price that applies to all customer groups the discount will not apply.

This can work only if they have specific prices for the customer group.

Example: Price - Customer group ID is My_Customer_Group — if the price used in the line item is not specifically defined for this customer group (for example a default price for all channels, customer groups, countries, etc) then the discount will not apply even if the customer belongs to that customer group.

From the API, it seems like you can't apply this type of promotion at the product level, but you can do it at the cart level (using the user assigned to the cart). This means that it's not automatically applicable when showing the PDP.

Is this correct?

i) Search for all applicable discounts for a signed-in customer using customer email or custom fields on customer resources?

ii) Can cart discounts be queried by custom fields values? For example, search all cart-discounts where customer-type is "Employee" (here the customer-type is a custom field on a cart discount)

iii) Search for all discount codes for a particular customer-group or search discounts codes using custom fields?

These scenarios work well only when a cart is configured and the cart has these fields out of the box or through custom fields. Customer is looking for finding applicable promotions even before customer builds a cart and browsing as a signed-in customer.

Buy 2 for $99 Polos. Expected outcome:

• 2 items in cart - Buy 2 for $99
• 3 items in cart – 2 for $99, 3rd at full price
• 4 items in cart – 2 for $99 applies, so total is $198
• 5 items in cart – 2 for $99 applies to 4 items, 5th item is full price

Is there another way to get to the outcome they are after using the commercetools promotions engine?

1. Add the even qty items (2, 4, 6, and so on) as one line item on cart with a line item custom field defined and single qty item (qty=1) as a separate line item on the cart. The cart will add separate line items if custom fields/its values are different.

2. Create a fixed price cart discount with Cart Promotion Rule & Cart Qualifier as below:

3. Fixed price for each line item = 49.5 if the double qty sells for 99 (half the original price)

4. Promotion Rule -> product.id or sku = "xyz" and custom.<line_item_custom_field_name> = "<custom value>"
5. Cart Qualifier Rule -> lineItemExists(quantity = 2) = true or lineItemExists(quantity = 4) = true or lineItemExists(quantity = 6) = true

Alternatively, the bundle price option is another viable approach, though the above works without changing the product data model.

Details: Customer buys item X which makes them eligible for a gift with purchase, however, they get to choose one item from the list of 10 items instead of the one predefined product as a gift. Our current promotion rules allow a predefined product as a gift but does not offer a selection of choices to customer. Multibuy promotions option at line level also doesn't solve this.

1. Use a custom field on cart discount of 2-for-1 discount to mark as "Not to combine with VIP" or any appropriate flag/indicator if this discount cannot be combined with VIP or any other discount.

2. When adding a 2-for-1 cart discount to the cart, update a custom field on the cart to mention that this discount cannot be combined with VIP discount.

3. Configure the VIP cart discount predicate to check for cart discount custom attribute where its value is NOT "VIP Discount" or the expected value.

   In this scenario the VIP discount won't get applied based on the predicates.

4. Additionally, you can use custom fields on VIP discount as well to consider for the vice-versa scenario where 2-for-1 discount cannot be applied if VIP discount exists on a cart.

Yes, you may use the Discounts endpoint API (Cart Discounts, Product Discounts, Discount Codes) to query for discounts in commercetools. To be able to use automatic cart discounts efficiently, a dummy cart or a real cart is more appropriate to see if a cart is eligible for such discounts where no discount code is required.

API extensions cannot be created on discounts resources therefore, this validation flow will have to be a custom logic that you may have to implement by applying custom logic. A better way to manage this would be to have a feed come from your coupons system either via nightly job or a cron job (every 15/30/60 mins?) to commercetools and then update the validity on discount codes in commercetools so that the discounts in commercetools are valid and can be used on carts & checkout.

• Assuming that the coupon code is set with cart discount where free shipping is the target for that discount to be applied on a cart.

• When the coupon code for free shipping is added to cart, it will show the discount code as "Matches Cart" (as long as the cart qualifies with the cart discount condition) — the storefront can use this info to show the eligibility of free shipping to the customer.

• Now on checkout, when customer adds shipping address and chooses a shipping method or when the storefront adds a shipping method based on the shipping address, the shipping charges will automatically be discounted as the cart discount is active. Meaning if the shipping charge was $20, it will show the shipping fee of $20 as price but it will also show discounted shipping price as zero under shipping info.

Long story short, they don't need to add shipping address to know the eligibility of a free shipping discount code.

You can edit/extend the validity dates. There is no restriction on modifying those dates.

If direct discounts are present:

• discount codes: NOT supported (blocked)
• cart discounts: NOT supported (blocked)
• product discounts: Supported (allowed)

Part 2: Discount Solutions to Un-supported Scenarios

The scenario is as follows: If a customer buys more than one units of a specific product they want the first unit to be for example $50 and the rest to have a 20% discount.

Tiered prices does not support it, because the price applies to all units and the customer wants to charge the first one a different (higher) price. In addition if there are other conditions for this discount to apply that can be added to a cart discount predicate but not for prices.

Multibuy discounts also do not provide a solution, for example buy 1 get 1 with 20% discount works great for 2 units but not for 3 (only even numbers).

The use case is as follows: If a customer buys 1 product A and one product B, they want to provide a specific discount (absolute or percent) to one of the products (A or B). They are trying to achieve a discounted price for the pair without implementing bundles.

Multibuy does not provide a solution because if the predicate requires for example SKU to be either product A OR product B then for example 2 units of product A will get the discount.

Key Platform Limits (Discounts)

Discount Type Quick Reference

• Can only be used with platform pricing (not ExternalAmount/External)
• Applied at product variant level, before items are added to the cart
• Do NOT stack — only the highest-ranked (lowest sortOrder value) applies per variant
• Max 500 active at once

• Work with platform or external pricing
• Applied when items are added to the cart
• Stack by default unless stackingMode: "StopAfterThisDiscount" is set
• Rounding: configurable via priceRoundingMode (default HalfEven)

1. Via shipping method's freeAbove threshold in Project Settings
2. As a Cart Discount with target.type: "shipping"
3. Via discount codes linked to a shipping cart discount

Discount Groups and Discount Combination Mode

Discount Groups

Discount Groups let you bundle multiple cart discounts under a single logical entity. This is the primary tool for managing large-scale campaigns like Black Friday or Cyber Week.

Why use them

Without Discount Groups, disabling a campaign means toggling off each individual discount rule one by one. A Discount Group can be deactivated in a single action, instantly stopping all discounts in that group.

Limits

• Up to 100 Cart Discounts per Discount Group
• Up to 100 Discount Groups per project

How selection works within a group

Discount application sequence when Discount Groups are active:

1. Product discounts are pre-computed and applied to the product price.
2. Cart discounts are computed against the original (non-product-discounted) price. If cart discounts belong to a group, only the best one from that group is selected.
3. The product-discounted price is compared against the cart-discounted price, and the lower of the two is applied to the cart.

Creating a group

Each Discount Group has:

• A key (unique identifier)
• A rank / sortOrder (a globally-unique decimal across all cart discounts and Discount Groups; higher fires first)
• A Discount prioritization mode — currently only "Best deal" is available (applies the discount with the lowest resulting cart price)

discountCombinationMode (Project-Level Setting)

Two modes

BestDeal application sequence

1. Product discounts are pre-computed and applied to the product price.
2. Cart discounts are computed against the original (non-product-discounted) price (if discounts belong to a Discount Group, only the best one per group is selected).
3. The product-discounted price is compared against the cart-discounted price. The lower of the two is applied.

discountTypeCombination response field

• type — the combination mode that was applied (Stacking or BestDeal)
• chosenDiscountType — the winning discount type (ProductDiscount or CartDiscount)

Use this field for discount analytics and debugging unexpected discount outcomes.

Platform Limits Reference (Cart Discounts)

Store-Specific Discount Codes

Store-specific discount codes link a discount code to store-aware cart discounts so the promotion only applies in the intended store context.

• No additional implementation work — associate the discount code with a cart discount that has a store assignment. The code automatically inherits the store context.
• The store field on cart discounts is an array — a single cart discount can apply across up to 500 stores.
• There is no project-level toggle. The feature activates implicitly when a code is associated with a store-specific cart discount.
• Use case: merchants using stores as regional or brand partitions — prevents discount code conflicts across store boundaries and simplifies regional campaign management.

Handling Dynamic Shipping Costs

Overview

Consider a scenario where the shipping cost is computed by a 3rd party logistics provider, therefore at the time of cart creation the precise shipping cost is unknown.

There are two methods to handle this:

1. Method 1: Using cart freeze & the SetCustomShippingMethod API call
2. Method 2: Using Order Edits

Method 1: Using cart freeze & the SetCustomShippingMethod API call

Structure of the $0 shipping method (predicates may be used as required)

{
            "id": "d07b163f-f76d-41c9-8aa3-b9de2d4529ec",
            "version": 1,
            "versionModifiedAt": "2024-12-08T19:16:38.773Z",
            "createdAt": "2024-12-08T19:16:38.773Z",
            "lastModifiedAt": "2024-12-08T19:16:38.773Z",
            "lastModifiedBy": {
                "isPlatformClient": true,
                "user": {
                    "typeId": "user",
                    "id": "{user-id}"
                }
            },
            "createdBy": {
                "isPlatformClient": true,
                "user": {
                    "typeId": "user",
                    "id": "{user-id}"
                }
            },
            "name": "Example Dynamic Delivery",
            "localizedName": {
                "en-US": "Example Dynamic Delivery"
            },
            "localizedDescription": {
                "en-US": "Example Dynamic Delivery"
            },
            "taxCategory": {
                "typeId": "tax-category",
                "id": "193570d0-555f-4be2-a172-6ff5639952e6"
            },
            "zoneRates": [
                {
                    "zone": {
                        "typeId": "zone",
                        "id": "a77a57f0-01bb-4e6e-99af-08c0e6d0b5a6"
                    },
                    "shippingRates": [
                        {
                            "price": {
                                "type": "centPrecision",
                                "currencyCode": "USD",
                                "centAmount": 0,
                                "fractionDigits": 2
                            },
                            "tiers": []
                        }
                    ]
                }
            ],
            "active": true,
            "isDefault": false,
            "predicate": "1 = 1",
            "key": "example-dynamic-delivery",
            "references": []
        }

Cart Creation

curl --location 'https://api.us-central1.gcp.commercetools.com/{your-project-key}/carts' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer' \
--data '{
  "key": "example-cart-key-1",
  "currency": "USD",
  "country": "US",
  "shippingMode": "Single",
  "lineItems": [
    {
      "sku": "SCM-02",
      "quantity": 1
    },
    {
      "sku": "MCP-01",
      "quantity": 1
    }
  ]
}
'

Setting the shipping address on the cart

curl --location 'https://api.us-central1.gcp.commercetools.com/{your-project-key}/carts/{cart-id}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer' \
--data '{
    "version": 5,
    "actions": [
        {
            "action" : "setShippingAddress",
            "address" : {
              "key" : "example-address-key",
              "title" : "My Address",
              "salutation" : "Mr.",
              "firstName" : "Jane",
              "lastName" : "Smith",
              "streetName" : "Main",
              "streetNumber" : "123",
              "postalCode" : "10001",
              "city" : "New York",
              "state" : "NY",
              "country" : "US"
            }
          }
    ]
}'

Associating the $0 shipping method to the cart (since the exact shipping cost is unknown)

curl --location 'https://api.us-central1.gcp.commercetools.com/{your-project-key}/carts/{cart-id}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer' \
--data '{
    "version": 8,
    "actions": [
        {
            "action" : "setShippingMethod",
            "shippingMethod" : {
              "id" : "d07b163f-f76d-41c9-8aa3-b9de2d4529ec",
              "typeId" : "shipping-method"
            }
          }
    ]
}'

Freezing the cart

curl --location 'https://api.us-central1.gcp.commercetools.com/{your-project-key}/carts/{cart-id}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer' \
--data '{
    "version": 10,
    "actions": [
        {
            "action" : "freezeCart"
          }
    ]
}'

Associating the new shipping cost to the cart using the SetCustomShippingMethod API call

curl --location 'https://api.us-central1.gcp.commercetools.com/{your-project-key}/carts/{cart-id}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer' \
--data '{
    "version": 13,
    "actions": [
        {
            "action" : "setCustomShippingMethod",
            "shippingMethodName" : "myCustomShippingMethod",
            "shippingRate" : {
              "price" : {
                "currencyCode" : "USD",
                "centAmount" : 990
              }
            },
            "taxCategory" : {
              "id" : "193570d0-555f-4be2-a172-6ff5639952e6",
              "typeId" : "tax-category"
            }
          }
    ]
}'

Converting the frozen cart to an order

curl --location 'https://api.us-central1.gcp.commercetools.com/{your-project-key}/orders' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer' \
--data '{
  "cart" : {
    "id" : "{cart-id}",
    "typeId" : "cart"
  },
  "version" : 13
}'

{
    "type": "Order",
    "id": "{order-id}",
   ///
    "shippingInfo": {
        "shippingMethodName": "myCustomShippingMethod",
        "price": {
            "type": "centPrecision",
            "currencyCode": "USD",
            "centAmount": 990,
            "fractionDigits": 2
        },
        "shippingRate": {
            "price": {
                "type": "centPrecision",
                "currencyCode": "USD",
                "centAmount": 990,
                "fractionDigits": 2
            },
            "tiers": []
        }///
        "shippingMethodState": "MatchesCart"
    },
    "shippingAddress": {
        "title": "My Address",
        "salutation": "Mr.",
        "firstName": "Jane",
        "lastName": "Smith",
        "streetName": "Main",
        "streetNumber": "123",
        "postalCode": "10001",
        "city": "New York",
        "state": "NY",
        "country": "US",
        "key": "example-address-key"
    },
    "shipping": [],
    "lineItems": [///],
    "customLineItems": [],
    "transactionFee": true,
    "discountCodes": [],
    "directDiscounts": [],
    "cart": {
        "typeId": "cart",
        "id": "{cart-id}"
    },
    "itemShippingAddresses": [],
    "refusedGifts": []
}

Method 2: Using Order Edits

Cart creation

curl --location 'https://api.us-central1.gcp.commercetools.com/{your-project-key}/carts' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer' \
--data '{
  "key": "example-cart-key-2",
  "currency": "USD",
  "country": "US",
  "shippingMode": "Single",
  "lineItems": [
    {
      "sku": "SCM-02",
      "quantity": 1
    },
    {
      "sku": "MCP-01",
      "quantity": 1
    }
  ]
}
'

Setting the shipping address on the cart

curl --location 'https://api.us-central1.gcp.commercetools.com/{your-project-key}/carts/{cart-id-2}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer' \
--data '{
    "version": 5,
    "actions": [
        {
            "action" : "setShippingAddress",
            "address" : {
              "key" : "example-address-key",
              "title" : "My Address",
              "salutation" : "Mr.",
              "firstName" : "Jane",
              "lastName" : "Smith",
              "streetName" : "Main",
              "streetNumber" : "123",
              "postalCode" : "10001",
              "city" : "New York",
              "state" : "NY",
              "country" : "US"
            }
          }
    ]
}'

Associating the $0 shipping method to the cart (since the exact shipping cost is unknown)

curl --location 'https://api.us-central1.gcp.commercetools.com/{your-project-key}/carts/{cart-id-2}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data '{
    "version": 8,
    "actions": [
        {
            "action" : "setShippingMethod",
            "shippingMethod" : {
              "id" : "d07b163f-f76d-41c9-8aa3-b9de2d4529ec",
              "typeId" : "shipping-method"
            }
          }
    ]
}'

Convert the cart to an order

curl --location 'https://api.us-central1.gcp.commercetools.com/{your-project-key}/orders' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data '{
  "cart" : {
    "id" : "{cart-id-2}",
    "typeId" : "cart"
  },
  "version" : 8
}'

Create an OrderEdit draft and set the appropriate CustomShippingMethod in it

curl --location 'https://api.us-central1.gcp.commercetools.com/{your-project-key}/orders/edits' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data '{
  "key" : "example-order-edit-key",
  "resource" : {
    "typeId" : "order",
    "id" : "{order-id}"
  },
  "stagedActions" : [ {
  "action": "setCustomShippingMethod",
  "shippingMethodName": "example-dynamic-shipping-update",
  "shippingRate": {
    "price": {
      "currencyCode": "USD",
      "centAmount": 990
    }
  },
  "taxCategory": {
    "typeId": "tax-category",
    "id": "193570d0-555f-4be2-a172-6ff5639952e6"
  }
} ],
  "comment" : "updated shipping costs"
}'

Following this, apply the order edit.

Accept the order edit preview and proceed with completing the order edit.

Financing Options

How to setup financing options to be displayed in the PDP

• 0% financing for 18 months
• 0% financing for 12 months
• etc.

Need to include specific text and additional information about each financing option.

Option 1: Custom Fields on the Price

Setup the financing options as a set of custom fields in the price (one record for each financing option).

• Retrieved with the product information

• Requires setup for each variant and can be confusing to the user
• For each price, requires one additional price for the period when the financing is available

Option 2: Custom Objects Associated with the Product

Use a set of custom objects associated with the product (same for all variants). Each custom object will contain one financing option's information.

• Can be set at product level

• Need to check the validity period; not enough to expand when the product is retrieved
• Is maintained in the custom object (via the API or custom app)

Additional Answers

• Can be defined for a number of products (by category, brand, etc.)
• Validity period is set for the discount
• Supports custom fields to save all the necessary information for each financing option

Fixed Price Combo Discount

Part 1: Fixed Price Combo Discount

Scenario

The customer wants to provide fixed price discounts when specific items are added to the cart. The net effect would be to provide discounted price for each item in a combo or bundle. The customer does not want to create static bundles for each combination of items.

Create a promotion scheme capable of discounting multiple products by a set amount when added to the cart. In this example fixed price discounts and a discount code will be used.

Two products will be created with different published prices. The discounts will reduce the variant prices to $5 so that the combined price for the two products is $10.

Custom Type

Create a lineItem custom type containing two attributes. The two attributes will be set during the add item calls to the cart API and will also be used in the cart discount predicate. These attributes also can aid in item cleanup.

curl --location 'https://api.us-central1.gcp.commercetools.com/{{project-key}}/types' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data '{
  "key" : "lineItemComboType",
  "name" : {
    "en" : "lineItemComboType"
  },
  "description" : {
    "en" : "LineItem Combo type"
  },
  "resourceTypeIds" : [ "line-item" ],
  "fieldDefinitions" : [ 
      {
        "name" : "isPartOfCombo",
        "label" : {
        "en" : "isPartOfCombo"
        },
        "required" : true,
        "type" : {
        "name" : "Boolean"
        }
    },
    {
        "name" : "comboId",
        "label" : {
        "en" : "comboId"
        },
        "required" : false,
        "type" : {
        "name" : "String"
        }
    }
  ]
}'

Cart Discount

Build a cart discount containing a fixed price discount which reduces the price of the target skus to $5. The discount code required option is selected.

The promotion rule predicate is created to include the custom line item type attributes and the skus for the items (skus could be replaced by categories).

The predicate syntax is:

(custom.isPartOfCombo = true and custom.comboId is defined) and (sku = "simple-sandwich" or sku = "simple-soup")

The cart qualifier is set to apply to all shopping carts without exclusion. This could be set to target specific carts if needed.

Discount Code

The setup for the discount code is straightforward — associate it with the cart discount created above.

Cart Interactions

Items are added to the cart using the custom type defined above. The first combo item is added with the isCombo set to false and the comboId with no value.

curl --location 'https://api.us-central1.gcp.commercetools.com/{{project-key}}/carts/{{}cart-id}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data '{
    "version": {{version}},
    "actions": [
        {
            "action" : "addLineItem",
            "sku": "simple-soup",
            "quantity" : 1,
            "externalTaxAmount" : {
              "name" : "StandardExternalTaxRate",
              "amount" : 0.19,
              "country" : "US"
            },
            "custom" : {
                "type" : {
                    "key" : "lineItemComboType",
                    "typeId" : "type"
                    },
                "fields" : {
                "isPartOfCombo" : false,
                "comboId" : ""
                }
            }
            
          }
    ]
}'

When the second combo item is added to the cart, the item is added with the isCombo flag set to true and the comboId set to some value (GUID). The request also includes update commands on the first lineItem to set the isCombo attribute to true and the comboID to the new value.

curl --location 'https://api.us-central1.gcp.commercetools.com/{{project-key}}/carts/{{cart-id}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data '{
    "version": 26,
    "actions": [
        {
            "action" : "setLineItemCustomField",
            "lineItemId" : "{{line-item-id}}",
            "name" : "isPartOfCombo",
            "value" : true
        },
        {
            "action" : "setLineItemCustomField",
            "lineItemId" : "{{line-item-id}}",
            "name" : "comboId",
            "value" : "soup-combo-2"
        },
        {
            "action" : "addLineItem",
            "sku": "simple-sandwich",
            "quantity" : 1,
            "externalTaxAmount" : {
              "name" : "StandardExternalTaxRate",
              "amount" : 0.19,
              "country" : "US"
            },
            "custom": {
                "type" : {
                    "key" : "lineItemComboType",
                    "typeId" : "type"
                    },
                    "fields" : {
                    "isPartOfCombo" : true,
                    "comboId" : "soup-combo-2"
                    }
            }
            
          }
    ]
}'

The comboId would be unique for each pair of combo items. When line items are added with unique custom attribute values they are added as new line items — as opposed to incrementing the quantity of an existing line item. The comboId could also aid in cleanup of items as customers add and remove items from the cart.

When the discount code is added to the cart the discount is applied only to the items with the matching skus, isCombo=true and a comboId value.

Representative Cart Examples

# one set of combo items 
{
  "data": {
    "carts": {
      "results": [
        {
          "id": "{cart-id}",
          "lineItems": [
            {
              "id": "1fb0b0a6-94f5-4cd8-be44-6459d77f588a",
              "custom": {
                "customFieldsRaw": [
                  {
                    "name": "isPartOfCombo",
                    "value": true
                  },
                  {
                    "name": "comboId",
                    "value": "soup-combo-1"
                  }
                ]
              },
              "quantity": 1,
              "variant": {
                "sku": "simple-soup",
                "price": {
                  "country": "US",
                  "key": "simple-soup",
                  "value": {
                    "centAmount": 800,
                    "currencyCode": "USD",
                    "fractionDigits": 2
                  }
                }
              },
              "discountedPricePerQuantity": [
                {
                  "quantity": 1,
                  "discountedPrice": {
                    "value": {
                      "centAmount": 500,
                      "currencyCode": "USD",
                      "fractionDigits": 2
                    },
                    "includedDiscounts": [
                      {
                        "discount": {
                          "key": "soup-sandwidth-combo-sandwich-discount-dup",
                          "name": null
                        }
                      }
                    ]
                  }
                }
              ]
            },
            {
              "id": "04357fa1-204c-44a3-9670-e2c0efebd726",
              "custom": {
                "customFieldsRaw": [
                  {
                    "name": "isPartOfCombo",
                    "value": true
                  },
                  {
                    "name": "comboId",
                    "value": "soup-combo-1"
                  }
                ]
              },
              "quantity": 1,
              "variant": {
                "sku": "simple-sandwich",
                "price": {
                  "country": null,
                  "key": "default-price",
                  "value": {
                    "centAmount": 1000,
                    "currencyCode": "USD",
                    "fractionDigits": 2
                  }
                }
              },
              "discountedPricePerQuantity": [
                {
                  "quantity": 1,
                  "discountedPrice": {
                    "value": {
                      "centAmount": 500,
                      "currencyCode": "USD",
                      "fractionDigits": 2
                    },
                    "includedDiscounts": [
                      {
                        "discount": {
                          "key": "soup-sandwidth-combo-sandwich-discount-dup",
                          "name": null
                        }
                      }
                    ]
                  }
                }
              ]
            }
          ],
          "totalPrice": {
            "centAmount": 1000,
            "currencyCode": "USD",
            "fractionDigits": 2
          },
          "discountCodes": [
            {
              "discountCode": {
                "id": "0788fbc9-d0d3-46b9-801e-826b18404636",
                "code": "10$-SOUP_AND_SANDWICH"
              }
            }
          ]
        }
      ]
    }
  }
}