> ## 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.

# Listings

> Return what is for sale on one event, right now

# Listings

Returns every listing currently for sale on one event. Retail calls this while a buyer's page is loading, filters the results by its own rules, and shows what passes. Nothing here is stored.

<Warning>
  **Answer within 4.5 seconds, and never retry internally.** The buyer's page has a hard budget. A slow success is worse than a fast failure, because by the time it arrives the page has already rendered the event as unavailable.
</Warning>

Listings are **quotes, not inventory**. A `vendorListingId` may change between calls, and a listing that has been bought should disappear from the response, not report quantity 0.

## Query Parameters

<ParamField query="vendorKey" type="string" required>
  Your supplier identifier.
</ParamField>

<ParamField query="vendorEventId" type="string" required>
  The event, as you returned it from [Catalog](/vendor-api/catalog).
</ParamField>

## Response

Return `{ "listings": [] }` when the event genuinely has nothing for sale. If you could not ask your system, return an error instead: an empty list shows a live event as sold out, and nobody investigates a sold-out event.

<ResponseField name="listings" type="array" required>
  <Expandable title="Listing object">
    <ResponseField name="vendorListingId" type="string" required>
      Your id for this listing. Retail sends it back on quote and order.
    </ResponseField>

    <ResponseField name="vendorEventId" type="string" required>
      The event this listing belongs to.
    </ResponseField>

    <ResponseField name="format" type="string" required>
      How the ticket reaches the buyer. One of:

      | Value | Meaning |
      | - | - |
      | `eticket` | A printable or scannable ticket with a barcode Retail can retrieve. |
      | `mobile_transfer` | Transferred into the buyer's own account with the box office, addressed to their email. |
      | `flash_seats` | An account-based mobile ticket, also delivered to the buyer's email. |
      | `physical` | A paper ticket couriered to an address. |
      | `local_pickup` | Collected at the venue or another location. |
      | `paperless` | Entry by card or ID, no ticket to hand over. |
      | `unknown` | You cannot tell. Never sold. |

      Classify from your system's delivery-method field, not from a yes/no "e-ticket" flag. A flag like that is often true for mobile transfers too, and overstates e-ticket supply several times over.
    </ResponseField>

    <ResponseField name="productKind" type="string" default="ticket">
      What the listing **is**: `ticket` (admission), `parking`, or `other`. A parking pass is delivered exactly like an e-ticket, so nothing else in the payload tells it apart from a seat. **Always send this.** It defaults to `ticket`, and an add-on without it will be sold as admission.
    </ResponseField>

    <ResponseField name="section" type="string">
      Section name as printed on the ticket.
    </ResponseField>

    <ResponseField name="row" type="string">
      Row.
    </ResponseField>

    <ResponseField name="wholesalePrice" type="number" required>
      Price per ticket Gomry Retail pays you.
    </ResponseField>

    <ResponseField name="retailPrice" type="number" required>
      Your suggested retail price per ticket. A reference for pricing only: Gomry sets its own price from `wholesalePrice`.
    </ResponseField>

    <ResponseField name="currency" type="string" required>
      ISO 4217 code for both prices.
    </ResponseField>

    <ResponseField name="availableQuantity" type="integer" required>
      Tickets available in this listing.
    </ResponseField>

    <ResponseField name="splits" type="integer[]" required>
      The quantities you will sell in one purchase. **An allow-list, not a range.** `[2, 4]` means 2 or 4, never 3. Send your system's array exactly as it is. Most multi-value arrays have a gap, so reducing them to a minimum and maximum produces orders that always fail. A `0` in the array is ignored.
    </ResponseField>

    <ResponseField name="inHand" type="boolean" required>
      The seller holds the tickets right now and can start delivery immediately. `false` is normal for tickets sold months ahead and does **not** mean undeliverable. Pair it with `inHandOn`.
    </ResponseField>

    <ResponseField name="inHandOn" type="string">
      ISO 8601 date the seller expects to be able to deliver. Send it whenever `inHand` is `false`.
    </ResponseField>

    <ResponseField name="instantDelivery" type="boolean" required>
      The ticket can be handed over immediately after purchase. This is about the **ticket**.
    </ResponseField>

    <ResponseField name="automated" type="boolean" default="false">
      Your system accepts an order for this listing on the spot, with no human broker involved. This is about the **order**, and it is independent of `instantDelivery`. When `false`, Retail tells the buyer their ticket is being confirmed and waits for acceptance.
    </ResponseField>

    <ResponseField name="vendorEticketFlag" type="boolean">
      Your system's own yes/no e-ticket flag, if it has one, sent next to `format`. A listing with `format: "eticket"` and `vendorEticketFlag: false` is withheld, because that disagreement usually means a mobile ticket mislabelled as an e-ticket.
    </ResponseField>

    <ResponseField name="signature" type="string">
      A price-lock token, if your system issues one. Retail sends it back as `listingSignature` on the order.
    </ResponseField>

    <ResponseField name="publicNotes" type="string">
      Seller notes a buyer may read, for example "Obstructed view".
    </ResponseField>

    <ResponseField name="raw" type="any">
      Your system's listing payload, untouched. Stored with the order as evidence of what was bought. It must not contain buyer data.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -H "X-API-Key: $GOMRY_RETAIL_API_KEY" \
    "https://integration.example.com/api/vendor/v1/listings?vendorKey=acme&vendorEventId=3273941"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "listings": [
      {
        "vendorListingId": "tg_88412093",
        "vendorEventId": "3273941",
        "format": "eticket",
        "productKind": "ticket",
        "section": "118",
        "row": "12",
        "wholesalePrice": 96.0,
        "retailPrice": 128.0,
        "currency": "USD",
        "availableQuantity": 4,
        "splits": [2, 4],
        "inHand": false,
        "inHandOn": "2026-11-12",
        "instantDelivery": false,
        "automated": true,
        "vendorEticketFlag": true,
        "signature": "sig_5f1c2a",
        "publicNotes": "Aisle seats",
        "raw": {}
      }
    ]
  }
  ```

  ```json 404 theme={null}
  { "error": { "code": "not_found", "message": "Unknown event 3273941" } }
  ```
</ResponseExample>