Skip to navigation
Endpoints

Orders

Push orders and ticket line items for your events
View as Markdown

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

{
    "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.

FieldRequiredDescription
order_idYesYour order ID
event_idYesYour event ID. Must match an event already in Hive, or the request fails with 422.
statusYesOne of started, completed, partial_payment, cancelled, pending
created_at, updated_atYesISO 8601 timestamps. updated_at must be at or after created_at.
user.email or user.phone_numberYes (at least one)Identifies the purchaser. email follows the contacts rules.
itemsYesAt least one line item
items[].item_idYesYour ID for the line item. Must be unique within the order’s items.
items[].priceYesJSON number, >= 0, at most 2 decimal places
items[].quantityYesInteger, >= 1
items[].statusNoOne of completed, cancelled, started, transferred, resold
items[].tier_id, items[].tier_nameNoThe ticket tier
purchased_atNoISO 8601 timestamp
Other user fieldsNoSame as contacts, 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: 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.

The endpoint is asynchronous and returns 202 Accepted. See 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/) before submitting its orders.