> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.hive.co/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.hive.co/_mcp/server.

# Orders

## Create or update orders

`POST /orders/` pushes order and ticket data to Hive.

**Required scope:** `orders:write`. Also request `contacts:write` so you can create contacts before their orders (see [Modeling notes](#modeling-notes)).

```json
{
    "orders": [
        {
            "order_id": "ord_98765",
            "event_id": "evt_45678",
            "status": "completed",
            "user": {
                "email": "jamie@example.com",
                "first_name": "Jamie",
                "last_name": "Smith",
                "phone_number": "+15195551234",
                "gender": "female",
                "birthday": "1990-05-15",
                "address": {
                    "address": "123 Main Street",
                    "city": "Toronto",
                    "state": "Ontario",
                    "country": "Canada",
                    "zip": "M5V 1A1"
                },
                "is_email_opt_in": true,
                "is_sms_opt_in": false,
                "custom_properties": {
                    "favorite_color": "blue",
                    "membership_tier": "gold",
                    "source": "partner_signup"
                }
            },
            "items": [
                {
                    "item_id": "item_001",
                    "status": "completed",
                    "tier_id": "tier_ga",
                    "tier_name": "General Admission",
                    "price": 45.0,
                    "quantity": 2
                }
            ],
            "purchased_at": "2026-02-01T10:00:00Z",
            "created_at": "2026-02-01T09:55:00Z",
            "updated_at": "2026-02-01T10:00:00Z"
        }
    ]
}
```

### Fields

`orders` takes an array of 1–50 orders.

| Field                                  | Required           | Description                                                                                          |
| -------------------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------- |
| `order_id`                             | Yes                | Your order ID                                                                                        |
| `event_id`                             | Yes                | Your event ID. Must match an [event](/docs/events) already in Hive, or the request fails with `422`. |
| `status`                               | Yes                | One of `started`, `completed`, `partial_payment`, `cancelled`, `pending`                             |
| `created_at`, `updated_at`             | Yes                | ISO 8601 timestamps. `updated_at` must be at or after `created_at`.                                  |
| `user.email` or `user.phone_number`    | Yes (at least one) | Identifies the purchaser. `email` follows the [contacts](/docs/contacts#fields) rules.               |
| `items`                                | Yes                | At least one line item                                                                               |
| `items[].item_id`                      | Yes                | Your ID for the line item. Must be unique within the order's `items`.                                |
| `items[].price`                        | Yes                | JSON number, `>= 0`, at most 2 decimal places                                                        |
| `items[].quantity`                     | Yes                | Integer, `>= 1`                                                                                      |
| `items[].status`                       | No                 | One of `completed`, `cancelled`, `started`, `transferred`, `resold`                                  |
| `items[].tier_id`, `items[].tier_name` | No                 | The ticket tier                                                                                      |
| `purchased_at`                         | No                 | ISO 8601 timestamp                                                                                   |
| Other `user` fields                    | No                 | Same as [contacts](/docs/contacts#fields), except `updated_at`, which isn't accepted on `user`       |

ID fields (`order_id`, `event_id`, `item_id`, `tier_id`, `tier_name`) are trimmed and must be non-blank. Unknown fields are ignored. Timestamps follow the same rules as [contacts](/docs/contacts#fields): ISO 8601 strings only, and a timestamp without an offset is interpreted in `America/Toronto`, so always include one.

If any order fails validation, including an `event_id` that doesn't exist in Hive, the whole batch is rejected with `422 Unprocessable Entity` and nothing is saved. See [Errors & Status Codes](/docs/errors-status-codes).

The endpoint is asynchronous and returns `202 Accepted`. See [How It Works](/docs/how-it-works).

## Modeling notes

* **One event per order.** An order is scoped to a single event. If a purchaser bought tickets to multiple events in one transaction, send a separate order object for each event, each with its own `event_id`.
* **Season tickets and packages.** Send them as separate events for now. A dedicated event series concept is planned for a future API version.
* **Contacts from orders.** Submitting an order currently creates the contact if one doesn't already exist, but this behavior isn't guaranteed. Request both `contacts:write` and `orders:write`, and make sure the contact exists (via [`POST /contacts/`](/docs/contacts)) before submitting its orders.