# Orders

> Quotes, placing orders, the payment, delivery times and moving orders on.

Quotes, placing orders, the payment, delivery times and moving orders on. Generated from the [OpenAPI spec](https://dev.mongrl.com/openapi.json). Each endpoint says which key it needs; see [Authentication](https://dev.mongrl.com/guides/authentication.md).

| Method | Path | What it does |
|---|---|---|
| GET | [`/v1/me/orders`](#list-the-signed-in-users-orders) | List the signed-in user's orders |
| POST | [`/v1/me/orders`](#buy-a-listing) | Buy a listing |
| POST | [`/v1/me/orders/quote`](#price-an-order-without-placing-it) | Price an order without placing it |
| GET | [`/v1/me/orders/{id}`](#get-one-of-the-users-orders) | Get one of the user's orders |
| GET | [`/v1/me/orders/{id}/delivery-booking`](#when-the-delivery-comes) | When the delivery comes |
| PUT | [`/v1/me/orders/{id}/delivery-booking`](#choose-when-the-delivery-comes) | Choose when the delivery comes |
| POST | [`/v1/me/orders/{id}/transitions/{transition}`](#move-an-order-on) | Move an order on |

## List the signed-in user's orders

`GET /v1/me/orders` · operation `listMyOrders`

As buyer (purchases) or seller (sales), newest first.

**Auth:** your secret key (`Authorization: Bearer sk_…`) and the user's session (`X-User-Session: …`), from your server

**Parameters**

| Name | In | Type | Notes |
|---|---|---|---|
| `state` | query | string |  |
| `limit` | query | integer | ≥ 1; ≤ 100; default `25` |
| `offset` | query | integer | ≥ 0; ≤ 10000 |
| `as` | query | string | one of `buyer`, `seller`; default `"buyer"` |

**Responses:** `200` [OrderListOutputBody](#orderlistoutputbody) · `default` [a problem](https://dev.mongrl.com/reference/conventions.md#errors)

## Buy a listing

`POST /v1/me/orders` · operation `placeOrder`

Reserves the stock and starts the payment. Pay within 15 minutes with payment.client_secret, or the order expires and the item is released.

**Auth:** your secret key (`Authorization: Bearer sk_…`) and the user's session (`X-User-Session: …`), from your server

**Body** (`application/json`): [PlaceOrderRequest](#placeorderrequest)

**Responses:** `201` [PlaceOrderResponse](#placeorderresponse) · `default` [a problem](https://dev.mongrl.com/reference/conventions.md#errors)

## Price an order without placing it

`POST /v1/me/orders/quote` · operation `quoteOrder`

What the buyer would pay, line by line, e.g. to show a voucher's effect at checkout. Placing the order prices it the same way.

**Auth:** your secret key (`Authorization: Bearer sk_…`) and the user's session (`X-User-Session: …`), from your server

**Body** (`application/json`): [QuoteRequest](#quoterequest)

**Responses:** `200` [QuoteBody](#quotebody) · `default` [a problem](https://dev.mongrl.com/reference/conventions.md#errors)

## Get one of the user's orders

`GET /v1/me/orders/{id}` · operation `getMyOrder`

Its buyer or its seller.

**Auth:** your secret key (`Authorization: Bearer sk_…`) and the user's session (`X-User-Session: …`), from your server

**Parameters**

| Name | In | Type | Notes |
|---|---|---|---|
| `id` * | path | string |  |

**Responses:** `200` [OrderBody](#orderbody) · `default` [a problem](https://dev.mongrl.com/reference/conventions.md#errors)

## When the delivery comes

`GET /v1/me/orders/{id}/delivery-booking` · operation `getMyDeliveryBooking`

The buyer's booked delivery time and the open slots. 409 when the delivery isn't booked by the buyer (not paid yet, collected, or arranged by the carrier).

**Auth:** your secret key (`Authorization: Bearer sk_…`) and the user's session (`X-User-Session: …`), from your server

**Parameters**

| Name | In | Type | Notes |
|---|---|---|---|
| `id` * | path | string |  |

**Responses:** `200` [DeliveryBookingBody](#deliverybookingbody) · `default` [a problem](https://dev.mongrl.com/reference/conventions.md#errors)

## Choose when the delivery comes

`PUT /v1/me/orders/{id}/delivery-booking` · operation `bookMyDelivery`

One of the open slots; it can be changed until the lead time.

**Auth:** your secret key (`Authorization: Bearer sk_…`) and the user's session (`X-User-Session: …`), from your server

**Parameters**

| Name | In | Type | Notes |
|---|---|---|---|
| `id` * | path | string |  |

**Body** (`application/json`): [SlotInputBody](#slotinputbody)

**Responses:** `200` [DeliveryBookingBody](#deliverybookingbody) · `default` [a problem](https://dev.mongrl.com/reference/conventions.md#errors)

## Move an order on

`POST /v1/me/orders/{id}/transitions/{transition}` · operation `takeMyOrderTransition`

One of the order's available_transitions for the user, e.g. mark-delivered (seller, with data.tracking_number) or mark-received (buyer).

**Auth:** your secret key (`Authorization: Bearer sk_…`) and the user's session (`X-User-Session: …`), from your server

**Parameters**

| Name | In | Type | Notes |
|---|---|---|---|
| `id` * | path | string |  |
| `transition` * | path | string |  |

**Body** (`application/json`): [TransitionInputBody](#transitioninputbody)

**Responses:** `200` [OrderBody](#orderbody) · `default` [a problem](https://dev.mongrl.com/reference/conventions.md#errors)

## Schemas

Fields marked * are always present in responses and required in requests.

### OrderListOutputBody

| Field | Type | Notes |
|---|---|---|
| `items` * | [OrderBody](#orderbody)[] |  |

### PlaceOrderRequest

| Field | Type | Notes |
|---|---|---|
| `currency` | string | What the buyer pays in, one of the marketplace's; the listing's when omitted |
| `delivery` | [DeliveryBody](#deliverybody) |  |
| `listing_id` * | string |  |
| `quantity` | integer | 1 when omitted. ≥ 1; ≤ 100 |
| `voucher_code` | string | max 40 chars |

### PlaceOrderResponse

| Field | Type | Notes |
|---|---|---|
| `order` * | [OrderBody](#orderbody) |  |
| `payment` * | [PaymentStruct](#paymentstruct) |  |

### QuoteRequest

| Field | Type | Notes |
|---|---|---|
| `currency` | string | What the buyer pays in; the listing's when omitted |
| `delivery` | [DeliveryBody](#deliverybody) |  |
| `listing_id` * | string |  |
| `quantity` | integer | 1 when omitted. ≥ 1; ≤ 100 |
| `voucher_code` | string | max 40 chars |

### QuoteBody

| Field | Type | Notes |
|---|---|---|
| `currency` * | string |  |
| `line_items` * | [LineItemBody](#lineitembody)[] |  |
| `total` * | integer |  |

### OrderBody

| Field | Type | Notes |
|---|---|---|
| `available_transitions` * | string[] | What the caller can do now, e.g. mark-delivered |
| `buyer_id` * | string |  |
| `chargeback` | [ChargebackBody](#chargebackbody) |  |
| `created_at` * | string (date-time) |  |
| `currency` * | string |  |
| `delivery` * | map of string | Tracking number, carrier… as given when marked delivered |
| `history` * | [EventBody](#eventbody)[] |  |
| `id` * | string |  |
| `line_items` * | [LineItemBody](#lineitembody)[] |  |
| `listing_id` * | string |  |
| `payout` | [PayoutBody](#payoutbody) |  |
| `quantity` * | integer |  |
| `refunded_outside` | integer | Refunded in Stripe outside the order, in the order's currency |
| `seller_id` * | string |  |
| `state` * | string | pending_payment, purchased, delivered, received, disputed, canceled, payment_expired |
| `state_entered_at` * | string (date-time) |  |
| `total` * | integer | In minor units of currency |

### DeliveryBookingBody

| Field | Type | Notes |
|---|---|---|
| `booked` | [SlotBody](#slotbody) |  |
| `changeable` * | boolean | The booked time can still be changed |
| `slots` * | [SlotBody](#slotbody)[] |  |

### SlotInputBody

| Field | Type | Notes |
|---|---|---|
| `date` * | string | YYYY-MM-DD |
| `window` * | string | max 40 chars |

### TransitionInputBody

| Field | Type | Notes |
|---|---|---|
| `data` | map of string | E.g. tracking_number and carrier when marking delivered |

### DeliveryBody

| Field | Type | Notes |
|---|---|---|
| `address` | [Address](#address) | Where to ship to (shipping only) |
| `method` | string | One of the listing's; may be omitted when it offers only one. collect: from the marketplace location it's stored at. one of `shipping`, `pickup`, `buyer_arranged`, `collect` |
| `option` | string | Shipping with the marketplace: one of its delivery options (the first when omitted) |

### PaymentStruct

| Field | Type | Notes |
|---|---|---|
| `client_secret` * | string | For the payment form |

### LineItemBody

| Field | Type | Notes |
|---|---|---|
| `amount` * | integer |  |
| `code` * | string |  |
| `label` * | string |  |
| `quantity` * | integer |  |
| `unit_price` * | integer |  |

### ChargebackBody

| Field | Type | Notes |
|---|---|---|
| `id` * | string |  |
| `reason` * | string |  |
| `status` * | string | Stripe's dispute status, e.g. needs_response, under_review, won, lost |

### EventBody

| Field | Type | Notes |
|---|---|---|
| `actor` * | string | one of `buyer`, `seller`, `operator`, `system` |
| `at` * | string (date-time) |  |
| `data` | map of string |  |
| `from` * | string |  |
| `to` * | string |  |
| `transition` * | string |  |

### PayoutBody

| Field | Type | Notes |
|---|---|---|
| `amount` * | integer | What the seller is paid |
| `commission` * | integer |  |
| `currency` * | string |  |
| `status` * | string | pending until the buyer has the item. one of `pending`, `paid`, `waiting_for_payout_details`, `held_for_chargeback` |
| `storage_fee` | integer | Taken for storage, per started month |
| `storage_months` | integer |  |
| `subtotal` * | integer |  |

### SlotBody

| Field | Type | Notes |
|---|---|---|
| `date` * | string | YYYY-MM-DD |
| `full` | boolean |  |
| `label` * | string | e.g. 08–12 |
| `window` * | string |  |

### Address

| Field | Type | Notes |
|---|---|---|
| `city` | string |  |
| `country` * | string | ISO 3166, e.g. SE |
| `line1` | string |  |
| `line2` | string |  |
| `name` | string |  |
| `phone` | string |  |
| `postal_code` * | string |  |