Reward Networks Reward Networks Developer Hub

Rate limits, scopes & versioning

Rate limits

120 requests per minute per API key by default. A different limit can be configured for your key by the Reward Networks team — ask if a busy site needs more.

Over the limit the API answers 429 Too Many Requests with a Retry-After header (seconds). Back off for that long; do not hammer.

Practical guidance for a till: one sale is at most 3 calls (validate, preview, commit), so 120/minute covers 40 sales a minute per key. Give each store its own key if you are anywhere near that.

Scopes

A key without scopes has full access. Restrict a key when the client only needs part of the API — a reporting integration should not be able to award points.

Scope Endpoints
transactions.write qr/validate, transactions/preview, transactions/commit, transactions/redeem, transactions/{id}/void, rewards/claim, packages/redeem/preview, packages/redeem, item-deals/redeem/preview, item-deals/redeem, birthday-gift/redeem/preview, birthday-gift/redeem, customers/{id}/redemptions, customers/{id}/redemptions/{id}/cancel
members.write members/add
customers.read customers/lookup, customers/{id}/balance, customers/{id}/redeem-options
catalog.read branches, campaigns/status, vouchers, rewards/catalog
history.read transactions, redemptions, redemptions/{id}

A call outside the key's scopes answers 403 with This API key does not have the required \history.read` scope.`

Idempotency

Send an Idempotency-Key header (any unique string, a UUID v4 is ideal) on every POST that changes something. Replays within 24 hours return the stored response with Idempotency-Replayed: true. Details in Award points & stamps.

Versioning

All endpoints live under /api/partner/v1/.

  • Within v1, changes are additive only. New endpoints, new optional request fields and new response fields may appear at any time. Existing fields never change meaning or disappear. Parse responses leniently: ignore fields you do not know.
  • Breaking changes ship under a new prefix (/v2/) with a migration period during which both versions run.
  • Deprecations are announced in the portal and by email to the developer account.

Environments

The base URL of these docs is the environment they are served from. Staging and production have separate developer accounts, keys, merchants and webhooks — nothing is shared.
This environment https://staging.app.rewards.network/api/partner/v1
Keys rn_test_… for the sandbox merchant, rn_live_… for real merchants

Timestamps and money

  • Timestamps are ISO 8601 in UTC (2026-09-22T10:41:07+00:00).
  • Monetary amounts in requests are decimal numbers (48.50). In stored objects (transaction.final_amount) they may come back as strings with two decimals; computed fields (points_earned, discount_amount) are numbers.
  • Points and stamps are integers.