API reference

Build on aperatif.ai

A REST API for connecting your POS, website and existing systems to your aperatif.ai ERP, CRM and loyalty platform.

Base URL

https://api.aperatif.ai/v1

Authentication

Authorization: Bearer <API_KEY>

Customers

POST/customers

Create a customer

Create a customer record shared across CRM, ERP invoicing and loyalty. Duplicate phone numbers or emails are merged automatically.

name string

Full name of the customer

phone string

Mobile number in international format

email string

Optional email address

branch_id string

Branch where the customer was registered

Request

curl -X POST https://api.aperatif.ai/v1/customers \
  -H "Authorization: Bearer $APERATIF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Sara Khan", "phone": "+971500000000"}'

Response

{
  "id": "cus_71kQ2",
  "name": "Sara Khan",
  "phone": "+971500000000",
  "loyalty": { "tier": "Silver", "points": 0 },
  "created_at": "2026-09-28T10:14:03Z"
}

GET/customers/{id}

Retrieve a customer

Fetch a customer with their CRM activity summary, lifetime value and loyalty status.

Request

curl https://api.aperatif.ai/v1/customers/cus_71kQ2 \
  -H "Authorization: Bearer $APERATIF_API_KEY"

Response

{
  "id": "cus_71kQ2",
  "name": "Sara Khan",
  "lifetime_value": 4820.5,
  "open_tickets": 0,
  "loyalty": { "tier": "Gold", "points": 12480 }
}

GET/customers

List customers

Returns a paginated list of customers. Filter by segment, tier or branch.

segment string

Only return customers in this segment

tier string

Loyalty tier name

limit integer

Page size, 1–100. Defaults to 20

Response

{
  "data": [ { "id": "cus_71kQ2", "name": "Sara Khan" } ],
  "has_more": false,
  "next_cursor": null
}

Orders & inventory

POST/orders

Create a sales order

Record a sale. Stock is deducted, the invoice is posted to finance and loyalty points are awarded in one step.

customer_id string

The customer placing the order

branch_id string

Branch or warehouse fulfilling the order

lines array

Products, quantities and unit prices

Request

{
  "customer_id": "cus_71kQ2",
  "branch_id": "br_marina",
  "lines": [ { "sku": "CF-250", "qty": 2, "price": 120 } ]
}

Response

{
  "id": "ord_5Xa1",
  "total": 252.0,
  "vat": 12.0,
  "points_awarded": 240,
  "status": "confirmed"
}

GET/inventory/{sku}

Get stock levels

Real-time stock for a product across every branch and warehouse.

Response

{
  "sku": "CF-250",
  "total": 1320,
  "locations": [
    { "branch_id": "br_marina", "on_hand": 140, "reorder_point": 100 }
  ]
}

Loyalty

POST/loyalty/transactions

Earn or redeem points

Award points for a purchase or redeem a reward. Earning rules and tier multipliers are applied automatically.

Request

{
  "customer_id": "cus_71kQ2",
  "type": "earn",
  "amount": 240
}

Response

{
  "id": "ltx_8Pm2",
  "points": 360,
  "multiplier": 1.5,
  "balance": 12840
}

Webhooks

POST/webhooks

Create a webhook

Subscribe an HTTPS endpoint to platform events. Payloads are signed with an HMAC-SHA256 secret.

Request

{
  "url": "https://example.com/hooks/aperatif",
  "events": ["order.created", "loyalty.tier_changed"]
}

Response

{
  "id": "whk_2mZ8",
  "secret": "whsec_…",
  "events": ["order.created", "loyalty.tier_changed"]
}

CRM

PATCH/deals/{id}

Update a deal

Move a deal to a new pipeline stage, change its value or reassign its owner.

Request

{
  "stage": "won",
  "value": 18500
}

Response

{
  "id": "deal_3Qe",
  "stage": "won",
  "updated_at": "2026-09-28T10:20:11Z"
}