---
title: "Revalidates a previously redeemed checkout cashback against the current cart state."
method: POST
path: "/v1/pvt/Checkout/refresh"
tags: ["Checkout"]
---

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

`POST /v1/pvt/Checkout/refresh`

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.

## Request body

- ExternalApiCheckoutActionRequest — Request payload for checkout actions that need both customer identification and checkout reference.
  - `CustomerId` string — Required customer identifier used by the merchant platform, such as e-mail or CPF/document.
  - `Customer` ExternalApiCustomerIdentifierRequest — Optional customer identifiers used when the tenant configuration changes which value is used as the customer's OriginalId.
    - `Document` string, nullable — Customer document. Required when `Checkout.CustomerOriginalIdSource` is set to `document`. The value is normalized to digits only before the customer lookup.
    - `Email` string, nullable — Customer e-mail. Required when `Checkout.CustomerOriginalIdSource` is set to `email`.
  - `CheckoutId` string — Required checkout or cart identifier from the e-commerce platform.
  - `Total` number, nullable — Optional current checkout total value. Send this only when the platform integration needs the caller to provide the latest checkout amount explicitly.

## Response `200`

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

- BaseExternalApiResponseOfCheckoutRefreshCashbackResponse — Standard response envelope used by the External API.
  - `ErrorMessage` string, 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.
  - `ErrorCode` integer, nullable — Legacy numeric error code derived from internal API errors when available. This field is relevant only for error flows that use `ApiResponseErrorDescription`.
  - `Result` CheckoutRefreshCashbackResponse2 — Result returned by the checkout refresh operation.
    - `CashbackRemoved` boolean — Indicates whether the refresh operation removed the cashback from the checkout.
    - `CustomerMessage` string — Human-readable message describing the final checkout state after the refresh operation.
  - `Code` string, 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.
  - `CodeName` string, nullable — Symbolic enum name associated with `Code`, such as `CheckoutNotFound`.
  - `Severity` 0 | 1 | 2 — 0 = Success 1 = Warning 2 = Error
  - `HasWarning` boolean — 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.
  - `HasError` boolean — 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`.

---

[API](https://skmtc.net/bonifiq/apis/bonifiq-private-apis.md) · [All operations](https://skmtc.net/bonifiq/apis/bonifiq-private-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/bonifiq/bonifiq-private-apis/revisions/070a57eeffdc/schema)