> For the complete documentation index, see [llms.txt](https://docs.perkville.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.perkville.com/integrations/integrating-perkville/integrating-your-app-with-perkville/rewards-page/redeem-confirmation-page.md).

# Redeem confirmation page

This page should confirm the reward the customer is about to redeem, the point cost, and any restrictions that apply. Use this page to prevent failed redemptions before the customer submits.

<figure><img src="https://2181708597-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSiE75SeColbiBVbet0NZ%2Fuploads%2Fl50jOA8XkVHx9yaYUzrQ%2Fredeem_confirmation_Perkville_page.png?alt=media&amp;token=2cc545fd-3cfb-4cc4-84ce-c9b1c587e0be" alt="" width="375"><figcaption></figcaption></figure>

### What to show

* **Reward title**
* **Points required**
* **Description** (if present)
* **Redemption instructions** (if present)
* **Fine print** (if present)
* **Business fine print** (if present)
* **Location** being used for redemption
* **Redemption limits** (if present)
* **Required level / required attributes** (if present)
* **Current point balance**
* **Projected balance after redemption** (current balance − points required)

### When to disable the Redeem button (pre‑submit)

Disable redemption if any of the following are true:

* `can_redeem = false`
* `user_redemption_limit_info.has_met_limit = true`
* `must_redeem_at_home_location = true` and the customer is not at their home location

Always show the reason in the UI when you can infer it (required level, required attributes, limit reached, etc.).

Additionally, if offering a location selection when redeeming, please only include locations at which the perk is available.

### **Submit Redemption**

Once the customer confirms their redemption, use the [**Transaction** endpoint](https://www.perkville.com/developers/docs/v2/#v2_resource_27_anchor) to submit the redemption request. This will process the transaction and deduct the appropriate points from the customer's account.

{% hint style="info" %}
If using ADMIN\_CUSTOMER\_REDEEM scopes, and you do not want the voucher immediately marked as USED, set `voucher_start_as_unused = true`. This will respect the initial voucher status set for the perk (e.g. UNUSED, PENDING, etc).
{% endhint %}

#### **Successful redemption**

When the redemption succeeds:

* Show a success state
* If a **voucher** is returned, show:
  * Redirect to the voucher detail view (recommended)
  * Voucher code / identifier
  * Redemption instructions
  * Expiration date (if present)

#### Error handling (customer‑safe copy)

These are common redemption‑time errors and recommended customer‑safe messages:

* `pv_txn_insufficient_points`\
  “You don’t have enough points to redeem this reward.”
* `pv_perk_redemption_limit_reached`\
  “You’ve reached the redemption limit for this reward.”
* `pv_txn_perk_not_active`\
  “This reward is no longer available.”
* `pv_perk_not_available`\
  “This reward is not available right now.”
* `pv_txn_ineligible_loc`\
  “This reward isn’t available at this location.”
* `pv_txn_loc_not_home_loc`\
  “This reward must be redeemed at your home location.”
* `pv_no_coupons_left`\
  “This reward is currently unavailable. Please try again later.”
* `pv_txn_user_not_active`\
  “You must join the loyalty program before redeeming rewards.”
* `pv_txn_user_inactive`\
  “Your account is inactive. Please contact support.”
* `pv_txn_user_banned`\
  “Your account is not eligible to redeem rewards.”
* `pv_txn_biz_not_active`\
  “This loyalty program is no longer active.”

### Handling an unexpected or generic redemption error

If the redemption request fails or the app cannot confirm the result, **do not immediately submit the transaction again**. A network timeout or generic error may occur even when the first request was processed.

1. **Check the result before retrying.** Refresh the customer's points balance, transaction history, and voucher list to see whether the points were deducted or a new voucher was issued.
2. **If the redemption succeeded**, show the existing voucher or success details instead of submitting a duplicate request.
3. **If no redemption appears**, allow a retry only after the application has established that the prior attempt did not process, or follow the integration's safe retry and deduplication procedure.
4. **If the outcome remains unclear**, show a helpful message such as: "We couldn't confirm your redemption. Please check your rewards history before trying again, or ask the business for help."

For support investigations, record the business, customer reference, reward/perk ID, selected location, approximate time and timezone, request or transaction reference (if available), and the error code or response. Do not include passwords, access tokens, or other secrets in screenshots or support messages. Refer to [Perkville Support](https://docs.perkville.com/overview/support.md) when the outcome cannot be verified.

For business staff: check the customer's transaction and voucher history before manually adjusting points or issuing a replacement reward. A failed screen response alone does not prove the redemption failed.

See [Rewards page](https://docs.perkville.com/integrations/integrating-perkville/integrating-your-app-with-perkville/rewards-page.md) for the customer-facing eligibility and redemption rules.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.perkville.com/integrations/integrating-perkville/integrating-your-app-with-perkville/rewards-page/redeem-confirmation-page.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
