Skip to main content

FAQ

Getting started​

What is the production API base URL?​

Use https://api.remyrewards.co.uk. All currently documented public endpoints are under /v1/public.

How do I get an API key?​

Open Integrations → API in the Remy Merchant Portal and select Create key. Name the key, choose the minimum required scopes, and optionally set an expiry date. Copy the secret when it is displayed: Remy stores only a one-way hash and cannot display it again. Use a separate key for each integration and environment.

Can I have more than one API key?​

Yes. A merchant can have up to 10 active keys, so production, staging, internal tools, and third-party integrations can be rotated or revoked independently. Revoked and expired keys remain visible in the portal for audit history but do not count as active keys.

How do I rotate or revoke a key?​

Open Integrations → API in the Merchant Portal. Rotation creates a new secret with the same name, scopes, and expiry, then immediately revokes the old key. Update your secret manager with the newly displayed value. Revocation immediately rejects future requests made with that key and cannot be undone.

How do I authenticate a request?​

Send the key in the X-API-Key request header. Keep it on your server; never put it in browser code, a mobile application, a public repository, or a URL.

X-API-Key: YOUR_API_KEY

How can I check whether a key works?​

Call GET /v1/public/auth. A successful response confirms the merchant associated with the key. A missing or invalid key returns 401.

Do I need to send a User-Agent?​

Yes. Send a meaningful User-Agent identifying your integration and version, for example ExampleCheckout/1.4. Most standard HTTP clients add one automatically, but you should verify this in production.

Does the API use OAuth scopes?​

The API uses scopes attached to each API key, rather than OAuth access tokens. Each endpoint reference lists its required scope. Call GET /v1/public/me to inspect the current key. Cross-merchant resource identifiers return 404.

Vouchers and customer vouchers​

Are voucher endpoints for templates or customer vouchers?​

GET /v1/public/vouchers and GET /v1/public/vouchers/{id} return merchant voucher templates. Use /v1/public/customers/{customerId}/vouchers and /v1/public/customers/{customerId}/vouchers/{voucherId} for customer voucher instances.

Which voucher identifier should I use?​

For customer-scoped reads, use the customer voucher id returned by GET /v1/public/customers/{customerId}/vouchers. Template IDs and customer voucher IDs are different resources.

How do I list vouchers?​

Call GET /v1/public/vouchers to list merchant templates. Call GET /v1/public/customers/{customerId}/vouchers to list one customer's vouchers; use cursor and limit for pagination and status to filter by voucher state.

Which voucher statuses can I filter by?​

The current filters are pending, active, partial, redeemed, expired, and cancelled. Treat new status values as possible backwards-compatible additions and avoid failing on values you do not recognise.

What is the difference between value and remainingValue?​

value is the issued voucher's original value. remainingValue is the amount still available after any successful redemptions. Monetary values use the ISO 4217 code in currency.

Can I find a voucher by its human-readable code?​

Call GET /v1/public/vouchers/lookup?code=... to find a customer voucher by its human-readable code. Use the returned customer-voucher ID for PDF, redemption, and management requests.

Why does an existing voucher return 404?​

The identifier may be invalid, may refer to a template rather than an issued voucher, or may belong to another merchant. Remy intentionally does not expose cross-merchant resources.

How do I fully redeem a voucher?​

Call POST /v1/public/vouchers/{id}/redeem without an amount field. This redeems the full remaining value.

How do I partially redeem a voucher?​

Send a positive amount smaller than or equal to the remaining value. Partial redemption is accepted only when allowPartialRedemption is true.

What happens when the amount equals the remaining value?​

The voucher is fully redeemed. The returned voucher data contains its updated status and remaining value.

Can I redeem an expired, cancelled, pending, or already redeemed voucher?​

No. Only an eligible active or partially redeemed issued voucher can be redeemed. Always use the API response as the source of truth rather than changing local balances optimistically.

How can I tell whether partial redemption is allowed?​

Read allowPartialRedemption from the issued voucher. If it is false, omit amount and redeem the full remaining value.

Is a redemption request safe to retry after a timeout?​

Do not assume a timeout means the redemption failed: the server may have completed it before the connection was lost. Retrieve the voucher and inspect its remaining value and redemption history before deciding what to do. Avoid automatic retries that could redeem value twice.

What should I store after a redemption?​

Store the issued-voucher ID, requested amount, returned status and remaining value, timestamp, and your own transaction or till reference. Do not store more recipient data than you need.

How do I download a voucher PDF?​

Call GET /v1/public/vouchers/{id}/pdf with the API key header. The response is binary application/pdf content with a download filename, not JSON. Stream it as binary data and do not log the file contents.

Why can PDF requests be throttled before other requests?​

PDF generation is more resource-intensive and has its own limit of 10 requests per minute per API key, in addition to the overall limits. Cache a securely stored PDF where your legal and privacy obligations permit rather than repeatedly regenerating it.

Orders and rewards​

What does the order endpoint do?​

POST /v1/public/orders/create sends a completed order to Remy. Depending on the merchant's configuration, it can award stamps or points, issue rewards, and redeem a coupon included with the order.

Which order fields are required?​

Refer to the endpoint reference and OpenAPI schema for the authoritative request shape. Validate required fields and types before sending the request, and send only genuine completed orders.

How do I avoid processing an order twice?​

Use a stable, unique order_number and Idempotency-Key from your commerce system, keep a durable record of successful submissions, and reconcile an uncertain result with GET /v1/public/orders before retrying. A network timeout alone does not prove that the request failed.

Can I retrieve orders after submitting them?​

Yes. Use GET /v1/public/orders to list processed orders and GET /v1/public/orders/{id} for one order. You can filter the list by exact order number or customer ID.

How do I update a reward coupon code?​

Call POST /v1/public/rewards/update-coupon with the issued userRewardId and the new couponCode. Codes are stored in uppercase. Redeemed or expired rewards cannot be updated.

How do I list or redeem an issued reward?​

Use GET /v1/public/customers/{customerId}/rewards and GET /v1/public/customers/{customerId}/rewards/{rewardId} for customer rewards. Redeem an active customer reward with the nested .../{rewardId}/redeem endpoint, the rewards:redeem scope, and an Idempotency-Key. Top-level reward reads return merchant templates.

Are rewards and vouchers the same resource?​

No. Use the rewards endpoint to update the coupon code on an issued reward. Use the voucher endpoints to list, retrieve, render, and redeem issued vouchers. Do not interchange their identifiers.

What do the card endpoints return?​

GET /v1/public/cards returns merchant loyalty-card templates. Customer-specific stamp or point balances are returned by GET /v1/public/customers/{customerId}/cards; use the card-instance ID for stamp and point actions.

Pagination and responses​

How does pagination work?​

List responses include a pagination object alongside data. Start without cursor; while hasMore is true, pass nextCursor unchanged to the next request. Keep limit at or below 100 and keep the same filters between requests.

Which operations require an idempotency key?​

Order creation, reward redemption, and voucher issuance, redemption, cancellation, adjustment, and sending require Idempotency-Key. Reward coupon updates also support it and should use a key when they may be retried. See Idempotency.

What does a normal error response look like?​

Errors return JSON with a numeric code and human-readable message.

{
  "code": 400,
  "message": "A required field is missing or invalid"
}

Do not build application logic by matching the exact message text; use the HTTP status and documented response fields.

Which errors should I retry?​

Do not retry 400, 401, 403, or 404 without correcting the request, key, scopes, or identifier. An idempotency-related 409 may be retried only as the same request after Retry-After. Retry transient 5xx responses with bounded exponential backoff and jitter. Retry 429 only after the specified delay.

What should I do with response fields I do not recognise?​

Ignore and preserve compatibility with them. Remy may add response fields and enum values within v1 without creating a new major API version.

Rate limits and reliability​

What are the default rate limits?​

The overall limits are 120 authenticated requests per minute and 10,000 per day per API key, with up to 10 concurrent requests. Order creation and voucher redemption each allow 60 requests per minute, while voucher PDF generation allows 10 per minute. Failed authentication is limited to 10 failures per five minutes per IP address.

See Rate Limits for the full rules. Endpoint limits apply in addition to the overall limits.

How do I know when a rate limit resets?​

A 429 response includes Retry-After where applicable. Rate-limit headers also report the limit, remaining capacity, and reset delay. Pause for at least the stated interval before retrying.

Can I request a higher limit?​

Contact your Remy account or support contact with the endpoints involved, expected sustained and peak traffic, concurrency, and launch date. Higher limits are not automatic and should be agreed before increasing production traffic.

How should my integration handle downtime?​

Use finite connection and request timeouts, bounded retries for safe operations, and a queue or reconciliation process where appropriate. Fail closed for redemptions when the result is unknown: do not tell a customer that value remains available until you have reconciled the voucher.

Security and data​

What should I do if an API key is exposed?​

Stop using the key, remove it from the exposed location, contact Remy to revoke or rotate it, and review logs for unauthorised requests. Rewriting repository history or deleting a log does not make the old key safe; rotate it.

Can I call the API directly from a browser or mobile application?​

No. Doing so exposes the API key to users and attackers. Call Remy from your own authenticated backend and return only the minimum information required by your client application.

May I log API requests and responses?​

Log enough metadata to support monitoring and reconciliation, but redact X-API-Key, personal data, voucher codes where unnecessary, and PDF content. Apply access controls and a defined retention period to logs.

What data should I send to Remy?​

Send only fields required for the documented operation and for which you have a lawful basis. Do not place secrets, payment-card data, or unnecessary personal data in free-text fields, identifiers, headers, or support tickets.

Versions, tooling, and support​

How is the API versioned?​

The major version appears in the path; the current version is /v1. Backwards-compatible fields, endpoints, and enum values may be added within that version. Breaking changes will ordinarily use a new major namespace or include migration guidance.

How do I download the OpenAPI file?​

Use openapi.json, or open the OpenAPI Spec page. The file can generate typed clients and validation models, but generated code still needs review, secure credential handling, timeouts, and retry controls.

Where are API changes announced?​

Review the Changelog and the affected endpoint documentation. Pin your integration to the documented major API version and test changes before production rollout.

What information should I include in a support request?​

Include the endpoint, HTTP method, approximate timestamp and timezone, HTTP status, a redacted request/response example, and any safe transaction or order reference. Never send an API key, full customer record, or other secret in a support ticket.

Read the Terms and Conditions, Security, Developer Guidelines, and Rate Limits before launching an integration. Your signed agreement with Remy takes precedence where it conflicts with the public developer documentation.