Skip to content
CreatoRainCreatoRain API

The merchant saw this booking

POST
/reservations/{reservation_id}/acknowledge
curl --request POST \
  --url https://data.creatorain.com/partner/v1/reservations/7f1c2b64-6f6a-4a7d-9a0e-1c2b647f1c2b/acknowledge \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "kind": "forwarded_to_manager" }'

Called when the merchant presses confirm in YOUR UI. Tell us which action it was: forwarded_to_manager (they passed it to whoever is on the floor) or acknowledged_self (they dealt with it themselves).

This is the one thing in the whole chain we cannot see. We know the notice went out, we know the creator confirmed, and we find out afterwards whether anybody arrived. Whether a person at the restaurant actually read it is yours to tell us, and it is the link that turns out to have been broken when a visit goes wrong.

IDEMPOTENT PER (reservation_id, kind). A retry answers 200 with the instant we ALREADY HOLD, never a new one: that instant is when the merchant pressed the button, and a lost response must not be able to move it. The two kinds are independent, so a booking that was forwarded AND acknowledged carries both, each with its own time.

PARTNER KEY ONLY. A per-store dashboard token cannot write here, which is the reason it stays a browser-safe credential: send the acknowledgement from your own backend.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
reservation_id
required
string format: uuid

OUR id for the booking, as it reached you in a reservation.* webhook or in a reservations list. A uuid: anything else is refused with 400 validation_error naming reservation_id, which tells you to look at your code rather than at your data.

Example 

7f1c2b64-6f6a-4a7d-9a0e-1c2b647f1c2b

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

What the merchant did. Two values and no third: this is the whole product question, and a value we accepted but had no meaning for would leave both sides believing something had been recorded.

object
kind
required

forwarded_to_manager: they passed the booking to whoever is on the floor. acknowledged_self: they dealt with it themselves.

string
Allowed values: forwarded_to_manager acknowledged_self

Examples

Exampleforwarded

Passed to the manager on duty

{
  "kind": "forwarded_to_manager"
}

Responses

Section titled “Responses”

200

Section titled “200”

Recorded. The same body on the first call and on every repeat.

Media typeapplication/json

What we now hold. On a repeat this is the FIRST acknowledgement’s time, not the retry’s. No personal data: an acknowledgement says a booking was seen, not who is coming.

object
reservation_id
required
string format: uuid
kind
required
string
Allowed values: forwarded_to_manager acknowledged_self
acknowledged_at
required

RFC 3339 with the STORE’S offset, because “the manager saw this at 4 pm” only means anything at the restaurant.

string
nullable
timezone
required
string
nullable

Example 

{
  "kind": "forwarded_to_manager",
  "acknowledged_at": "2026-09-11T16:04:12-07:00",
  "timezone": "America/Los_Angeles"
}

400

Section titled “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

Section titled “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"
  }
}

404

Section titled “404”

reservation_not_found. No store enrolled under this key holds that booking. One answer whether the booking belongs to another partner, to another account, or to nobody: a caller who could tell those apart could count our bookings by walking ids.

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

Section titled “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"
  }
}