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?​

API keys are provisioned for a Remy merchant and integration. Contact your Remy account or support contact to request one. Use a separate key for each integration and environment where possible.

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?​

Not currently. Each API key is bound to one merchant and can access the public endpoints documented for that merchant. Cross-merchant resource identifiers return 404. Endpoint-level scopes may be introduced as the API grows.

Issued vouchers​

Are voucher endpoints for templates or issued vouchers?​

They operate on issued customer voucher instances. Merchant voucher templates are not returned by these endpoints.

Which voucher identifier should I use?​

Use the issued voucher's id returned by GET /v1/public/vouchers. Do not use the voucher code or template identifier as the path parameter.

How do I list vouchers?​

Call GET /v1/public/vouchers. Use page and limit for pagination, status to filter by voucher state, and search to match voucher codes or titles. The default page size is 10 and the maximum is 100.

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?​

The list endpoint's search parameter can search voucher codes and titles. Once found, use the returned issued-voucher id for get, PDF, and redemption 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 from your commerce system, keep a durable record of successful submissions, and reconcile an uncertain result before retrying. A network timeout alone does not prove that the request failed.

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.

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.

Pagination and responses​

How does pagination work?​

List responses include a pagination object alongside data. Start with page=1, honour the returned pagination metadata, and request subsequent pages until complete. Keep limit at or below 100.

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, or 404 without correcting the request or identifier. Retry transient 5xx responses with bounded exponential backoff and jitter. Retry 429 only after the specified delay. For write requests, first consider whether the original operation may have completed.

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.