Every request goes to the base URL with your store key in the Authorization header. Start with a test key and switch to the live one when your website is ready.
XEN public API for company websites: a store's catalog, cart, orders and payments, and a clinic's appointment booking and management. It authenticates with the store or company key (Authorization: Bearer pk_… | sk_…): the public one (pk_) from the browser and only from its origins; the secret one (sk_) only server to server. A test key also reads the store in draft.
Schemebearer. Store key created in XEN → Developers → API keys.
Public key (pk)
Goes in the browser and only answers the origins you registered for it.
Secret key (sk)
Server to server only. Never put it in code the browser downloads.
Scopes per key
Each key carries its own scopes. A route that needs one the key lacks answers 403.Scopes named in the reference: orders:read, payments:write, leads:create, clinic:read, appointments:create, appointments:manage, appointments:read, requests:create
Catalog
Parameters
Name
In
Type
Required
Description
lang
query
string
No
Catalog language; if the store does not have it, its main one.example "es"
Response 200
Field
Type
Description
datarequired
Store
name
string
slug
string
currency
string
languages
string[]
language
string
mode
string
Values: live, test
status
string
closed: the store was temporarily closed from XEN. The catalog can still be read, but quoting, creating an order and another payment attempt answer 409 store_closed.Values: open, closed
closure
object | null
Only with status: closed: the store's message in the requested language (it may be empty) and the reopening date, if the store set one. After that date the store opens again by itself.
message
string
reopensAt
string | null (date-time)
categories
object[]
slug
string
name
string
parent
string | null
order
integer
image
Images | null
Photo URL by size (longest side: xs 96, s 240, m 600, l 1200, xl 2048).
xs
string
s
string
m
string
l
string
xl
string
attributes
object[]
key
string
name
string
shipping
object
zones
object[]
id
string
name
string
regions
string[]
Ids from GET /v1/places.
fee
number
Amount in the store currency, with two decimals.
freeFrom
number | null
toQuote
boolean
Shipping to be quoted: the store sets it on each order.
With the same Idempotency-Key header it returns the order already created (without token). With gateway the order waits for its payment and next.url leads to the checkout of the store gateway (Wompi, Mercado Pago or Bold); on return, report the transaction with gateway-return.
Parameters
Name
In
Type
Required
Description
Idempotency-Key
header
string
No
minLength 8 · maxLength 100
Bodyrequired
Field
Type
Description
linesrequired
CartLine[]
maxItems 50
productrequired
string
Product slug.
quantityrequired
integer
min 1
options
object
{ optionId: valueId | [valueIds] }.
*
string | string[]
buyerrequired
object
namerequired
string
emailrequired
string
phone
string
In international format («+51 987654321») so the consent is tied to their WhatsApp.
document
object
type
string
number
string
consent
string[]
Codes from consentCategories the buyer checked themselves; they are stored on their contact with the order as proof. Unknown codes are ignored.maxItems 20
With email or phone (the newsletter needs an email). fields are the extra checkout fields the store defines (event date, guests…), without requiring the mandatory ones. With the same Idempotency-Key header it returns the one already created. Scope leads:create.
Scope clinic:read. It counts each professional's schedule, their appointments, live holds, blocks, the minimum notice (longer for new patients) and the horizon. It doesn't expose the chair.
Parameters
Name
In
Type
Required
Description
serviceId
query
string
Yes
locationId
query
string
Yes
professionalId
query
string
No
A professional or any.default "any"
from
query
string (date)
No
Local date of the location; today by default.
to
query
string (date)
No
Up to 13 days after from; 6 by default.
patientType
query
string
No
Values: new, existing
appointmentCode
query
string
No
When rescheduling: the code of the appointment being moved (with appointmentToken); its own slot counts as free.
appointmentToken
query
string
No
Response 200
Field
Type
Description
datarequired
object
timezone
string
days
object[]
date
string (date)
slots
ClinicSlot[]
slot
string
Opaque signed slot (expires in 30 minutes). Pass it as is to POST /v1/clinic/holds.
startsAt
string (date-time)
localStart
string
Local time of the location.example "2026-11-10T10:30"
Scope appointments:create. The hold lasts holdSeconds; if another booking won the slot, 409 slot_unavailable with up to 3 alternatives for the same patient type. The booking must use the patientType the hold was made with. The same Idempotency-Key of an expired hold answers 410. With too many live holds at the clinic, 429.
Parameters
Name
In
Type
Required
Description
Idempotency-Key
header
string
No
With the same key it returns what was already created (without token).minLength 8 · maxLength 100
Bodyrequired
Field
Type
Description
slotrequired
string
patientType
string
Values: new, existing
appointment
object
When rescheduling: the appointment being moved. Its own slot counts as free.
Scope appointments:create. It creates or reuses the patient by document without telling whether they existed, creates the appointment (instant → confirmed, request → requested), notifies the clinic, sends the email and the webhook. Per-phone write limit (429). 410 hold_expired if the hold expired.
Parameters
Name
In
Type
Required
Description
Idempotency-Key
header
string
No
With the same key it returns what was already created (without token).minLength 8 · maxLength 100
Bodyrequired
Field
Type
Description
hold
string
Hold id from POST /v1/clinic/holds (or send slot).
holdSecret
string
slot
string
Signed slot, without holding it first.
serviceId
string
If sent, it must match the slot.
locationId
string
professionalId
string
patientType
string
Values: new, existing
forWhom
string
Values: self, dependent
patientrequired
object
firstNamerequired
string
lastNamerequired
string
birthDaterequired
string (date)
Required. Someone under 18 (on the clinic's local date) books with forWhom: dependent.
documentrequired
object
typerequired
string
Values: DNI, CE, PAS, CC, TI, RC, OTRO
numberrequired
string
phone
string
email
string
guardian
object
Required with forWhom: dependent (minor or dependent person), with their name and document.
name
string
relation
string
phone
string
email
string
document
object
typerequired
string
Values: DNI, CE, PAS, CC, TI, RC, OTRO
numberrequired
string
reason
string
maxLength 500
channels
string[]
Where the confirmation and reminders go. Empty: none (only the on-screen confirmation). Without the field: email.
visitorIp
string
The visitor's IP: stored truncated with each accepted consent.
consents
object[]
The required ones from GET /v1/clinic must come accepted in their version.
code
string
version
string
accepted
boolean
attribution
object
source
string
landingPath
string
utm
object
*
string
referrer
string
Response 201
Field
Type
Description
datarequired
ClinicAppointmentCreated
code
string
token
string | null
Returned only once; with the same Idempotency-Key, null.
Scope requests:create. It returns the code (LR-…) and the answer deadline (15 business days), and sends the copy to the consumer's email with the provider's identification.
Parameters
Name
In
Type
Required
Description
Idempotency-Key
header
string
No
With the same key it returns what was already created (without token).minLength 8 · maxLength 100
Bodyrequired
Field
Type
Description
kindrequired
string
Values: reclamo, queja
replyChannel
string
Where the answer goes: email requires the email; letter, the address.Values: email, letterdefault "email"
XEN notifies your server with a signed POST whenever something changes in your store. Webhooks are created in XEN, under Developers, and each one receives the events you choose.
Signed in X-Xen-Signature: t=<seconds>,v1=<HMAC-SHA256 hex of "<t>.<body>"> with the webhook secret. Answer 2xx in under 5 s; otherwise XEN retries with growing waits for about 22 hours and pauses the webhook after 20 failures in a row.
{ order } shaped like GET /v1/orders/{code}, { store, product } or { promo }; the appointment ones and message.created, { code, status, startsAt, serviceId, professionalId, locationId } without clinical data.
Verify the signature
Split t and v1 from X-Xen-Signature, compute the HMAC-SHA256 of <t>.<body> with the webhook secret over the body exactly as it arrived, and compare it with v1 in constant time.
Every error answers with the same object, with a stable type for your code and a message for people.
Status
Meaning
400
The request is not valid (body, parameters, coupon or lines that cannot be sold).
401
The key is missing, invalid or expired.
403
Origin not allowed, secret key in the browser, insufficient scope or module turned off.
404
It does not exist in the key's store or company (in Clinic, also a code or token that doesn't match).
409
The store is temporarily closed (store_closed): the catalog can be read, but no quote, no new order and no new payment attempt. GET /v1/store has its message and reopening date.
429
The key's per-minute limit was exceeded (Retry-After: 60).
Each key has a limit of requests per minute. Past it, the API answers 429 and the Retry-After header says how many seconds to wait.
Orders without duplicates
Send the Idempotency-Key header on POST /orders. If you repeat the request with the same key, you get the order already created instead of a new one.minLength 8 · maxLength 100