canonical: https://jentic.com/apis/remyrewards.co.uk/remyrewards

# Remyrewards Remy Public API

The Remy Public API connects a merchant's till, online shop, or booking system to their Remy loyalty programme. Orders posted with a customer_email, order_value, and order_source feed the programme, and you can give stamps or points on a customer's loyalty card, give and redeem rewards, and issue, send, redeem, adjust, or cancel vouchers. Read operations return customers with their loyalty state, the merchant's card, reward, and voucher templates, and the API key's own identity and usage.

## For AI agents

Record orders, give stamps and points, issue and redeem vouchers, and read customer loyalty state in a Remy loyalty programme. Authenticated with the X-API-Key header.

## Scope

Does not handle card payments, point-of-sale checkout, or email marketing campaigns. Use for running a Remy loyalty programme's orders, stamps, points, rewards, and vouchers only.

## Capabilities

- Record an order against a customer's email so it counts toward Remy loyalty
- Give stamps or points on a customer's loyalty card, optionally tagged with a locationId
- Give a reward to a customer and redeem it at the till
- Issue a voucher from a template and email it to the recipient
- Look up a voucher by its code and redeem an amount against it
- Adjust a voucher's remaining value or cancel it with a reason
- Read a customer's loyalty state, cards, rewards, and vouchers

## Use cases

### Agent-run loyalty desk

Your agent answers staff or customer questions about a Remy loyalty programme. It finds the customer by email, reads their loyalty state and cards, and gives stamps or points when a purchase was missed, so routine loyalty fixes happen in chat instead of in the merchant dashboard.

Example prompt: Call GET `/v1/public/customers` with email set to the customer's address, then POST `/v1/public/customers/{customerId}/cards/{cardId}/stamps` with quantity set to 1 and a unique Idempotency-Key header

### Feed orders into the loyalty programme

When an online or in-store sale completes, the order is posted to Remy with customer_email, order_value, and order_source (plus an optional order_number and coupon_code) and an Idempotency-Key header, so retries never double-count a purchase.

Example prompt: Call POST `/v1/public/orders/create` with customer_email, order_value set to 24.50, order_source set to 'web', and a unique Idempotency-Key header

### Gift voucher issuing and redemption

An agent issues a voucher from a voucher template by voucherTemplateId, optionally setting value, recipientEmail, and send so Remy emails it. At redemption it looks up the voucher by code, redeems an amount, and can adjust the remaining value or cancel the voucher with a reason.

Example prompt: Call GET `/v1/public/vouchers/lookup` with code set to the voucher code, then POST `/v1/public/vouchers/{id}/redeem` with amount set to 10 and an Idempotency-Key header

### Reward fulfilment at the till

Rewards a customer has earned are listed per customer and redeemed with the customer reward operation, optionally recording the locationId of the branch. Rewards can also be given directly by rewardId for goodwill gestures.

Example prompt: Call GET `/v1/public/customers/{customerId}/rewards`, then POST `/v1/public/customers/{customerId}/rewards/{rewardId}/redeem` with the branch locationId and a unique Idempotency-Key header

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v1/public/orders/create` | Process an order |
| GET | `/v1/public/customers/{id}/loyalty` | Get customer loyalty |
| POST | `/v1/public/customers/{customerId}/cards/{cardId}/stamps` | Give stamps |
| POST | `/v1/public/customers/{customerId}/cards/{cardId}/points` | Give points |
| POST | `/v1/public/vouchers` | Issue voucher |
| GET | `/v1/public/vouchers/lookup` | Look up voucher by code |
| POST | `/v1/public/vouchers/{id}/redeem` | Redeem voucher |
| POST | `/v1/public/customers/{customerId}/rewards/{rewardId}/redeem` | Redeem customer reward |

## Key resources

- **Orders** — Purchases fed into the loyalty programme; create, list by orderNumber or customerId, read
- **Customers** — Programme members; list by email or search, read, and read loyalty state
- **Customer loyalty cards** — A customer's cards; read, give stamps, give points, adjust points
- **Customer rewards** — Rewards held by a customer; list, give, read, redeem
- **Vouchers** — Voucher templates and issued vouchers; issue, look up by code, redeem, adjust, cancel, send, PDF
- **API identity and usage** — Verify the key, read the key's identity and its API usage

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 64 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 73 / 100
  - Developer Experience & Jentic Compatibility: 64 / 100
  - AI-Readiness & Agent Experience: 50 / 100
  - Agent Usability: 94 / 100
  - Security: 50 / 100
  - AI Discoverability: 75 / 100
- **View full report:** https://jentic.com/apis/remyrewards.co.uk/remyrewards/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring Remy by hand means sending the X-API-Key header, generating Idempotency-Key values for balance-changing calls, and paging customer and voucher lists with cursor and limit. Through Jentic you install once, import Remy from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Remy puts the customer id in the URL path (`/v1/public/customers/{customerId}/...`), so a rule can limit your agent to one customer's cards and rewards, and voucher operations carry the voucher id in the path too. You choose the operations it may call, so balance-changing ones like voucher cancellation or points adjustment are not included unless you add them.
- **Credential handling:** Your Remy API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'give loyalty stamps' or 'redeem a gift voucher', and Jentic returns the matching Remy operation with its input schema so the agent sends the right fields and headers.

## Related APIs

- **LoyaltyLion** — Ecommerce loyalty and rewards platform
- **Antavo** — Loyalty programme management platform
- **Shopify** — Store orders to feed into Remy

## FAQ

### What authentication does the Remy Public API use?

Per its OpenAPI spec, the Remy Public API authenticates with an API key from the merchant's Remy integration settings, sent in the X-API-Key header. GET `/v1/public/auth` verifies a key. Through Jentic, the key is stored encrypted by your own Jentic One instance and injected at execution time.

### Why do some Remy calls need an Idempotency-Key header?

Operations that change balances, such as processing an order, issuing or redeeming a voucher, and giving or redeeming rewards, take an Idempotency-Key header. Sending the same key on a retry stops a purchase or redemption from being applied twice.

### Can I redeem a gift voucher by its code with the Remy API?

Yes. Call GET `/v1/public/vouchers/lookup` with the code to find the voucher, then POST `/v1/public/vouchers/{id}/redeem` with the amount to take off. POST `/v1/public/vouchers/{id}/adjust` sets a new remainingValue with a reason if a correction is needed.

### What are the rate limits for the Remy Public API?

The OpenAPI spec does not state a numeric limit, though its operations declare a TooManyRequests response when you exceed one, and GET `/v1/public/usage` reports your key's API usage. Check https://developer.remyrewards.co.uk for current limits.

### Is there a Remy Rewards MCP server?

You don't need an MCP server to give your agent Remy. Jentic connects it directly from the API Directory: import it, store your X-API-Key once, and your agent calls it. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Can I limit what my agent is allowed to do with the Remy Public API?

Yes. A customer-service agent could be allowed to read customers and give stamps under `/v1/public/customers/{customerId}/cards/{cardId}/stamps`, while voucher cancel, voucher adjust, and points adjust stay off its list. It can then fix a missed stamp but cannot change balances any other way, and every call is logged.