{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Rewards & Redemptions","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"rewards--redemptions","__idx":0},"children":["Rewards & Redemptions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Rewards let you turn part of a payment into credits that a customer can spend on a later one. The credits sit on a reward account tied to your marketplace and follow the customer who earned them only that customer can redeem them, and the credits expire after a set period (12 months by default)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The flow has two sides. You ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["generate"]}," rewards by attaching a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reward"]}," block to one or more splits inside a capture. You ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["redeem"]}," them later by sending a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reward_redemption"]}," block on the next capture. In between, you can read what each customer has on hand through the Customer endpoints."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-rewards-work","__idx":1},"children":["How rewards work"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The reward account is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["marketplace-scoped"]},". It's provisioned during onboarding there's no API to create one and you reference it by its UUID inside every reward generation and redemption."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each entry on a reward account is tied to one customer. When a payment includes a split with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reward"]}," block, the customer named at the top of the request is credited for the amount in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reward.value"]},". That credit becomes part of the customer's available balance until it's redeemed or expires."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Redemption works the other way around: on a later capture for the same customer, send a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reward_redemption"]}," block and the matching value is debited from the balance and applied against the payment."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"generating-rewards-on-a-capture","__idx":2},"children":["Generating rewards on a capture"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Attach a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reward"]}," block to any split inside the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["capture.splits[]"]}," array. The customer at the top of the request is the one credited."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST 'https://api.test.easypay.pt/2.0/single' \\\n  -H 'AccountId: YOUR_ACCOUNT_ID' \\\n  -H 'ApiKey: YOUR_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"type\": \"sale\",\n    \"method\": \"cc\",\n    \"value\": 50.00,\n    \"currency\": \"EUR\",\n    \"customer\": {\n      \"id\": \"649e88cf-0b78-4c36-8f99-33f5ebb812a1\",\n      \"name\": \"John Doe\",\n      \"email\": \"john.doe@example.com\"\n    },\n    \"capture\": {\n      \"descriptive\": \"Order #1029\",\n      \"splits\": [\n        {\n          \"split_descriptive\": \"Marketplace seller\",\n          \"account\": {\n            \"id\": \"7e697e0c-c2bf-422a-9535-ab0b750bb832\"\n          },\n          \"value\": 50.00,\n          \"reward\": {\n            \"account\": {\n              \"id\": \"458b2fc4-3092-4de3-abd4-fe1600c09420\"\n            },\n            \"value\": 2.50,\n            \"expiration_date\": \"2027-04-02\"\n          }\n        }\n      ]\n    }\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["What each reward field does:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reward.account.id"]},": the marketplace's reward account that holds the credit. Use the same UUID across every reward you want pooled on the same balance."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reward.value"]},": how much of that split becomes a credit. It doesn't change what the customer pays at the till; it's an amount the marketplace contributes off the split's value."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reward.expiration_date"]},": optional. Defaults to 12 months from the transaction date. Past this date the credit can no longer be redeemed."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"reading-a-customers-balance","__idx":3},"children":["Reading a customer's balance"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Two endpoints expose what a customer has."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /customer/{id}"]}," returns the customer plus a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reward_balances"]}," array with one entry per reward account they hold credits on. Use this when you want a quick total before showing a \"Use your rewards\" option at checkout."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n    \"id\": \"649e88cf-0b78-4c36-8f99-33f5ebb812a1\",\n    \"name\": \"John Doe\",\n    \"email\": \"john.doe@example.com\",\n    \"reward_balances\": [\n        {\n            \"account_id\": \"458b2fc4-3092-4de3-abd4-fe1600c09420\",\n            \"available_balance\": 12.5\n        }\n    ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /customer/{id}/rewards"]}," lists every individual movement on the ledger each ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REWARD"]}," earned and each ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REDEMPTION"]}," spent newest first. It supports filtering by account, type, expiry, and creation date."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl 'https://api.test.easypay.pt/2.0/customer/649e88cf-0b78-4c36-8f99-33f5ebb812a1/rewards?type[]=REWARD&account_id[]=458b2fc4-3092-4de3-abd4-fe1600c09420' \\\n  -H 'AccountId: YOUR_ACCOUNT_ID' \\\n  -H 'ApiKey: YOUR_API_KEY'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n    \"metadata\": { \"next_cursor\": null, \"count\": 2 },\n    \"data\": [\n        {\n            \"id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n            \"account_id\": \"458b2fc4-3092-4de3-abd4-fe1600c09420\",\n            \"type\": \"REWARD\",\n            \"amount\": 10.0,\n            \"expiration_date\": \"2027-01-15\",\n            \"capture\": { \"id\": \"c6056234-a3f9-42de-b944-3ed793fcb6bb\" },\n            \"created_at\": \"2026-01-15T10:30:00Z\"\n        },\n        {\n            \"id\": \"b2c3d4e5-f6a7-8901-bcde-f12345678901\",\n            \"account_id\": \"458b2fc4-3092-4de3-abd4-fe1600c09420\",\n            \"type\": \"REWARD\",\n            \"amount\": 2.5,\n            \"expiration_date\": \"2027-04-02\",\n            \"capture\": { \"id\": \"b6f53027-0478-4728-9269-8bcc0f8088ea\" },\n            \"created_at\": \"2026-04-02T09:12:00Z\"\n        }\n    ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the ledger when you need a per-movement audit trail for example, when a customer asks where a particular credit came from, or when you want to warn about credits about to expire."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"redeeming-rewards-on-a-capture","__idx":4},"children":["Redeeming rewards on a capture"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To spend credits, add a top-level ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reward_redemption"]}," block to either ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /single"]}," (when paying in a single step) or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /capture/{id}"]}," (when capturing an earlier authorisation)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Redemption is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["per reward account"]},": one ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reward_redemption"]}," block targets one account UUID. The redeemed value must not exceed the available balance on that account, nor the value of the payment itself."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Full redemption"]}," apply the entire available balance:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n    \"type\": \"sale\",\n    \"method\": \"CC\",\n    \"value\": 50.0,\n    \"customer\": {\n        \"id\": \"649e88cf-0b78-4c36-8f99-33f5ebb812a1\"\n    },\n    \"reward_redemption\": {\n        \"account\": {\n            \"id\": \"458b2fc4-3092-4de3-abd4-fe1600c09420\"\n        },\n        \"value\": 50.0\n    }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Partial redemption"]}," apply only some of the balance:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n    \"type\": \"sale\",\n    \"method\": \"CC\",\n    \"value\": 50.0,\n    \"customer\": {\n        \"id\": \"649e88cf-0b78-4c36-8f99-33f5ebb812a1\"\n    },\n    \"reward_redemption\": {\n        \"account\": {\n            \"id\": \"458b2fc4-3092-4de3-abd4-fe1600c09420\"\n        },\n        \"value\": 5.0\n    }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In both cases the customer is charged ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["value − reward_redemption.value"]}," through the chosen payment method. The redeemed amount is debited from the balance immediately and shows up as a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REDEMPTION"]}," entry on the ledger."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"earning-and-spending-in-the-same-request","__idx":5},"children":["Earning and spending in the same request"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A single payment can do both. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reward_redemption"]}," block sits at the top of the request and reduces the amount the customer pays; the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["capture.splits[].reward"]}," blocks credit the customer based on the splits. They don't interact you can redeem €10 from a previous balance and earn €5 of fresh credits in the same capture."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Sale with Splits and Reward Redemption"]}," example on ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi#tag/Single-Payment"},"children":["POST /single"]}," shows the combined shape end-to-end."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":6},"children":["Next Steps"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi#tag/Customer"},"children":["Customer endpoints"]},": balance and ledger reference"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi#tag/Single-Payment"},"children":["Single Payment"]},": earn and redeem in one step"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi#tag/Captures"},"children":["Captures"]},": earn and redeem on a separate capture"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/guides/authorizations-captures"},"children":["Authorizations & Captures"]},": when to split auth and capture"]}]}]},"headings":[{"value":"Rewards & Redemptions","id":"rewards--redemptions","depth":1},{"value":"How rewards work","id":"how-rewards-work","depth":2},{"value":"Generating rewards on a capture","id":"generating-rewards-on-a-capture","depth":2},{"value":"Reading a customer's balance","id":"reading-a-customers-balance","depth":2},{"value":"Redeeming rewards on a capture","id":"redeeming-rewards-on-a-capture","depth":2},{"value":"Earning and spending in the same request","id":"earning-and-spending-in-the-same-request","depth":2},{"value":"Next Steps","id":"next-steps","depth":2}],"frontmatter":{"seo":{"title":"Rewards & Redemptions"}},"lastModified":"2026-05-28T13:31:47.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/guides/rewards-and-redemptions","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}