Feed it to openapi-generator for a typed client, or import it into Postman or Insomnia. It is generated from the running router, so it describes what is deployed rather than what was last written down.

curl -s https://winery.sipspos.com/api/v1/market \
  -H "Authorization: Bearer sk_live_…"

curl -si https://winery.sipspos.com/api/v1/customers \
  -H "Authorization: Bearer sk_test_…"

HTTP/1.1 200 OK
X-Sipspos-Environment: test

Money is an object, never a float.

{"amount_cents": 4200, "currency": "CAD"}. null means unknown — it never means zero.

Ids are opaque and prefixed.

prod_…, cus_…, ord_…. Store them whole: the prefix is how an id sent to the wrong endpoint is refused at the boundary instead of resolving to the wrong object. Integer primary keys never cross the boundary.

Timestamps carry the winery's own offset.

ISO-8601 in the winery's time zone, which GET /v1/market names. A naive timestamp you send is read in that zone.

Lists are cursor-paginated.

Send back next_cursor verbatim; there is no page number and no offset. Cursors are signed and bound to the filters they were minted under, so one cannot be replayed against a differently filtered list. An unrecognised query parameter is a 400, not a shrug.

Errors all share one shape.

{"error": {"type": …, "message": …, "request_id": …}}, always with a real status code. Branch on type; quote request_id (also in the X-Request-Id header, on successes too) and we can find the one log line.

Rate limits are per key.

A throttled request answers 429 with Retry-After. Limits are per key, not per IP, so one partner's polling cannot throttle another's.

A warehouse or 3PL bridge.

Subscribe to fulfillment.created, pull the parcel from /v1/fulfillments — what is in it, where it is going, whether it is a shop order or a club allocation — push it into your WMS, then POST /v1/fulfillments/{id}/ship with the carrier and tracking number when it leaves. That marks the parcel shipped, emails the customer their tracking, and emits fulfillment.shipped, so nobody retypes a tracking number into a second system. Needs fulfillment:read and fulfillment:write. The bite: that write reaches a customer's inbox, which almost nothing else on this API does — ask for fulfillment:write only if you are the party that actually ships, and expect a winery to say no otherwise.

Nightly accounting reconciliation.

sale.completed and order.paid tell you when there is something to post; /v1/sales and /v1/orders carry the line items and a tax_breakdown per rate, in cents with an explicit currency — a sale also carries its payments and any refunds against it. Enough to write a journal entry per day without inferring tax back out of a total. Needs sales:read, plus orders:read if the winery sells online. The bite: orders:read requires the online store, so a tasting-room-only winery cannot issue it however much they want to — build the register half to stand on its own, or your integration works at one winery and not the next.

A concierge, hotel or wine-route booking widget.

/v1/experiences lists what is bookable, /v1/experiences/{id}/availability gives real slots for a date, and POST /v1/bookings takes the reservation. A regional tourism site can show five wineries' Saturdays on one page. Needs bookings:read and bookings:write. The bite: availability is computed by us from the winery's schedule, blackouts, venue hours and capacity — you never see the raw schedule, which is precisely what stops anybody reimplementing those rules and double-booking a Saturday. An experience that charges at booking time is refused, because this API cannot take payment; send that guest to the winery's own page.

A club retention loop that does not phone anybody twice.

/v1/club/members filtered by club_status finds the members whose billing is failing; /v1/customers/{id}/communications says whether the winery has already reached out and whether the message actually arrived; POST /v1/customers/{id}/notes records that you called, onto the winery's own timeline rather than into a parallel record only you can see; and tags segments what is left. Needs customers:read and customers:write. The bite: the timeline is per customer, so a "who have we contacted this week" sweep is one request each — read the history for the names you are about to work, not for the whole club.

A stocktake app for a phone.

Somebody walks the cellar with a scanner: /v1/inventory for what the system thinks is there, POST /v1/inventory/adjustments for each correction with a reason, /v1/inventory/movements for the ledger behind the numbers. Every change is attributed to the API key rather than to a member of staff who was not there. Needs inventory:read and inventory:write. The bite: a partner may write restock, adjustment, wastage and import — and deliberately not sale, refund or allocation, because those reasons belong to the systems that do them and writing one would make the winery's reports describe a transaction that never happened.

A CRM or mailing-list mirror.

customer.created and customer.updated push the change to you; you re-read the customer and mirror it, consent flags included. Needs customers:read. The bite: there is no ?updated_since= on customers — that column does not exist and we will not fake it out of created_at, which would find new customers and silently never report an edit. So the webhook is the sync primitive here rather than a nicety, and a mirror built on polling would go quietly stale on exactly the fields that matter: addresses and opt-outs.

A regional marketplace across several wineries.

One integration, many wineries: /v1/market tells you per winery whether to say "province" or "state", which currency the money is in and where it may ship, so there is no country conditional in your code. Then /v1/products to list, POST /v1/shipping/quote to ask before you sell, POST /v1/orders/quote to price the cart, and POST /v1/orders to record it once you have charged. Needs market:read, catalog:read and orders:write. The bite: you are the merchant of record. There is no hosted checkout to hand a shopper and nothing here charges a card — you take the money on your own account and send us your payment reference.