> ## Documentation Index > Fetch the complete documentation index at: https://developers.bonifiq.com.br/llms.txt > Use this file to discover all available pages before exploring further. # This method can be used to redeem a reward in behalf of a customer. > There are 2 types of rewards: - Discount Rewards: Percent (10%) or Value (R$10,00). This rewards are simples as they use pre-configured values - Cashback: As a value (R$5,00). The used value must be informed in the `Value` field of the request body They both can be used with this method. Just be aware that: - The field `Value` must have the selected cashback value for the purchase. Use only if the reward is **Cashback** type - For other rewards this field can be null The `rewardId` field can be obtained by calling the `rewards/available` endpoint The `customerId` field in the body is the same used in the `rewards/avaible` endpoint. ## The `OriginalKey` field This field allows you to create idempotency: even if you make the exactly same request twice it will redeem only once. As distributed systems should be fault-tolerant it may result in requests being done more than one time. Not using the `OriginalKey` may duplicate a redeem request ### How to use this field Inform some string that is unique for this change. For instance: if you are redeeming the reward Id=OPQ for customerID=ABC regarding the OrderId=123 with Value=10,our key could be `OPQ-ABC-123-10` If you dont need this kind of verification you can just use some time-related string, such as `2023-01-01 23:59:00:000` ## Coupon Generation It's important to note that unlike the `customers/{id}/redeem` endpoint this call **will not** generate a coupon in BonifiQ. That is true even if the reward if configured so. This is by design as in Point of Sale endpoints it is expected that the caller (PoS) will give the customer the necessary discounts. ## The `ExternalCode` return One of the most important fields returned by this method is the `ExternalCode`. This field represents an External identification for this redeem. This exact value must be passed on the `Coupon` field for the Order Add Method from this API. This will make a link between the redeem and the order. **Important**: Remember to pass the `ExternalCode` value to the `Coupon` field when adding an order ## OpenAPI ````yaml https://api.bonifiq.com.br/swagger/Private%20APIs/swagger.json post /v1/pvt/POS/rewards/{id}/redeem openapi: 3.0.0 info: title: BonifiQ Private APIs description: >- # Introduction This is the BonifiQ Private APIs documentation. With these endpoints you can interact with BonifiQ systems and enhance your program points. # Limitations These endpoints are intended to be used in backend communication so they are not CORS-compatible and cannot be used by in-browser frontend libraries (such as React, Angular, Vue, jQuery, etc) If are required to call BonifiQ API from a browser, please refer to our [Public APIs](https://api.bonifiq.com.br/apidocs/public) # Authentication These Private APis use the [Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) scheme. You need both an API Token (Username) and API Key (Password) to use with it You can generate this key pair in BonifiQ admin panel, at the "API Keys" menu. # How to use this page ## Making calls You can simulate, test and make calls to API from this Swagger page. To do that: - Click on the **Authorize** button - Inform the Username (API Token) and Passwoird (API Key) and click on **Authorize** - From the list bellow, choose an API call and click on **Try it out** - Inform the required parameters (if any) and click on **Execute** ## Verifying requests and responses bodies In every API Call there is an explanation of what each field means, theirs types and accepted values for all Requests and Responses. To view this information, just go to any API Call bellow and in the Responses section, click on the Schema. version: 1.0.0 servers: - url: https://api.bonifiq.com.br security: [] tags: - name: POS description: >- Flow methods to integrate BonifiQ with a POS system. Check the Flow Documentation link on the right externalDocs: description: Flow Documentation url: >- https://suporte.bonifiq.com.br/support/solutions/articles/159000319538-integrar-com-pdv - name: Checkout description: Operations related to checkout cashback redeem, refresh and removal - name: Customization description: Retrieve customizations for the loyalty program - name: Rewards description: Interact with rewards already redeemed paths: /v1/pvt/POS/rewards/{id}/redeem: post: tags: - POS summary: This method can be used to redeem a reward in behalf of a customer. description: >- There are 2 types of rewards: - Discount Rewards: Percent (10%) or Value (R$10,00). This rewards are simples as they use pre-configured values - Cashback: As a value (R$5,00). The used value must be informed in the `Value` field of the request body They both can be used with this method. Just be aware that: - The field `Value` must have the selected cashback value for the purchase. Use only if the reward is **Cashback** type - For other rewards this field can be null The `rewardId` field can be obtained by calling the `rewards/available` endpoint The `customerId` field in the body is the same used in the `rewards/avaible` endpoint. ## The `OriginalKey` field This field allows you to create idempotency: even if you make the exactly same request twice it will redeem only once. As distributed systems should be fault-tolerant it may result in requests being done more than one time. Not using the `OriginalKey` may duplicate a redeem request ### How to use this field Inform some string that is unique for this change. For instance: if you are redeeming the reward Id=OPQ for customerID=ABC regarding the OrderId=123 with Value=10,our key could be `OPQ-ABC-123-10` If you dont need this kind of verification you can just use some time-related string, such as `2023-01-01 23:59:00:000` ## Coupon Generation It's important to note that unlike the `customers/{id}/redeem` endpoint this call **will not** generate a coupon in BonifiQ. That is true even if the reward if configured so. This is by design as in Point of Sale endpoints it is expected that the caller (PoS) will give the customer the necessary discounts. ## The `ExternalCode` return One of the most important fields returned by this method is the `ExternalCode`. This field represents an External identification for this redeem. This exact value must be passed on the `Coupon` field for the Order Add Method from this API. This will make a link between the redeem and the order. **Important**: Remember to pass the `ExternalCode` value to the `Coupon` field when adding an order operationId: POS_Redeem parameters: - name: id in: path required: true schema: type: integer format: int32 x-position: 1 requestBody: x-name: request description: Parameters used in redeeming content: application/json: schema: $ref: '#/components/schemas/CouponlessRewardGenerateRequest' required: true x-position: 2 responses: '200': description: '' content: application/json: schema: $ref: >- #/components/schemas/BaseExternalApiResponseOfCouponlessRewardRedeemResponse security: - Basic Authentication: [] components: schemas: CouponlessRewardGenerateRequest: type: object additionalProperties: false properties: CustomerId: type: string description: The id of the customer. It can be email or document (CPF/CNPJ). Value: type: number description: >- Used only for Cashback Rewards. It the Cashback value selected by the customer. You can use either Points or Value for representing the selected amount of cashback to use. format: decimal nullable: true Points: type: integer description: >- Used only for Cashback Rewards. It the Cashback represented by points selected by the customer. You can use either Points or Value for representing the selected amount of cashback to use. format: int32 nullable: true OriginalKey: type: string description: >- This field allows you to create idempotency: even if you make the exactly same request twice it will consume the redeem only once. As distributed systems should be fault-tolerant it may result in requests being done more than one time. Not using the `OriginalKey` may duplicate a redeem request Inform some string that is unique for this change. For instance: if you are redeeming the reward Id=OPQ for customerID=ABC regarding the OrderId=123 with Value=10,our key could be `OPQ-ABC-123-10` If you dont need this kind of verification you can just use some time-related string, such as `2023-01-01 23:59:00:000` Metadatas: type: array description: >- Use this field as a key-value store for fields unique to your Business Use Case nullable: true xml: wrapped: true items: xml: name: CouponlessRewardGenerateRequestMetadata oneOf: - $ref: '#/components/schemas/CouponlessRewardGenerateRequestMetadata' RedeemOrigin: description: >- Use this field to send redeem origin. Have 4 types: LandingPage, Widget, Copilot, Checkout, API, PDV. nullable: true oneOf: - $ref: '#/components/schemas/RedeemOrigin' Branch: description: >- A Branch is physical location or outlet of a store (loja, filial, etc). This is used to receive information of which store the purchase was made. It can be later used to create rules for points or filtering reports. nullable: true oneOf: - $ref: '#/components/schemas/CreateOrderBranch' SalesPerson: description: >- A sales person is the person responsible for the sale. It can be used for filtering reports. nullable: true oneOf: - $ref: '#/components/schemas/CreateOrderSalesPerson' ForceGenerateCoupon: type: boolean description: >- Normally this endpoint generates a redeem without a coupon. Setting this property to true forces to generate a coupon in the ecommerce plataform nullable: true BaseExternalApiResponseOfCouponlessRewardRedeemResponse: type: object description: Standard response envelope used by the External API. additionalProperties: false properties: ErrorMessage: type: string description: >- Error message returned when the request fails validation or processing. For warnings and successful responses, consumers should usually inspect `Result`, `Code` and `Severity` first. nullable: true ErrorCode: type: integer description: >- Legacy numeric error code derived from internal API errors when available. This field is relevant only for error flows that use `ApiResponseErrorDescription`. format: int32 nullable: true Result: description: Business payload returned by the endpoint. nullable: true oneOf: - $ref: '#/components/schemas/CouponlessRewardRedeemResponse' Code: type: string description: >- 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. nullable: true CodeName: type: string description: >- Symbolic enum name associated with `Code`, such as `CheckoutNotFound`. nullable: true Severity: description: >- Final severity of the response. `Success` means the action completed as expected, `Warning` means the request was valid but the business outcome is informational or non-ideal, and `Error` means the request should be treated as a failure. oneOf: - $ref: '#/components/schemas/ExternalApiResponseSeverity' HasWarning: type: boolean description: >- 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: type: boolean description: >- 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`. CouponlessRewardGenerateRequestMetadata: type: object additionalProperties: false properties: Name: type: string Value: type: string RedeemOrigin: type: integer description: |- 0 = LandingPage 1 = Widget 2 = Copilot 3 = Checkout 4 = API 5 = PDV x-enumNames: - LandingPage - Widget - Copilot - Checkout - API - PDV enum: - 0 - 1 - 2 - 3 - 4 - 5 CreateOrderBranch: type: object additionalProperties: false properties: OriginalId: type: string description: >- This is the Id of the branch (filial, loja, etc) in the client store. Can be any string. Name: type: string description: This is the name of the branch. Can be any string possible CreateOrderSalesPerson: type: object additionalProperties: false properties: OriginalId: type: string description: This is the Id of the Sales Person. Can be any string or number. Name: type: string description: This is the name of the sales person. Can be any string. CouponlessRewardRedeemResponse: type: object additionalProperties: false properties: RewardId: type: integer description: This is the unique-id for this reward format: int32 Point: description: It`s the underlining point record generating from using this reward oneOf: - $ref: '#/components/schemas/CouponlessRewardRedeemPointResponse' ExternalCode: type: string description: >- When sending orders to BonifiQ use this field value in the `Coupon` field for the Order This is necessary so we know that this order used this reward OriginalKey: type: string description: This is the key that was send in the redeem request Coupon: description: If the request forces the coupon generation It is returned here nullable: true oneOf: - $ref: '#/components/schemas/RewardRedeemCoupon' ExternalApiResponseSeverity: type: integer description: |- 0 = Success 1 = Warning 2 = Error x-enumNames: - Success - Warning - Error enum: - 0 - 1 - 2 CouponlessRewardRedeemPointResponse: type: object additionalProperties: false properties: PointId: type: integer format: int32 Quantity: type: integer format: int32 Metadatas: type: array nullable: true xml: wrapped: true items: xml: name: ExternalApiPointMetadata oneOf: - $ref: '#/components/schemas/ExternalApiPointMetadata' RewardRedeemCoupon: type: object additionalProperties: false properties: CouponCode: type: string CouponType: $ref: '#/components/schemas/CouponType' CouponValue: type: number format: decimal ValidDateStart: type: string format: date-time nullable: true ValidDateEnd: type: string format: date-time nullable: true ExternalApiPointMetadata: type: object additionalProperties: false properties: Name: type: string Value: type: string CouponType: type: integer description: |- 0 = FixedValue 1 = Percent 2 = FreeShipping 3 = DiscountShipping 4 = Others x-enumNames: - FixedValue - Percent - FreeShipping - DiscountShipping - Others enum: - 0 - 1 - 2 - 3 - 4 securitySchemes: Basic Authentication: type: http description: Use API Basic Auth Keys name: Basic Authentication in: header scheme: basic ````