For merchants and POS vendors
DrippleX API
Connect your point of sale to DrippleX. Push your catalogue and stock, read live orders, and tell us when they are ready.
Getting started
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.
- Sign in to your DrippleX merchant account.
- Create an integration. DrippleX returns an integration id and an API key.
- Copy the key. It is shown once and stored hashed — we cannot show it to you again, only replace it.
- 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.
Authentication
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.
Scopes
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.
| Scope | Grants |
|---|---|
| catalog:read | Read your imported products and category mappings |
| catalog:write | Push your product catalogue to DrippleX |
| inventory:read | Read the stock levels DrippleX holds |
| inventory:write | Push stock levels to DrippleX |
| orders:read | List DrippleX orders and read one in detail |
| orders:write | Update the status of a DrippleX order |
Endpoints
All paths are relative to https://api.dripplex.com/api/v1.
| Endpoint | Scope | What it does |
|---|---|---|
| POST /integrations/catalogue/sync | catalog:write | Submit your catalogue. Returns a job you can poll. |
| GET /integrations/catalogue/jobs/{integrationId} | catalog:read | Poll the progress and outcome of a catalogue sync. |
| GET /integrations/catalogue/products/{integrationId} | catalog:read | List the products DrippleX imported from you. |
| PUT /integrations/inventory/sync | inventory:write | Push current stock levels. Send only what changed. |
| GET /integrations/inventory/levels/{integrationId} | inventory:read | Read the stock levels DrippleX currently holds. |
| GET /integrations/orders/list | orders:read | List your DrippleX orders. This is how a POS learns about new ones. |
| GET /integrations/orders/detail/{orderNumber} | orders:read | Read one order, with its items. |
| PUT /integrations/orders/status/{orderNumber} | orders:write | Tell DrippleX an order is accepted, preparing or ready. |
Receiving orders
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/listPoll 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.
Money on an order
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 orderThat residual is the delivery fee plus the DX fee, each net of any DrippleX promotion. It is not the delivery fee on its own.
Errors
| 400 | The request was understood but something in the body is invalid. The message names the field. |
| 401 | The key did not authenticate. Wrong key, wrong integration id, or the key was rotated or revoked. |
| 403 | The key authenticated but does not carry the scope this endpoint requires. |
| 404 | No such order, job or integration — or not one of yours. |
| 429 | Too many requests. Slow your polling down. |
A 401 is deliberately indistinguishable across every way a key can fail to authenticate. That is an anti-enumeration control, not a vague error.
What the API does not do yet
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.
Getting help
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.