The REST API lets your own systems work with your workspace: sync contacts with a CRM, send events from your shop, reply to customers from another tool, or close conversations automatically.

Base URL: https://app.shopxare.com/api/v1
Format: JSON in, JSON out. Times are ISO 8601 in UTC.
Machine-readable reference: /api/v1/openapi.json (OpenAPI 3.1, import it into Postman, Insomnia or a code generator).

Tokens

Create a token in Settings → API (owners and admins, or anyone whose role has the developer permission). You confirm your password, choose a name, the scopes and an expiry, and see the token once — copy it then; we only keep a hash.

Send it in every request:

curl https://app.shopxare.com/api/v1/me \
  -H "Authorization: Bearer sxa_…"

A token acts as the teammate who created it. It can never do more than that teammate's role allows, and it stops working when that teammate leaves the workspace or is deactivated. Revoke a token at any time in the same place.

Scope	Allows
`conversations:read`	list conversations, read messages
`conversations:write`	reply, add notes, close, snooze, assign, prioritise, tag
`contacts:read`	list and look up contacts, read their events
`contacts:write`	create, update and delete contacts, track events
`workspace:read`	list teammates, teams and tags

Endpoints

Method	Path	Scope
GET	`/me`	any
GET	`/conversations`	conversations:read
GET	`/conversations/{id}`	conversations:read
PATCH	`/conversations/{id}`	conversations:write
GET	`/conversations/{id}/messages`	conversations:read
POST	`/conversations/{id}/messages`	conversations:write
POST	`/conversations/{id}/tags`	conversations:write
GET, POST	`/contacts`	contacts:read / contacts:write
GET, PATCH, DELETE	`/contacts/{id}`	contacts:read / contacts:write
GET, POST	`/contacts/{id}/events`	contacts:read / contacts:write
GET	`/teammates`, `/teams`, `/tags`	workspace:read

Reply to a customer

curl -X POST https://app.shopxare.com/api/v1/conversations/01K7…/messages \
  -H "Authorization: Bearer sxa_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-shipped" \
  -d '{"body": "Your order has shipped 📦"}'

The reply reaches the customer on the conversation's channel — Messenger, email or Telegram — exactly like a reply from the inbox. Use "type": "note" for an internal note. With the same Idempotency-Key a retried request returns the first message (status 200 instead of 201) instead of sending twice.

Close or assign

curl -X PATCH https://app.shopxare.com/api/v1/conversations/01K7… \
  -H "Authorization: Bearer sxa_…" -H "Content-Type: application/json" \
  -d '{"status": "closed"}'

assignee_id (a teammate id from /teammates, or null), team_id, priority (normal, high) and status (open, snoozed with snoozed_until, closed) can be changed. Every change shows up in the conversation like it does in the inbox, and workflows run as usual.

Create or update a contact

curl -X POST https://app.shopxare.com/api/v1/contacts \
  -H "Authorization: Bearer sxa_…" -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "name": "Lena", "external_id": "user-7", "attributes": {"plan": "pro"}}'

Look someone up with GET /contacts?email=… or ?external_id=…. On PATCH, only the fields you send change; attributes are merged, and a key set to null is removed. The external_id is the same user id you pass to the Messenger with identity verification, so API and Messenger see the same person.

Track an event

curl -X POST https://app.shopxare.com/api/v1/contacts/01K7…/events \
  -H "Authorization: Bearer sxa_…" -H "Content-Type: application/json" \
  -d '{"name": "order_placed", "meta": {"order_id": "A-1042", "total": 59.9}}'

The same as Shopxare('trackEvent', …) in the JavaScript API, but from your server.

Pagination

Lists return {"object": "list", "data": [...], "next_cursor": "…"}, newest first. Pass next_cursor back as cursor until it is null. limit is 1–100 (default 25). To sync changes, filter with updated_since.

Messages are listed oldest first: pass the last id you received as after_id while has_more is true.

Errors

Errors always have the same shape:

{ "error": { "code": "validation_failed", "message": "…", "fields": { "email": ["…"] } } }

Status	Code	Meaning
401	`unauthorized`	missing, wrong, expired or revoked token
402	`limit_reached`	a package limit is reached (e.g. number of contacts)
403	`insufficient_scope`, `forbidden`, `feature_unavailable`	the token lacks the scope, its teammate the permission, or the package the API
404	`not_found`	no such object in this workspace
422	`validation_failed`, `invalid_request`	the input is wrong; see `fields`
429	`rate_limited`	too many requests; wait `Retry-After` seconds

Rate limits

Requests are counted per token per minute; the limit comes from your package and is shown in Settings → API. Every response carries X-RateLimit-Limit and X-RateLimit-Remaining.

Getting told about changes

The API is for asking and changing. To be told when something happens — a new conversation, a reply, a closed ticket — use webhooks.