cart.update
Return updated cart totals for integrations configured to use cart-update callbacks.
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
Confirm whether the division uses the Universal Merchant API or a plugin callback format. See Handle merchant callbacks. A plugin integration's update-cart handler requires its specific callback URL.
Request
The Universal Merchant API request wraps the update in data:
{
"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
Return status: success with an updated order_create in the envelope your integration requires. The callback-format example 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.
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
| 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 with the environment, division public ID, timestamp, order reference, and redacted request and response. Never send API keys or signing secrets.