Developers

XEN API

Your website reads the catalog, quotes the cart and creates orders in XEN.

Get started

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.

Base URL
https://api.xeneural.com/v1
Version
1.0.0
curl https://api.xeneural.com/v1/products \
  -H "Authorization: Bearer pk_test_…"

Authentication

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.

Scheme bearer. 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

NameInTypeRequiredDescription
langquerystringNoCatalog language; if the store does not have it, its main one.example "es"

Response 200

FieldTypeDescription
datarequiredStore
namestring
slugstring
currencystring
languagesstring[]
languagestring
modestringValues: live, test
statusstringclosed: 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
closureobject | nullOnly 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.
messagestring
reopensAtstring | null (date-time)
categoriesobject[]
slugstring
namestring
parentstring | null
orderinteger
imageImages | nullPhoto URL by size (longest side: xs 96, s 240, m 600, l 1200, xl 2048).
xsstring
sstring
mstring
lstring
xlstring
attributesobject[]
keystring
namestring
shippingobject
zonesobject[]
idstring
namestring
regionsstring[]Ids from GET /v1/places.
feenumberAmount in the store currency, with two decimals.
freeFromnumber | null
toQuotebooleanShipping to be quoted: the store sets it on each order.
pickupobject[]
idstring
namestring
addressstring
paymentMethodsstring[]
checkoutFieldsobject[]
idstring
labelstring
typestringValues: text, textarea, number, date, bool, select
requiredboolean
stockobject
showQuantityboolean
bannersobject[]
idstring
textstring
imagestring | null
urlstring | null
couponstring | null
kindstring
consentCategoriesobject[]WhatsApp message categories the buyer can accept at checkout (unchecked boxes). Empty if the company doesn't use Conversations.
codestring
namestring

Errors: 401 403 429

Parameters

NameInTypeRequiredDescription
langquerystringNoCatalog language; if the store does not have it, its main one.example "es"
categoryquerystringNo
qquerystringNo
price_minquerystringNo
price_maxquerystringNo
expandquerystringNoWith options each product comes with its full page (description, bullets and options).Values: options
preorderquerybooleanNo
salequerybooleanNo
featuredquerybooleanNo
sortquerystringNoValues: default, price_asc, price_desc, newest, name
pagequeryintegerNomin 1
limitqueryintegerNomin 1 · max 100

Response 200

FieldTypeDescription
dataProduct | ProductDetail[]
pageinteger
limitinteger
totalinteger
hasMoreboolean

Errors: 400 401 403 429

Parameters

NameInTypeRequiredDescription
slugpathstringYes
langquerystringNoCatalog language; if the store does not have it, its main one.example "es"

Response 200

FieldTypeDescription
datarequiredProductDetail
slugstring
namestring
skustring | null
imagesImages[]
xsstring
sstring
mstring
lstring
xlstring
priceobject
amountnumberAmount in the store currency, with two decimals.
compareAtnumber | null
currencystring
onSaleboolean
unitstringValues: unit, person
mininteger
categoriesstring[]
tagsstring[]
attributesobject
preorderobject
enabledboolean
depositnumber | null
featuredboolean
availabilityAvailability
statusstringValues: in, limited, out
quantityintegerOnly if the store publishes quantities.
publishedAtstring | null (date-time)
descriptionstring
bulletsstring[]
optionsobject[]
idstring
namestring
kindstringValues: variant, addon
requiredboolean
minintegerHow many values must be chosen at least (0 = optional; equal to max = exactly that many).
maxinteger
whenobject | nullConditional option: shown, and counted, only if one of values was chosen in option option.
optionstring
valuesstring[]
valuesobject[]
idstring
namestring
priceDeltanumberAmount in the store currency, with two decimals.
skustring | null
availabilityAvailability
statusstringValues: in, limited, out
quantityintegerOnly if the store publishes quantities.
seoobject
titlestring
descriptionstring

Errors: 401 403 404 429

Parameters

NameInTypeRequiredDescription
parentquerystringNoexample "state:CO-DC"

Response 200

FieldTypeDescription
datarequiredobject[]
idstring
namestring

Errors: 400 401 403 429

Cart and orders

Bodyrequired

FieldTypeDescription
linesrequiredCartLine[]maxItems 50
productrequiredstringProduct slug.
quantityrequiredintegermin 1
optionsobject{ optionId: valueId | [valueIds] }.
*string | string[]
shippingShipping
methodrequiredstringValues: ship, pickup
statestringState or department (GET /v1/places).
citystringCity of that state (GET /v1/places?parent=).
pickupIdstring
couponstring
emailstringFor the coupon's per-buyer usage limit.
langstring

Response 200

FieldTypeDescription
datarequiredQuote
linesobject[]
productstring
namestring
skustring | null
imageImages | nullPhoto URL by size (longest side: xs 96, s 240, m 600, l 1200, xl 2048).
xsstring
sstring
mstring
lstring
xlstring
optionsobject[]
quantityinteger
unitPricenumber | null
totalnumberAmount in the store currency, with two decimals.
availabilityAvailability
statusstringValues: in, limited, out
quantityintegerOnly if the store publishes quantities.
issuestring | nullValues: null, not_found, no_price, option_required, option_invalid, min_quantity, out_of_stock, insufficient_stock, zone_not_covered, pickup_not_found, region_required, method_not_allowed, coupon_not_found, coupon_not_for_store, coupon_not_started, coupon_expired, coupon_exhausted, coupon_buyer_limit, coupon_min_subtotal, coupon_not_applicable
subtotalnumberAmount in the store currency, with two decimals.
discountnumberAmount in the store currency, with two decimals.
promotionobject | null
namestring
kindstring
couponstring | null
amountnumberAmount in the store currency, with two decimals.
freeShippingobject | null
namestring
couponstring | null
couponobject | null
codestring
issuestring | nullValues: null, not_found, no_price, option_required, option_invalid, min_quantity, out_of_stock, insufficient_stock, zone_not_covered, pickup_not_found, region_required, method_not_allowed, coupon_not_found, coupon_not_for_store, coupon_not_started, coupon_expired, coupon_exhausted, coupon_buyer_limit, coupon_min_subtotal, coupon_not_applicable
shippingobject
feenumberAmount in the store currency, with two decimals.
zoneobject | null
idstring
namestring
freeboolean
toQuotebooleanThe total goes without shipping: the store quotes it later (it can't be paid online yet).
issuestring | nullValues: null, not_found, no_price, option_required, option_invalid, min_quantity, out_of_stock, insufficient_stock, zone_not_covered, pickup_not_found, region_required, method_not_allowed, coupon_not_found, coupon_not_for_store, coupon_not_started, coupon_expired, coupon_exhausted, coupon_buyer_limit, coupon_min_subtotal, coupon_not_applicable
totalnumberAmount in the store currency, with two decimals.
currencystring
issuesobject[]If there is any, POST /v1/orders answers 400.
lineinteger | null
codestring | nullValues: null, not_found, no_price, option_required, option_invalid, min_quantity, out_of_stock, insufficient_stock, zone_not_covered, pickup_not_found, region_required, method_not_allowed, coupon_not_found, coupon_not_for_store, coupon_not_started, coupon_expired, coupon_exhausted, coupon_buyer_limit, coupon_min_subtotal, coupon_not_applicable

Errors: 400 401 403 409 429

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

NameInTypeRequiredDescription
Idempotency-KeyheaderstringNominLength 8 · maxLength 100

Bodyrequired

FieldTypeDescription
linesrequiredCartLine[]maxItems 50
productrequiredstringProduct slug.
quantityrequiredintegermin 1
optionsobject{ optionId: valueId | [valueIds] }.
*string | string[]
buyerrequiredobject
namerequiredstring
emailrequiredstring
phonestringIn international format («+51 987654321») so the consent is tied to their WhatsApp.
documentobject
typestring
numberstring
consentstring[]Codes from consentCategories the buyer checked themselves; they are stored on their contact with the order as proof. Unknown codes are ignored.maxItems 20
shippingrequiredobject
methodrequiredstringValues: ship, pickup
pickupIdstring
addressobject
linestring
statestring
citystring
zipstring
notesstring
paymentrequiredobject
methodrequiredstringValues: preorder, cod, external, gateway
returnUrlstringWith gateway: where the buyer returns to (https).
fieldsobjectExtra checkout fields by id.
couponstring
notestring
langstring

Response 201

FieldTypeDescription
datarequiredobject
codestring
tokenstring | nullShown only once.
statusstring
totalnumberAmount in the store currency, with two decimals.
currencystring
nextNextStepWhat the website does after creating the order.
typestringValues: confirmation, cash_on_delivery, external_payment, redirect
urlstringWith redirect: the gateway checkout.
providerstringValues: wompi, mercadopago, bold
referencestring
amountnumberAmount in the store currency, with two decimals.
currencystring

Errors: 400 401 403 409 429

Parameters

NameInTypeRequiredDescription
codepathstringYesOrder code.example "OBL-000123"
tokenquerystringNoBuyer token returned by POST /v1/orders (with the public key).

Response 200

FieldTypeDescription
datarequiredOrder
codestring
statusstringValues: new, pending_payment, paid, confirmed, preparing, ready, shipped, delivered, cancelled, refunded
modestringValues: live, test
createdAtstring (date-time)
buyerobject
namestring
emailstring
linesobject[]
namestring
skustring | null
optionsobject[]
quantityinteger
unitPricenumberAmount in the store currency, with two decimals.
totalnumberAmount in the store currency, with two decimals.
shippingobject
methodstring
zoneobject | null
pickupobject | null
feenumberAmount in the store currency, with two decimals.
toQuoteboolean
totalsobject
subtotalnumberAmount in the store currency, with two decimals.
discountnumberAmount in the store currency, with two decimals.
shippingnumberAmount in the store currency, with two decimals.
taxnumberAmount in the store currency, with two decimals.
totalnumberAmount in the store currency, with two decimals.
currencystring
couponstring | null
paymentobject
methodstring
statusstringValues: unpaid, partial, paid, refunded
timelineobject[]
statusstring
atstring (date-time)

Errors: 401 403 404 429

Payments

Parameters

NameInTypeRequiredDescription
codepathstringYesOrder code.example "OBL-000123"

Body

FieldTypeDescription
tokenstringBuyer token returned by POST /v1/orders (with the public key).
returnUrlstring

Response 200

FieldTypeDescription
datarequiredobject
codestring
nextNextStepWhat the website does after creating the order.
typestringValues: confirmation, cash_on_delivery, external_payment, redirect
urlstringWith redirect: the gateway checkout.
providerstringValues: wompi, mercadopago, bold
referencestring
amountnumberAmount in the store currency, with two decimals.
currencystring

Errors: 400 401 403 404 409 429

Parameters

NameInTypeRequiredDescription
codepathstringYesOrder code.example "OBL-000123"

Bodyrequired

FieldTypeDescription
tokenstringBuyer token returned by POST /v1/orders (with the public key).
transactionIdrequiredstringThe id Wompi adds, or the payment_id Mercado Pago adds, to the return URL. With Bold it may be empty: XEN looks the payment up by the order.

Response 200

FieldTypeDescription
datarequiredOrder
codestring
statusstringValues: new, pending_payment, paid, confirmed, preparing, ready, shipped, delivered, cancelled, refunded
modestringValues: live, test
createdAtstring (date-time)
buyerobject
namestring
emailstring
linesobject[]
namestring
skustring | null
optionsobject[]
quantityinteger
unitPricenumberAmount in the store currency, with two decimals.
totalnumberAmount in the store currency, with two decimals.
shippingobject
methodstring
zoneobject | null
pickupobject | null
feenumberAmount in the store currency, with two decimals.
toQuoteboolean
totalsobject
subtotalnumberAmount in the store currency, with two decimals.
discountnumberAmount in the store currency, with two decimals.
shippingnumberAmount in the store currency, with two decimals.
taxnumberAmount in the store currency, with two decimals.
totalnumberAmount in the store currency, with two decimals.
currencystring
couponstring | null
paymentobject
methodstring
statusstringValues: unpaid, partial, paid, refunded
timelineobject[]
statusstring
atstring (date-time)

Errors: 400 401 403 404 429

Parameters

NameInTypeRequiredDescription
codepathstringYesOrder code.example "OBL-000123"

Bodyrequired

FieldTypeDescription
amountrequirednumberAmount in the store currency, with two decimals.
referencerequiredstring
methodstringHow it was collected, for the history.

Response 200

FieldTypeDescription
datarequiredOrder
codestring
statusstringValues: new, pending_payment, paid, confirmed, preparing, ready, shipped, delivered, cancelled, refunded
modestringValues: live, test
createdAtstring (date-time)
buyerobject
namestring
emailstring
linesobject[]
namestring
skustring | null
optionsobject[]
quantityinteger
unitPricenumberAmount in the store currency, with two decimals.
totalnumberAmount in the store currency, with two decimals.
shippingobject
methodstring
zoneobject | null
pickupobject | null
feenumberAmount in the store currency, with two decimals.
toQuoteboolean
totalsobject
subtotalnumberAmount in the store currency, with two decimals.
discountnumberAmount in the store currency, with two decimals.
shippingnumberAmount in the store currency, with two decimals.
taxnumberAmount in the store currency, with two decimals.
totalnumberAmount in the store currency, with two decimals.
currencystring
couponstring | null
paymentobject
methodstring
statusstringValues: unpaid, partial, paid, refunded
timelineobject[]
statusstring
atstring (date-time)

Errors: 400 401 403 404 429

Leads

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.

Parameters

NameInTypeRequiredDescription
Idempotency-KeyheaderstringNominLength 8 · maxLength 100

Bodyrequired

FieldTypeDescription
typerequiredstringValues: contact, quote, newsletter
namestring
emailstring
phonestring
messagestringmaxLength 2000
fieldsobjectExtra checkout fields by id.
consentbooleanAgreed to be contacted by the store.
langstring

Response 201

FieldTypeDescription
datarequiredobject
idstring
statusstringValues: new, contacted, closed

Errors: 400 401 403 429

Clinic

Scope clinic:read. With a live key, the clinic must have online booking published.

Response 200

FieldTypeDescription
datarequiredClinicProfile
namestring
countrystringValues: PE, CO
phonestring
whatsappstring
emailstring
licenseobject | null
labelstringexample "COP"
verifyUrlstring
locationsobject[]
idstring
namestring
addressstring
referencestring
geoobject | null
latnumber
lngnumber
timezonestringexample "America/Lima"
hoursobject[]
dayOfWeekintegermin 0 · max 6
opensstringexample "09:00"
closesstringexample "20:00"
servicesobject[]
idstring
codestring
namestring
descriptionstring
categorystring | null
durationMininteger
modestringinstant confirms on booking; request waits for the clinic to confirm.Values: instant, request
patientTypesstring[]
prepstring
professionalsobject[]
idstring
titlestring
namestring
specialtystring
licenseobject | null
typestring | null
numberstring
rnestring | nullNational Specialist Registry number, if any.
biostring
photoUrlstring | null
acceptsNewboolean
serviceIdsstring[]Published services they see patients for: their own list and the service's, as availability uses.
policiesobject
gridMininteger
minNoticeMininteger
minNoticeNewMininteger
maxDaysAheadinteger
holdSecondsinteger
cancelUntilHoursinteger
consentsobject[]
codestring
versionstring
requiredboolean
textstring

Errors: 401 403 429

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

NameInTypeRequiredDescription
serviceIdquerystringYes
locationIdquerystringYes
professionalIdquerystringNoA professional or any.default "any"
fromquerystring (date)NoLocal date of the location; today by default.
toquerystring (date)NoUp to 13 days after from; 6 by default.
patientTypequerystringNoValues: new, existing
appointmentCodequerystringNoWhen rescheduling: the code of the appointment being moved (with appointmentToken); its own slot counts as free.
appointmentTokenquerystringNo

Response 200

FieldTypeDescription
datarequiredobject
timezonestring
daysobject[]
datestring (date)
slotsClinicSlot[]
slotstringOpaque signed slot (expires in 30 minutes). Pass it as is to POST /v1/clinic/holds.
startsAtstring (date-time)
localStartstringLocal time of the location.example "2026-11-10T10:30"
durationMininteger
professionalobject
idstring
namestring
nextAvailableDatestring | null (date)

Errors: 400 401 403 404 429

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

NameInTypeRequiredDescription
Idempotency-KeyheaderstringNoWith the same key it returns what was already created (without token).minLength 8 · maxLength 100

Bodyrequired

FieldTypeDescription
slotrequiredstring
patientTypestringValues: new, existing
appointmentobjectWhen rescheduling: the appointment being moved. Its own slot counts as free.
codestring
tokenstring

Response 201

FieldTypeDescription
datarequiredobject
holdstring
holdSecretstringShown only once.
expiresAtstring (date-time)

Errors: 400 401 403 404 409 429

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

NameInTypeRequiredDescription
Idempotency-KeyheaderstringNoWith the same key it returns what was already created (without token).minLength 8 · maxLength 100

Bodyrequired

FieldTypeDescription
holdstringHold id from POST /v1/clinic/holds (or send slot).
holdSecretstring
slotstringSigned slot, without holding it first.
serviceIdstringIf sent, it must match the slot.
locationIdstring
professionalIdstring
patientTypestringValues: new, existing
forWhomstringValues: self, dependent
patientrequiredobject
firstNamerequiredstring
lastNamerequiredstring
birthDaterequiredstring (date)Required. Someone under 18 (on the clinic's local date) books with forWhom: dependent.
documentrequiredobject
typerequiredstringValues: DNI, CE, PAS, CC, TI, RC, OTRO
numberrequiredstring
phonestring
emailstring
guardianobjectRequired with forWhom: dependent (minor or dependent person), with their name and document.
namestring
relationstring
phonestring
emailstring
documentobject
typerequiredstringValues: DNI, CE, PAS, CC, TI, RC, OTRO
numberrequiredstring
reasonstringmaxLength 500
channelsstring[]Where the confirmation and reminders go. Empty: none (only the on-screen confirmation). Without the field: email.
visitorIpstringThe visitor's IP: stored truncated with each accepted consent.
consentsobject[]The required ones from GET /v1/clinic must come accepted in their version.
codestring
versionstring
acceptedboolean
attributionobject
sourcestring
landingPathstring
utmobject
*string
referrerstring

Response 201

FieldTypeDescription
datarequiredClinicAppointmentCreated
codestring
tokenstring | nullReturned only once; with the same Idempotency-Key, null.
statusstringValues: requested, confirmed
startsAtstring (date-time)
localStartstring
timezonestring
serviceobject
idstring
namestring
professionalobject
idstring
namestring
locationobject
idstring
namestring
addressstring
manageUntilstring (date-time)Until when the website can cancel or reschedule.

Errors: 400 401 403 404 409 410 429

Scope appointments:manage with the token. With a secret key and appointments:read, without token. Code or token that don't match: 404.

Parameters

NameInTypeRequiredDescription
codepathstringYesAppointment code.example "CT-000123"
tokenquerystringNo“My appointment” token returned by the booking (it also goes in the emails). Never in the path.

Response 200

FieldTypeDescription
datarequiredClinicAppointment
codestring
statusstringValues: requested, confirmed, arrived, in_chair, completed, no_show, cancelled, rescheduled
confirmationstringValues: none, sent, confirmed, declined
startsAtstring (date-time)
localStartstring
timezonestring
durationMininteger
serviceobject
idstring
namestring
professionalobject
idstring
titlestring
namestring
locationobject
idstring
namestring
addressstring
canConfirmboolean
canCancelboolean
canRescheduleboolean
manageUntilstring (date-time)
latebooleanSomeone tried to cancel or reschedule inside the window.
prepstring
rescheduledTostring | nullCode of the new appointment if it was rescheduled.

Errors: 401 403 404 429

Scope appointments:manage.

Parameters

NameInTypeRequiredDescription
codepathstringYesAppointment code.example "CT-000123"

Bodyrequired

FieldTypeDescription
tokenrequiredstring“My appointment” token returned by the booking (it also goes in the emails). Never in the path.

Response 200

FieldTypeDescription
datarequiredClinicAppointment
codestring
statusstringValues: requested, confirmed, arrived, in_chair, completed, no_show, cancelled, rescheduled
confirmationstringValues: none, sent, confirmed, declined
startsAtstring (date-time)
localStartstring
timezonestring
durationMininteger
serviceobject
idstring
namestring
professionalobject
idstring
titlestring
namestring
locationobject
idstring
namestring
addressstring
canConfirmboolean
canCancelboolean
canRescheduleboolean
manageUntilstring (date-time)
latebooleanSomeone tried to cancel or reschedule inside the window.
prepstring
rescheduledTostring | nullCode of the new appointment if it was rescheduled.

Errors: 400 401 403 404 409 429

Scope appointments:manage. Inside the window it answers 409 policy_violation and the appointment is marked late.

Parameters

NameInTypeRequiredDescription
codepathstringYesAppointment code.example "CT-000123"

Bodyrequired

FieldTypeDescription
tokenrequiredstring“My appointment” token returned by the booking (it also goes in the emails). Never in the path.
reasonstringmaxLength 300

Response 200

FieldTypeDescription
datarequiredClinicAppointment
codestring
statusstringValues: requested, confirmed, arrived, in_chair, completed, no_show, cancelled, rescheduled
confirmationstringValues: none, sent, confirmed, declined
startsAtstring (date-time)
localStartstring
timezonestring
durationMininteger
serviceobject
idstring
namestring
professionalobject
idstring
titlestring
namestring
locationobject
idstring
namestring
addressstring
canConfirmboolean
canCancelboolean
canRescheduleboolean
manageUntilstring (date-time)
latebooleanSomeone tried to cancel or reschedule inside the window.
prepstring
rescheduledTostring | nullCode of the new appointment if it was rescheduled.

Errors: 400 401 403 404 409 429

Scope appointments:manage. It returns the new code and its token; the previous link no longer manages it.

Parameters

NameInTypeRequiredDescription
codepathstringYesAppointment code.example "CT-000123"
Idempotency-KeyheaderstringNoWith the same key it returns what was already created (without token).minLength 8 · maxLength 100

Bodyrequired

FieldTypeDescription
tokenrequiredstring“My appointment” token returned by the booking (it also goes in the emails). Never in the path.
holdrequiredstring
holdSecretrequiredstring

Response 201

FieldTypeDescription
datarequiredClinicAppointmentCreated
codestring
tokenstring | nullReturned only once; with the same Idempotency-Key, null.
statusstringValues: requested, confirmed
startsAtstring (date-time)
localStartstring
timezonestring
serviceobject
idstring
namestring
professionalobject
idstring
namestring
locationobject
idstring
namestring
addressstring
manageUntilstring (date-time)Until when the website can cancel or reschedule.

Errors: 400 401 403 404 409 410 429

Scope appointments:manage. It marks the clinic's messages as read.

Parameters

NameInTypeRequiredDescription
codepathstringYesAppointment code.example "CT-000123"
tokenquerystringYes“My appointment” token returned by the booking (it also goes in the emails). Never in the path.

Response 200

FieldTypeDescription
datarequiredClinicMessage[]
idstring
directionstringValues: patient, clinic
textstring
sentAtstring (date-time)
readboolean

Errors: 401 403 404 429

Scope appointments:manage. The clinic sees it in XEN (Clinic, Messages) and gets a bell notification.

Parameters

NameInTypeRequiredDescription
codepathstringYesAppointment code.example "CT-000123"
Idempotency-KeyheaderstringNoWith the same key it returns what was already created (without token).minLength 8 · maxLength 100

Bodyrequired

FieldTypeDescription
tokenrequiredstring“My appointment” token returned by the booking (it also goes in the emails). Never in the path.
textrequiredstringmaxLength 2000

Response 201

FieldTypeDescription
datarequiredClinicMessage
idstring
directionstringValues: patient, clinic
textstring
sentAtstring (date-time)
readboolean

Errors: 400 401 403 404 429

Scope appointments:manage. One per appointment; it can be corrected until the clinic imports it into the record.

Parameters

NameInTypeRequiredDescription
codepathstringYesAppointment code.example "CT-000123"

Bodyrequired

FieldTypeDescription
tokenrequiredstring“My appointment” token returned by the booking (it also goes in the emails). Never in the path.
answersrequiredobjectReason, medical history, allergies, medication, pregnancy, habits, anxiety (1 to 5).

Response 201

FieldTypeDescription
datarequiredobject
idstring
receivedAtstring (date-time)

Errors: 400 401 403 404 409 429

Scope requests:create. With phone or email; per-phone limit (429).

Parameters

NameInTypeRequiredDescription
Idempotency-KeyheaderstringNoWith the same key it returns what was already created (without token).minLength 8 · maxLength 100

Bodyrequired

FieldTypeDescription
kindrequiredstringValues: contact, callback, urgent, waitlist, arco, job
namestring
phonestring
emailstring
messagestringmaxLength 4000
preferencesobject
attributionobject

Response 201

FieldTypeDescription
datarequiredobject
idstring
statusstringValues: new, contacted, closed

Errors: 400 401 403 429

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

NameInTypeRequiredDescription
Idempotency-KeyheaderstringNoWith the same key it returns what was already created (without token).minLength 8 · maxLength 100

Bodyrequired

FieldTypeDescription
kindrequiredstringValues: reclamo, queja
replyChannelstringWhere the answer goes: email requires the email; letter, the address.Values: email, letterdefault "email"
consumerrequiredobject
namerequiredstring
documentobject
typestring
numberstring
addressstring
phonestring
emailstring
guardianstringParent or guardian if a minor.
serviceobject
descriptionstring
amountnumber
currencystring
detailrequiredstringmaxLength 4000
requeststringmaxLength 2000

Response 201

FieldTypeDescription
datarequiredobject
codestringexample "LR-000015"
dueAtstring (date-time)
createdAtstring (date-time)

Errors: 400 401 403 429

Webhooks

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.

Events

  • order.createdorder.created notice
  • order.updatedorder.updated notice
  • catalog.updatedcatalog.updated notice
  • promo.updatedpromo.updated notice
  • appointment.createdappointment.created notice
  • appointment.updatedappointment.updated notice
  • appointment.confirmedappointment.confirmed notice
  • appointment.cancelledappointment.cancelled notice
  • appointment.rescheduledappointment.rescheduled notice
  • appointment.completedappointment.completed notice
  • appointment.no_showappointment.no_show notice
  • message.createdmessage.created notice

Headers

NameInTypeRequiredDescription
X-Xen-EventheaderstringYes
X-Xen-DeliveryheaderstringYes
X-Xen-SignatureheaderstringYes

Notification body

FieldTypeDescription
idstringDelivery id (also in X-Xen-Delivery).
typestringValues: order.created, order.updated, catalog.updated, promo.updated, appointment.created, appointment.updated, appointment.confirmed, appointment.cancelled, appointment.rescheduled, appointment.completed, appointment.no_show, message.created, ping
createdstring (date-time)
modestring | nullValues: live, test, null
dataobject{ 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.

import crypto from "node:crypto";

const verifyXenSignature = (header, rawBody, secret) => {
  const parts = Object.fromEntries(header.split(",").map((part) => part.split("=")));
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");
  const received = String(parts.v1 || "");
  return (
    received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected))
  );
};

Errors and limits

Every error answers with the same object, with a stable type for your code and a message for people.

StatusMeaning
400The request is not valid (body, parameters, coupon or lines that cannot be sold).
401The key is missing, invalid or expired.
403Origin not allowed, secret key in the browser, insufficient scope or module turned off.
404It does not exist in the key's store or company (in Clinic, also a code or token that doesn't match).
409The 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.
429The key's per-minute limit was exceeded (Retry-After: 60).

Error shape

FieldTypeDescription
errorobject
typestringValues: missing_api_key, invalid_api_key, expired_api_key, origin_not_allowed, secret_key_in_browser, insufficient_scope, rate_limited, module_inactive, not_found, invalid_request, forbidden, internal_error, slot_unavailable, hold_expired, policy_violation, store_closed
messagestring

Error types

  • missing_api_key
  • invalid_api_key
  • expired_api_key
  • origin_not_allowed
  • secret_key_in_browser
  • insufficient_scope
  • rate_limited
  • module_inactive
  • not_found
  • invalid_request
  • forbidden
  • internal_error
  • slot_unavailable
  • hold_expired
  • policy_violation
  • store_closed

Per-minute limit

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