Enquiries Channel manager Bookings Your website Booking engine Pricing Log in Sign up
v2026-09

Create a booking

Write a booking your system took into Doorloom. Like every create on this API it requires an idempotency key, and it is the only endpoint that can refuse for reasons of inventory.

POST https://doorloom.com/api/integrations/v1/bookings Idempotency-Key required

Headers

Field Type Required Description
Authorization string Required Bearer <your API key>.
Content-Type string Required application/json.
Idempotency-Key string Required 8 to 128 characters, unique per create attempt. A UUID is ideal.

The idempotency contract

Retrying with the same key and the same body replays the original response byte-for-byte and never creates a second booking. The same key with a different body is refused with IDEMPOTENCY_KEY_REUSED. Keys are remembered for 24 hours and are shared with the property creates, so never reuse a key across endpoints.

Refusals are stored too. If a create fails with 409 UNAVAILABLE, retrying the same key replays that refusal rather than racing for the room again — so a naive retry loop cannot turn a conflict into a double booking.

Request body

Body

Field Type Required Description
external_booking_id string Required Your id for this booking. Max 128 characters. Unique within your integration — sending one twice returns the existing booking rather than creating another.
property object Required Which property is being booked.
property.doorloom_id integer Optional Doorloom's property id.
property.external_id string Optional Your alias for the property. Max 128 characters.
units array Required One entry per unit being booked. A two-unit stay is two entries. 1 to 20 entries.
units[].inventory_id integer Optional Pin a specific Doorloom unit.
units[].external_unit_id string Optional Pin a specific unit by your alias. Max 128 characters.
units[].adults integer Required 1 to 50.
units[].children integer Optional 0 to 50. Defaults to 0.
units[].meal_plan string Optional EP, CP, MP or AP.
units[].stay_price number Optional Room money for this unit across the whole stay. See pricing below.
check_in string Required YYYY-MM-DD. May not be before yesterday.
check_out string Required YYYY-MM-DD. Must be after check_in. Exclusive — the guest leaves this morning.
guest object Required The lead guest.
guest.name string Required Max 255 characters.
guest.phone_code string Optional Dialling code, max 8 characters. Defaults to +91.
guest.mobile string Required Max 20 characters.
guest.email string Optional Valid email, max 255 characters.
guest.country string Optional Max 64 characters. Stored, but not returned in the booking object.
pricing object Required What the guest is being charged.
pricing.total number Required The booking total. Doorloom stores it as given and does not re-price it.
pricing.currency string Optional ISO 4217 code of every pricing amount. Defaults to INR on create; omitted on update keeps the stored code. Unsupported codes are refused with a validation error.
pricing.includes_gst boolean Optional true or omitted: total already includes GST, and the invoice splits GST out of it. false: no GST applies to this booking. Doorloom never adds GST on top of total. See GST below.
pricing.breakdown object Optional Free-form. Stored verbatim and handed back to you unchanged; Doorloom never interprets it.
payment object Optional What you have collected so far.
payment.status string Optional paid, partial or unpaid. paid with no amount_collected means paid in full: the whole total is recorded as collected.
payment.amount_collected number Optional Recorded on the booking as a payment, so balance = total − payments.
payment.collected_by string Optional partner or host. Recorded in the note on the payment; it does not change any amount.
payment.reference string Optional Your payment reference. Max 128 characters.
source object Optional Where the booking came from.
source.channel string Optional e.g. airbnb. Max 64 characters. Set once at create — it cannot be patched later.
source.reference string Optional Your reference on that channel. Max 128 characters.
status string Optional confirmed or pending. Defaults to confirmed. Both hold inventory.
notes string Optional Max 2000 characters. Shown to the host on the booking; use it for special requests or children's ages.
billing object Optional Bill-to details for a business guest. They appear on the GST invoice.
billing.gstin string Optional The guest's GSTIN: 15 characters with a valid check character, any case (stored uppercase). An invalid GSTIN is a 422.
billing.company_name string Optional Registered company name. Max 255 characters.
billing.address string Optional Billing address. Max 500 characters.

Give the property as either doorloom_id or external_id. Sending neither is a 422. Stay length is capped; a stay longer than the platform maximum is refused on check_out.

Stay rules are yours to apply

A create is checked for availability and nothing else. The host's minimum and maximum stay, advance notice and same-day cutoff, which Doorloom enforces on the brand's own website, are not applied here. Read them from restrictions.changed and apply them before you take the booking.

Pricing: you set it

Doorloom stores pricing.total as the booking total and does not re-derive it. Your system is the source of truth for the price of a booking it took.

Per-unit stay_price values are used when every unit has one. If any is missing, the total is split evenly across units instead. Send all of them or none.

payment.amount_collected is recorded on the booking as a payment, and pricing.balance is total minus every payment on the booking, including any the host records in the app. To mark a booking as paid in full, send payment.status: "paid", with or without an amount_collected equal to the total. A later PATCH with a new amount_collected updates that same payment; 0 removes it.

GST

GST on a booking you created is fixed when you write it, from pricing.includes_gst, and never re-worked out from the host's settings later.

  • true or omitted: total already includes GST. If the host is GST-registered, the invoice splits GST out of it at the accommodation rate for each night's value; if not, no GST applies.
  • false: no GST applies to this booking.

Either way total is what the guest pays; Doorloom never adds GST on top. A booking in a currency other than INR carries no GST. The response's pricing.gst shows the mode and amount that were fixed. For a business guest, send their details in billing; they appear as the buyer on the GST invoice.

Units: pinning versus allocating

Each entry in units[] is one unit of the property for the whole stay.

  • Give inventory_id or external_unit_id to pin a specific unit.
  • Give neither to have Doorloom allocate any free unit.

A pinned unit that is taken is refused, never swapped

Doorloom will not quietly move the guest to a different room. If you pinned it and it is not free, you get 409 UNAVAILABLE and nothing is written. Omit the unit reference if you are happy with any room.

Example

Request json
{
    "external_booking_id": "PMS-100234",
    "property": {
        "external_id": "VILLA-9"
    },
    "units": [
        {
            "external_unit_id": "ROOM-A",
            "adults": 2,
            "children": 1,
            "meal_plan": "CP",
            "stay_price": 8000
        },
        {
            "adults": 2,
            "meal_plan": "EP",
            "stay_price": 8000
        }
    ],
    "check_in": "2026-10-12",
    "check_out": "2026-10-14",
    "guest": {
        "name": "Asha Rao",
        "phone_code": "+91",
        "mobile": "9876543210",
        "email": "[email protected]",
        "country": "IN"
    },
    "pricing": {
        "total": 18600,
        "currency": "INR",
        "includes_gst": true,
        "breakdown": {
            "room": 16000,
            "meals": 2600
        }
    },
    "payment": {
        "status": "partial",
        "amount_collected": 4000,
        "collected_by": "partner",
        "reference": "pay_123"
    },
    "source": {
        "channel": "airbnb",
        "reference": "HM-77"
    },
    "status": "confirmed",
    "notes": "Late arrival, around 11pm",
    "billing": {
        "gstin": "29AAACA1234A1ZG",
        "company_name": "Acme Travels Pvt Ltd",
        "address": "12 MG Road, Bengaluru"
    }
}

The first unit is pinned to ROOM-A; the second is left for Doorloom to allocate.

Responses

Field Type Description
201 created A new booking. data is the booking object.
200 duplicate A booking with this external_booking_id already exists. It is returned unchanged, with data.duplicate: true added. Treat this as success.
Response 201 (abridged) json
{
    "success": true,
    "message": "Booking created",
    "data": {
        "id": 55231,
        "external_booking_id": "PMS-100234",
        "revision": 1,
        "origin": "partner",
        "status": "confirmed",
        "property": {
            "doorloom_id": 902,
            "external_id": "VILLA-9"
        },
        "check_in": "2026-10-12",
        "check_out": "2026-10-14",
        "guests": {
            "adults": 4,
            "children": 1
        },
        "units": [
            "…"
        ],
        "pricing": {
            "currency": "INR",
            "total": 18600,
            "advance": 4000,
            "balance": 14600
        },
        "…": "…"
    }
}

When the stay is not available

A 409 UNAVAILABLE means no free unit for the whole stay, or a pinned unit that is taken. Nothing is written. The response carries the per-night picture so you can correct your calendar without a second call.

Response 409 json
{
    "success": false,
    "code": "UNAVAILABLE",
    "message": "Amber Villa, Alibaug is not available for the selected dates.",
    "errors": {
        "availability": {
            "property": {
                "doorloom_id": 902
            },
            "window": {
                "from": "2026-10-12",
                "to": "2026-10-13"
            },
            "total_units": 2,
            "dates": [
                {
                    "date": "2026-10-12",
                    "available_units": 1,
                    "total_units": 2,
                    "is_blocked": false,
                    "block_scope": null,
                    "units_cap": null
                },
                {
                    "date": "2026-10-13",
                    "available_units": 0,
                    "total_units": 2,
                    "is_blocked": false,
                    "block_scope": null,
                    "units_cap": null
                }
            ]
        }
    }
}

The conflict window ends on the last night

errors.availability.window.to is check_out minus one day — the last night of the stay, not the departure date. It lines up with dates[], which lists nights.

The dates[] array is exactly an availability.changed payload minus units[], so you can feed it through the same code path.

Errors

Errors

Status Code Meaning
422 VALIDATION_FAILED The request body failed validation. errors is Laravel's field bag: an object keyed by field path, each holding an array of messages.
422 IDEMPOTENCY_KEY_REQUIRED A create — POST /bookings, POST /properties or POST /properties/bulk — was sent without a usable Idempotency-Key header.
422 IDEMPOTENCY_KEY_REUSED The key has already been used, with a different request body. Doorloom fingerprints the body (SHA-256 over key-sorted JSON), so key order does not matter but any value change does. Keys are shared across every create endpoint, so a booking key resent on a property create is a reuse too.
409 IN_PROGRESS Two of your requests overlapped and this one lost. Either the same Idempotency-Key is still being processed, or another request is creating the same external id or changing the same property.
422 PROPERTY_NOT_MAPPED The property reference is missing, unknown, or outside your integration's coverage. Coverage is what you created through POST /properties plus what Doorloom staff mapped, and only ever includes properties the brand owner owns outright, never cohosted ones.
422 PROPERTY_ARCHIVED The property exists and is covered, but the host has archived it. Archived properties are off-market: they cannot take bookings, and they cannot be edited through the API.
422 UNIT_NOT_MAPPED A booking's units[] line, or the unit of an availability write, names a unit alias Doorloom does not know, or one that belongs to a different property.
422 UNIT_INACTIVE The unit is mapped but no longer sellable — deactivated or deleted by the host.
409 UNAVAILABLE There is no free unit for the whole stay, or a unit you pinned is taken. Nothing was written. Doorloom never silently swaps a pinned unit for another.
429 RATE_LIMITED You exceeded one of the rate limits. The standard Retry-After and X-RateLimit-* headers are set on the response. The second message is the calendar-write limit: 10 calls per property per hour on each of PUT availability, rates and restrictions.

What happens afterwards

A successful create emits an availability.changed event for the property, because inventory moved. It requires no action from you.

It does not emit a booking.changed: the 201 is your confirmation. That event starts with the first change after the create, whether it is your own update or cancel echoed back with origin: "partner", or the host editing the booking in the app.

If your integration has host notifications switched on (the default), the host gets a notification in the Doorloom app for a booking created as confirmed. Doorloom does not send the guest a WhatsApp message or an email for a booking created through this API, so your own confirmation is the one the guest receives.

Something unclear or wrong on this page? Write to [email protected] and tell us which page — we would rather fix the doc than answer the ticket twice.