# Rigaly API

> Create loyalty programs effortlessly with the Rigaly API

## Docs

- [Create a code batch](https://docs.rigaly.com/api-reference/code-batches/create-a-code-batch.md): Creates a batch of up to **32,768 unique single-use codes** per batch (create multiple batches for larger runs) to print on physical products. Creation is instant — codes are derived from a per-batch cryptographic secret, not stored — and **you are only charged the per-transaction fee when a code is…
- [Deactivate a batch](https://docs.rigaly.com/api-reference/code-batches/deactivate-a-batch.md): Stops further claims for every code in the batch. Already-claimed codes are unaffected.
- [Export all codes](https://docs.rigaly.com/api-reference/code-batches/export-all-codes.md): Streams every code in the batch (regenerated deterministically). CSV columns are `code,serial,deep_link`. Hand the file to your manufacturer/printer and have each `deep_link` printed as a QR code — scanning it opens the Rigaly app with the code ready to claim.
- [Get batch stats](https://docs.rigaly.com/api-reference/code-batches/get-batch-stats.md)
- [List code batches](https://docs.rigaly.com/api-reference/code-batches/list-code-batches.md)
- [Verify a code](https://docs.rigaly.com/api-reference/code-batches/verify-a-code.md): Support tool — checks a code's validity and claim status **without claiming it**. Only resolves codes from your own batches.
- [Attach an external identifier](https://docs.rigaly.com/api-reference/customers/attach-an-external-identifier.md): Link your own customer ID (e.g. from your e-commerce platform) to a Rigaly customer, then use it as `identifier` everywhere.
- [Customer transaction history](https://docs.rigaly.com/api-reference/customers/customer-transaction-history.md): The customer's points ledger at your business, filterable by type and date range.
- [Get customer balance](https://docs.rigaly.com/api-reference/customers/get-customer-balance.md)
- [List customers](https://docs.rigaly.com/api-reference/customers/list-customers.md): Paginated customer list with balances, visit stats, and tier. `search` filters by name, email, or phone. For behavior-based filtering (spend, recency, frequency…) use the segments endpoints.
- [List external identifiers](https://docs.rigaly.com/api-reference/customers/list-external-identifiers.md): Business-scoped external identifiers (e.g. your own customer IDs) attached to this customer.
- [Look up a customer](https://docs.rigaly.com/api-reference/customers/look-up-a-customer.md): Resolves an identifier to a customer and returns their balance at your business. Resolution order: email (contains `@`) → business-scoped external identifier → phone number.
- [Remove an external identifier](https://docs.rigaly.com/api-reference/customers/remove-an-external-identifier.md)
- [Update an external identifier](https://docs.rigaly.com/api-reference/customers/update-an-external-identifier.md)
- [List PTS devices](https://docs.rigaly.com/api-reference/devices/list-pts-devices.md): Read-only list of your point-of-sale terminals with login status and activity. Device lifecycle management (register, pair, remove) is done in the dashboard.
- [Assign customer level](https://docs.rigaly.com/api-reference/levels-tiers/assign-customer-level.md): Manually assigns a level/tier to the customer, or clears the manual override with `tier_id: null` (the customer returns to automatic qualification).
- [Create a level](https://docs.rigaly.com/api-reference/levels-tiers/create-a-level.md)
- [Delete a level](https://docs.rigaly.com/api-reference/levels-tiers/delete-a-level.md)
- [Get customer level](https://docs.rigaly.com/api-reference/levels-tiers/get-customer-level.md)
- [List levels (tiers)](https://docs.rigaly.com/api-reference/levels-tiers/list-levels-tiers.md): Returns the tier system settings and all tiers with their benefits (points multiplier, cashback boost, referral bonus, tier-reach bonus).
- [Reorder levels](https://docs.rigaly.com/api-reference/levels-tiers/reorder-levels.md)
- [Update a level](https://docs.rigaly.com/api-reference/levels-tiers/update-a-level.md)
- [Update tier system settings](https://docs.rigaly.com/api-reference/levels-tiers/update-tier-system-settings.md)
- [Verify API key](https://docs.rigaly.com/api-reference/meta/verify-api-key.md): Verifies the API key and returns the authenticated business and key metadata. Use it as a connectivity check.
- [Deduct points](https://docs.rigaly.com/api-reference/points/deduct-points.md): Deducts raw points from a customer's balance (for store credit, discounts applied in your own system, etc.). Fails if the balance is insufficient. Supports `Idempotency-Key`.
- [Issue points](https://docs.rigaly.com/api-reference/points/issue-points.md): Issues points to a customer identified by `user_id` **or** `identifier` (email, phone, or a business-scoped external identifier). Tier multipliers, signup bonuses, and promo bonuses apply automatically — `points_issued` in the response is the final amount credited.
- [Create a promotion](https://docs.rigaly.com/api-reference/promotions/create-a-promotion.md)
- [Delete a promotion](https://docs.rigaly.com/api-reference/promotions/delete-a-promotion.md)
- [Get a promotion](https://docs.rigaly.com/api-reference/promotions/get-a-promotion.md)
- [List promotions](https://docs.rigaly.com/api-reference/promotions/list-promotions.md)
- [Update a promotion](https://docs.rigaly.com/api-reference/promotions/update-a-promotion.md)
- [Cancel a raffle](https://docs.rigaly.com/api-reference/raffles/cancel-a-raffle.md): Cancels the raffle and refunds all entry points to participants.
- [Create a raffle](https://docs.rigaly.com/api-reference/raffles/create-a-raffle.md)
- [Delete a raffle](https://docs.rigaly.com/api-reference/raffles/delete-a-raffle.md)
- [End a raffle early](https://docs.rigaly.com/api-reference/raffles/end-a-raffle-early.md): Closes entries immediately; the draw proceeds as scheduled. Winner management (reroll, replace, confirm) is done in the dashboard.
- [Get a raffle (with entry counts)](https://docs.rigaly.com/api-reference/raffles/get-a-raffle-with-entry-counts.md)
- [List raffle entries](https://docs.rigaly.com/api-reference/raffles/list-raffle-entries.md)
- [List raffle winners](https://docs.rigaly.com/api-reference/raffles/list-raffle-winners.md)
- [List raffles](https://docs.rigaly.com/api-reference/raffles/list-raffles.md)
- [Update a raffle](https://docs.rigaly.com/api-reference/raffles/update-a-raffle.md)
- [Complete a redemption](https://docs.rigaly.com/api-reference/redemptions/complete-a-redemption.md): Consumes the redemption code: verifies ownership, pending status, expiry, reward cooldowns/eligibility, and the customer's balance; deducts the points; and marks the redemption completed. This is the same engine Rigaly PTS terminals use. Supports `Idempotency-Key`.
- [Validate a redemption code](https://docs.rigaly.com/api-reference/redemptions/validate-a-redemption-code.md): Validates a customer's redemption code **without consuming it**. Returns the reward (including its `conditions` text) and the customer, so your system can check the purchase against the reward before completing. Codes are created when customers redeem a reward in the Rigaly app.
- [Delete the review questionnaire](https://docs.rigaly.com/api-reference/reviews/delete-the-review-questionnaire.md)
- [Get the review questionnaire](https://docs.rigaly.com/api-reference/reviews/get-the-review-questionnaire.md)
- [List reviews](https://docs.rigaly.com/api-reference/reviews/list-reviews.md): Paginated anonymous customer reviews (star ratings + questionnaire answers). Reviews are anonymous by design.
- [Review stats](https://docs.rigaly.com/api-reference/reviews/review-stats.md): Aggregated stats — overall star average, totals, and per-question breakdowns.
- [Update the review questionnaire](https://docs.rigaly.com/api-reference/reviews/update-the-review-questionnaire.md): Creates or replaces the questionnaire customers answer when reviewing your business (question types include stars, text, single/multiple choice, tags).
- [Create a reward](https://docs.rigaly.com/api-reference/rewards/create-a-reward.md): Creates a reward customers can redeem with points. Scheduling (`start_date`/`end_date`), time-of-day windows (`time_active`), cooldowns, birthday gating, and free-text `conditions` are supported — see the guides for how `conditions` powers product-specific rewards.
- [Delete a reward](https://docs.rigaly.com/api-reference/rewards/delete-a-reward.md)
- [Get a reward](https://docs.rigaly.com/api-reference/rewards/get-a-reward.md)
- [List rewards](https://docs.rigaly.com/api-reference/rewards/list-rewards.md)
- [Update a reward](https://docs.rigaly.com/api-reference/rewards/update-a-reward.md): Partial update — include only the fields to change (e.g. `{ "active": false }` to disable).
- [List segment customers](https://docs.rigaly.com/api-reference/segments/list-segment-customers.md): Full paginated customer list for a segment filter spec.
- [List segment presets](https://docs.rigaly.com/api-reference/segments/list-segment-presets.md): Catalog of ready-made customer segments (champions, loyal, at-risk, big spenders, birthday this month…).
- [Preview a segment](https://docs.rigaly.com/api-reference/segments/preview-a-segment.md): Returns the match count and a small sample for a segment filter — either a `preset_id` or custom filters (spend, visits, recency, time-of-day, birthday month…).
- [Business transaction history](https://docs.rigaly.com/api-reference/transactions/business-transaction-history.md): All PTS- and API-originated transactions with filters. API-originated rows have `device_id: null`.
- [Authentication](https://docs.rigaly.com/authentication.md): API keys, security, and key lifecycle
- [Errors](https://docs.rigaly.com/errors.md): Response envelope and error handling
- [AI Connector (MCP)](https://docs.rigaly.com/guides/ai-connector.md): Manage your loyalty program by talking to Claude or ChatGPT
- [Issue points & validate rewards](https://docs.rigaly.com/guides/issue-and-validate.md): The core loyalty loop for any integration
- [Mass codes for physical products](https://docs.rigaly.com/guides/mass-codes.md): Print tens of thousands of unique loyalty codes on your products — pay only when they're redeemed
- [Most used routes](https://docs.rigaly.com/guides/most-used-routes.md): The endpoints most integrations need, with example cases
- [Earn on specific products or hours](https://docs.rigaly.com/guides/product-specific-earning.md): Award points only for qualifying line items or time windows
- [Claim rewards on specific products only](https://docs.rigaly.com/guides/product-specific-redemption.md): Enforce product restrictions when honoring reward codes
- [Quickstart](https://docs.rigaly.com/quickstart.md): Issue your first loyalty points in five minutes
- [Rate limits](https://docs.rigaly.com/rate-limits.md): Request limits and how to handle 429 responses

## OpenAPI Specs

- [v1](https://docs.rigaly.com/openapi/v1.yaml)