Order bumps

Order bumps are one-click upsells shown at checkout — "Add a gift card?". They appear after the shopper selects payment method but before completing the order. Use these endpoints to manage which products trigger which bumps for which segments.

List checkout bumps

Lists the order bumps (one-click add-ons) that match the products of a checkout.

Authorization

X-Sales-Channel-Origin<token>

For /api/vc/{connectionId}/* routes the connectionId (vc_*) is in the URL path — not a header. Live-mode requests must also send a matching Origin header.

In: header

Path Parameters

connectionIdstring

Sales channel ID (vc_*), the canonical salesChannelId. connectionId is the deprecated name of the same value and is still the literal path segment.

checkoutIdstring

Checkout id, returned by checkout (create checkout).

Query Parameters

locale?string

Language code, for example he. Used only when no Accept-Language header is sent. A language the store does not support, or the store's default language, returns the default text.

Header Parameters

originstring

Origin of the storefront page making the call, for example https://shop.example.com. Required: a request with no Origin header is refused with 403. On a LIVE channel its host must equal the channel's registered domain (or one of its subdomains) or match an allowed origin. A TEST channel with no domain accepts any origin; once a domain is set it is matched as on LIVE.

accept-language?string

Preferred language, for example he. Its first tag is used when it is one of the store's supported languages other than the default; translated fields are then returned in that language. Falls back to the locale query parameter.

X-SDK-Version?string

Version of the calling SDK (the Brainerce SDK sends it automatically). Informational: it is recorded on the channel and never changes the response.

curl -X GET "https://api.brainerce.com/api/vc/string/checkout/string/bumps?locale=string" \
  -H "origin: string" \
  -H "accept-language: string" \
  -H "X-SDK-Version: string"

curl -X GET "https://api.brainerce.com/api/vc/string/checkout/string/bumps?locale=string" \  -H "origin: string" \  -H "accept-language: string" \  -H "X-SDK-Version: string"

{
  "bumps": [
    {
      "id": "clx1234567890",
      "title": "string",
      "description": "string",
      "bumpProduct": {
        "id": "clprd_abc123",
        "name": "string",
        "slug": "blue-mug",
        "basePrice": "9.00",
        "salePrice": "19.99",
        "images": [
          {
            "url": "https://cdn.brainerce.com/products/abc123.jpg",
            "alt": "Blue mug"
          }
        ],
        "type": "SIMPLE",
        "variants": [
          {}
        ]
      },
      "bumpVariantId": "clbumpvariant_abc123",
      "requiresVariantSelection": false,
      "lockedVariant": {
        "id": "clvar_abc123",
        "name": "string",
        "attributes": {}
      },
      "originalPrice": "9.00",
      "discountedPrice": "7.20",
      "discountType": "PERCENTAGE",
      "discountValue": "20"
    }
  ]
}

{
  "statusCode": 403,
  "code": "INSUFFICIENT_SCOPE",
  "message": "API key does not have the required scope: products:write",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/vc/{connectionId}/checkout/{checkoutId}/bumps"
}

{
  "statusCode": 404,
  "code": "RESOURCE_NOT_FOUND",
  "message": "Resource not found",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/vc/{connectionId}/checkout/{checkoutId}/bumps"
}

{
  "statusCode": 429,
  "code": "RATE_LIMITED",
  "message": "Too many requests",
  "details": {
    "retryAfterSeconds": 12
  },
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/vc/{connectionId}/checkout/{checkoutId}/bumps"
}

Add order bump

Adds an order bump product to the cart with its discount applied. A variable bump product needs variantId unless the merchant locked one on the bump.

Authorization

X-Sales-Channel-Origin<token>

For /api/vc/{connectionId}/* routes the connectionId (vc_*) is in the URL path — not a header. Live-mode requests must also send a matching Origin header.

In: header

Path Parameters

connectionIdstring

Sales channel ID (vc_*), the canonical salesChannelId. connectionId is the deprecated name of the same value and is still the literal path segment.

cartIdstring

Cart id, returned by cart (create cart).

Query Parameters

locale?string

Language code, for example he. Used only when no Accept-Language header is sent. A language the store does not support, or the store's default language, returns the default text.

cartToken?string

Proof that the caller holds this cart. For a guest cart send the cart sessionToken (returned when the cart was created). Required on every cart write when the store runs cart ownership in enforce mode; a missing or wrong token answers 403 CART_ACCESS_DENIED (never 401). A customer cart is proven by the customer Bearer token instead. Send either the cartToken query parameter or the X-Cart-Session header.

Header Parameters

originstring

accept-language?string

X-SDK-Version?string

Version of the calling SDK (the Brainerce SDK sends it automatically). Informational: it is recorded on the channel and never changes the response.

x-cart-session?string

Request Body

bumpConfigIdstring

Id of the order-bump configuration being accepted.

Lengthlength <= 100

variantId?string

Variant of the bump product to add. Required when the bump product is VARIABLE and the merchant did not lock a variant on the bump config; ignored when they did (the locked variant always wins). Must belong to the bump product.

Lengthlength <= 100

curl -X POST "https://api.brainerce.com/api/vc/string/cart/string/bump?locale=string&cartToken=string" \
  -H "origin: string" \
  -H "accept-language: string" \
  -H "X-SDK-Version: string" \
  -H "x-cart-session: string" \
  -H "Content-Type: application/json" \
  -d '{
    "bumpConfigId": "clbumpconfig_abc123"
  }'

curl -X POST "https://api.brainerce.com/api/vc/string/cart/string/bump?locale=string&cartToken=string" \  -H "origin: string" \  -H "accept-language: string" \  -H "X-SDK-Version: string" \  -H "x-cart-session: string" \  -H "Content-Type: application/json" \  -d '{    "bumpConfigId": "clbumpconfig_abc123"  }'

{
  "id": "clcrt_abc123",
  "sessionToken": "string",
  "customerId": "clcustomer_abc123",
  "status": "ACTIVE",
  "currency": "USD",
  "notes": "string",
  "analyticsClientId": "clanalyticsclient_abc123",
  "analyticsSessionId": "clanalyticssession_abc123",
  "subtotal": "39.80",
  "discountAmount": "5.00",
  "ruleDiscountAmount": "0",
  "promoDiscountTotal": "0",
  "couponCode": "WELCOME10",
  "appliedDiscounts": [
    {
      "ruleId": "cldr_abc123",
      "ruleName": "string",
      "type": "PRODUCT_DISCOUNT",
      "discountAmount": "5.00",
      "description": "string"
    }
  ],
  "nudges": [
    {
      "ruleId": "cldr_abc123",
      "text": "string",
      "type": "AMOUNT_NEEDED",
      "amountNeeded": "12.00",
      "quantityNeeded": 1
    }
  ],
  "items": [
    {
      "id": "clx1234567890",
      "productId": "clprd_abc123",
      "variantId": "clvariant_abc123",
      "quantity": 2,
      "unitPrice": "19.90",
      "currentUnitPrice": "21.90",
      "priceChanged": true,
      "priceDelta": "2.00",
      "priceDirection": "increased",
      "isAvailable": true,
      "unavailableReason": null,
      "discountAmount": "0",
      "promoDiscountAmount": "0",
      "promoSource": "BUNDLE",
      "promoSourceId": "clpromosource_abc123",
      "notes": "string",
      "metadata": {},
      "customizations": {},
      "product": {
        "id": "clprd_abc123",
        "name": "string",
        "sku": "MUG-BLU",
        "images": [
          {
            "url": "https://cdn.brainerce.com/products/abc123.jpg",
            "alt": "Blue mug"
          }
        ]
      },
      "variant": {
        "id": "clvar_abc123",
        "name": "string",
        "sku": "MUG-BLU-L",
        "image": {
          "url": "https://cdn.brainerce.com/products/abc123.jpg",
          "alt": "Blue mug"
        }
      },
      "modifiers": [
        {
          "modifierId": "clmod_abc123",
          "modifierGroupId": "clmgr_abc123",
          "name": "string",
          "priceDelta": "1.50",
          "freeApplied": false,
          "effectivePrice": "1.50",
          "positionInGroup": 0
        }
      ],
      "modifiersTotal": "1.50",
      "parentCartItemId": "clparentcartitem_abc123",
      "createdAt": "2026-01-15T10:30:00.000Z",
      "updatedAt": "2026-01-15T10:30:00.000Z"
    }
  ],
  "itemCount": 3,
  "hasPriceChanges": false,
  "hasUnavailableItems": false,
  "unavailableItemIds": [],
  "expiresAt": "2026-01-15T10:30:00.000Z",
  "createdAt": "2026-01-15T10:30:00.000Z",
  "updatedAt": "2026-01-15T10:30:00.000Z",
  "reservation": {
    "hasReservation": true,
    "expiresAt": "2026-01-15T10:30:00.000Z",
    "remainingSeconds": 540,
    "strategy": "ON_CART",
    "countdownMessage": "string"
  },
  "recommendations": {
    "recommendations": [
      {
        "id": "clprd_abc123",
        "name": "string",
        "slug": "blue-mug",
        "basePrice": "24.00",
        "salePrice": "19.99",
        "images": [
          {
            "url": "https://cdn.brainerce.com/products/abc123.jpg",
            "alt": "Blue mug"
          }
        ],
        "type": "SIMPLE",
        "inventory": {
          "total": 42,
          "available": 39,
          "trackingMode": "TRACKED",
          "inStock": true,
          "canPurchase": true
        },
        "targetVariantId": null,
        "requiresVariantSelection": false,
        "pinnedVariant": {
          "id": "clvar_abc123",
          "name": "string",
          "attributes": {}
        },
        "variants": [
          {
            "id": "clvar_abc123",
            "name": "string",
            "attributes": {},
            "image": {
              "url": "https://cdn.brainerce.com/products/abc123.jpg",
              "alt": "Blue mug"
            },
            "price": "24.00",
            "salePrice": null
          }
        ],
        "relationType": "CROSS_SELL"
      }
    ]
  },
  "upgrades": {
    "upgrades": {}
  },
  "bundles": {
    "bundles": [
      {
        "id": "clx1234567890",
        "name": "string",
        "description": "string",
        "triggerProductId": "cltriggerproduct_abc123",
        "productIds": [
          "string"
        ],
        "offeredProducts": [
          {
            "id": "clprd_abc123",
            "name": "string",
            "slug": "blue-mug",
            "basePrice": "30.00",
            "salePrice": "19.99",
            "images": [
              {
                "url": "https://cdn.brainerce.com/products/abc123.jpg",
                "alt": "Blue mug"
              }
            ],
            "type": "SIMPLE",
            "variantId": "clvariant_abc123",
            "requiresVariantSelection": false,
            "pinnedVariant": {
              "id": "clvar_abc123",
              "name": "string",
              "attributes": {}
            },
            "variants": [
              {
                "id": "clvar_abc123",
                "name": "string",
                "attributes": {},
                "image": {
                  "url": "https://cdn.brainerce.com/products/abc123.jpg",
                  "alt": "Blue mug"
                },
                "price": "24.00",
                "salePrice": null
              }
            ],
            "originalPrice": "30.00",
            "discountedPrice": "24.00"
          }
        ],
        "discountType": "PERCENTAGE",
        "discountValue": "20",
        "totalOriginalPrice": "30.00",
        "totalDiscountedPrice": "24.00"
      }
    ]
  }
}

{
  "statusCode": 400,
  "code": "VALIDATION_FAILED",
  "message": "name should not be empty, price must be a positive number",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/vc/{connectionId}/cart/{cartId}/bump"
}

{
  "statusCode": 403,
  "code": "INSUFFICIENT_SCOPE",
  "message": "API key does not have the required scope: products:write",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/vc/{connectionId}/cart/{cartId}/bump"
}

{
  "statusCode": 404,
  "code": "RESOURCE_NOT_FOUND",
  "message": "Resource not found",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/vc/{connectionId}/cart/{cartId}/bump"
}

{
  "statusCode": 409,
  "code": "CONFLICT",
  "message": "The request conflicts with the current state of the resource",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/vc/{connectionId}/cart/{cartId}/bump"
}

{
  "statusCode": 429,
  "code": "RATE_LIMITED",
  "message": "Too many requests",
  "details": {
    "retryAfterSeconds": 12
  },
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/vc/{connectionId}/cart/{cartId}/bump"
}

Remove order bump

Removes an order bump product from the cart.

Authorization

X-Sales-Channel-Origin<token>

For /api/vc/{connectionId}/* routes the connectionId (vc_*) is in the URL path — not a header. Live-mode requests must also send a matching Origin header.

In: header

Path Parameters

connectionIdstring

Sales channel ID (vc_*), the canonical salesChannelId. connectionId is the deprecated name of the same value and is still the literal path segment.

cartIdstring

Cart id, returned by cart (create cart).

bumpConfigIdstring

Order bump configuration id, from checkout/{checkoutId}/bumps.

Query Parameters

locale?string

Language code, for example he. Used only when no Accept-Language header is sent. A language the store does not support, or the store's default language, returns the default text.

cartToken?string

Header Parameters

originstring

accept-language?string

X-SDK-Version?string

Version of the calling SDK (the Brainerce SDK sends it automatically). Informational: it is recorded on the channel and never changes the response.

x-cart-session?string

curl -X DELETE "https://api.brainerce.com/api/vc/string/cart/string/bump/string?locale=string&cartToken=string" \
  -H "origin: string" \
  -H "accept-language: string" \
  -H "X-SDK-Version: string" \
  -H "x-cart-session: string"

curl -X DELETE "https://api.brainerce.com/api/vc/string/cart/string/bump/string?locale=string&cartToken=string" \  -H "origin: string" \  -H "accept-language: string" \  -H "X-SDK-Version: string" \  -H "x-cart-session: string"

{
  "id": "clcrt_abc123",
  "sessionToken": "string",
  "customerId": "clcustomer_abc123",
  "status": "ACTIVE",
  "currency": "USD",
  "notes": "string",
  "analyticsClientId": "clanalyticsclient_abc123",
  "analyticsSessionId": "clanalyticssession_abc123",
  "subtotal": "39.80",
  "discountAmount": "5.00",
  "ruleDiscountAmount": "0",
  "promoDiscountTotal": "0",
  "couponCode": "WELCOME10",
  "appliedDiscounts": [
    {
      "ruleId": "cldr_abc123",
      "ruleName": "string",
      "type": "PRODUCT_DISCOUNT",
      "discountAmount": "5.00",
      "description": "string"
    }
  ],
  "nudges": [
    {
      "ruleId": "cldr_abc123",
      "text": "string",
      "type": "AMOUNT_NEEDED",
      "amountNeeded": "12.00",
      "quantityNeeded": 1
    }
  ],
  "items": [
    {
      "id": "clx1234567890",
      "productId": "clprd_abc123",
      "variantId": "clvariant_abc123",
      "quantity": 2,
      "unitPrice": "19.90",
      "currentUnitPrice": "21.90",
      "priceChanged": true,
      "priceDelta": "2.00",
      "priceDirection": "increased",
      "isAvailable": true,
      "unavailableReason": null,
      "discountAmount": "0",
      "promoDiscountAmount": "0",
      "promoSource": "BUNDLE",
      "promoSourceId": "clpromosource_abc123",
      "notes": "string",
      "metadata": {},
      "customizations": {},
      "product": {
        "id": "clprd_abc123",
        "name": "string",
        "sku": "MUG-BLU",
        "images": [
          {
            "url": "https://cdn.brainerce.com/products/abc123.jpg",
            "alt": "Blue mug"
          }
        ]
      },
      "variant": {
        "id": "clvar_abc123",
        "name": "string",
        "sku": "MUG-BLU-L",
        "image": {
          "url": "https://cdn.brainerce.com/products/abc123.jpg",
          "alt": "Blue mug"
        }
      },
      "modifiers": [
        {
          "modifierId": "clmod_abc123",
          "modifierGroupId": "clmgr_abc123",
          "name": "string",
          "priceDelta": "1.50",
          "freeApplied": false,
          "effectivePrice": "1.50",
          "positionInGroup": 0
        }
      ],
      "modifiersTotal": "1.50",
      "parentCartItemId": "clparentcartitem_abc123",
      "createdAt": "2026-01-15T10:30:00.000Z",
      "updatedAt": "2026-01-15T10:30:00.000Z"
    }
  ],
  "itemCount": 3,
  "hasPriceChanges": false,
  "hasUnavailableItems": false,
  "unavailableItemIds": [],
  "expiresAt": "2026-01-15T10:30:00.000Z",
  "createdAt": "2026-01-15T10:30:00.000Z",
  "updatedAt": "2026-01-15T10:30:00.000Z",
  "reservation": {
    "hasReservation": true,
    "expiresAt": "2026-01-15T10:30:00.000Z",
    "remainingSeconds": 540,
    "strategy": "ON_CART",
    "countdownMessage": "string"
  },
  "recommendations": {
    "recommendations": [
      {
        "id": "clprd_abc123",
        "name": "string",
        "slug": "blue-mug",
        "basePrice": "24.00",
        "salePrice": "19.99",
        "images": [
          {
            "url": "https://cdn.brainerce.com/products/abc123.jpg",
            "alt": "Blue mug"
          }
        ],
        "type": "SIMPLE",
        "inventory": {
          "total": 42,
          "available": 39,
          "trackingMode": "TRACKED",
          "inStock": true,
          "canPurchase": true
        },
        "targetVariantId": null,
        "requiresVariantSelection": false,
        "pinnedVariant": {
          "id": "clvar_abc123",
          "name": "string",
          "attributes": {}
        },
        "variants": [
          {
            "id": "clvar_abc123",
            "name": "string",
            "attributes": {},
            "image": {
              "url": "https://cdn.brainerce.com/products/abc123.jpg",
              "alt": "Blue mug"
            },
            "price": "24.00",
            "salePrice": null
          }
        ],
        "relationType": "CROSS_SELL"
      }
    ]
  },
  "upgrades": {
    "upgrades": {}
  },
  "bundles": {
    "bundles": [
      {
        "id": "clx1234567890",
        "name": "string",
        "description": "string",
        "triggerProductId": "cltriggerproduct_abc123",
        "productIds": [
          "string"
        ],
        "offeredProducts": [
          {
            "id": "clprd_abc123",
            "name": "string",
            "slug": "blue-mug",
            "basePrice": "30.00",
            "salePrice": "19.99",
            "images": [
              {
                "url": "https://cdn.brainerce.com/products/abc123.jpg",
                "alt": "Blue mug"
              }
            ],
            "type": "SIMPLE",
            "variantId": "clvariant_abc123",
            "requiresVariantSelection": false,
            "pinnedVariant": {
              "id": "clvar_abc123",
              "name": "string",
              "attributes": {}
            },
            "variants": [
              {
                "id": "clvar_abc123",
                "name": "string",
                "attributes": {},
                "image": {
                  "url": "https://cdn.brainerce.com/products/abc123.jpg",
                  "alt": "Blue mug"
                },
                "price": "24.00",
                "salePrice": null
              }
            ],
            "originalPrice": "30.00",
            "discountedPrice": "24.00"
          }
        ],
        "discountType": "PERCENTAGE",
        "discountValue": "20",
        "totalOriginalPrice": "30.00",
        "totalDiscountedPrice": "24.00"
      }
    ]
  }
}

{
  "statusCode": 403,
  "code": "INSUFFICIENT_SCOPE",
  "message": "API key does not have the required scope: products:write",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/vc/{connectionId}/cart/{cartId}/bump/{bumpConfigId}"
}

{
  "statusCode": 404,
  "code": "RESOURCE_NOT_FOUND",
  "message": "Resource not found",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/vc/{connectionId}/cart/{cartId}/bump/{bumpConfigId}"
}

{
  "statusCode": 409,
  "code": "CONFLICT",
  "message": "The request conflicts with the current state of the resource",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/vc/{connectionId}/cart/{cartId}/bump/{bumpConfigId}"
}

{
  "statusCode": 429,
  "code": "RATE_LIMITED",
  "message": "Too many requests",
  "details": {
    "retryAfterSeconds": 12
  },
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/vc/{connectionId}/cart/{cartId}/bump/{bumpConfigId}"
}

Example default

Example default

Example default

Example default

Example default

Example default

Example default

Example default

Example default

Example default

Example default

Example default