DrippleX API

Everything below needs one thing first: an integration and its key. You create both from your DrippleX merchant account — nobody has to provision them for you.

1. Sign in to your DrippleX merchant account.
2. Create an integration. DrippleX returns an integration id and an API key.
3. Copy the key. It is shown once and stored hashed — we cannot show it to you again, only replace it.
4. Send both on every request, as the two headers below.

Lost the key, or think someone else has it? Rotate it. The old key stops working immediately.

Two headers, on every request. There is no bearer token and no OAuth flow — the key authenticates, and the integration id says which of your integrations it belongs to.

curl https://api.dripplex.com/api/v1/integrations/orders/list \
  -H "x-integration-id: YOUR_INTEGRATION_ID" \
  -H "x-integration-key: YOUR_API_KEY"

Keep the key server-side. It is not safe in a browser, a mobile app or anything a customer can read.

A key carries scopes, and each endpoint requires one. A key without the scope is refused with 403 — distinct from 401, which means the key itself did not authenticate.

Your credential is also issued catalog:read and inventory:read, which no endpoint reads today. Reading back what DrippleX imported is done by a signed-in merchant, not by a key. We would rather say so here than have you discover it against a 401.

All paths are relative to https://api.dripplex.com/api/v1.

Two different credentials appear below, and they are not interchangeable. The endpoints your POS calls unattended authenticate with the integration key. The rest — category mappings, sync history, imported products, stock levels and conflicts — are things a person decides, so they authenticate a merchant signed in to DrippleX and are normally used from the merchant portal rather than from your POS. Sending an integration key to one of those returns 401.

DrippleX will not invent a category for you. Your POS sends its own category name on each item — categoryName — and DrippleX resolves it through a mapping the merchant controls. Until a name is mapped, products carrying it import uncategorised and each one raises a CATEGORY_UNMAPPED conflict. The sync still succeeds and no item is lost; the products simply will not sit anywhere a customer browses.

So map your categories first. It is three steps, and it is done once — a mapping stays in force for every later sync.

1. Get the DrippleX categories and their ids. This route is public, so you can call it before anything else exists:

GET https://api.dripplex.com/api/v1/categories

2. For each category name your POS sends, point it at one DrippleX category. Signed in as the merchant:

PUT https://api.dripplex.com/api/v1/integrations/catalogue/mappings/{integrationId}
Authorization: Bearer <merchant session token>
Content-Type: application/json

{
  "externalCategoryName": "Pastries",
  "categoryId": "305c2d0d-00e5-4f43-935d-c5852c885300"
}

Several of your categories may point at the same DrippleX one — a bakery mapping Cakes, Pastries and Cookies all to Restaurants & Food is normal and correct. A pharmacy would instead map OTC Medicines to Pharmacy & Health and Baby Care to Baby, Kids & Toys. The mapping describes your shop, not a fixed list.

The name is matched exactly as your POS spells it, including case and spacing. Pastries and pastries are two different mappings. Normalising them here would silently stop matching what your POS actually sends.

3. Sync your catalogue. Products now land in the right category, and GET /integrations/conflicts/{integrationId} comes back empty.

The call is idempotent on (integration, category name), so re-pointing a category later is the same request as mapping it the first time, and a retry is never an error. If you add a new category at the till, map it before its products sync — or map it afterwards and re-send them; the conflicts resolve either way.

Plenty of tills cannot make an outbound HTTPS call, and some cannot be extended at all. That does not put the merchant out of reach — it only means the catalogue travels as a file instead of a request.

A merchant can import their products from a spreadsheet in the DrippleX merchant portal, or over the API as themselves:

POST https://api.dripplex.com/api/v1/merchant/catalogue/import
Authorization: Bearer <merchant session token>

{
  "csv": "SKU,Name,Price,Quantity,Category
PIE-001,Meat Pie,800,60,Pastries",
  "idempotencyKey": "catalogue-2026-09-23",
  "dryRun": true
}

Send dryRun: true first, always. It validates and reports without writing anything, so the rejected rows and their line numbers come back before a single product is created. A bad row never fails the file — the rest still import.

The import runs through the same engine as a POS push, so it behaves the same way: products land as drafts, SKUs are the identity, category mappings apply, and replaying an idempotency key returns the original job rather than importing twice. The column headings are flexible — SKU, Item Code and Product Code are all understood — and a template is at GET /merchant/catalogue/import/template.

What this does not solve: a till that cannot export a file at all. There the products are entered by hand, once.

DrippleX does not call your server. There are no outbound webhooks. Your POS learns about a new order by polling:

GET https://api.dripplex.com/api/v1/integrations/orders/list

Poll on an interval that suits your kitchen or counter — most merchants use 30 to 60 seconds. Then acknowledge progress so the customer sees it:

PUT https://api.dripplex.com/api/v1/integrations/orders/status/{orderNumber}

This is the contract today, and it is deliberate rather than unfinished. If webhooks are added they will be a complete subsystem — signed payloads, rotating secrets, idempotency keys, retry with backoff, delivery history and replay — not a URL we post to and hope.

An order carries subtotal, discount, tax and total. It deliberately does not carry DrippleX's delivery fee or DX fee as separate lines: those are our economics and are not needed to fulfil an order.

The difference is derivable in aggregate and we would rather say so than pretend otherwise:

total − (subtotal − discount + tax) = DrippleX fees on this order

That residual is the delivery fee plus the DX fee, each net of any DrippleX promotion. It is not the delivery fee on its own.

A 401 is deliberately indistinguishable across every way a key can fail to authenticate. That is an anti-enumeration control, not a vague error.

Stated so you can plan around it rather than discover it:

• No outbound webhooks. Polling is the contract.
• Your POS cannot create a DrippleX order. Orders originate with the customer in the DrippleX app.
• Your POS cannot take a DrippleX payment. Payment is handled in the app before the order reaches you.
• Settlement is not driven from the POS. DrippleX settles you on its own schedule; the API does not initiate or report payouts.

The interactive reference lists every request and response shape and lets you try calls against your own integration. For anything it does not answer, contact DrippleX merchant support.