Skip to main content

Send sponsor redemptions to a CRM

When a perk from a sponsor package is redeemed, XQUARE can tell your systems, so the sponsor sees the redemption in their CRM next to their other leads. Your systems can also redeem perks themselves through the API.

  1. In the vendor panel, open Connections and add your endpoint with the sponsor.redemption.created event. Add sponsor.package.purchased and sponsor.package.expired too if your CRM tracks packages.
  2. In your receiver, verify the signature. Then answer 2xx straight away and queue the CRM write.
  3. Write to the CRM keyed on the event id, so a retried delivery never creates a second activity.
{
  "id": "evt_…",
  "type": "sponsor.redemption.created",
  "api_version": "2026-10-08",
  "created_at": "2026-10-20T09:12:44.000Z",
  "space_id": "…",
  "data": { "…": "…" }
}

data carries ids and business fields only, never customer contact data.

v1 — expanding

The field list of each event's data is not published yet. Until it is, read the fields you need defensively and ignore fields you do not know.

Redeem a perk from your own system​

If your Space bought the sponsor package, your system can redeem a perk by the code the shopper shows. Scope: sponsor_redemptions:create.

POST /v1/sponsor-packages/{id}/redemptions
Authorization: Bearer xq_live_…
Idempotency-Key: crm-redeem-000917
Content-Type: application/json

{ "code": "…" }

A successful redemption answers 201 with the redemption: id, sponsor_package_id, credits_charged and redeemed_at.

  • The redemption is charged in credits, once, however often you retry with the same Idempotency-Key. The sponsor.redemption.created webhook is also sent once.
  • Each successful redemption also counts against your plan's monthly API action allowance. When it is used up you get 429 allowance_exhausted with Retry-After, and nothing is charged.
  • A perk that is a voucher is refused with use_voucher_redeem. Redeem it with POST /v1/vouchers/redeem instead (see Redeem a voucher from a POS).
  • Only the key of the Space that bought the package can redeem. Any other Space gets 404 not_found.

All codes: Errors.

Reading packages​

GET /v1/sponsor-packages lists the sponsor packages your Space is part of, and GET /v1/sponsor-packages/{id} reads one. Scope: sponsor_packages:read.

What about the customer?​

Payloads carry no customer personal data.

Not yet available

A pseudonymous customer reference (customer_ref) in voucher events is under legal review and is not sent today. Do not build a CRM match on it.

Last updated on