List orders
Retrieves a paginated list of orders belonging to your Billy organization sorted by their creation date (created_at DESC).
Retrieves a paginated list of orders belonging to your Billy organization sorted by their creation date (created_at DESC).
Authorization
HTTPBearer API key authentication. Format: Bearer billy:o:<organization_id>:<api_key>
Example: Bearer billy:o:yyyyyyyyyyyyyyyy:xxxxxxxxxxxxxxxxx
In: header
Query Parameters
Page index (1-based, e.g., 1 for first page, 2 for second page)
1 <= value1Maximum number of records to return
Return results where updatedAt is at or after this value. For datetime fields, use ISO 8601 format with timezone offset (e.g. 2026-03-01T00:00:00+02:00).
Return results where updatedAt is at or before this value. For datetime fields, use ISO 8601 format with timezone offset (e.g. 2026-03-01T00:00:00+02:00).
Returns orders that contain at least one item from any of the given event IDs (comma separated, max 10).
Filter by order status (PENDING, FULFILLED, CANCELLED)
Filter by the customer's email, the value reported as customer.email (exact match, case-insensitive)
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/orders"{ "items": [ { "orderId": "b2c8c0d4-1f2e-4a3b-9c6d-2e7f1a8b3c4d", "orderNumber": "XI3RHEF", "salesChannelId": "5ad8d09e-c789-49e6-a8f8-1434f880beeb", "salesChannelName": "Box Office", "status": "FULFILLED", "customer": { "customerId": "eecedea0-e9ed-44d9-9fbf-6cc24a2b2bf4", "email": "jane@example.com", "firstName": "Jane", "lastName": "Doe" }, "billingAddress": { "type": "personal", "firstName": "Jane", "lastName": "Doe", "companyName": null, "vatNumber": null, "phone": "+33612345678", "addressLine1": "12 Rue de la Paix", "addressLine2": null, "city": "Paris", "postalCode": "75001", "countryCode": "FR" }, "currency": "EUR", "totalPrice": 150, "totalPaidPrice": 140, "subtotalPrice": 130, "subtotalPaidPrice": 120, "discountAmount": 10, "discountCode": "SUMMER10", "paymentProvider": "Stripe", "paymentMethod": "VISA", "serviceFees": 5, "deliveryFees": 2.5, "totalVatAmount": 25, "delivery": { "type": "home_delivery", "carrierId": "carrier_001", "homeDeliveryAddress": { "type": "personal", "firstName": "Jane", "lastName": "Doe", "addressLine1": "12 Rue de la Paix", "addressLine2": null, "city": "Paris", "postalCode": "75001", "countryCode": "FR" }, "pickupPoint": null }, "placedItems": [ { "offerId": "a9e51970-77db-4439-b1d8-7432203e04a2", "offerName": "Early Bird - General Admission", "inventoryId": "63c4f1e7-2b8a-4c9d-8e1f-5a6b7c8d9e0f", "quantity": 2, "unitPrice": 65, "unitPaidPrice": 60, "unitDiscountAmount": 5, "discountCode": "SUMMER10", "priceLabel": "Early Bird", "offerType": "TICKET", "eventId": "34280fd9-3f2f-4831-90ec-d76ac0cb7c8b", "sessionId": "6095dfdb-aa90-4d18-b0cb-3f9ef4b82238", "unitVatAmount": 10 } ], "optIns": [ { "name": "Marketing emails", "accepted": true } ], "createdAt": "2024-03-15T14:30:00Z", "fulfilledAt": "2024-03-15T14:35:00Z", "cancelledAt": null, "updatedAt": "2024-03-15T14:35:00Z", "paymentStatus": "PAID", "refundedAmount": null, "ticketsProtected": true, "addOns": [ { "category": "INSURANCE", "serviceId": "neat", "serviceName": "Neat", "addOnPaidPrice": 3.6 }, { "category": "DONATION", "serviceId": "common-cents", "serviceName": "Common Cents", "addOnPaidPrice": 1 } ] } ], "page": 1, "perPage": 20, "totalPages": 1}