XQUARE API

The XQUARE API lets your own systems — a point-of-sale, a CRM, a gate scanner — work with your Space's vouchers, events and sponsor packages. Signed webhooks tell your systems when something happens.

v1 — expanding

This developer section is version 1. The guides cover what the API does today; more detail and more examples will be added over time. The API reference is generated from the released spec (api-v1.0.0). Operations served since that release may still be labelled "planned" there until the next spec release; the changelog lists what is live.

Base URL and keys

Environment	Base URL	Keys
Live	https://api.xquare.net/v1	xq_live_…

A sandbox environment for test keys (xq_test_…) is not open yet — see Sandbox. Each server accepts only the keys for its own environment. A key for the other environment gets 401 unauthorized, the same answer as an unknown key.

Authentication

Send your Space's API key as a bearer token:

Authorization: Bearer xq_live_XXXXXXXXXXXXXXXX

Create and revoke keys in the vendor panel under Account → API keys. A key is shown once, when you create it. Store it in your server's secret store. Never put a key in a browser, a mobile app or a public repository.

Each key has a list of scopes, chosen when you create it. Every operation needs one scope (for example vouchers:redeem). A key without it gets 403 insufficient_scope.

A key always acts for the Space that created it. The API takes the Space from the key, never from the request. An object that belongs to another Space answers 404 not_found, exactly like an object that does not exist.

Your Space's plan must include the XQUARE API. If it does not, every call answers 403 plan_capability_missing.

Every response

• X-Request-Id is on every response. Quote it when you contact support.
• Errors have the same shape everywhere: { "error": { "code", "message", "request_id" } }. See Errors.
• RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset show your per-minute limit. See Rate limits.
• Every POST needs an Idempotency-Key header. See Retries and idempotency.

Guides

• Redeem a voucher from a POS
• Send sponsor redemptions to a CRM
• Check in tickets from a gate scanner
• Receive and verify webhooks
• Send orders from your store (inbound connections)
• Sandbox

Reference

• API reference (all operations, generated from the spec)
• Webhook events
• Retries and idempotency
• Errors
• Rate limits
• Changelog