V2.01 Spendstream API & Developer Hub

## Sections
• [Spendstream's REST API V2](https://developers.spendstream.co.uk/spendstream-s-rest-api-v2.md): Build gift cards, cashback and affiliate rewards directly into your product. The Spendstream API V2 gives publishers a single integration for managing gift card distribution, affiliate offers, cashback rewards and transaction reporting. Use the API to: Onboard and manage your users Surface offers from more than 4,000 affiliate brands Issue digital gift cards from over 150 major brands Track purchases and cashback activity Receive real-time transaction updates Reconcile the commission generated through your platform Spendstream provides the underlying rewards infrastructure, including brand inventory, supplier relationships and payment capabilities, allowing you to focus on building the customer experience. Two ways to integrate Choose how much of the user experience you want to build and manage. White-Label Launch a fully branded rewards platform without building the front end yourself. Spendstream hosts and manages the platform while applying your branding, content and product configuration. Optional single sign-on allows users to move from your platform into the rewards experience without needing to log in again. The white-label option is best suited to businesses that want to launch quickly with minimal engineering work. You provide: Your brand assets and configuration Your users or user authentication Your preferred products and reward structure Spendstream manages the storefront, brand catalogue, transactions and supporting infrastructure. Full API Build the entire rewards experience inside your own website or application. Your platform controls the interface and customer journey while communicating directly with Spendstream through the API. The Full API option gives you maximum flexibility over: User experience and interface design Reward calculations and messaging Product presentation Customer communications Internal reporting and workflows Spendstream continues to manage the underlying brand inventory, supplier relationships, gift card fulfilment and affiliate connectivity. Choose your products Your Spendstream account can be configured for Gift Cards, Affiliates or Both. Gift cards Allow users to purchase digital gift cards from more than 150 major brands. Gift card orders can be funded through: A prepaid publisher balance A Spendstream-hosted payment page Gift cards are issued digitally and can be presented to users through your own interface or the Spendstream white-label platform. Affiliates Give users access to tracked offers from more than 4,000 online brands. Users follow a tracked link to the retailer and complete their purchase directly with the brand. Spendstream then receives transaction and commission information from the relevant affiliate network. Your integration can use this information to provide cashback, loyalty points, account credit, competition entries or another reward determined by your business. Gift Cards and Affiliates Combine both products to give users access to instant gift card savings and tracked online offers through one integrated experience. API responses are adapted to your account configuration so that you only receive the products and fields relevant to your integration. Getting started A typical Full API integration follows these steps: Choose your integration model and products. Receive your staging API credentials. Exchange your API credentials for a bearer token. Create or synchronise your users. Retrieve the relevant brands, offers and categories. Implement your gift card or affiliate customer journeys. Configure webhooks for real-time updates. Complete staging testing before moving to production. Staging Environment Use the staging environment while developing and testing your integration. https://staging-api.spendstream.io/v2 For example: https://staging-api.spendstream.io/v2/getBrands Production credentials and environment details are provided as part of the onboarding process. Authentication The Spendstream API uses bearer-token authentication. Your API key and secret are used to generate an HMAC-SHA256 signature, which is then exchanged for a bearer token valid for 10 hours. Include the bearer token in the Authorization header of every subsequent API request: Authorization: Bearer <access_token> Standard API bearer tokens remain valid for 10 hours. White-label user login tokens use a shorter validity period and should be refreshed as part of the user authentication flow. API credentials must be stored securely and must never be exposed in browser-side or mobile application code. Users The Users resource allows you to create and manage the people using your rewards programme. Use it to: Create new users Update existing user information Retrieve individual users List users associated with your account Record or retrieve relevant user activity Users provide the connection between your customer records and activity recorded within Spendstream. Where possible, retain the Spendstream user identifier alongside the corresponding identifier in your own platform. Brands The Brands resource provides access to the brands available through your Spendstream account. Depending on your product configuration, a brand may support: Affiliates Digital gift cards Promotional offers More than one product type Brand availability can vary by country, account configuration and product type. Use the brand data returned by the API to display information such as: Brand name Brand imagery Product availability Offer information Redemption or purchase instructions Applicable terms and conditions Do not permanently hard-code brand information, as availability and commercial terms may change. Promotions The Promotions resource returns active promotional offers available through participating brands. Promotions may include enhanced commission rates, increased cashback or time-limited offers. Use the promotion start and end dates returned by the API to ensure that an offer is only displayed while it remains valid. Promotional availability can change independently of the underlying brand, so promotion data should be refreshed regularly. Cashback The Cashback resource provides the affiliate offer catalogue available to your account. Cashback offers can include: The gross commission or cashback rate The revenue share available to your business Customer-facing offer information Tracking links Offer terms and exclusions Relevant brand and category information When a user follows a tracked link, the transaction is attributed through the relevant affiliate network. Transaction confirmation is not normally immediate. Affiliate transactions can initially be reported as pending and may later be approved, declined or amended. Use transaction webhooks rather than the customer returning to your website as the authoritative source of transaction status. Categories The Categories resource provides the taxonomy used to organise brands and offers. Categories can be used to: Build navigation menus Group similar brands Filter search results Create category landing pages Improve offer discovery A brand may appear in one or more categories. Category identifiers should be used when filtering API results rather than relying only on category names. Transactions The Transactions resource provides a central record of qualifying activity generated through your account. Transactions can include: Gift card purchases Affiliate purchases Cashback activity Commission adjustments Transaction status changes Transaction records may include a breakdown of: Customer spend Gross commission Publisher commission User reward Transaction status Affiliate transactions may move through several states before they are finalised. Your platform should store the Spendstream transaction identifier and update its local record whenever a transaction update is received. Changes are also sent through the TRANSACTION_UPDATED webhook event. Gift Cards The Gift Cards resource allows you to offer and issue digital gift cards through your platform. Depending on your configuration, gift card orders can be funded using: Your prepaid Spendstream balance A Spendstream-hosted payment gateway The API supports flows where customer and order information has already been created within Spendstream, as well as flows where the required order information is supplied directly in the purchase request. Before submitting an order: Confirm that the brand is currently available Confirm the permitted gift card values Check the available publisher balance where applicable Validate the recipient information Prevent accidental duplicate submissions Gift card fulfilment should only be treated as successful once the API has returned a confirmed order result. Digital gift cards are generally non-refundable once issued, subject to the applicable agreement and legal requirements. Balances The Balances resource returns information about your prepaid Spendstream balance. Publishers using the prepaid funding model should check their available balance before submitting a gift card order. Balance information can be used for: Internal finance reporting Low-balance notifications Purchase validation Reconciliation Funding forecasts Your available balance must be sufficient to cover the relevant gift card order. Payments The Payments resource is available to Full API publishers using Spendstream's hosted payment gateway instead of a prepaid balance. Use it to create a secure hosted payment link for the customer. The customer completes payment through the Spendstream-hosted checkout before the corresponding gift card is issued. This allows you to offer gift cards through your own interface without directly collecting or processing the customer's card details. Your integration should rely on the payment and transaction status returned by Spendstream rather than assuming that a customer has paid because they returned to your platform. Webhooks Webhooks provide real-time notifications when important data changes within Spendstream. Available events: TRANSACTION_UPDATED — sent when a gift card or affiliate transaction is created or its status or financial information changes. USER_UPDATED — sent when relevant information associated with a user changes. Webhook requests are signed using HMAC so that your system can verify that the request originated from Spendstream. Your webhook handler should: Verify the signature before processing the event Return a successful response promptly Process events idempotently Use the event identifier or resource identifier to prevent duplicate processing Retrieve the latest resource data where necessary Record failed processing attempts for investigation Process each event as an upsert keyed by the Spendstream identifier: create the local record if you do not already have it, and update it if you do. Never create a second record for an event you have already processed. Recommended integration approach For a reliable integration: Develop and test against the staging environment Keep API credentials on a secure server Store Spendstream resource identifiers Refresh catalogue and promotional data regularly Treat webhook notifications as the source of transaction updates Allow for pending and amended affiliate transactions Validate balances before submitting gift card orders Reconcile transactions and commission against your internal records Start with Authentication, then implement Users and the catalogue resources required for your selected products.
• [Authentication](https://developers.spendstream.co.uk/authentication.md): Exchange your API key and secret for a bearer token valid for 10 hours. The POST /getToken operation is the only endpoint that does not require bearer authentication; it uses an HMAC-SHA256 handshake over the request body. Token lifetime: 10 hours. When a token is about to expire, call getToken again. The response's expiry field is a Unix timestamp. This token authenticates your publisher account , not an individual end-user — obtain one and reuse it across all of your users' activity. You do not need to call getToken on each end-user visit; only refresh it as it nears expiry. For white-label single sign-on, the per-user login token is a separate concept — see the Users tag. HMAC signature computation: Plain Text code = hash_hmac('sha256', api_key + time_stamp, api_secret) code = hash_hmac('sha256', api_key + time_stamp, api_secret) The time_stamp must be the current timestamp at the point the signature is computed. Large clock drift (more than a few minutes) will cause signature-mismatch errors.
  • [Exchange API credentials for a bearer token valid for 10 hours.](https://developers.spendstream.co.uk/authentication/exchange-api-credentials-for-a-bearer-token-valid-for-10-hours.md): The only unauthenticated endpoint in the API. Submit your API key, a current timestamp, and an HMAC-SHA256 signature over the concatenation of the two: ``` code = hash_hmac('sha256', api_key + time_stamp, api_secret) ``` On success, returns a JWT (HS256) valid for 10 hours. Include it on subsequent calls as `Authorization: Bearer <token>`. **Clock drift** is the most common source of failures — the `time_stamp` must reflect the moment the signature was computed, and your server clock should be accurate to within a minute or two. **Rate limiting** applies at five requests per minute per IP.
• [Users](https://developers.spendstream.co.uk/users.md): Register, retrieve, and update the end-users tied to your publisher account — each keyed by a UID you supply. For white-label integrations, user responses also include a per-user SSO login token that drops the user straight into the hosted storefront, distinct from the API bearer token.
  • [List users registered against the calling publisher.](https://developers.spendstream.co.uk/users/list-users-registered-against-the-calling-publisher.md): Returns users belonging to the calling publisher. The response shape differs by publisher type: Gift Card publishers see `total-amount`; Affiliate publishers see the full cashback-lifecycle breakdown (`pending-amount`, `approved-amount`, `payable-amount`, `paid-amount`, `declined-amount`). For white-label (SSO-enabled) publishers, each user record includes a `token` — an SSO login token that places the user directly into their white-label session.
  • [Register a new end-user against the calling publisher.](https://developers.spendstream.co.uk/users/register-a-new-end-user-against-the-calling-publisher.md): Creates a new user record keyed by your supplied `UID`. `UID` uniqueness is scoped to your publisher — the same UID can exist under different publishers. For SSO-enabled (white-label) publishers, a per-user SSO login token is generated once at creation and mirrored into the publisher's linked database; set `whitelabel=1` to skip the mirror if you manage user storage yourself. **Required before `POST /paymentLink`.** Payment-link generation requires the end-user to exist under your publisher; calling `paymentLink` with an unregistered `user_id` returns `400 {"message": "no valid user"}`. Register every paying user here first. **Idempotency caveat (current behaviour).** Re-posting the same `UID` for the same publisher returns `400 {"message": "User already exists with UID"}` — the endpoint is **not** idempotent today. Receivers should treat this 400 as success (the user is already registered) and proceed to `paymentLink`. A future release intends to make this endpoint return the existing user record idempotently; until then, handle the 400 defensively. Also triggers an email/CRM contact sync for a specific set of publishers (configured server-side). This is hard-coded server-side; you cannot opt in or out from the request.
  • [Update attributes on an existing user record.](https://developers.spendstream.co.uk/users/update-attributes-on-an-existing-user-record.md): Merge-updates a user record keyed by `UID`. Fields omitted from the request body retain their existing values. Triggers a `USER_UPDATED` webhook to any registered consumer URL after a successful update. Use this endpoint to propagate name, email, phone, or status changes from your system of record into Spendstream — particularly important for white-label integrations where Spendstream may display these values to the end-user.
  • [Record a user activity log entry against a token.](https://developers.spendstream.co.uk/users/record-a-user-activity-log-entry-against-a-token.md): Appends an activity log entry to the user identified by the supplied SSO login token . The userID and message fields are stored verbatim; Spendstream looks up the user's UID from the token, not from userID alone. Intended for white-label integrations that want to surface user-facing activity (e.g. "viewed rewards page", "redeemed voucher") in the publisher's activity feed.
  • [Set a user's email-reminder opt-in preference.](https://developers.spendstream.co.uk/users/set-a-user-s-email-reminder-opt-in-preference.md): Records whether an end-user has opted in to reminder/notification emails. Pass `submitremind` as `1` to opt in or `0` to opt out; the flag and a submission date are stored against the user. Primarily used by the white-label storefronts to honour a user's preference toggle. This is a notification-preference flag only — it does not affect transactions or auth.
• [Brands](https://developers.spendstream.co.uk/brands.md): Browse the Brand catalogue Spendstream makes available to your users — names, imagery, categories, and redemption detail. The response shape depends on your publisher type: Gift Card publishers receive redemption methods and denominations; Affiliate publishers receive commission groups and tracking metadata.
  • [List the brand catalogue available to the calling publisher.](https://developers.spendstream.co.uk/brands/list-the-brand-catalogue-available-to-the-calling-publisher.md): Returns the brand catalogue surfaced to your end-users, scoped to your publisher's country and type. The response shape **differs by publisher type**: Gift Card publishers see redemption-method and denomination metadata (`fixed-amount`, `flexed-amount`, `balance-check`) alongside gift-card-supplier brand metadata; Affiliate publishers see commission groups (`commission-groups`) and tracking-URL attribution patterns (`offer-activated-url`, `affiliate-network-id`). Set `withPromos=1` to embed the currently active promotion inside each brand record. This is most useful for Gift Card publishers building catalogue views; Affiliate publishers typically iterate `/getPromotions` separately instead.
• [Promotions](https://developers.spendstream.co.uk/promotions.md): Active promotional offers tied to Brands — each carries the offer terms, the linked Brand, and the publisher-facing commission. The public commission fields are `processing-fee` and `client-commission`. Use `GET /getPromotionsList` for the full offer list with embedded Brand detail.
  • [List active promotions (flat, minimal) — deprecated.](https://developers.spendstream.co.uk/promotions/list-active-promotions-flat-minimal-deprecated.md): **Deprecated — do not build new integrations against this endpoint.** It is backed by `Promotions::index`, which Ashan has confirmed (2026-06-09) is unused legacy/test code scheduled for removal. Use `GET /getPromotionsList` (`Promotions::list`) instead, which returns the same promotions plus the embedded brand-detail block and the current commission breakdown. > This endpoint exists on the `/api/` and `/v1/` prefixes only — there is no `/v2/` route. The example below therefore shows the `/api/` URL. Returns the flat promotion list — promotion metadata plus linked brand name and category array, but no embedded brand detail block. Date filtering uses an inclusive window: a promotion is included if `start-date = to-date`. Supplying only one bound applies no filter; both bounds must be present.
  • [List active promotions with embedded brand detail.](https://developers.spendstream.co.uk/promotions/list-active-promotions-with-embedded-brand-detail.md): Returns the rich promotion list — each promotion carries a fully embedded `brands` block with imagery, terms, `how-it-works` redemption detail, denomination rules, and balance-check capability. The response shape is the same for all publisher types. The public commission fields are `processing-fee` and `client-commission`.
• [Cashback](https://developers.spendstream.co.uk/cashback.md): The affiliate commission offers your users can redeem through tracked links — the affiliate-side equivalent of the gift-card Promotions list. This catalogues the available offers and their rates; you earn commission on each attributed transaction, reported asynchronously via the `TRANSACTION_UPDATED` webhook. Affiliate publishers can use this alongside, or instead of, `GET /getPromotionsList`.
  • [List active affiliate commission offers (primary variant).](https://developers.spendstream.co.uk/cashback/list-active-affiliate-commission-offers-primary-variant.md): Returns the affiliate commission-offer catalogue — offers your users can redeem through affiliate tracking links. Each offer carries the gross commission rate, the computed customer revenue share (either percentage or fixed depending on `commission-type`), and a human-readable `commission-rates` summary string. This is the affiliate-publisher equivalent of `GET /getPromotionsList`; affiliate publishers typically use one or the other. Commission attribution for actual user redemptions arrives asynchronously via the `TRANSACTION_UPDATED` webhook — this endpoint catalogues offers but does not return per-user transaction data. For that, use `/getTransactionsList`.
• [Categories](https://developers.spendstream.co.uk/categories.md): The category taxonomy that organises the Brand catalogue — the groupings (such as supermarkets, fashion, and travel) used to help users browse and filter Brands. Use it to build navigation and discovery in your own interface, and to cross-reference Brands and Promotions by category.
  • [List brand categories.](https://developers.spendstream.co.uk/categories/list-brand-categories.md): Returns the category taxonomy used to group brands. Each category carries an array of the brand IDs that belong to it. Use this endpoint to build a category-navigation view; fetch the individual brands separately via `/getBrands` filtered by `brand-id`.
• [Transactions](https://developers.spendstream.co.uk/transactions.md): Retrieve the purchases and cashback events attributable to your users. The response shape branches by publisher type: gift card transactions carry a `gift-card-url` and a `transaction-type` of `float` or `gateway`; affiliate transactions carry the commission breakdown and a status. The same events are pushed in real time via the `TRANSACTION_UPDATED` webhook.
  • [List transactions attributable to the calling publisher's users.](https://developers.spendstream.co.uk/transactions/list-transactions-attributable-to-the-calling-publisher-s-users.md): Returns purchases and cashback events. Response shape differs by publisher type: Gift Card transactions include `gift-card-url`, `free-entries`, and a `transaction-type` of `float` (drawn from the publisher's prepaid balance) or `gateway` (paid via hosted payment gateway). Affiliate transactions include `promo-id`, `affiliate-network-id`, commission breakdown (`client-rev-share`, `user-cashback`), and a `transaction-type` of `Voucher` or `Normal`. The gift-card variant returns a legacy `amount-spend` field — prefer the replacement `purchase-amount` for new integrations; both are currently populated.
  • [Get a user's aggregated transaction summary.](https://developers.spendstream.co.uk/transactions/get-a-user-s-aggregated-transaction-summary.md): Returns an aggregated summary for a single user: total commission earned, total spend, and total purchase count. Despite the name, this endpoint does not look up a single transaction — it summarises all transactions for the given `UID`. Use `/getTransactionsList?UID=...` for a per-transaction breakdown.
  • [Flag an affiliate transaction as paid to the end-user.](https://developers.spendstream.co.uk/transactions/flag-an-affiliate-transaction-as-paid-to-the-end-user.md): For Affiliate publishers managing cashback payouts to end-users outside Spendstream. Call this when you've remitted the user's cashback to them; Spendstream records the status for reporting but does not perform any payment action. The response confirms the transaction's current status — if the transaction is still in `pending` state, the call returns `400` and no status change occurs.
• [Gift Cards](https://developers.spendstream.co.uk/gift-cards.md): Issue gift cards programmatically on behalf of your users. Issuance is synchronous — a successful response returns the card URL, reference, and face value, ready to surface to the user. Purchases are funded from your prepaid float, or via a hosted payment link (see Payments).
  • [Process a gift card fulfilment from a pre-existing order in the publisher's database.](https://developers.spendstream.co.uk/gift-cards/process-a-gift-card-fulfilment-from-a-pre-existing-order-in-the-publisher-s-database.md): Gift card fulfilment for publishers that maintain their own order table in a database Spendstream connects to. Call this with an `orderId` from your system; Spendstream reads the full order detail from your database, issues the gift card via the gift-card supplier, records the transaction, updates the user's earnings, and dispatches a `TRANSACTION_UPDATED` webhook. Most new integrations should use `/giftCardRequestApi` instead — it accepts all order detail in the request body and does not require Spendstream to have a direct database connection to your order table.
  • [Issue a gift card directly via the API (self-contained request).](https://developers.spendstream.co.uk/gift-cards/issue-a-gift-card-directly-via-the-api-self-contained-request.md): The primary gift card issuance endpoint for modern integrations. All order detail is supplied in the request body — no external database connection required. Calculates the entry count (for prize-draw publishers, e.g. one free ticket per £10 spent), creates an internal order record, issues the card via the gift-card supplier, updates the user's earnings, and dispatches a `TRANSACTION_UPDATED` webhook. On supplier failure, the error is persisted for debugging and an alert email is dispatched internally. The response echoes the supplier's error message to the caller.
  • [Check the remaining balance on an issued gift card.](https://developers.spendstream.co.uk/gift-cards/check-the-remaining-balance-on-an-issued-gift-card.md): Queries the gift-card supplier for the remaining balance on a gift card that Spendstream previously issued, keyed by the `transactionid` returned from issuance. Only brands that support balance check are queryable — if the brand doesn't support balance check, the call returns `400` with an explanatory message. Recent balance lookups (within five minutes) are served from cache; otherwise the call hits the upstream supplier directly. **Response field:** read the balance from `available_balance`.
• [Balances](https://developers.spendstream.co.uk/balances.md): Check your publisher prepaid float — the funds Spendstream holds for you to draw down against when issuing gift cards. Query it before initiating a purchase; a configurable alert fires when the balance falls below your threshold.
  • [Check the calling publisher's prepaid float balance.](https://developers.spendstream.co.uk/balances/check-the-calling-publisher-s-prepaid-float-balance.md): Returns the publisher's own prepaid float balance — the pool that float-mode gift card orders draw down from. A side effect fires if the balance falls below the publisher's configured low-balance threshold: a "URGENT: Spendstream Float Balance — Top-Up Required" email is dispatched to the publisher's billing contact. There is no parameter to suppress this email.
• [Payments](https://developers.spendstream.co.uk/payments.md): Generate a secure, hosted payment link so your end-users can pay for a gift card directly — for API publishers that don't run their own gateway. The user completes payment on the hosted page; Spendstream handles the callback, issues the gift card, and fires a transaction webhook on success.
  • [Generate a hosted payment gateway URL for a gift card purchase.](https://developers.spendstream.co.uk/payments/generate-a-hosted-payment-gateway-url-for-a-gift-card-purchase.md): For API-mode publishers that don't use the prepaid float model. Creates an order record and returns a hosted payment gateway URL. Redirect the end-user to that URL; they complete payment there, after which Spendstream receives the gateway callback and issues the gift card automatically. **Preconditions — read before integrating:** 1. **The `user_id` MUST already be registered against your publisher.** Call `POST /addNewUser` first if the user is new. Posting a `user_id` that does not exist in your publisher's user table returns `400 {"message": "no valid user"}` — even if the same UID is registered under a different publisher (UIDs are scoped per publisher). See the *Integration Sequence* guide for the full call order. 2. **The `promo_id` MUST belong to your publisher's catalogue.** Promo IDs are publisher-scoped; passing a `promo_id` you don't own returns `400`. Look up valid IDs via `GET /getBrands` or `GET /getPromotionsList`. 3. **Your publisher must be configured as API-mode with a payment-gateway integration.** Float-model publishers (where Spendstream holds your prepaid balance) should call `POST /giftCardRequestApi` instead and never hit this endpoint. The success callback lives at `/payment-success` (GET, browser-facing, not listed in this API reference). On success, Spendstream issues the gift card, updates the user's balance, dispatches a `TRANSACTION_UPDATED` webhook, and redirects the user back to the publisher's configured redirect URL.
• [Webhooks](https://developers.spendstream.co.uk/webhooks.md): System webhook endpoints
  • [{$request.body#/webhook_url}](https://developers.spendstream.co.uk/webhooks/usdrequest-body-webhook_url.md): **Callback:** userUpdated **Expression:** `{$request.body#/webhook_url}`
  • [{$request.body#/webhook_url}](https://developers.spendstream.co.uk/webhooks/usdrequest-body-webhook_url-1.md): **Callback:** userUpdated **Expression:** `{$request.body#/webhook_url}`
  • [{$request.body#/webhook_url}](https://developers.spendstream.co.uk/webhooks/usdrequest-body-webhook_url-2.md): **Callback:** transactionUpdated **Expression:** `{$request.body#/webhook_url}`
  • [{$request.body#/webhook_url}](https://developers.spendstream.co.uk/webhooks/usdrequest-body-webhook_url-3.md): **Callback:** transactionUpdated **Expression:** `{$request.body#/webhook_url}`
  • [{$request.body#/webhook_url}](https://developers.spendstream.co.uk/webhooks/usdrequest-body-webhook_url-4.md): **Callback:** transactionUpdated **Expression:** `{$request.body#/webhook_url}`