Create an agreement

Books the customer into the units named, as a `draft` agreement. Each unit is checked, under a lock, by the same rule every hold, booking and transfer uses: a unit that is archived, not in service (occupied, under maintenance, overlocked or unavailable), already booked, or held for someone else is refused with a 409 that says which, and nothing is created. A unit reserved for this same customer is not refused: the booking takes that reservation up, whether or not `reservation_id` names it. One agreement takes up at most one reservation, so a booking of two reserved units is refused (422) — book each on its own. Refusing held, archived and out-of-service units is a tightening made on 27 September 2026; such units were booked before.

Books the customer into the units named, as a draft agreement. Each unit is checked, under a lock, by the same rule every hold, booking and transfer uses: a unit that is archived, not in service (occupied, under maintenance, overlocked or unavailable), already booked, or held for someone else is refused with a 409 that says which, and nothing is created. A unit reserved for this same customer is not refused: the booking takes that reservation up, whether or not reservation_id names it. One agreement takes up at most one reservation, so a booking of two reserved units is refused (422) — book each on its own. Refusing held, archived and out-of-service units is a tightening made on 27 September 2026; such units were booked before.

Authorization

AuthorizationBearer <token>

Present an API key (sb_live_… / sb_test_…), an OAuth2 access token, or a static token as a Bearer credential. The operator is implied by the credential; it is never in the path. Only a SHA-256 hash of an API key is stored server-side.

In: header

Header Parameters

Idempotency-Key?string

A unique key that makes this mutation safe to retry. Repeats replay the stored response; reuse with a different body returns 409 idempotency_conflict.

Lengthlength <= 255

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

site_id*string

Formatuuid

unit_id?|

The single unit this agreement covers. For several units send unit_ids instead and leave this null — the agreement then records its units as allocations rather than here.

Formatuuid

unit_ids?array<>

Several units on one agreement, any mix of types, all at the agreement's site. Each is held with a pending allocation as the agreement is created, so a unit cannot be booked twice. Sending exactly one is equivalent to sending unit_id.

contact_id*string

Formatuuid

order_id?|

The online checkout's order this booking is for (set by the website's checkout, not by the desk). A repeat request for the booking the order already has is answered with it (200, nothing created); an order that has ended is refused (409). When the order ends unsigned and unpaid, the booking is ended with it (terminated) and its unit goes back on sale.

Formatuuid

licence_fee_minor?|

Periodic licence fee (never "rent"), minor units.

Formatint64

currency?string

ISO-4217 currency of the money fields on this resource.

Length3 <= length <= 3

billing_interval?string

Value in

"week"
"month"
"4week"
"quarter"
"6month"
"year"

move_in_date?|

Formatdate

notice_period_days?|

Days of notice the customer must give to end the licence. When omitted on create, it inherits the site's default_notice_period_days (14 out of the box) — it is NOT 0.

deposit_minor?|

A refundable security deposit taken with this agreement, minor units. Recorded as a held deposit and collected on the agreement's first invoice, as a line outside VAT scope (a security deposit is not consideration until it is applied). Omit it, or send 0, for no deposit.

Formatint64

Range0 <= value

unit_prices?

What each unit costs on this agreement, keyed by unit id — the breakdown behind licence_fee_minor, which stays the total. Recorded against each unit's allocation, so the licence can state a fee per unit and a partial move-out knows what to stop charging for. Every key must be one of this agreement's units. Omit it and no per-unit split is recorded, which is the correct state for a caller that only knows one total.

reservation_id?|

Book the unit a reservation holds, taking the reservation up: it becomes converted and the agreement records it. The unit and the customer must be the reservation's (422), and it must still be held (409 when it has lapsed, been cancelled or been taken up). Booking a unit held for the same customer without naming the reservation takes it up too. Any other customer's hold on the unit is refused with a 409 unit_reserved. When the booking is of that one unit, an omitted licence_fee_minor and move_in_date are the reservation's price and move-in date, or today when that date has passed. A promotion the reservation offered goes on the subscription made for this agreement (POST /v1/subscriptions with no promotion_code).

Formatuuid

Response Body

`application/json`

curl -X POST "https://example.com/agreements" \  -H "Content-Type: application/json" \  -d '{    "site_id": "72771e6a-6f5e-4de4-a5b9-1266c4197811",    "contact_id": "f245e2a3-e141-4d41-912c-b1c1f5bd5598"  }'

{  "data": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "object": "agreement",    "site_id": "72771e6a-6f5e-4de4-a5b9-1266c4197811",    "unit_id": "5becc822-b69e-4e66-a762-ad8e868dcab6",    "contact_id": "f245e2a3-e141-4d41-912c-b1c1f5bd5598",    "order_id": "93101167-9065-4b9c-b98b-5d789a3ed9fe",    "number": "string",    "status": "quote",    "licence_fee_minor": 0,    "currency": "str",    "billing_interval": "week",    "move_in_date": "2019-08-24",    "move_out_date": "2019-08-24",    "notice_given_at": "2019-08-24T14:15:22Z",    "notice_period_days": 0,    "terminated_at": "2019-08-24T14:15:22Z",    "contract_id": "9aafc1a8-e497-46c9-ba0b-bd5b03c353e4",    "created_at": "2019-08-24T14:15:22Z",    "updated_at": "2019-08-24T14:15:22Z",    "reservation_id": "b947feb5-3593-40ee-8244-4428da3fe32d"  }}

{  "data": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "object": "agreement",    "site_id": "72771e6a-6f5e-4de4-a5b9-1266c4197811",    "unit_id": "5becc822-b69e-4e66-a762-ad8e868dcab6",    "contact_id": "f245e2a3-e141-4d41-912c-b1c1f5bd5598",    "order_id": "93101167-9065-4b9c-b98b-5d789a3ed9fe",    "number": "string",    "status": "quote",    "licence_fee_minor": 0,    "currency": "str",    "billing_interval": "week",    "move_in_date": "2019-08-24",    "move_out_date": "2019-08-24",    "notice_given_at": "2019-08-24T14:15:22Z",    "notice_period_days": 0,    "terminated_at": "2019-08-24T14:15:22Z",    "contract_id": "9aafc1a8-e497-46c9-ba0b-bd5b03c353e4",    "created_at": "2019-08-24T14:15:22Z",    "updated_at": "2019-08-24T14:15:22Z",    "reservation_id": "b947feb5-3593-40ee-8244-4428da3fe32d"  }}

{  "error": {    "code": "unauthorized",    "message": "Missing or invalid credential."  }}

{  "error": {    "code": "insufficient_scope",    "message": "The credential lacks a scope required by this endpoint."  }}

{  "error": {    "code": "unit_reserved",    "message": "A12 is reserved for Priya Shah until 6th Oct ’26."  }}

{  "error": {    "code": "validation_error",    "message": "That reservation holds a different unit.",    "details": [      {        "field": "reservation_id",        "issue": "holds a different unit"      }    ]  }}

{  "error": {    "code": "rate_limited",    "message": "Rate limit exceeded. Retry after 7s."  }}

{  "error": {    "code": "validation_error",    "message": "string",    "details": [      {        "field": "string",        "issue": "string"      }    ]  }}

Authorization

Header Parameters

Request Body

Response Body

200application/json

201application/json

401application/json

403application/json

409application/json

422application/json

429application/json

defaultapplication/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`