Every store's bookings, for your operations desk

GET

/reservations

curl --request GET \
  --url 'https://data.creatorain.com/partner/v1/reservations?from=2026-09-01&to=2026-09-30&status=pending&acknowledged=false&limit=50' \
  --header 'Authorization: Bearer <token>'

• Production (live stores; a live key is issued per partner)
• Sandbox, for integration testing (test keys, test stores)

The same rows as the per-store list, across every store enrolled under your key, each row also carrying partner_location_id and location_id so it can be attributed.

YOUR “NEEDS FOLLOW-UP” LIST IS THIS CALL WITH FOUR PARAMETERS:

GET /partner/v1/reservations?status=confirmed&from=2026-09-11&to=2026-09-12&acknowledged=false

Those are the visits arriving that nobody at the restaurant has confirmed seeing, and they are the same bookings unacknowledged_upcoming on GET /summary counts, so a desk can go from the number straight to the rows.

PARTNER KEY ONLY. A store token cannot read this: a merchant’s browser must never be able to read the whole chain’s schedule, which is the reason the per-store credential exists.

Authorizations

• partnerApiKey

Parameters

Query Parameters

from

string format: date

Earliest VISIT DATE to include, YYYY-MM-DD in the store’s own calendar. A value we cannot read is refused rather than ignored: a reconciliation run whose window was silently dropped would read the whole book and report it as one month.

Example

2026-09-01

to

string format: date

Latest VISIT DATE to include, YYYY-MM-DD, inclusive.

Example

2026-09-30

status

string

Allowed values: pending confirmed rejected cancelled completed no_show

Return only bookings in this state.

acknowledged

boolean

true for bookings a human at the restaurant has confirmed seeing (you told us so with POST /reservations/{reservation_id}/acknowledge), false for the ones nobody has. Omit it for both.

1 and 0 are accepted as well. ANY OTHER VALUE IS REFUSED with 400 validation_error rather than ignored, and that is on purpose: a follow-up list that silently returned every booking would show your desk a queue of work that has already been done.

Example

false

cursor

string

The next_cursor from the previous page, sent back UNCHANGED. Omit it for the first page.

It is opaque: do not build one yourself. It names a POSITION in the sort order rather than a count of rows to skip, which is why a page stays stable when a booking is touched between two requests. A cursor we did not issue is refused with 400 validation_error, rather than silently treated as the first page, so a broken client fails loudly instead of looping over page one for ever.

limit

integer

default: 50 >= 1 <= 200

Rows per page. Default 50, maximum 200. A larger value is CLAMPED to 200 rather than refused, so you never have to guess the ceiling.

Responses

200

A page of bookings across every store of this key.

Media typeapplication/json

object

items

required

Array<object>

One creator booking. NO PERSONAL DATA: no guest name, email or phone, no internal notes, and no free-text party note (those routinely carry dietary and medical detail).

object

booked_by

Who made the booking. Every booking on this API is a CreatoRain creator visit, so this is always creatorain. Also on the reservation webhook events.

string

Allowed values: creatorain

no_charge

Always true: the visit is at no charge to the store (show it as “CreatoRain, no charge”). Also on the reservation webhook events.

boolean

reservation_id

string format: uuid

status

string

Allowed values: pending confirmed rejected cancelled completed no_show

arrive_at

RFC 3339 with the STORE’S offset. The digits are the restaurant’s wall clock, so render them as they are; do not convert.

string

nullable

timezone

string

nullable

party_size

How many people are coming, the creator included. Always a number: 2 (the creator plus one guest) when the booking does not state one. The same value the webhook events send.

integer

creator

As much of the creator as an outside system may see. Their contact details are never returned on this API.

object

handle

Their public handle.

string

nullable

followers

Cross-platform follower total, not one platform’s count.

integer

nullable

platforms

The platforms they publish on. Always an array, never null.

Array<string>

dish

The dish chosen for this booking, or null when none was chosen. Never a guess from the store’s menu. The same value the webhook events send.

string

nullable

created_at

RFC 3339 with the store’s offset.

string

nullable

updated_at

RFC 3339 with the store’s offset. This is the sort key of the list.

string

nullable

acknowledged_at

When a human at the restaurant told us they had seen this booking, RFC 3339 with the STORE’S offset. Null when nobody has, which is what acknowledged=false filters on.

THE EARLIEST ACKNOWLEDGEMENT, not the latest. A booking can carry both kinds (forwarded to the manager, and acknowledged), and the question this answers is “has anybody seen this yet, and when”.

string

nullable

acknowledged_kind

Which kind that earliest acknowledgement was. Null when there is none.

string

nullable

Allowed values: forwarded_to_manager acknowledged_self

partner_location_id

Present only on GET /reservations, where a row has to say which store it belongs to.

string

location_id

Present only on GET /reservations.

string format: uuid

next_cursor

required

Send this back as cursor for the next page. NULL means this was the last page, and it is honest about that: we read one row beyond your limit to answer the question, so a page that happens to be exactly full does not cost you an extra empty request.

string

nullable

Example

{
  "items": [
    {
      "booked_by": "creatorain",
      "no_charge": true,
      "status": "pending",
      "arrive_at": "2026-09-14T19:00:00-07:00",
      "timezone": "America/Los_Angeles",
      "party_size": 2,
      "creator": {
        "handle": "example_creator",
        "followers": 48213,
        "platforms": [
          "instagram",
          "tiktok"
        ]
      },
      "acknowledged_at": "2026-09-11T16:04:12-07:00",
      "acknowledged_kind": "forwarded_to_manager"
    }
  ]
}

400

validation_error. field names the offending parameter.

Media typeapplication/json

object

error

required

object

code

required

The stable value to branch on.

string

Allowed values: unauthorized forbidden_ip rate_limited validation_error location_already_exists location_not_found location_terminated reservation_not_found conflict internal_error

message

required

A human sentence. Copy, not contract; it may be reworded.

string

field

The request field at fault, dotted for a nested one (plan.term_months).

string

Example

{
  "error": {
    "code": "unauthorized"
  }
}

401

unauthorized. A missing, malformed, unknown or revoked key; or an invalid, expired or wrong-store dashboard token. One answer for every case on purpose: the holder of a bad credential learns nothing from the difference.

Media typeapplication/json

object

error

required

object

code

required

The stable value to branch on.

string

Allowed values: unauthorized forbidden_ip rate_limited validation_error location_already_exists location_not_found location_terminated reservation_not_found conflict internal_error

message

required

A human sentence. Copy, not contract; it may be reworded.

string

field

The request field at fault, dotted for a nested one (plan.term_months).

string

Example

{
  "error": {
    "code": "unauthorized"
  }
}

429

rate_limited. Over this key’s requests-per-minute ceiling.

Media typeapplication/json

object

error

required

object

code

required

The stable value to branch on.

string

Allowed values: unauthorized forbidden_ip rate_limited validation_error location_already_exists location_not_found location_terminated reservation_not_found conflict internal_error

message

required

A human sentence. Copy, not contract; it may be reworded.

string

field

The request field at fault, dotted for a nested one (plan.term_months).

string

Example

{
  "error": {
    "code": "unauthorized"
  }
}