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

# Place an order

> One order per marketplace sale. Gomry issues the tickets inside the request.

Place one order per marketplace sale, for one [product](https://docs.gomry.com/distribution-api/list-products.md): tickets to an event, or seats on one session of an experience. Gomry issues them inside the request and answers with them.

> [!NOTE]
>
> **`external_ref` makes it safe to retry.** It is your order id. Send the same `external_ref` with the same lines and you get the same order back, never a second one. A timeout or a dropped connection is safe to retry as is.

**external\_ref** `string` *required*

Your order id. 1 to 128 letters, digits, `.`, `_`, `:` or `-`. Reusing it with different lines is refused with `order_mismatch`.

**product\_id** `string` *required*

From [products](https://docs.gomry.com/distribution-api/list-products.md): `evt_…` or `exp_…`.

**start** `string`

Experiences only, and required there: the session's `start.utc`, from the product's sessions. An event has one session and needs none.

**hold\_id** `string`

When you [held the seats](https://docs.gomry.com/distribution-api/create-hold.md) first. The order must match the hold's session and lines.

**lines** `array` *required*

One to 20 lines.

**Line**

**offer\_id** `string` *required*

From the product's `offers`.

**quantity** `integer` *required*

1 to 50, within the offer's `min_per_order` and `max_per_order`.

**buyer** `object` *required*

**Buyer**

**name** `string` *required*

The buyer's name, or the marketplace's name when it keeps the buyer's.

**email** `string`

When you have it, Gomry emails the buyer their tickets. Leave it out when the marketplace keeps it: the buyer can still claim their tickets from the [accept link](https://docs.gomry.com/distribution-api/delivery.md). An experience needs an email here or in `transfer_to`: Gomry sends the booking confirmation.

**phone** `string`

Optional.

**transfer\_to** `object`

The person the marketplace sold the tickets to, when you know them. Gomry hands the tickets over like a mobile transfer: it emails them the order's accept link and fills the accept page in for them. The tickets stay in the `buyer` name until they accept. Send it on every post of the order; the first one Gomry receives is kept. See [Delivery](https://docs.gomry.com/distribution-api/delivery.md).

**Recipient**

**email** `string` *required*

Where Gomry sends the accept link.

**first\_name** `string`

Optional.

**last\_name** `string`

Optional.

```bash theme={null}
curl -X POST https://www.gomry.com/api/v1/distribution/orders \
  -H "Authorization: Bearer gdk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "external_ref": "mkt-1834221",
    "product_id": "evt_4wfgqZSyaLdroutDkeZ7",
    "lines": [{ "offer_id": "hnTv4341P391VfkiH5XT", "quantity": 2 }],
    "buyer": { "name": "StubHub" },
    "transfer_to": { "first_name": "Grace", "last_name": "Hopper", "email": "grace@example.com" }
  }'
```

Seats on an experience session name the session's start:

```json theme={null}
{
  "external_ref": "gyg:GYG123:res-1",
  "product_id": "exp_1y9Gr0O6FGmS38BSQcJf",
  "start": "2026-12-01T10:00:00.000Z",
  "hold_id": "acme__cart-1",
  "lines": [{ "offer_id": "tc-adult", "quantity": 2 }],
  "buyer": { "name": "Ada Lovelace", "email": "ada@example.com" }
}
```

Answers `201` with the [order](https://docs.gomry.com/distribution-api/get-order.md#the-order).

## When an order is refused

Nothing is issued and nothing is owed. The common ones:

| `code` | Do this |
| - | - |
| `sold_out` | Cancel the sale on the marketplace. Re-read the product. |
| `not_listed` | The offer stopped selling (`reason` says why). Take it down and cancel the sale. |
| `credit_limit_reached` | Pay your [statement](https://docs.gomry.com/distribution-api/get-statement.md). The same order succeeds once you are under your limit. |
| `order_in_progress` | The first attempt is still issuing. Retry in a few seconds with the same `external_ref`. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.