Reference

API reference

Every resource in the Coastly Partner API. All paths are relative to the base URL, all requests use bearer auth, and all bodies are JSON.

Base URL

https://coastly.surf/api/v1

Authentication

Authorization: Bearer ck_live_…

Conventions used throughout

• Errors follow one envelope; see the error codes. Every response includes an X-Request-Id header.
• List endpoints are cursor-paginated (limit default 50, max 100; cursor) and return { data, has_more, next_cursor }. Many accept updated_since. See pagination.
• Writes to reservations and orders require an Idempotency-Key header. See idempotency.
• Amounts are integers in the currency's minor unit, paired with a currency field.

Properties Room types Availability Rates Reservations Orders Invoices Commission

Properties

A property is a bookable location: a hotel, hostel, or stay.

GET/propertiesproperties:read

List properties. Accepts limit, cursor, and updated_since.

shell

curl "https://coastly.surf/api/v1/properties?limit=50" \
  -H "Authorization: Bearer $COASTLY_KEY"

200 OK

{
  "data": [
    {
      "id": "prop_1a2b3c",
      "name": "Casa Marea",
      "type": "hotel",
      "town": "Playa Venao",
      "timezone": "America/Panama",
      "currency": "USD",
      "status": "active"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

POST/propertiesproperties:write

Create a property.

shell

curl -X POST https://coastly.surf/api/v1/properties \
  -H "Authorization: Bearer $COASTLY_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Casa Marea", "type": "hotel", "town": "Playa Venao", "currency": "USD" }'

GET/properties/{id}properties:read

Retrieve a single property by id.

PATCH/properties/{id}properties:write

Update a property. Send only the fields you want to change.

shell

curl -X PATCH https://coastly.surf/api/v1/properties/prop_1a2b3c \
  -H "Authorization: Bearer $COASTLY_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "inactive" }'

Room types

Room types describe the sellable units within a property, with capacity and add-ons.

GET/room-typesroom_types:read

List room types. Filterable by property.

Parameter	Type	Description
`property_id`	string	Only room types for this property.
`limit`	integer	Page size (default 50, max 100).
`cursor`	string	Pagination cursor.
`updated_since`	string	ISO 8601; only records changed since.

200 OK

{
  "data": [
    {
      "id": "rt_ocean_king",
      "property_id": "prop_1a2b3c",
      "name": "Ocean King",
      "max_guests": 2,
      "units": 4,
      "addons": [{ "id": "addon_bfast", "name": "Breakfast", "price": 900 }]
    }
  ],
  "has_more": false,
  "next_cursor": null
}

POST/room-typesroom_types:write

Create a room type under a property.

GET/room-types/{id}room_types:read

Retrieve a single room type.

PATCH/room-types/{id}room_types:write

Update a room type.

A property has at most one default room type. A POST or PATCH that sets is_default: true while the property already has a default is rejected with 409 conflict and nothing is written. To move the default, first PATCH the current default with is_default: false, then set the new one.

409 Conflict

{
  "error": {
    "code": "conflict",
    "message": "This property already has a default room. Unset it first (PATCH that room with is_default: false), then set this one.",
    "request_id": "req_8Kd2p1"
  }
}

Availability

Availability is the number of sellable units per room type per date. Read it or push it for a date range.

GET/availabilityavailability:read

Read availability for a room type across a date range.

Parameter	Type	Description
`room_type_id`	string	Required. The room type to query.
`from`	string	Required. Start date (YYYY-MM-DD), inclusive.
`to`	string	Required. End date (YYYY-MM-DD), exclusive.

shell

curl "https://coastly.surf/api/v1/availability?room_type_id=rt_ocean_king&from=2026-07-01&to=2026-07-05" \
  -H "Authorization: Bearer $COASTLY_KEY"

200 OK

{
  "room_type_id": "rt_ocean_king",
  "days": [
    { "date": "2026-07-01", "available": 4, "closed": false },
    { "date": "2026-07-02", "available": 2, "closed": false },
    { "date": "2026-07-03", "available": 0, "closed": true },
    { "date": "2026-07-04", "available": 3, "closed": false }
  ]
}

PUT/availabilityavailability:write

Set availability for specific dates. Days not included are left unchanged.

shell

curl -X PUT https://coastly.surf/api/v1/availability \
  -H "Authorization: Bearer $COASTLY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "room_type_id": "rt_ocean_king",
    "days": [
      { "date": "2026-07-03", "available": 4, "closed": false },
      { "date": "2026-07-04", "closed": true }
    ]
  }'

Rates

Rates are the nightly price per room type per date, in the property's currency (minor units).

GET/ratesrates:read

Read rates for a room type across a date range. Accepts room_type_id, from, to.

200 OK

{
  "room_type_id": "rt_ocean_king",
  "currency": "USD",
  "days": [
    { "date": "2026-07-01", "rate": 14000 },
    { "date": "2026-07-02", "rate": 14000 },
    { "date": "2026-07-03", "rate": 16500 }
  ]
}

PUT/ratesrates:write

Set nightly rates for specific dates.

shell

curl -X PUT https://coastly.surf/api/v1/rates \
  -H "Authorization: Bearer $COASTLY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "room_type_id": "rt_ocean_king",
    "currency": "USD",
    "days": [
      { "date": "2026-07-03", "rate": 16500 },
      { "date": "2026-07-04", "rate": 16500 }
    ]
  }'

Reservations

Reservations are bookings against a property's room types. Writes require an Idempotency-Key and are conflict-safe.

GET/reservationsreservations:read

List reservations. Accepts limit, cursor, updated_since.

POST/reservationsreservations:write

Create a reservation. Requires the Idempotency-Key header.

Parameter	Type	Description
`property_id`	string	Required. Property being booked.
`check_in`	string	Required. YYYY-MM-DD.
`check_out`	string	Required. YYYY-MM-DD, after check_in.
`guests`	integer	Required. Total guests.
`rooms`	array	Required. [{ room_type_id, units, guests }].
`addons`	array	Optional. [{ addon_id, qty }].
`customer_id`	string	Optional. Existing customer to attach.
`guest_name`	string	Optional when customer_id is set.
`guest_email`	string	Optional when customer_id is set.

shell

curl -X POST https://coastly.surf/api/v1/reservations \
  -H "Authorization: Bearer $COASTLY_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f9a1c7e-2b6d-4a11-9c2e-8d7f4b1a0e55" \
  -d '{
    "property_id": "prop_1a2b3c",
    "check_in": "2026-07-12",
    "check_out": "2026-07-15",
    "guests": 2,
    "rooms": [{ "room_type_id": "rt_ocean_king", "units": 1, "guests": 2 }],
    "addons": [{ "addon_id": "addon_bfast", "qty": 2 }],
    "guest_name": "Ana Rivera",
    "guest_email": "ana@example.com"
  }'

201 Created

{
  "id": "res_9Fq2c8",
  "property_id": "prop_1a2b3c",
  "status": "confirmed",
  "check_in": "2026-07-12",
  "check_out": "2026-07-15",
  "guests": 2,
  "rooms": [{ "room_type_id": "rt_ocean_king", "units": 1, "guests": 2 }],
  "guest_name": "Ana Rivera",
  "total": { "amount": 42000, "currency": "USD" },
  "created": 1751328000
}

If the rooms are no longer available you receive 409 with reservation_conflict or availability_closed.

GET/reservations/{id}reservations:read

Retrieve a single reservation.

PATCH/reservations/{id}reservations:write

Modify a reservation (dates, rooms, guests, add-ons). Requires Idempotency-Key.

POST/reservations/{id}/cancelreservations:write

Cancel a reservation.

shell

curl -X POST https://coastly.surf/api/v1/reservations/res_9Fq2c8/cancel \
  -H "Authorization: Bearer $COASTLY_KEY"

Orders

Orders are marketplace, F&B, and services purchases in a normalized shape. See the POS guide for the full object.

GET/ordersorders:read

List orders. Accepts limit, cursor, updated_since.

POST/ordersorders:write

Create an order. Requires the Idempotency-Key header.

200 OK

{
  "id": "ord_5T8w2h",
  "status": "confirmed",
  "vendor_id": "prop_1a2b3c",
  "items": [{ "sku": "ceviche-classic", "qty": 2, "line_total": 2000 }],
  "totals": { "subtotal": 2000, "delivery_fee": 300, "total": 2300, "currency": "USD" },
  "created": 1751328000
}

GET/orders/{id}orders:read

Retrieve a single order.

PATCH/orders/{id}orders:write

Update an order (for example, advance its status).

Invoices

Read-only access to issued invoices.

GET/invoicesinvoices:read

List invoices. Accepts limit, cursor, updated_since.

200 OK

{
  "data": [
    {
      "id": "inv_3Qr8",
      "number": "2026-000148",
      "status": "paid",
      "amount": { "total": 42000, "currency": "USD" },
      "issued_at": "2026-07-15T12:00:00Z",
      "paid_at": "2026-07-15T12:04:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Commission

Read-only access to Coastly commission statements. Commission is calculated weekly.

GET/commissioncommission:read

List commission statements. Accepts limit, cursor, updated_since.

200 OK

{
  "data": [
    {
      "id": "com_7Yh2",
      "period_start": "2026-06-22",
      "period_end": "2026-06-28",
      "gross": { "amount": 512000, "currency": "USD" },
      "rate": 0.15,
      "commission": { "amount": 76800, "currency": "USD" },
      "status": "settled"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Next steps

Set up signed event delivery with the webhooks guide, or review authentication and error handling.