Orders Sync

Early Access

This endpoint is available, under early access. Its behaviour or response format may change before general availability. Contact us if you plan to use it in a production integration.

The v3/orders/sync endpoint provides an incremental, paged feed of confirmed orders from a Spektrix system. It's designed for keeping an external system continuously in step with sales data, without re-downloading every order each time you run a sync.

This endpoint uses System Owner mode, so all calls must be authenticated. For more detail on signing requests, see our guide to Authentication.

How It Works

Rather than downloading every order every time, v3/orders/sync makes use of standard incremental pagination: it lets you fetch only the orders that have changed since a supplied timestamp. You then keep the timestamp of the last order you received as a high-water mark, and pass it back on your next call.

Making a Request

The endpoint takes a single required parameter, since, which is an ISO-8601 date/time. Orders modified on or after that instant will be returned, oldest first, up to a maximum of 100 orders per page.

Request

GET

https://system.spektrix.com/{{clientname}}/api/v3/orders/sync?since=2024-06-01T00:00:00.0000000

Response

{
  "paging": {
    "limit": 100,
    "next": "/api/v3/orders/sync?since=2024-06-02T09:14:52.0000000"
  },
  "values": [
    {
      "orderId": "1759AQHDBDQSDDTVTGMMVRMSSSKTGKB",
      "orderFriendlyId": "AB12CD",
      "customerId": "842BVQKLMNPQRSTVBCDGHJKLMNPQRST",
      "customerFriendlyId": "CUST-3345",
      "lastModified": "2024-06-01T18:22:10.0000000",
      "attributes": [
        { "name": "Source", "value": "Web" }
      ],
      "tickets": [
        {
          "id": "551ABCDEFGHJKLMNPQRSTVBCDGHJKLM",
          "ticketId": "552ABCDEFGHJKLMNPQRSTVBCDGHJKLM",
          "attributes": [],
          "seat": { "id": "12034" },
          "band": { "id": "77ABCDEFGHJKLMNPQRSTVBCDGHJKLMN" },
          "instance": { "id": "98ABCDEFGHJKLMNPQRSTVBCDGHJKLMN" },
          "event": { "id": "31ABCDEFGHJKLMNPQRSTVBCDGHJKLMN" },
          "ticketType": { "id": "5ABCDEFGHJKLMNPQRSTVBCDGHJKLMNP" },
          "discount": 0.00,
          "originalPrice": 25.00,
          "price": 25.00,
          "priceOverridden": false,
          "total": 27.50,
          "soldAsPartOfFixedSubscription": false
        }
      ],
      "merchandise": [],
      "donations": [
        {
          "id": "9ABCDEFGHJKLMNPQRSTVBCDGHJKLMNP",
          "fundId": "3ABCDEFGHJKLMNPQRSTVBCDGHJKLMNP",
          "total": 10.00
        }
      ],
      "vouchers": [],
      "membershipSubscriptions": [],
      "fixedSeriesSubscriptions": [],
      "totals": {
        "totalDeliveryCharges": 1.50,
        "totalPaymentCharges": 0.00,
        "totalTransactionCharges": 2.50,
        "total": 41.00
      }
    }
  ]
}

The shape of each order, and of the line items within it, is covered in Response Objects below.

Determining What Has Changed

Spektrix keeps an audit trail of when each order was created or last modified. The endpoint returns the oldest-first batch of orders whose audit timestamp is greater than or equal to since, ordered by that timestamp ascending. Only confirmed transactions are included, so in-progress baskets are excluded. Each order's lastModified value in the response is that audit timestamp.

Paging Through Results

1. Call the endpoint with your since value.
2. Read up to 100 orders from values.
3. Follow the paging.next URL.
4. Repeat until paging.next is null.

The service looks ahead by one record. If a 101st record exists there are more pages, and the response includes a paging.next URL whose since is set to the lastModified of that 101st record. When fewer than 101 records are available you've reached the end and paging.next is null.

Boundary records can repeat

Because the cursor uses >= since, Orders sharing the exact same lastModified timestamp as your cursor can be returned again on the next page. Treat every record as an upsert, keyed on orderId, so that repeats are harmless.

The Response Envelope

Every response is a paginated envelope containing the page of orders plus paging metadata.

Property	Type	Description
values	array	The page of order objects (0–100 items). Each element is an Order.
paging.limit	integer	Maximum page size. This is always 100.
paging.next	string / null	URL to fetch the next page, or null when there are no more results.

Conventions Used in the Data

• IDs: most identifiers are Spektrix API IDs, which (like elsewhere in the API) are opaque strings such as 1759AQHDBDQSDDTVTGMMVRMSSSKTGKB. They're stable per object and can be used to cross-reference other API v3 endpoints, such as Events and Instances. Orders and Customers have a short, human-readable friendly ID.
• Money: monetary fields are decimal amounts in the client's own currency, for example 12.50. The currency is determined by the organisation's configuration.
• Dates: ISO-8601 date/time strings.
• Optional objects: some nested objects are omitted entirely when they don't apply. For example, a ticket's seat is only present for reserved seating events.

Response Objects

Order

An order is the top-level record of a completed sale. It groups the customer, the individual line items (by type), any custom attributes, and the calculated totals.

Property	Type	Description
orderId	string	The order's API ID.
orderFriendlyId	string	Short, human-readable order reference shown in Spektrix and on customer confirmations. Use this to cross-reference with v3/orders.
customerId	string	API ID of the customer who owns the order. null for orders with no attached customer.
customerFriendlyId	string	Human-readable customer reference. null if there is no customer.
lastModified	datetime	Audit timestamp of when the order was created or last changed. This is the value used as the sync cursor.
attributes	array	Custom order-level attributes configured by the organisation. See Attribute.
tickets	array	Ticket line items. See Ticket.
merchandise	array	Merchandise line items. See Merchandise.
donations	array	Donation line items. See Donation.
vouchers	array	Gift voucher line items. See Voucher.
membershipSubscriptions	array	Membership purchases. See Membership Subscription.
fixedSeriesSubscriptions	array	Fixed series (season or package) subscriptions. See Fixed Series Subscription.
totals	object	Order-level monetary totals. See Order Totals.

Ticket

A single admission to a performance. This is the richest line item type, and references the event, the specific dated instance, and the price band, seat and ticket type it was sold under.

Property	Type	Description
id	string	API ID of this ticket line.
ticketId	string	API ID of the issued ticket record.
attributes	array	Custom per-ticket attributes. See Attribute.
seat	object	Optional. The seat sold, as { id }. Present only for reserved seating events, and omitted for unreserved seating.
band	object	Price band, as { id }. Bands group seats and prices, for example Stalls or Circle.
instance	object	The specific dated performance, as { id }.
event	object	The event, as { id }.
ticketType	object	Ticket type, as { id }, for example Adult, Concession or Child.
discount	money	Discount applied to this ticket.
originalPrice	money	Price before any discount or override.
price	money	Price actually charged for the ticket.
priceOverridden	boolean	true if an operator manually overrode the price.
total	money	Line total including per-ticket commission where charged. Where no commission applies, this matches price.
soldAsPartOfFixedSubscription	boolean	true if this ticket was bought as part of a fixed series or season package.

Merchandise

A non-ticket stock item on the order, for example a programme or CD. Identical stock items on the same order are grouped into one entry with a quantity.

Property	Type	Description
stockId	string	API ID of the stock item.
quantity	integer	Number of units of this stock item on the order.
price	money	Unit price charged.
originalPrice	money	Unit price before discount or override.
discount	money	Discount applied per unit.
priceOverridden	boolean	true if the price was manually overridden.
total	money	Line total: the unit total, including commission where charged, multiplied by quantity.

Donation

A donation made as part of the order.

Property	Type	Description
id	string	API ID of the donation line.
fundId	string	API ID of the fund the donation was made to.
total	money	Donation amount.

Voucher

A gift voucher purchased as part of the order.

Property	Type	Description
id	string	API ID of the voucher.
total	money	Face value, or amount paid for the voucher.

Membership Subscription

A membership purchased on the order. Memberships are often paired with a donation, for example where a membership fee is treated partly as a gift.

Property	Type	Description
id	string	API ID of the membership subscription line.
membershipId	string	API ID of the membership type purchased.
relatedDonationId	string	API ID of an associated donation, if the membership generated one. null otherwise.
total	money	Amount charged for the membership.

Fixed Series Subscription

A fixed series (season ticket or package) subscription. The individual tickets belonging to it appear in the order's tickets array with soldAsPartOfFixedSubscription set to true.

Property	Type	Description
fixedSeriesGroupId	string	API ID of the fixed series group the subscription belongs to.

Order Totals

Order-level monetary summary. All values are in the client's currency.

Property	Type	Description
totalDeliveryCharges	money	Total delivery or fulfilment charges on the order.
totalPaymentCharges	money	Total payment-related charges, for example card fees.
totalTransactionCharges	money	Total per-transaction charges or booking fees.
total	money	Grand total value of the order.

Attribute

Each organisation can define custom fields, known as Attributes, on orders and tickets. They appear as simple name/value pairs. The set of attributes varies per client, so treat them as an open-ended dictionary.

Property	Type	Description
name	string	The configured attribute name.
value	string	The attribute's value for this order or ticket.

Typical Integration Pattern

1. On first run, call with a since far in the past to backfill all orders, paging via paging.next until it's null.
2. Store the largest lastModified you've seen as your high-water mark.
3. On each subsequent run, call ?since={{high-water mark}} and page to the end.
4. Upsert every order by orderId, so that any re-sent boundary records simply overwrite.