# cart.update

> Return updated cart totals for integrations configured to use cart-update callbacks.

Source: https://help.boltapp.com/api-reference/merchant-callback/cart-update

Bolt uses `cart.update` when the integration needs your server to recalculate a cart after supported item, discount, gift-card, or fee changes. Discount routing depends on the division configuration; some single-code flows use discount validation instead.

## Before implementing [#before-implementing]

Confirm whether the division uses the Universal Merchant API or a plugin callback format. See [Handle merchant callbacks](/api-reference/merchant-callback/how-bolt-calls-you). A plugin integration's update-cart handler requires its specific callback URL.

## Request [#request]

The Universal Merchant API request wraps the update in `data`:

```json
{
  "event": "cart.update",
  "data": {
    "type": "cart.update",
    "order_reference": "order_1001",
    "discount_codes_to_add": ["SAVE20"],
    "discount_codes_to_remove": [],
    "add_items": [],
    "remove_items": []
  }
}
```

Plugin requests carry the body fields at the root. Use `order_reference` to load the cart. Handle absent or empty change arrays. When discount codes are supplied, read `discount_codes_to_add`, not a singular `discount_code` field.

## Response [#response]

Return `status: success` with an updated `order_create` in the envelope your integration requires. The [callback-format example](/api-reference/merchant-callback/how-bolt-calls-you#the-response-envelope-depends-on-your-integration-type) shows a complete digital-item calculation.

Preserve unchanged cart information while updating totals and discounts. Required fields depend on the order contract; `channel` is optional and does not explain a missing `order_create` error.

```javascript title="JavaScript"
const updatedOrderCreate = {
  ...originalOrderCreate,
  cart: {
    ...originalOrderCreate.cart,
    total_amount: discountedTotal,
    discounts: updatedDiscounts,
  },
};
```

This snippet updates an existing order-create object; its inputs come from your stored cart and pricing calculation. Amounts use the currency's minor units.

If you accept a code, include that code and its discount in the returned cart. An unchanged cart does not communicate that the code was applied. For a rejected update, use `status: failure` and the callback's `errors` array.

## Troubleshooting [#troubleshooting]

| Symptom                                         | Check                                                                         |
| ----------------------------------------------- | ----------------------------------------------------------------------------- |
| No request arrives                              | Verify the configured flow, callback URL, DNS, TLS, and inbound traffic rules |
| Discount code is absent in your handler         | Read `discount_codes_to_add` from the correct request envelope                |
| Bolt reports missing updated order-create input | Verify `order_create` exists at the location required by your integration     |
| Checkout rejects an accepted code               | Confirm the returned discounts contain the requested code and adjusted totals |
| Signature verification fails                    | Verify the raw body against the correct active or pending secret              |

Do not diagnose missing optional metadata or `channel` from an error that names a missing `order_create` object. Inspect the actual response body and integration format.

If a request fails or never arrives, check the callback URL and inbound traffic rules. Contact [support](/support) with the environment, division public ID, timestamp, order reference, and redacted request and response. Never send API keys or signing secrets.