Record Endpoint Errors

What the Record endpoint does

Record is the final step before order completion. It re-evaluates the cart, confirms the currently applicable promotions match expectations, and — if they do — commits the promotion usage records. A successful Record response is your confirmation that promotion usage has been tracked and the order price is valid.

What a Record error means

An error from Record means the promotion state did not match expectations at the moment of recording. The most common cause is an expectations mismatch — the same condition caught by Verify Expected — but it can also be a transient failure.

Do not capture payment if Record returns an error. The promotion usage has not been recorded, and proceeding would mean capturing a price the customer may not have agreed to.

What to do when Record fails

1. Do not proceed with payment. An errored Record means the order's promotion state is unconfirmed.
2. Re-call Verify to get the current applicable promotions and updated cart totals.
3. Present the updated cart to the customer and inform them that pricing has changed. A clear message like "The price of your order has changed — please review before confirming" is appropriate.
4. Ask the customer to confirm the updated prices before attempting Record again.
5. Re-attempt Record only after the customer confirms they accept the current prices.

If Record is failing repeatedly without a promotion change

If Record is failing on every attempt even after re-verifying and confirming with the customer, check:

• Request body structure — compare your request payload against the Record endpoint API reference. A missing required field (such as customer.email for non-anonymous orders) will cause a persistent failure.
• API key validity — confirm the Backend API key in your request is current and has not been rotated or revoked. The Backend API key is required for Record; a Frontend API key will be rejected.
• Expected promotions list — the appliedPromotions list you pass to Record must come from the most recent Verify or Verify Expected response, not a cached list from earlier in the session.

If you cannot resolve the issue after these checks, contact support with the request body (with any sensitive customer data redacted) and the error response.

For implementation details, see the Custom Storefront integration guide.