# One store's creator bookings GET /locations/{partner\_location\_id}/reservations Select code sampleFetchcURL ```js const url = 'https://data.creatorain.com/partner/v1/locations/store_123/reservations?from=2026-09-01&to=2026-09-30&status=pending&acknowledged=false&limit=50'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request GET \ --url 'https://data.creatorain.com/partner/v1/locations/store_123/reservations?from=2026-09-01&to=2026-09-30&status=pending&acknowledged=false&limit=50' \ --header 'Authorization: Bearer ' ``` - Production (live stores; a live key is issued per partner) - Sandbox, for integration testing (test keys, test stores) The main query behind a merchant’s dashboard. Newest touched first. EITHER CREDENTIAL: the partner key or that store’s own token. `acknowledged=false` narrows it to the bookings nobody at the restaurant has confirmed seeing, which is what a merchant’s own “still to confirm” panel filters on. NO PERSONAL DATA IS RETURNED, and there is no free-text search parameter, because our reservation search index is built from exactly the fields this projection withholds. ## Authorizations - **[partnerApiKey](/partner-api/reference/#partnerapikey)** - **[storeTokenHeader](/partner-api/reference/#storetokenheader)** - **[storeTokenQuery](/partner-api/reference/#storetokenquery)** ## Parameters ### Path Parameters **partner\_location\_id** required string <= 200 characters YOUR id for the store, as you sent it to `POST /locations`. #### Example ``` store_123 ``` ### 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 ```json 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. Media typeapplication/json object **items** required Array 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 **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 ```json { "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 ```json { "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 ```json { "error": { "code": "unauthorized" } } ``` ### 404 `location_not_found`. No store of this key carries that `partner_location_id`. 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 ```json { "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 ```json { "error": { "code": "unauthorized" } } ```