Sign in

v4

OpenAPI 3.0.02026-07-31811,0021.1 MB
Checkout

Revalidates a previously redeemed checkout cashback against the current cart state.

Use this endpoint after the shopper changes the cart contents, total amount or other platform-side checkout data. BonifiQ compares the current checkout with the redeemed cashback and decides whether the cashback can remain applied or must be removed.

When to use

Call this endpoint after cart updates and before finishing the order whenever your platform can change the final checkout value after the cashback redeem step.

Input parameters

  • CustomerId (required): Customer identifier used by your store, such as e-mail or CPF/document.
  • CheckoutId (required): Platform checkout/cart identifier to be revalidated.
  • Total (optional): Current checkout total. Use it when the integration requires the caller to send the latest total explicitly.

Response envelope

The endpoint returns BaseExternalApiResponse<CheckoutRefreshCashbackResponse>.

  • Code: two-digit business code for the final outcome.
  • CodeName: enum name associated with Code.
  • Severity: Success, Warning or Error.
  • HasError: true only for request/validation failures that should be treated as an API error.
  • HasWarning: true when the request is valid but the outcome is informational or non-ideal.
  • Result.CashbackRemoved: true when the cashback was removed from the checkout.
  • Result.CustomerMessage: human-readable message describing the final state.

Business outcomes

A valid request may still return Severity = Warning. This is expected when:

  • the checkout has no cashback currently applied
  • the cashback remains applied without changes
  • the cashback is removed because the cart changed

Validation errors

Invalid requests return 400 Bad Request with Severity = Error. This happens when the customer cannot be identified or the CheckoutId is missing.

Response codes

  • 01 / CustomerNotFound / Error: the informed customer could not be found.
  • 02 / CheckoutIdRequired / Error: the request did not include CheckoutId.
  • 04 / CashbackNotApplied / Warning: the checkout currently has no cashback to refresh.
  • 05 / CashbackStillApplied / Warning: the redeemed cashback remains valid and stays applied.
  • 06 / CashbackRemovedByCartChange / Warning: the cashback was removed because the cart changed and the redeem is no longer valid.
post/v1/pvt/Checkout/refresh

Request body

CustomerIdstring

Required customer identifier used by the merchant platform, such as e-mail or CPF/document.

CheckoutIdstring

Required checkout or cart identifier from the e-commerce platform.

Totalnumber nullable

Optional current checkout total value. Send this only when the platform integration needs the caller to provide the latest checkout amount explicitly.

Response

A checkout refresh response with business code, severity and refresh outcome.

ErrorMessagestring nullable

Error message returned when the request fails validation or processing. For warnings and successful responses, consumers should usually inspect Result, Code and Severity first.

ErrorCodeinteger nullable

Legacy numeric error code derived from internal API errors when available. This field is relevant only for error flows that use ApiResponseErrorDescription.

Codestring nullable

Endpoint-specific business code formatted as a two-digit string, such as 03 or 07. This field is available for success, warning and error outcomes.

CodeNamestring nullable

Symbolic enum name associated with Code, such as CheckoutNotFound.

Severity0 | 1 | 2

0 = Success 1 = Warning 2 = Error

HasWarningboolean

Convenience flag that is true when Severity is Warning. Warnings are valid 200 OK business outcomes and should not be handled as transport or validation errors.

HasErrorboolean

Indicates whether the request failed and should be handled as an error response. This flag is reserved for real API errors; warnings must keep this property as false.