> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gomry.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Vendor API
> Connect your ticket inventory to Gomry Retail by implementing the Vendor API
# Vendor API
Gomry Retail is Gomry's resale business. It buys ticket inventory from suppliers and sells it on Gomry as the merchant of record. Buyers see a Gomry ticket, and they never see the supplier it came from.
The Vendor API is the contract that connects a supplier to Gomry Retail. **You build and host an integration service that implements it**, translating each call into whatever your own system needs. Gomry Retail calls your service. Nothing on the Gomry side ever calls your platform directly, knows its hostname or reads its wire format.
```
Gomry (storefront)
⇅
Gomry Retail calls your integration for every endpoint on this tab
⇅
Your integration implements the Vendor API, owns your credentials and quirks
⇅
Your ticketing system
```
**Retail is the client for every endpoint in this reference.** The only traffic that runs the other way is [webhooks](/vendor-api/webhooks), which your integration sends to Retail to say something changed.
## Base URL
You give us one HTTPS base URL for your deployment. Retail appends the paths below to it, including the `/api` prefix:
```
https://integration.example.com/api/vendor/v1/catalog
```
A base URL may include a path (for example `https://example.com/gomry`). Retail keeps it and appends to it. Localhost and other loopback URLs are rejected in production.
## What you implement
| Endpoint | Purpose | Called |
| - | - | - |
| [`GET /api/vendor/v1/catalog`](/vendor-api/catalog) | Your events, paged | Every 15 minutes |
| [`GET /api/vendor/v1/listings`](/vendor-api/listings) | What is for sale on one event, right now | While a buyer loads a page |
| [`POST /api/vendor/v1/quote`](/vendor-api/quote) | Price a purchase, including tax | At checkout |
| [`POST /api/vendor/v1/orders`](/vendor-api/place-order) | Place an order | Once per purchase |
| [`GET /api/vendor/v1/orders`](/vendor-api/search-orders) | Find orders by Retail's reference | After an unclear submit, after webhooks, hourly |
| [`GET /api/vendor/v1/fulfilment`](/vendor-api/fulfilment) | Has the ticket been released yet? | Every 10 minutes per open order |
| [`GET /api/vendor/v1/credentials`](/vendor-api/credentials) | The admission barcode itself | Once, at delivery |
| [`GET /api/vendor/v1/venue-map`](/vendor-api/venue-map) | The venue map image | When a seat map is needed |
Every endpoint is required except `venue-map`. An event with no map still sells.
## How a sale flows
Retail pages through your catalog on a schedule and stores your events. An event is something that could be sold. It is not yet a promise that anything is.
When a buyer opens a Gomry event page, Retail asks for listings on that event and shows only what passes its rules. Listings are quotes, never stored.
The buyer commits. Retail quotes the chosen listing to get the tax on both legs and a `taxSignature`.
Retail places the order with its own `reference`, once. If the reply is lost, Retail does not retry. It searches for the reference instead.
Retail learns the order's state by searching (after a webhook, or on its hourly sweep). Only `accepted` commits Retail to paying you.
Retail polls fulfilment until the ticket is `ready`, then fetches the credential once and renders it inside Gomry's own ticket.
## Conventions
* **JSON everywhere**, with `camelCase` field names.
* **IDs are strings**, even when yours are numeric. Retail never parses them.
* **Money is a number in major units** (`42.5` means 42.50), per ticket unless the field says total. `currency` is a three-letter ISO 4217 code.
* **Timestamps are ISO 8601.**
* **Every request carries `vendorKey`**, the identifier Gomry assigns to your supplier account. A deployment that serves one supplier can ignore it.
* **Unknown fields are ignored**, so you can add your own. A missing required field fails the whole response, not just that item. Validate before you answer.
* **Never report a failure as an empty result.** An empty list means you asked and there is nothing. If you could not ask, return an error. The difference decides whether an event shows as sold out and whether a ticket is bought twice.
## Buyer data
Retail stores no buyer identity: no name, no email, no card, no address. Two fields on [Place order](/vendor-api/place-order) carry some anyway, because delivery needs them:
* `shippingAddress`, for a physical ticket that must be couriered.
* `buyerEmail`, for a seat transferred into the buyer's own account.
Both pass through Retail without being stored. Your integration must do the same: hand them to your system on the order, and never persist them anywhere else or write them to logs or error reports.
## What a buyer must never see
Gomry never tells a buyer where a ticket came from. That is why the contract moves **values, not links**:
* Venue maps travel as image bytes, never as a URL on your domain.
* Tickets travel as barcode values that Gomry renders in its own design, never as your PDF.
## Next steps
The `X-API-Key` header, the error format and the time budget for each call.
Tell Retail an order changed without waiting for its next sweep.
What we exchange with you and what to check before inventory reaches buyers.
Start with the first endpoint Retail calls.