91:T3f17,# Handle checks, refusals and errors Mandate responses answer two separate questions: 1. **Could the API understand and process the request?** The HTTP status answers this. 2. **Does the authority permit the requested action?** A result boolean and `checks` answer this. A robust integration handles both layers. HTTP 200 alone is never proof that the user authorized a charge. ## The control flow For issue: 1. require HTTP 201, 2. save `id` and `confirm_expires_at`. For confirm: 1. require HTTP 200, 2. require `confirmed: true`, 3. save `token` unchanged. For verify: 1. require HTTP 200, 2. require `valid: true`, 3. require every returned check to have `ok: true`. Settlement applies the same pattern to exercise with `exercised: true`. > [!warning] > Do not collapse transport success and authorization into one “success” branch. Log the result boolean, failed checks, mandate ID, and reconciliation reference separately. ## HTTP status reference | Status | Meaning | Action | |---|---|---| | 200 | The request was processed. The body may still be a refusal. | Read the operation boolean, `reason`, and `checks`. | | 201 | A mandate was issued. | Save `id` and `confirm_expires_at`; the mandate is still pending. | | 401 | The API key or bearer token is missing or invalid. | Fix the credential; the request never reached the service. | | 404 | The path mandate ID does not exist. | Stop retrying that ID. | | 422 | Body or query validation failed. | Fix the field identified by `detail`; nothing was created. | Successful responses do not use a shared envelope. The list endpoint returns `{ "user_id", "mandates" }`; other operations return their resource or result directly. ## Confirmation refusals Confirm returns HTTP 200 with `confirmed: false` and no token when the draft cannot become authority: | `reason` | Returned status | Recovery | |---|---|---| | `already confirmed` | Usually `active` | Retrieve the mandate and use its existing token. | | `revoked` | `revoked` | Issue a new mandate only after obtaining new user intent. | | `confirmation window expired` | `expired` | Issue a new proposal and present it again. | Concurrent confirmation requests are serialized by a database uniqueness rule. One wins; the other receives `already confirmed`. ## Verification order ![Token, lifecycle, binding, constraint, and amount checks run in a fixed order. Exercise adds jti_match after the shared pipeline.](data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA3MjAgMTU4IiByb2xlPSJpbWciIGFyaWEtbGFiZWxsZWRieT0idGl0bGUgZGVzYyI+CiAgPHRpdGxlIGlkPSJ0aXRsZSI+VmVyaWZpY2F0aW9uIG9yZGVyPC90aXRsZT4KICA8ZGVzYyBpZD0iZGVzYyI+Q2hlY2tzIHJ1biBpbiBhIGZpeGVkIG9yZGVyOiB0b2tlbiAoc2lnbmF0dXJlLCBleHBpcnkpLCBsaWZlY3ljbGUgKGtub3duLCBjb25maXJtZWQsIHJldm9jYXRpb24sIHNpbmdsZV91c2UpLCBjYWxsZXIgKGFnZW50X2JpbmRpbmcpLCBjaGFyZ2UgKGNvbnN0cmFpbnRzLCB0aGVuIGFtb3VudCBvciBidWRnZXQpLiBFeGVyY2lzZSBhbG9uZSBhZGRzIGp0aV9tYXRjaC48L2Rlc2M+CiAgPGRlZnM+CiAgICA8bWFya2VyIGlkPSJhIiBtYXJrZXJVbml0cz0idXNlclNwYWNlT25Vc2UiIG1hcmtlcldpZHRoPSI5IiBtYXJrZXJIZWlnaHQ9IjkiIHJlZlg9IjgiIHJlZlk9IjQuNSIgb3JpZW50PSJhdXRvIj48cGF0aCBkPSJNMCwwIEw5LDQuNSBMMCw5IFoiIGNsYXNzPSJhaCIvPjwvbWFya2VyPgogICAgPG1hcmtlciBpZD0iYS10ZWFsIiBtYXJrZXJVbml0cz0idXNlclNwYWNlT25Vc2UiIG1hcmtlcldpZHRoPSI5IiBtYXJrZXJIZWlnaHQ9IjkiIHJlZlg9IjgiIHJlZlk9IjQuNSIgb3JpZW50PSJhdXRvIj48cGF0aCBkPSJNMCwwIEw5LDQuNSBMMCw5IFoiIGNsYXNzPSJhaC10ZWFsIi8+PC9tYXJrZXI+CiAgICA8bWFya2VyIGlkPSJhLWFtYmVyIiBtYXJrZXJVbml0cz0idXNlclNwYWNlT25Vc2UiIG1hcmtlcldpZHRoPSI5IiBtYXJrZXJIZWlnaHQ9IjkiIHJlZlg9IjgiIHJlZlk9IjQuNSIgb3JpZW50PSJhdXRvIj48cGF0aCBkPSJNMCwwIEw5LDQuNSBMMCw5IFoiIGNsYXNzPSJhaC1hbWJlciIvPjwvbWFya2VyPgogICAgPG1hcmtlciBpZD0iYS1yZWQiIG1hcmtlclVuaXRzPSJ1c2VyU3BhY2VPblVzZSIgbWFya2VyV2lkdGg9IjkiIG1hcmtlckhlaWdodD0iOSIgcmVmWD0iOCIgcmVmWT0iNC41IiBvcmllbnQ9ImF1dG8iPjxwYXRoIGQ9Ik0wLDAgTDksNC41IEwwLDkgWiIgY2xhc3M9ImFoLXJlZCIvPjwvbWFya2VyPgogICAgPG1hcmtlciBpZD0iYS1vcGVuIiBtYXJrZXJVbml0cz0idXNlclNwYWNlT25Vc2UiIG1hcmtlcldpZHRoPSI5IiBtYXJrZXJIZWlnaHQ9IjkiIHJlZlg9IjgiIHJlZlk9IjQuNSIgb3JpZW50PSJhdXRvIj48cGF0aCBkPSJNMCwwIEw5LDQuNSBMMCw5IiBjbGFzcz0iYWgtb3BlbiIvPjwvbWFya2VyPgogIDwvZGVmcz4KICA8c3R5bGU+CiAgICA6cm9vdCB7CiAgICAgIC0taW5rOiAjMWEyMzMyOyAtLWluay1tdXRlZDogIzRhNTU2ODsgLS1ib3JkZXI6ICNjNWNkZDg7IC0tYmc6ICNmZmZmZmY7CiAgICAgIC0tdGVhbDogIzBkNzM3NzsgLS10ZWFsLWZpbGw6ICNlOGY2ZjY7CiAgICAgIC0tYW1iZXI6ICNiNDUzMDk7IC0tYW1iZXItZmlsbDogI2ZlZjNjNzsKICAgICAgLS1yZWQ6ICNiOTFjMWM7IC0tcmVkLWZpbGw6ICNmZWYyZjI7CiAgICAgIC0tbXV0ZWQtZmlsbDogI2YxZjVmOTsKICAgIH0KICAgIEBtZWRpYSAocHJlZmVycy1jb2xvci1zY2hlbWU6IGRhcmspIHsKICAgICAgOnJvb3QgewogICAgICAgIC0taW5rOiAjZThlZGY0OyAtLWluay1tdXRlZDogIzk0YTNiODsgLS1ib3JkZXI6ICMzMzQxNTU7IC0tYmc6ICMwYjBmMTQ7CiAgICAgICAgLS10ZWFsOiAjMmRkNGJmOyAtLXRlYWwtZmlsbDogIzBmMmUyZTsKICAgICAgICAtLWFtYmVyOiAjZmJiZjI0OyAtLWFtYmVyLWZpbGw6ICMzYjJmMGE7CiAgICAgICAgLS1yZWQ6ICNmODcxNzE7IC0tcmVkLWZpbGw6ICMzYTE0MTQ7CiAgICAgICAgLS1tdXRlZC1maWxsOiAjMWUyOTNiOwogICAgICB9CiAgICB9CiAgICB0ZXh0IHsgZm9udC1mYW1pbHk6IHVpLXNhbnMtc2VyaWYsIHN5c3RlbS11aSwgLWFwcGxlLXN5c3RlbSwgIlNlZ29lIFVJIiwgUm9ib3RvLCAiSGVsdmV0aWNhIE5ldWUiLCBBcmlhbCwgc2Fucy1zZXJpZjsgZmlsbDogdmFyKC0taW5rKTsgfQogICAgLmJnIHsgZmlsbDogdmFyKC0tYmcpOyB9CiAgICAuaCB7IGZvbnQtc2l6ZTogMTJweDsgZm9udC13ZWlnaHQ6IDYwMDsgfQogICAgLm1vbm8geyBmb250LXNpemU6IDExcHg7IGZvbnQtZmFtaWx5OiB1aS1tb25vc3BhY2UsIFNGTW9uby1SZWd1bGFyLCBNZW5sbywgQ29uc29sYXMsIG1vbm9zcGFjZTsgfQogICAgLm51bSB7IGZvbnQtc2l6ZTogMTBweDsgZm9udC13ZWlnaHQ6IDYwMDsgZmlsbDogdmFyKC0taW5rLW11dGVkKTsgfQogICAgLmxibCB7IGZvbnQtc2l6ZTogMTBweDsgZmlsbDogdmFyKC0taW5rLW11dGVkKTsgfQogICAgLnRhZyB7IGZvbnQtc2l6ZTogMTBweDsgZm9udC13ZWlnaHQ6IDYwMDsgZmlsbDogdmFyKC0taW5rLW11dGVkKTsgbGV0dGVyLXNwYWNpbmc6IDAuMDRlbTsgfQogICAgLmhhbG8geyBwYWludC1vcmRlcjogc3Ryb2tlOyBzdHJva2U6IHZhcigtLWJnKTsgc3Ryb2tlLXdpZHRoOiA0cHg7IHN0cm9rZS1saW5lam9pbjogcm91bmQ7IH0KICAgIC5ib3ggeyBmaWxsOiB2YXIoLS1iZyk7IHN0cm9rZTogdmFyKC0tYm9yZGVyKTsgc3Ryb2tlLXdpZHRoOiAxLjI7IH0KICAgIC5ib3gtbXV0ZWQgeyBmaWxsOiB2YXIoLS1tdXRlZC1maWxsKTsgc3Ryb2tlOiB2YXIoLS1ib3JkZXIpOyBzdHJva2Utd2lkdGg6IDEuMjsgfQogICAgLmJveC10ZWFsIHsgZmlsbDogdmFyKC0tdGVhbC1maWxsKTsgc3Ryb2tlOiB2YXIoLS10ZWFsKTsgc3Ryb2tlLXdpZHRoOiAxLjI7IH0KICAgIC5ib3gtYW1iZXIgeyBmaWxsOiB2YXIoLS1hbWJlci1maWxsKTsgc3Ryb2tlOiB2YXIoLS1hbWJlcik7IHN0cm9rZS13aWR0aDogMS4yOyB9CiAgICAuYm94LXJlZCB7IGZpbGw6IHZhcigtLXJlZC1maWxsKTsgc3Ryb2tlOiB2YXIoLS1yZWQpOyBzdHJva2Utd2lkdGg6IDEuMjsgfQogICAgLmZyYW1lIHsgZmlsbDogbm9uZTsgc3Ryb2tlOiB2YXIoLS1ib3JkZXIpOyBzdHJva2Utd2lkdGg6IDE7IHN0cm9rZS1kYXNoYXJyYXk6IDUgNDsgfQogICAgLmZyYW1lLWZpbGwgeyBmaWxsOiB2YXIoLS1tdXRlZC1maWxsKTsgc3Ryb2tlOiB2YXIoLS1ib3JkZXIpOyBzdHJva2Utd2lkdGg6IDE7IHN0cm9rZS1kYXNoYXJyYXk6IDUgNDsgfQogICAgLmxpZmVsaW5lIHsgc3Ryb2tlOiB2YXIoLS1ib3JkZXIpOyBzdHJva2Utd2lkdGg6IDE7IHN0cm9rZS1kYXNoYXJyYXk6IDQgNDsgfQogICAgLmFyciB7IGZpbGw6IG5vbmU7IHN0cm9rZTogdmFyKC0taW5rLW11dGVkKTsgc3Ryb2tlLXdpZHRoOiAxLjU7IG1hcmtlci1lbmQ6IHVybCgjYSk7IH0KICAgIC5hcnItdGVhbCB7IGZpbGw6IG5vbmU7IHN0cm9rZTogdmFyKC0tdGVhbCk7IHN0cm9rZS13aWR0aDogMS41OyBtYXJrZXItZW5kOiB1cmwoI2EtdGVhbCk7IH0KICAgIC5hcnItYW1iZXIgeyBmaWxsOiBub25lOyBzdHJva2U6IHZhcigtLWFtYmVyKTsgc3Ryb2tlLXdpZHRoOiAxLjU7IG1hcmtlci1lbmQ6IHVybCgjYS1hbWJlcik7IH0KICAgIC5hcnItcmVkIHsgZmlsbDogbm9uZTsgc3Ryb2tlOiB2YXIoLS1yZWQpOyBzdHJva2Utd2lkdGg6IDEuNTsgbWFya2VyLWVuZDogdXJsKCNhLXJlZCk7IH0KICAgIC5hcnItZmFpbCB7IGZpbGw6IG5vbmU7IHN0cm9rZTogdmFyKC0tcmVkKTsgc3Ryb2tlLXdpZHRoOiAxLjU7IHN0cm9rZS1kYXNoYXJyYXk6IDQgMzsgbWFya2VyLWVuZDogdXJsKCNhLXJlZCk7IH0KICAgIC5yZXQgeyBmaWxsOiBub25lOyBzdHJva2U6IHZhcigtLWluay1tdXRlZCk7IHN0cm9rZS13aWR0aDogMTsgc3Ryb2tlLWRhc2hhcnJheTogNCAzOyBtYXJrZXItZW5kOiB1cmwoI2Etb3Blbik7IH0KICAgIC5sbi1yZWQgeyBmaWxsOiBub25lOyBzdHJva2U6IHZhcigtLXJlZCk7IHN0cm9rZS13aWR0aDogMS41OyB9CiAgICAubG4tYW1iZXIgeyBmaWxsOiBub25lOyBzdHJva2U6IHZhcigtLWFtYmVyKTsgc3Ryb2tlLXdpZHRoOiAxLjI7IHN0cm9rZS1kYXNoYXJyYXk6IDQgMzsgfQogICAgLmhvcCB7IGZpbGw6IHZhcigtLWJnKTsgc3Ryb2tlOiB2YXIoLS1pbmstbXV0ZWQpOyBzdHJva2Utd2lkdGg6IDEuNTsgfQogICAgLmhvcC10ZWFsIHsgc3Ryb2tlOiB2YXIoLS10ZWFsKTsgfQogICAgLnRpY2sgeyBzdHJva2U6IHZhcigtLWluay1tdXRlZCk7IHN0cm9rZS13aWR0aDogMTsgfQogICAgLmFoIHsgZmlsbDogdmFyKC0taW5rLW11dGVkKTsgfSAuYWgtdGVhbCB7IGZpbGw6IHZhcigtLXRlYWwpOyB9IC5haC1hbWJlciB7IGZpbGw6IHZhcigtLWFtYmVyKTsgfSAuYWgtcmVkIHsgZmlsbDogdmFyKC0tcmVkKTsgfQogICAgLmFoLW9wZW4geyBmaWxsOiBub25lOyBzdHJva2U6IHZhcigtLWluay1tdXRlZCk7IHN0cm9rZS13aWR0aDogMTsgfQogICAgLmRvdCB7IGZpbGw6IHZhcigtLWluay1tdXRlZCk7IH0KICAgIC5zZWctZmxpZ2h0IHsgZmlsbDogdmFyKC0tYW1iZXItZmlsbCk7IHN0cm9rZTogdmFyKC0tYW1iZXIpOyBzdHJva2Utd2lkdGg6IDEuMjsgfQogICAgLnNlZy1ob3RlbCB7IGZpbGw6IHZhcigtLXRlYWwtZmlsbCk7IHN0cm9rZTogdmFyKC0tdGVhbCk7IHN0cm9rZS13aWR0aDogMS4yOyB9CiAgICAudHJhY2sgeyBmaWxsOiB2YXIoLS1tdXRlZC1maWxsKTsgc3Ryb2tlOiB2YXIoLS1ib3JkZXIpOyBzdHJva2Utd2lkdGg6IDE7IH0KICAgIC50LXRlYWwgeyBmaWxsOiB2YXIoLS10ZWFsKTsgfSAudC1hbWJlciB7IGZpbGw6IHZhcigtLWFtYmVyKTsgfSAudC1yZWQgeyBmaWxsOiB2YXIoLS1yZWQpOyB9CiAgPC9zdHlsZT4KCiAgPHJlY3QgY2xhc3M9ImJnIiB3aWR0aD0iNzIwIiBoZWlnaHQ9IjE1OCIvPgogIDxyZWN0IGNsYXNzPSJib3gtdGVhbCIgeD0iMTgiIHk9IjEyIiB3aWR0aD0iMTI0IiBoZWlnaHQ9IjEzNCIgcng9IjgiLz4KICA8dGV4dCBjbGFzcz0idGFnIiB4PSIzMCIgeT0iMzQiPlRPS0VOPC90ZXh0PgogIDx0ZXh0IGNsYXNzPSJudW0iIHg9IjMwIiB5PSI2MiI+MTwvdGV4dD4KICA8dGV4dCBjbGFzcz0ibW9ubyIgeD0iNDgiIHk9IjYyIj5zaWduYXR1cmU8L3RleHQ+CiAgPHRleHQgY2xhc3M9Im51bSIgeD0iMzAiIHk9Ijg2Ij4yPC90ZXh0PgogIDx0ZXh0IGNsYXNzPSJtb25vIiB4PSI0OCIgeT0iODYiPmV4cGlyeTwvdGV4dD4KICA8cGF0aCBjbGFzcz0iYXJyIiBkPSJNMTQ0IDc5IEgxNTciLz4KICA8cmVjdCBjbGFzcz0iYm94IiB4PSIxNTgiIHk9IjEyIiB3aWR0aD0iMTI0IiBoZWlnaHQ9IjEzNCIgcng9IjgiLz4KICA8dGV4dCBjbGFzcz0idGFnIiB4PSIxNzAiIHk9IjM0Ij5MSUZFQ1lDTEU8L3RleHQ+CiAgPHRleHQgY2xhc3M9Im51bSIgeD0iMTcwIiB5PSI2MiI+MzwvdGV4dD4KICA8dGV4dCBjbGFzcz0ibW9ubyIgeD0iMTg4IiB5PSI2MiI+a25vd248L3RleHQ+CiAgPHRleHQgY2xhc3M9Im51bSIgeD0iMTcwIiB5PSI4NiI+NDwvdGV4dD4KICA8dGV4dCBjbGFzcz0ibW9ubyIgeD0iMTg4IiB5PSI4NiI+Y29uZmlybWVkPC90ZXh0PgogIDx0ZXh0IGNsYXNzPSJudW0iIHg9IjE3MCIgeT0iMTEwIj41PC90ZXh0PgogIDx0ZXh0IGNsYXNzPSJtb25vIiB4PSIxODgiIHk9IjExMCI+cmV2b2NhdGlvbjwvdGV4dD4KICA8dGV4dCBjbGFzcz0ibnVtIiB4PSIxNzAiIHk9IjEzNCI+NjwvdGV4dD4KICA8dGV4dCBjbGFzcz0ibW9ubyIgeD0iMTg4IiB5PSIxMzQiPnNpbmdsZV91c2U8L3RleHQ+CiAgPHBhdGggY2xhc3M9ImFyciIgZD0iTTI4NCA3OSBIMjk3Ii8+CiAgPHJlY3QgY2xhc3M9ImJveCIgeD0iMjk4IiB5PSIxMiIgd2lkdGg9IjEyNCIgaGVpZ2h0PSIxMzQiIHJ4PSI4Ii8+CiAgPHRleHQgY2xhc3M9InRhZyIgeD0iMzEwIiB5PSIzNCI+Q0FMTEVSPC90ZXh0PgogIDx0ZXh0IGNsYXNzPSJudW0iIHg9IjMxMCIgeT0iNjIiPjc8L3RleHQ+CiAgPHRleHQgY2xhc3M9Im1vbm8iIHg9IjMyOCIgeT0iNjIiPmFnZW50X2JpbmRpbmc8L3RleHQ+CiAgPHBhdGggY2xhc3M9ImFyciIgZD0iTTQyNCA3OSBINDM3Ii8+CiAgPHJlY3QgY2xhc3M9ImJveC1hbWJlciIgeD0iNDM4IiB5PSIxMiIgd2lkdGg9IjEyNCIgaGVpZ2h0PSIxMzQiIHJ4PSI4Ii8+CiAgPHRleHQgY2xhc3M9InRhZyIgeD0iNDUwIiB5PSIzNCI+Q0hBUkdFPC90ZXh0PgogIDx0ZXh0IGNsYXNzPSJudW0iIHg9IjQ1MCIgeT0iNjIiPjg8L3RleHQ+CiAgPHRleHQgY2xhc3M9Im1vbm8iIHg9IjQ2OCIgeT0iNjIiPmNvbnN0cmFpbnRzPC90ZXh0PgogIDx0ZXh0IGNsYXNzPSJudW0iIHg9IjQ1MCIgeT0iODYiPjk8L3RleHQ+CiAgPHRleHQgY2xhc3M9Im1vbm8iIHg9IjQ2OCIgeT0iODYiPmFtb3VudDwvdGV4dD4KICA8cGF0aCBjbGFzcz0iYXJyIiBkPSJNNTY0IDc5IEg1NzciLz4KICA8cmVjdCBjbGFzcz0iZnJhbWUtZmlsbCIgeD0iNTc4IiB5PSIxMiIgd2lkdGg9IjEyNCIgaGVpZ2h0PSIxMzQiIHJ4PSI4Ii8+CiAgPHRleHQgY2xhc3M9InRhZyIgeD0iNTkwIiB5PSIzNCI+RVhFUkNJU0U8L3RleHQ+CiAgPHRleHQgY2xhc3M9Im51bSIgeD0iNTkwIiB5PSI2MiI+MTA8L3RleHQ+CiAgPHRleHQgY2xhc3M9Im1vbm8iIHg9IjYwOCIgeT0iNjIiPmp0aV9tYXRjaDwvdGV4dD4KPC9zdmc+Cg==) For a token that decodes successfully, checks follow this order: | Order | Check | Failure means | |---:|---|---| | 1 | `signature` | The token is not a valid ES256 token for the configured issuer and key. | | 2 | `expiry` | The JWT `exp` is in the past. | | 3 | `known` | The token's `jti` is not a mandate in this service. | | 4 | `confirmed` | No confirmation event exists. | | 5 | `revocation` | A revocation event exists. | | 6 | `single_use` | Closed only: an exercise event already exists. Open mandates skip this check. | | 7 | `agent_binding` | The mandate names an `agent_id` and the authenticated caller does not match it. | | 8 | one per constraint | The supplied charge violates a rule. Omitted when no charge is supplied. | | 9 | `currency`, `amount`, or `budget` | The charge conflicts with top-level `payment_amount`. Added only on failure. | | 10 | `jti_match` | Exercise only: the token ID differs from the mandate ID in the path. | Open responses also carry `spent` and `remaining`. Invalid or expired tokens stop early: ```json { "valid": false, "checks": [ { "check": "signature", "ok": false, "reason": "" } ] } ``` An expired token returns an `expiry` failure instead. Neither case includes `mandate_id`, and neither records a `verified` event. ## Read the whole check set A refusal can contain successful checks alongside the one that matters: ```json { "valid": false, "mandate_id": "mdt_0123456789abcdef0123456789abcdef", "checks": [ { "check": "signature", "ok": true, "reason": "valid ES256 signature" }, { "check": "expiry", "ok": true, "reason": "not expired" }, { "check": "known", "ok": true, "reason": "issued by this service" }, { "check": "confirmed", "ok": true, "reason": "user confirmed" }, { "check": "revocation", "ok": false, "reason": "revoked" }, { "check": "single_use", "ok": true, "reason": "not yet exercised" } ] } ``` Do not stop at the first `ok: true`, and do not infer validity from the presence of `mandate_id`. Require the top-level boolean and every check. ## Recovery by failed check | Failed check | What to do | |---|---| | `signature` | Reject the token. Do not edit or re-encode it. Confirm you received it from the expected environment. | | `expiry` | Obtain new user authority; do not extend the old token locally. | | `known` | Reject it in this environment. Check that issuer, database and deployment match. | | `confirmed` | Complete the user-confirmation flow before payment. | | `revocation` | Stop. New user intent requires a new mandate. | | `single_use` | Treat the closed mandate as already settled; reconcile rather than retrying exercise. | | `agent_binding` | Use the authenticated agent that owns the mandate or obtain a new mandate with the intended binding. | | constraint name | Correct the charge or obtain authority with different user-approved terms. | | `currency` / `amount` / `budget` | Correct the charge or obtain a new/expanded mandate. | | `jti_match` | Pair the token with its own mandate ID. | Never “fix” a refusal by deleting a constraint, changing claims, or substituting a different charge after confirmation. ## Retry and idempotency boundaries - **Issue is not idempotent.** Repeating it creates another mandate ID. - **Confirm can succeed once.** A repeat returns `confirmed: false` with `already confirmed`. - **Verify is repeatable, but not invisible.** Every decodable token records a `verified` event, even if a later check fails. - **Revoke is idempotent.** Repeats return `already_revoked: true`. - **Closed exercise succeeds once.** If the client loses the response, retrieve status and reconcile before retrying. - **Open exercise may succeed many times.** `reference_id` is stored for reconciliation but is not enforced as an idempotency key. That last point matters: settlement must provide its own duplicate-protection strategy around network retries. ## Audit trail `GET /v1/mandate/{id}/evidence` returns: - the draft or confirmed claims, - the confirmed token when one exists, - evidence supplied at issue, and - ordered lifecycle events. `issued` and `revoked` events may have `detail: null`. Non-null event details are returned as JSON-encoded strings, so consumers that need their structured contents must parse `detail` a second time. A successful token decode records `verified` even when a later lifecycle or constraint check fails. Closed settlement records `exercised`; open settlement records `charged`. Together, these events show what the user approved, what callers attempted, and what settlement committed. ## Continue - [Choose mandate constraints](#description/choose-mandate-constraints) - [Issue your first closed mandate](#description/issue-your-first-closed-mandate) - [Use an open mandate](#description/use-an-open-mandate) - [Design choices and AP2](#description/design-choices-and-ap2) 92:T12d6,# Watcher overview Watcher turns a user's travel intent into a durable price check. Your application creates a watch for an end user, and Watcher re-prices that stay on a schedule until the price qualifies or the check-in date arrives. When a price reaches the user's threshold, Watcher sends a signed event to your webhook. Your application decides how to notify the user or continue the booking flow. For a specific hotel, you can also collect the user's consent in advance and let Watcher complete the purchase automatically. Every API response is wrapped in `{"data": ...}`. Errors use standard HTTP status codes and `{"detail": "..."}`. ## How Watcher works 1. Your user chooses a stay and a maximum total price. 2. Your application creates a hotel watch or trip watch on the user's behalf. 3. Watcher stores the search, not a short-lived offer, and checks current prices on a schedule. 4. When a price qualifies, Watcher sends a signed webhook: - A notification watch sends the current price or matching hotels. - An armed auto-purchase watch attempts the booking and sends the outcome. 5. Your application verifies the event, handles it once, and updates or notifies the user. ## Choose a watch type | | Hotel watch | Trip watch | |---|---|---| | Best for | A user who has chosen one hotel | A user who is flexible within a destination | | Watches | One hotel for exact stay dates | Qualifying hotels in one destination for exact stay dates | | Triggers when | That hotel's total is at or below `trigger.amount` | Any matching hotel's total is at or below `trigger.amount` | | Optional filters | None | Minimum guest rating and star classes | | Event | `travel.hotel.watch.triggered` with the current price | `travel.hotel.trip_watch.triggered` with up to 3 matches, cheapest first | | Auto-purchase | Available with recorded consent | Not available | | ID prefix | `wtc_` | `twc_` | In both watch types, `trigger.type` is `below_total`. The `amount` is the maximum total for the whole stay in the requested currency, not a nightly price. Choose a hotel watch when the user already knows where they want to stay. Choose a trip watch when the destination and quality matter more than a particular hotel. ## Understand price behavior Watcher stores the search criteria and requests fresh prices on each check. It does not reserve an offer for a notification watch. > [!note] > Prices in triggered events are advisory. Fetch a fresh offer before asking the user to book. For auto-purchase, `data.booking.total_amount` in the purchased event is the binding total that was charged. The create response includes an immediate price when one is available: - Hotel watches return `current_total`. - Trip watches return `current_best`. - A `null` value means Watcher could not obtain a current price; the watch still remains active. - A value at or below the threshold means the user can act now. The watch is still created and will trigger on its next check. ## Understand ownership and identity The API gateway derives the organisation and end user from your API credential. Watcher scopes each watch to that organisation and user, so one user cannot list or manage another user's watches. Call `GET /v1/watcher/whoami` before creating a watch when you need to confirm which identity the request will use. ## Plan for the watch lifecycle A notification watch follows this lifecycle: - `active` — Watcher is checking prices. - `triggered` — a qualifying price produced an event; scheduled checks stop. - `expired` — the check-in date arrived before the watch triggered. You can rearm a triggered watch, optionally with a new threshold. Rearming schedules an immediate check. A stay that has already started cannot be rearmed. An auto-purchase hotel watch also uses: - `purchasing` — Watcher is re-pricing, validating consent, holding, and completing the booking. - `purchased` — the booking completed; `booking_id` identifies it. - `purchase_failed` — the attempt failed; `purchase_failure` explains why, and the user can still book manually. The watch `status` remains `active` while purchase consent is pending. Use `mode` to distinguish `notify`, `auto_book_pending`, and `auto_book`. ## Work within the limits - Creating a duplicate active watch for the same stay or trip returns 409. - For idempotent create requests, supply your own `id`: use `wtc_` for hotel watches or `twc_` for trip watches, followed by alphanumeric characters, with at most 40 characters in total. Reusing that ID returns the existing watch with 200. - Watcher checks active watches roughly every five minutes by default. - Watches expire automatically when the check-in date arrives. Ready to try the complete notification flow? [Create your first price watch](#description/getting-started-watches). 93:T1e1c,# Create your first price watch This tutorial takes one request — “Tell me when this Tokyo hotel costs 450 USD or less” — from API setup to a safely handled price-drop event. ## What you will build You will: 1. Confirm the user identity attached to your API key. 2. Register an endpoint for Watcher events. 3. Create a price watch for one hotel and stay. 4. Handle the signed event when the total reaches the user's threshold. 5. Recover events if your webhook receiver misses a delivery. ## Before you begin You need: - An OEX API key that acts for the end user creating the watch. - A public HTTP endpoint such as `https://your.service/hooks/oex`. - A secure secret store for the webhook signing secret. Every request in this tutorial goes through the Watcher gateway. Set your API key once: ```bash export OEX_API_KEY="" ``` ## 1. Verify your API identity Confirm which organisation and user the gateway will attach to your requests: ```bash curl "https://api.oex.sh/v1/watcher/whoami" \ -H "x-api-key: $OEX_API_KEY" ``` ```json { "data": { "org_id": "org_demo", "user_id": "usr_maya" } } ``` Store watches under the intended end user's credential. A user can list and manage only their own watches. ## 2. Register your webhook endpoint Register the receiver before creating a watch. This prevents you from missing an event if the current price already qualifies. ```bash curl -X POST "https://api.oex.sh/v1/watcher/webhooks" \ -H "content-type: application/json" \ -H "x-api-key: $OEX_API_KEY" \ -d '{ "url": "https://your.service/hooks/oex" }' ``` ```json { "data": { "org_id": "org_demo", "url": "https://your.service/hooks/oex", "events": [ "travel.hotel.watch.triggered", "travel.hotel.trip_watch.triggered", "travel.hotel.watch.purchased", "travel.hotel.watch.purchase_failed" ], "secret": "whsec_..." } } ``` > [!warning] > Save `secret` now. Watcher never returns it again. Registering another endpoint replaces the current URL and rotates the secret. The registration belongs to the organisation, not an individual user. The optional `events` field lets you subscribe to a subset; omitting it subscribes the endpoint to all four event types. ## 3. Create a hotel watch Create a watch for two adults staying from 10 to 13 September 2026. The threshold is the total for the full stay. ```bash curl -X POST "https://api.oex.sh/v1/watcher/travel/hotel/watches" \ -H "content-type: application/json" \ -H "x-api-key: $OEX_API_KEY" \ -d '{ "hotel_id": "hb_123456", "check_in": "2026-09-10", "check_out": "2026-09-13", "occupancy": [ {"adults": 2} ], "currency": "USD", "guest_nationality": "US", "trigger": { "type": "below_total", "amount": 450 } }' ``` Watcher prices the stay once while creating it: ```json { "data": { "id": "wtc_01hq3example", "status": "active", "mode": "notify", "hotel_id": "hb_123456", "check_in": "2026-09-10", "check_out": "2026-09-13", "occupancy": [ {"adults": 2} ], "currency": "USD", "guest_nationality": "US", "trigger": { "type": "below_total", "amount": 450 }, "mandate_id": null, "payment_instrument_id": null, "booking_id": null, "purchase_failure": null, "last_total": 512.4, "last_checked_at": "2026-08-25T09:15:00+00:00", "triggered_at": null, "notified_total": null, "created_at": "2026-08-25T09:15:00+00:00", "current_total": 512.4 } } ``` Save the `wtc_` ID. You will use it to retrieve, rearm, or delete this watch. The request must use future dates, a 3-letter currency code, a 2-letter guest nationality, and 1–4 rooms. Each room can contain 1–8 adults. ## 4. Interpret the current price Use `current_total` to give the user immediate feedback: - **Above 450:** The watch is ready. Watcher will continue checking. - **At or below 450:** Tell the user the price already meets their goal and offer the normal booking flow. The active watch will still trigger on its next check. - **`null`:** Watcher could not get a current price. The watch is still active and will try again on its scheduled checks. Notification prices are advisory. Do not save them as bookable offers; fetch a fresh offer when the user decides to book. ## 5. Receive the price-drop event When the hotel total reaches 450 USD or less, Watcher sends a JSON `POST` to your registered URL: ```json { "id": "evt_01hq4example", "type": "travel.hotel.watch.triggered", "created_at": "2026-08-28T10:20:00+00:00", "data": { "watch": { "id": "wtc_01hq3example", "status": "triggered", "mode": "notify", "hotel_id": "hb_123456", "check_in": "2026-09-10", "check_out": "2026-09-13", "occupancy": [ {"adults": 2} ], "currency": "USD", "guest_nationality": "US", "trigger": { "type": "below_total", "amount": 450 }, "mandate_id": null, "payment_instrument_id": null, "booking_id": null, "purchase_failure": null, "last_total": 438.7, "last_checked_at": "2026-08-28T10:20:00+00:00", "triggered_at": "2026-08-28T10:20:00+00:00", "notified_total": 438.7, "created_at": "2026-08-25T09:15:00+00:00" }, "user_id": "usr_maya", "current": { "total": 438.7, "currency": "USD", "room_type": "Deluxe King", "board": "Room only", "refundable": true } } } ``` For every delivery: 1. Verify `oex-signature` against the raw request body. 2. Reject stale requests and invalid signatures. 3. Deduplicate by the top-level event `id`. 4. Return a 2xx response within 10 seconds. 5. Notify the user or do other slow work asynchronously. Follow [Handle webhooks reliably](#description/webhooks-and-delivery) for signature verification, retries, and a production checklist. ## 6. Reconcile missed events Webhook delivery is at-least-once, but your receiver may still be unavailable beyond the retry window. Read the organisation's event log as a safety net: ```bash curl "https://api.oex.sh/v1/watcher/events?after=evt_01hq4example&limit=50" \ -H "x-api-key: $OEX_API_KEY" ``` The response is ordered from oldest to newest. Save the last event ID you processed and pass it as `after` on the next request. Process the event in each entry's `payload` using the same deduplication path as webhook deliveries. For your first reconciliation request, omit `after`. A supplied event ID must belong to your organisation. ## 7. Manage the watch List the current user's hotel watches: ```bash curl "https://api.oex.sh/v1/watcher/travel/hotel/watches" \ -H "x-api-key: $OEX_API_KEY" ``` Rearm a triggered watch with the same threshold: ```bash curl -X POST "https://api.oex.sh/v1/watcher/travel/hotel/watches/wtc_01hq3example/rearm" \ -H "content-type: application/json" \ -H "x-api-key: $OEX_API_KEY" \ -d '{}' ``` To change the threshold while rearming, send: ```json { "trigger": { "type": "below_total", "amount": 425 } } ``` Delete a watch the user no longer needs: ```bash curl -X DELETE "https://api.oex.sh/v1/watcher/travel/hotel/watches/wtc_01hq3example" \ -H "x-api-key: $OEX_API_KEY" ``` ## Next steps - Use a trip watch when the user is flexible about the hotel. See [Choose a watch type](#description/watcher-overview). - Let an eligible hotel watch complete the booking with explicit consent. See [Set up auto-purchase](#description/auto-purchase). - Make your event receiver production-ready. See [Handle webhooks reliably](#description/webhooks-and-delivery). 94:T225a,# Set up auto-purchase Auto-purchase lets an armed hotel watch book and charge the user when the price reaches their limit. Use it only after the user has chosen a specific hotel and explicitly agreed to the stay, travelers, payment method, and maximum total. Trip watches cannot auto-purchase. They always notify. ## Before you begin You need: - A working hotel-watch integration. If you have not created one yet, follow [Create your first price watch](#description/getting-started-watches). - An active OEX payment instrument that belongs to the acting user. - The travelers' names and a booking contact. - A clear record of the user's instruction to purchase within a price cap. - A webhook receiver subscribed to purchase outcome events. > [!warning] > Auto-purchase can move real money without the user being online. Never confirm a purchase mandate until you have shown the user exactly what will be booked and received their explicit approval. ## How consent protects the user Arming auto-purchase takes two API calls: 1. **Create the watch.** Watcher validates the payment instrument and drafts a mandate capped at `trigger.amount`. The watch enters `auto_book_pending`. 2. **Confirm the purchase.** After your application shows the user the final consent details, confirm the draft within 15 minutes. The watch then enters `auto_book`. While confirmation is pending, the watch behaves like a notification watch. A qualifying price sends `travel.hotel.watch.triggered`; Watcher never books or charges. ## 1. Collect purchase details and consent Collect these details together: - The hotel, stay dates, occupancy, currency, and guest nationality. - The maximum total for the stay. - One active `payment_instrument_id`. - Between 1 and 8 travelers. - A booking contact with an email address and phone number. - The user's own words authorizing the purchase, when available. The consent evidence can contain: - `human_messages` — the user's relevant messages. - `conversation_context` — a short description that makes those messages understandable later. For this example, Maya has agreed to book the Tokyo stay automatically at 450 USD or less. ## 2. Create a pending auto-purchase watch Add a complete `purchase` object to the hotel-watch request: ```bash curl -X POST "https://api.oex.sh/v1/watcher/travel/hotel/watches" \ -H "content-type: application/json" \ -H "x-api-key: $OEX_API_KEY" \ -d '{ "hotel_id": "hb_123456", "check_in": "2026-09-10", "check_out": "2026-09-13", "occupancy": [ {"adults": 2} ], "currency": "USD", "guest_nationality": "US", "trigger": { "type": "below_total", "amount": 450 }, "purchase": { "payment_instrument_id": "pi_abc123", "travelers": [ { "first_name": "Maya", "last_name": "Chen", "email": "maya@example.com", "is_lead": true }, { "first_name": "Jordan", "last_name": "Lee", "email": "jordan@example.com" } ], "contact": { "first_name": "Maya", "last_name": "Chen", "email": "maya@example.com", "phone": "+14155550123" }, "evidence": { "human_messages": [ "Book it automatically if the total drops to 450 USD or less." ], "conversation_context": "User selected the Tokyo stay for 10–13 September 2026." } } }' ``` The response includes the normal watch fields plus the pending mandate. Relevant fields are shown here: ```json { "data": { "id": "wtc_01hq3example", "status": "active", "mode": "auto_book_pending", "hotel_id": "hb_123456", "check_in": "2026-09-10", "check_out": "2026-09-13", "currency": "USD", "trigger": { "type": "below_total", "amount": 450 }, "mandate_id": "mdt_0123456789abcdef0123456789abcdef", "payment_instrument_id": "pi_abc123", "mandate_status": "pending", "confirm_expires_at": "2026-08-25T09:30:00+00:00", "current_total": 512.4 } } ``` Save `confirm_expires_at` and complete the user confirmation before that time. An unknown or inactive payment instrument returns 422. If the mandate service is unavailable, the request returns 502 and no consent shortcut is taken. ## 3. Show the user the confirmation Before confirming, show the user: - The hotel and stay dates. - Every traveler. - The booking contact. - The selected payment method. - The currency and maximum total of 450 USD. - That the purchase will happen automatically when a qualifying price is available. Do not treat the user's earlier interest in a price alert as purchase consent. Ask for a separate, explicit confirmation. ## 4. Confirm within 15 minutes After the user approves, confirm the pending mandate: ```bash curl -X POST "https://api.oex.sh/v1/watcher/travel/hotel/watches/wtc_01hq3example/confirm-purchase" \ -H "content-type: application/json" \ -H "x-api-key: $OEX_API_KEY" \ -d '{ "confirmation": { "channel": "sms", "message_id": "msg_42", "confirmed_by": "usr_maya" } }' ``` Watcher records `confirmation` with the mandate and returns the armed watch: ```json { "data": { "id": "wtc_01hq3example", "status": "active", "mode": "auto_book", "mandate_id": "mdt_0123456789abcdef0123456789abcdef", "mandate_status": "active" } } ``` The request body is optional, but include your confirmation record when you have one. If the confirmation window expired or the draft was revoked, Watcher returns 422 and leaves the watch pending. Delete it and create a new watch to collect fresh consent. Confirming a watch with no pending draft returns 409. ## 5. Handle the outcome When an armed watch first sees a qualifying price, its status changes to `purchasing`. Watcher then: 1. Fetches a fresh offer. 2. Verifies the mandate. 3. Holds the booking and obtains the binding total. 4. Checks the binding total against the user's cap. 5. Exercises the mandate and completes the booking. If the fresh offer is unavailable or has moved above 450 USD, Watcher returns the watch to `active` and keeps checking. This is normal price movement, so no purchase outcome event is sent. If the booking completes, Watcher sends `travel.hotel.watch.purchased`. This example abbreviates `data.watch` to the fields most relevant to the outcome: ```json { "id": "evt_01hq5purchased", "type": "travel.hotel.watch.purchased", "created_at": "2026-08-28T10:20:00+00:00", "data": { "watch": { "id": "wtc_01hq3example", "status": "purchased", "mode": "auto_book", "booking_id": "bkg_01hq3example" }, "user_id": "usr_maya", "booking": { "id": "bkg_01hq3example", "status": "CONFIRMED", "total_amount": { "amount": 438.7, "currency": "USD" } }, "mandate_id": "mdt_0123456789abcdef0123456789abcdef" } } ``` `data.booking.total_amount` is the binding amount charged. `data.booking.due_at_property` is also present when the hotel collects an additional amount at the property. If Watcher cannot safely complete the purchase, it sends `travel.hotel.watch.purchase_failed` with `data.reason` and `data.current` when a fresh price was available. A binding hold price above the cap is a failure, and the mandate is not exercised. Tell the user what happened and offer the normal manual booking flow. An armed watch sends a purchase outcome instead of `travel.hotel.watch.triggered`. Process both purchase events through the same verified, idempotent receiver described in [Handle webhooks reliably](#description/webhooks-and-delivery). ## Rearm or delete the watch Rearming an auto-purchase watch creates a replacement draft mandate and returns the watch to `auto_book_pending`. Show the consent details again and call `confirm-purchase` before expecting another automatic booking. You cannot rearm a watch while it is `purchasing` or after it is `purchased`; Watcher returns 409. Deleting an auto-purchase watch revokes its mandate on a best-effort basis, including an unconfirmed draft. A watch currently purchasing cannot be deleted. ## Launch checklist Before enabling auto-purchase for users, verify that your application: - Confirms the acting user with `whoami`. - Accepts only an active payment instrument owned by that user. - Collects complete traveler and contact details. - Records the user's explicit words and relevant context. - Shows the hotel, dates, travelers, payment method, currency, and cap before confirmation. - Confirms before `confirm_expires_at`. - Verifies and deduplicates every purchase event. - Handles both `purchased` and `purchase_failed`. - Offers a manual booking path after failure. 95:T1ece,# Handle webhooks reliably Watcher delivers every event as a signed JSON `POST`. Delivery is at-least-once, so a production receiver must verify the sender, accept duplicates safely, acknowledge quickly, and reconcile from the event log. ## Receiver contract Each request contains: - `content-type: application/json` - `oex-signature: t=,v1=` - A JSON body with a unique `id`, `type`, `created_at`, and type-specific `data` Use HTTPS for your production endpoint. Keep the `whsec_` signing secret in a secret manager and make it available only to the receiver. Do not perform expensive business work in the request handler. The handler's job is to verify the request and persist it durably for asynchronous processing. ## 1. Read the raw request body Read and preserve the exact request bytes before parsing JSON. Frameworks that automatically parse the body may require a raw-body or request-buffer API. > [!warning] > Verify the bytes Watcher sent. Re-serializing parsed JSON can change whitespace or key order and produce a different signature. Also read the `oex-signature` header. Reject the request if the body or header is missing. ## 2. Verify the signature The signed message is the timestamp, a period, and the raw body: ```text . ``` Verify in this order: ```text parts = parse_header(oex_signature) timestamp = integer(parts["t"]) provided = parts["v1"] reject if abs(current_unix_seconds - timestamp) > 300 message = utf8(timestamp + ".") + raw_body expected = lowercase_hex(hmac_sha256(webhook_secret, message)) reject unless constant_time_equal(expected, provided) ``` The 300-second tolerance limits replay attacks. Keep your server clock synchronized and compare the expected and provided signatures with your language's constant-time function. Return a 4xx response for a malformed header, stale timestamp, or invalid signature. Parse the JSON only after verification succeeds. ## 3. Deduplicate the event Watcher may deliver the same event more than once. This can happen when your endpoint times out after completing work or when delivery succeeds but Watcher cannot save the acknowledgement. Use the top-level `id` as an idempotency key: 1. Start a database transaction. 2. Insert the event ID into a table with a unique constraint. 3. Enqueue or store the event payload in the same transaction. 4. If the ID already exists, treat the delivery as accepted and return 2xx. 5. If you cannot persist the event, return a non-2xx response so Watcher retries. Do not deduplicate by watch ID. One watch can produce different events over its lifetime. ## 4. Acknowledge before doing slow work Commit the event to durable storage, then return any 2xx status within 10 seconds. Send notifications, call other services, and update application state in an asynchronous worker. Watcher retries after a timeout or non-2xx response using this schedule: 1. 1 minute 2. 5 minutes 3. 30 minutes 4. 2 hours 5. 12 hours 6. 24 hours After the retry attempts are exhausted, the event is marked `failed` in the event log. A 2xx response means you accepted responsibility for the event, so return it only after durable persistence. ## 5. Process by event type Every event includes `data.user_id`. Use it to route the outcome to the end user who owns the watch. | Event type | Important data | Recommended action | |---|---|---| | `travel.hotel.watch.triggered` | `data.watch` and advisory `data.current` price details | Notify the user and link to a fresh booking search | | `travel.hotel.trip_watch.triggered` | `data.watch` and up to 3 entries in `data.matches`, cheapest first | Show the qualifying hotels and fetch fresh offers when the user chooses one | | `travel.hotel.watch.purchased` | `data.watch`, `data.booking`, and `data.mandate_id` | Confirm the booking to the user using the binding `data.booking.total_amount` | | `travel.hotel.watch.purchase_failed` | `data.watch`, `data.reason`, and optional advisory `data.current` | Explain the failure and offer the manual booking flow | A trip match contains `hotel_id`, `name`, `guest_rating`, `star_rating`, `total`, `currency`, `room_type`, `board`, and `refundable`. An armed auto-purchase watch sends a purchase outcome instead of `travel.hotel.watch.triggered`. If a fresh price moves back above the cap before purchase, the watch returns to active and sends no outcome. ## Recover missed events The event log is the recovery path when your endpoint is unavailable beyond the retry window: ```bash curl "https://api.oex.sh/v1/watcher/events?after=evt_01hq2example&limit=50" \ -H "x-api-key: $OEX_API_KEY" ``` The response contains the organisation's events from oldest to newest. This example shows the fields used during reconciliation: ```json { "data": [ { "id": "evt_01hq3example", "type": "travel.hotel.watch.triggered", "status": "delivered", "created_at": "2026-08-28T10:20:00+00:00", "payload": { "id": "evt_01hq3example", "type": "travel.hotel.watch.triggered", "created_at": "2026-08-28T10:20:00+00:00", "data": { "watch": { "id": "wtc_01hq3example", "status": "triggered" }, "user_id": "usr_maya", "current": { "total": 438.7, "currency": "USD", "room_type": "Deluxe King", "board": "Room only", "refundable": true } } } } ] } ``` Each entry has an event `status` of `pending`, `delivered`, or `failed`. The full webhook body is in `payload`; the example above abbreviates `data.watch` for readability. For reliable reconciliation: 1. Omit `after` on the first request. 2. Process each `payload` through the same idempotent path as a webhook. 3. Save the last processed event ID. 4. Pass that ID as `after` on the next request. 5. Continue until the response contains fewer entries than your requested limit. `limit` accepts 1–200 and defaults to 50. A supplied `after` ID must exist in your organisation's event log or the API returns 404. ## Rotate the signing secret Registering the webhook again replaces the organisation's endpoint and rotates the secret immediately: ```bash curl -X POST "https://api.oex.sh/v1/watcher/webhooks" \ -H "content-type: application/json" \ -H "x-api-key: $OEX_API_KEY" \ -d '{ "url": "https://your.service/hooks/oex" }' ``` The response contains the new secret once. Store it immediately. For a controlled rotation: 1. Keep the old secret active in your verifier. 2. Re-register the endpoint and capture the new secret. 3. Add the new secret to the verifier as quickly as possible while retaining the old one. 4. Try verification with both secrets during the transition. 5. Remove the old secret after the new configuration is live and any in-flight request has finished. Because rotation takes effect before you can deploy the returned secret, a delivery during the short transition may fail and retry. Automate the secret update when possible. If you lose the new secret, register the endpoint again to rotate it. ## Production checklist Before accepting live events, verify that your receiver: - Uses HTTPS. - Reads the raw request body. - Rejects malformed, stale, and incorrectly signed requests. - Uses a constant-time signature comparison. - Stores event IDs under a unique constraint. - Persists or enqueues events before returning 2xx. - Responds within 10 seconds. - Processes every subscribed event type. - Reconciles the event log from a saved cursor. - Can accept both secrets during a planned rotation. Start with the complete tutorial in [Create your first price watch](#description/getting-started-watches), or review the additional consent controls in [Set up auto-purchase](#description/auto-purchase). 96:T3e2b,# Accept a card payment with the Payment SDK The Payment SDK lets your customer pay by card without leaving your checkout. You do not build a card form, you never handle a card number, and you do not call the payment service — the service you already integrate mints the payment for you and hands your page a single string, the **handoff token**, which is all the browser needs. Travel does this today: ask for it when you hold a booking, and the response carries the token beside the booking. Every service that needs your customer to pay will hand you the same token in the same way, and the code on this page does not change when it does. The card fields live inside the vault's iframe — the vault is the PCI-certified processor account TrustPixel operates — so a card number never reaches your page or your server. That is what keeps your integration at the lightest PCI level, SAQ A, and TrustPixel stays merchant of record for the charge. Every sample uses `$BASE_URL` for the API host and `$API_KEY` for your API key. The SDK itself takes no credential. > [!warning] > The handoff token carries a live client secret. Forward it to your page unchanged, never log it, and never put it in a URL. ## Add the SDK to your page One script tag is the whole browser-side install. It defines the global `TrustPixelPayment` constructor: ~~~html ~~~ `/v1/` is the evergreen channel: compatible fixes reach your checkout minutes after release, with no deploy of your own. To freeze the bytes instead, pin a release and let the browser verify it with Subresource Integrity — `

~~~ ## The SDK surface The constructor takes one object. Only the token and the mount point are required: | Option | Type | What it does | | --- | --- | --- | | `token` | `string` | The handoff token, forwarded unchanged. Required. | | `target` | `string \| HTMLElement` | The element the widget renders into, as a CSS selector or the element itself. Required. | | `appearance` | `object` | Passed to the vault to style the card fields your own CSS cannot reach. | | `wallets` | `object` | Which accelerated-checkout wallets the vault may offer, e.g. `{ link: "never" }`. A card-saving mount never offers Apple Pay or Google Pay. | And three methods: | Call | What happens | | --- | --- | | `mount()` | Renders the fields and the submit button into the target, and boots the vault in the background. Returns the widget, so it chains into `present()`. | | `present()` | Resolves with the settled result — `{ kind: "payment", outcome }` for a payment token, `{ kind: "setup", reference }` for a card-saving one — or rejects if the mount was cancelled or the vault failed. Calling it twice returns the same promise. | | `destroy()` | Takes the mount down and rejects a pending `present()`. Nothing had been submitted, so no money moved. | A widget is single-use: after `destroy()`, or once `present()` has settled, construct a new one to mount again. ## Give the customer another attempt A token belongs to one payment, so a declined card needs a new one. Do not call book — prebook again with a **new** idempotency key, which mints a fresh token, and mount a new widget into the same target. The new mount replaces the old one rather than stacking beside it. Prices are re-bound at prebook, so show the customer `total_amount` again before the second attempt if it moved. ## Let the customer cancel The Cancel button is yours, because only your page knows what cancelling means — hide the form, go back to the room list, drop the hold. Wire it to `destroy()`: ~~~js const widget = new TrustPixelPayment({ token, target: "#payment" }); cancelButton.onclick = () => widget.destroy(); try { const result = await widget.mount().present(); } catch (err) { if (err.name === "TrustPixelPaymentJsCancelledError") return backToRooms(); throw err; } ~~~ Once the customer has submitted and the vault is confirming, `destroy()` throws instead of cancelling. The attempt is already with the vault by then, and reporting it as cancelled could tell a customer nothing happened while their card was in fact charged — catch that and ask them to wait. A booking you abandon simply lapses at its `expires_at`. ## When the widget throws Every failure the SDK throws is a `TrustPixelPaymentJsError`, and each kind names itself on `err.name` — a stable value in every build, including minified ones. The classes hang off the `TrustPixelPaymentJs` global for `instanceof` checks. | `err.name` | What it means | | --- | --- | | `TrustPixelPaymentJsConfigError` | The constructor input is unusable: a missing or malformed token, or a target that matches no element. | | `TrustPixelPaymentJsStateError` | The lifecycle was misused: `present()` before `mount()`, or `destroy()` while the vault is confirming. | | `TrustPixelPaymentJsCancelledError` | Your own `destroy()` took the mount down. Nothing was submitted. | | `TrustPixelPaymentJsVaultError` | The vault refused something that is not a card outcome — most often a token that is stale or was minted elsewhere. | | `TrustPixelPaymentJsProviderError` | The token names a vault this build does not implement. The name is on the error's `provider` field. | A card decline is never among them: declines resolve, as in step 3. An empty token — what you get from a replayed prebook — is a `ConfigError` at construction, which is why step 1 reads it with a string fallback rather than assuming it is there. None of these messages print the token or the client secret. ## Style it The SDK ships **no CSS**. It renders two elements into your target and stamps them with class names, so everything visual is yours: ~~~css .tp-payment-element { /* the container holding the vault's iframe */ } .tp-payment-submit { /* the submit button: "Pay" */ } ~~~ The widget sets no margins of its own, so it never fights your layout — space around the mount point is your page's job. The card fields themselves live inside the vault's iframe where your CSS cannot reach; that boundary is what keeps you out of PCI scope, so style them through `appearance`, which is handed to the vault: ~~~js new TrustPixelPayment({ token, target: "#payment", appearance: { variables: { colorPrimary: "#0a6cff" } }, wallets: { link: "never" }, // also applePay / googlePay }); ~~~ `wallets` narrows what the vault may offer alongside the card fields — `{ link: "never" }` keeps Stripe Link's sign-up prompt out of your checkout. Omit the option and the vault's own defaults stand. The control only ever narrows: `"auto"` cannot switch on a wallet TrustPixel has disabled for the account. A card-saving token is the exception: that mount never offers Apple Pay or Google Pay, whatever `wallets` says, because TrustPixel does not save device wallets. Apple Pay and Google Pay appear on a payment only when the conditions for them hold; when one does not, the vault leaves the wallet out without an error and the card fields still work. TrustPixel must have registered your checkout's host for wallets — the host in the customer's address bar on the page that mounts the widget, with every host and subdomain registered on its own, so tell TrustPixel each one you take payments on. The page must be served over HTTPS; inside a cross-origin iframe, the iframe needs `allow="payment"` and its own host registered too. And the customer's browser and device must support the wallet, with a card in it. A wallet payment resolves `present()` exactly as a card payment does. ## Test it Use a sandbox API key. The same code produces test-mode tokens and the same SDK renders them — sandbox is a matter of credentials, not a different script. Pay with the vault's standard test cards: `4242 4242 4242 4242` with any future expiry and any CVC settles as `succeeded`, and `4000 0000 0000 0002` settles as `declined`. No real card is ever charged in sandbox, and no real room is held. ## Keep learning - [Getting started with Hotels](#description/getting-started-with-hotels) - [Getting started with Flights](#description/getting-started-with-flights) - [Booking lifecycle](#description/booking-lifecycle) - [Hotel Bookings](#tag/hotel-bookings)69:["$","$L71",null,{"full":true,"children":[["$","h1",null,{"className":"text-[1.75em] font-semibold","children":"Retrieve a mandate"}],["$","$L72",null,{"children":["$","$L73",null,{"payload":{"bundled":{"openapi":"3.2.0","info":{"title":"TrustPixel API","version":"0.1.0","description":"$74"},"servers":[{"url":"https://api.sandbox.oex.sh","description":"Sandbox"},{"url":"https://api.oex.sh","description":"Production"}],"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"tags":[{"name":"Hotel bookings","description":"You can prebook, complete and read stays belonging to your organization and user. Your responses contain the service's hotel IDs and amounts in major currency units.","kind":"nav"},{"name":"Hotel capabilities","description":"You can read supported operations and limits before preparing requests for a supplier.","kind":"nav"},{"name":"Hotel content","description":"You can read details, images, policies and reviews for a known hotel ID.","kind":"nav"},{"name":"Hotel offers","description":"You can price known hotel IDs and obtain offer references for prebook.","kind":"nav"},{"name":"Hotel places","description":"You can resolve destination queries into locations for hotel search.","kind":"nav"},{"name":"Hotel price calendar","description":"You can see a daily price index of indicative nightly prices for known hotel IDs.","kind":"nav"},{"name":"Hotel search","description":"You can find available hotels for a destination and a complete room party.","kind":"nav"},{"name":"Hotel webhooks","description":"You can receive signed booking events at your HTTPS endpoint and review or replay their deliveries.","kind":"nav"},{"name":"Airlines","description":"The airline directory, learned from the supplier as it is used: a carrier the table lacks is imported on its first lookup and served from the table afterwards. Search by name or code, list every learned code, or read one carrier, inactive ones included. Booking responses use these names and logos.","kind":"nav"},{"name":"Airports","description":"The airport directory. Search asks the supplier on every call, within an eight-second budget, and stores the page it returns; a lookup by code serves the stored airport or imports it once. Records carry the IATA and ICAO codes, name, city, state, country, coordinates and IANA time zone.","kind":"nav"},{"name":"Flight Bookings","description":"A booking is created by prebook, which re-prices the offer and stores the itinerary and passengers, and completed by book, which charges the saved instrument, has the airline issue the ticket and answers `CONFIRMED`. Every booking route needs the user the booking belongs to; a booking you do not own is a `404`.\n\nCancel is accepted with `202` and runs as a workflow you read back from the booking. Bags and seats are added at prebook; bags can also be bought on a confirmed booking as a separate payment.","kind":"nav"},{"name":"Flight Offers","description":"Offers are priced, bookable fares for one party and one itinerary, from one supplier chosen by routing rules or named in the request. Each offer carries an opaque `offer_reference`, the only handle you can prebook from, and an `expires_at`. Fetch offers and prebook in one flow; when the reference lapses, request offers again.\n\n`meta.supplier` names who priced the fares. An offer's bags are listed by its available-services call and its seats by its seat-maps call; both are chosen at prebook.","kind":"nav"},{"name":"Flight Webhooks","description":"Webhooks send your HTTPS endpoint a signed request when one of your organisation's bookings is confirmed, fails, is cancelled or has its cancellation refused, so you learn outcomes without polling. Every credential of your organisation manages the same subscriptions. Review each delivery and replay one your endpoint did not take.","kind":"nav"},{"name":"Mandates","description":"Create bounded payment authority, capture consent, inspect its evidence and lifecycle, or revoke it.","kind":"nav"},{"name":"Verification","description":"Evaluate an exact charge without settlement, then exercise the authority from the trusted payment path.","kind":"nav"},{"name":"Events","description":"The per-organisation event log, for reconciling missed deliveries.","kind":"nav"},{"name":"Hotel watches","description":"Price watches on one hotel for one stay; optionally armed to auto-purchase.","kind":"nav"},{"name":"Service","description":"Liveness probe and identity echo.","kind":"nav"},{"name":"Trip watches","description":"Price watches on a whole destination; notify-only.","kind":"nav"},{"name":"Webhooks","description":"Where triggered and purchase events are delivered, and the signing secret.","kind":"nav"}],"x-guides":[{"upstream":"hotel","slug":"hotel-overview","title":"Hotel API overview","summary":"You use one API to find, book and cancel a multiroom stay.","content":"$75"},{"upstream":"hotel","slug":"hotel-getting-started","title":"Hotel getting started","summary":"You follow a two-room example from search through booking.","content":"$76"},{"upstream":"hotel","slug":"hotel-conventions","title":"Hotel API conventions","summary":"You interpret IDs, money, dates, room order and pagination.","content":"$77"},{"upstream":"hotel","slug":"hotel-booking-flow","title":"Hotel booking flow","summary":"You search, assign every room, choose payment and complete your booking.","content":"$78"},{"upstream":"hotel","slug":"hotel-booking-lifecycle","title":"Hotel booking lifecycle","summary":"You choose your next action from the stored booking state.","content":"$79"},{"upstream":"hotel","slug":"hotel-retry-and-idempotency","title":"Hotel retries and idempotency","summary":"You recover interrupted calls without creating a second purchase.","content":"$7a"},{"upstream":"hotel","slug":"hotel-cancellations-recovery","title":"Hotel cancellations and recovery","summary":"You cancel live rooms, interpret refund intentions and handle uncertain results.","content":"$7b"},{"upstream":"hotel","slug":"hotel-webhooks","title":"Hotel webhooks","summary":"You receive signed booking events at your HTTPS endpoint.","content":"$7c"},{"upstream":"hotel","slug":"hotel-errors","title":"Hotel errors","summary":"You interpret stable error codes and reasons to choose a safe next action.","content":"$7d"},{"upstream":"flight","slug":"flight-overview","title":"Flight API overview","summary":"What the service does, the three calls that make a ticket, and how these docs are organised.","content":"$7e"},{"upstream":"flight","slug":"flight-getting-started","title":"Book your first flight","summary":"Your first flight booking: offers, prebook, book, read back.","content":"$7f"},{"upstream":"flight","slug":"flight-itineraries","title":"Flight itineraries and fares","summary":"Journeys and segments for one-way, return and multi-city trips, and the money and expiry fields on an offer.","content":"$80"},{"upstream":"flight","slug":"flight-search-best-practices","title":"Flight search best practices","summary":"Search for the real party, keep the offer with its supplier, respect expiry, and filter and sort what the supplier honours.","content":"$81"},{"upstream":"flight","slug":"flight-booking-lifecycle","title":"Flight booking lifecycle","summary":"How a booking moves from prebook through book and cancel, and what an interrupted call leaves behind.","content":"$82"},{"upstream":"flight","slug":"flight-liteapi-checkout","title":"Pay for a flight with LiteAPI","summary":"Pay through LiteAPI checkout, complete your booking and recover an interrupted session.","content":"$83"},{"upstream":"flight","slug":"flight-extras","title":"Add bags and seats to a flight booking","summary":"Choose seats and bags when you prebook, or buy bags on a confirmed booking as a separate purchase.","content":"$84"},{"upstream":"flight","slug":"flight-cancel","title":"Cancel a flight booking","summary":"Quote, cancel a confirmed ticket, and read what the refund did.","content":"$85"},{"upstream":"flight","slug":"flight-webhooks","title":"Flight webhooks","summary":"Receive signed booking events at your HTTPS endpoint, verify them and replay one your endpoint missed.","content":"$86"},{"upstream":"flight","slug":"flight-retry-and-idempotency","title":"Retry flight calls safely","summary":"Retry a failed call safely, replay prebook with the same key, and never resubmit an unknown result.","content":"$87"},{"upstream":"flight","slug":"flight-directories","title":"Airlines and airports","summary":"Look up airlines and airports by code or search text; the directories are learned from the supplier as you use them.","content":"$88"},{"upstream":"flight","slug":"flight-conventions","title":"Flight API conventions","summary":"The success and error envelopes, money, local and UTC times, ids and offer references.","content":"$89"},{"upstream":"flight","slug":"flight-errors","title":"Flight API errors","summary":"The error envelope, every code and reason with what to do next, and request ids.","content":"$8a"},{"upstream":"flight","slug":"flight-versioning","title":"Flight API versioning","summary":"What counts as a breaking change, how changes are announced, and how to read new enum values.","content":"$8b"},{"upstream":"mandate","slug":"mandates-overview","title":"Understand Mandates","summary":"Start here: how consent becomes signed payment authority, who owns each step, and when to choose closed or open.","content":"$8c"},{"upstream":"mandate","slug":"getting-started-mandates","title":"Issue your first closed mandate","summary":"Issue a closed mandate, record consent, verify the intended charge, hand it to settlement, and inspect the evidence.","content":"$8d"},{"upstream":"mandate","slug":"open-mandates","title":"Use an open mandate","summary":"Delegate a reusable budget with allowed payees, category limits, charge counts, and race-safe settlement.","content":"$8e"},{"upstream":"mandate","slug":"design-and-ap2","title":"Design choices and AP2","summary":"Why the lifecycle is split into issue, confirm, verify and exercise, plus the precise AP2 compatibility boundary.","content":"$8f"},{"upstream":"mandate","slug":"mandate-constraints","title":"Choose mandate constraints","summary":"Choose and combine amount, payee, time, category-budget and charge-count rules without widening authority.","content":"$90"},{"upstream":"mandate","slug":"checks-results-and-errors","title":"Handle checks, refusals and errors","summary":"Separate transport success from authorization, recover from failed checks, and use the evidence trail safely.","content":"$91"},{"upstream":"watcher","slug":"watcher-overview","title":"Watcher overview","summary":"Understand how Watcher works, choose the right watch type, and plan for its lifecycle.","content":"$92"},{"upstream":"watcher","slug":"getting-started-watches","title":"Create your first price watch","summary":"Create your first hotel price watch and safely process its webhook event.","content":"$93"},{"upstream":"watcher","slug":"auto-purchase","title":"Set up auto-purchase","summary":"Collect consent and arm a hotel watch to purchase within the user's price cap.","content":"$94"},{"upstream":"watcher","slug":"webhooks-and-delivery","title":"Handle webhooks reliably","summary":"Verify, deduplicate, process, and reconcile Watcher events reliably.","content":"$95"},{"upstream":"payment-js","slug":"accept-a-card-payment","title":"Accept a card payment with the Payment SDK","summary":"The handoff token from prebook, mounting the widget, reading the outcome, completing the booking — plus the SDK's options, methods and error names.","content":"$96"}],"paths":{"/v1/hotel/bookings/{id}/weather":{"get":{"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"operationId":"getBookingWeather","tags":["Hotel bookings"],"summary":"Get weather for your hotel stay","description":"You receive daily weather for your stored hotel coordinates and stay dates, including checkout day, regardless of your booking supplier. You need the same organization and user headers as a booking read. Measurements use metric units. Forecasts beyond one week are less reliable. You receive only available days; missing days and optional fields are unknown. Repeating this read requests fresh weather without changing your booking.","parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}},{"schema":{"type":"string","maxLength":128,"pattern":"^bkg_[a-zA-Z0-9-]+$"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Your available weather days, or an empty array when no forecast is available.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"booking_id":{"type":"string"},"hotel_id":{"type":"string","description":"Your stable hotel ID."},"start_date":{"type":"string","format":"date"},"end_date":{"type":"string","format":"date","description":"Your checkout day, included in the requested weather range."},"units":{"type":"string","enum":["metric"]},"days":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"temperature_min":{"type":"number","description":"Your daily minimum temperature in degrees Celsius."},"temperature_max":{"type":"number","description":"Your daily maximum temperature in degrees Celsius."},"summary":{"type":"string"},"conditions":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"icon":{"type":"string","description":"Your provider's weather icon code, when supplied."}},"required":["description"]}},"humidity_percent":{"type":"number","minimum":0,"maximum":100},"afternoon_humidity_percent":{"type":"number","minimum":0,"maximum":100},"wind_speed_mps":{"type":"number","minimum":0,"description":"Your forecast wind speed in metres per second."},"maximum_wind_speed_mps":{"type":"number","minimum":0,"description":"Your daily maximum wind speed in metres per second."},"precipitation_probability":{"type":"number","minimum":0,"maximum":1,"description":"Your chance of precipitation, from zero to one; this is not a precipitation amount."},"precipitation_total_mm":{"type":"number","minimum":0,"description":"Your total forecast precipitation in millimetres."}},"required":["date","temperature_min","temperature_max"]},"description":"Your available forecast days in date order. Missing days and fields are unknown; an empty array means no forecast is available for your stay."}},"required":["booking_id","hotel_id","start_date","end_date","units","days"]}},"required":["data"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"400":{"description":"Your request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hotel_HotelError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"404":{"description":"You cannot access this booking or it does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hotel_HotelError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"422":{"description":"Your stored hotel coordinates are missing, weather is not configured, or the provider rejected your dates or location.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hotel_HotelError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"500":{"description":"Your weather request could not complete because of an internal or provider configuration error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hotel_HotelError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}}}},"/v1/hotel/bookings/{id}/cancel":{"post":{"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"operationId":"cancelHotelBooking","tags":["Hotel bookings"],"summary":"Cancel your hotel booking","description":"You request cancellation of all remaining rooms. Cancellation continues asynchronously; read your booking for its current state and attempt history. Repeated requests reuse an active attempt, and can resume its failed workflow. A canceled stay remains canceled while refunds are processed. Your cancellation refund is the recorded intent, not confirmation of settlement; a null refund requires review. Its refund_to names the payments the refund returns to once the attempt completes.","parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}},{"schema":{"type":"string","maxLength":128,"pattern":"^bkg_[a-zA-Z0-9-]+$"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Your stored booking and cancellation attempts.","content":{"application/json":{"examples":{"cancel_in_progress":{"summary":"Your cancellation is processing","value":{"data":{"id":"bkg_example","reference_id":"order-example","status":"CANCEL_IN_PROGRESS","hotel":{"id":"htl_example","name":"Example Marina Hotel","address":"Example Avenue, Dubai, AE"},"check_in":"2027-11-22","check_out":"2027-11-24","total":{"amount":600,"currency":"USD"},"created_at":"2027-10-01T10:01:00Z","updated_at":"2027-10-02T09:01:00Z","confirmed_at":"2027-10-01T10:03:00Z","canceled_at":null,"payments":[{"id":"pay_example","status":"CAPTURED","amount":{"amount":600,"currency":"USD"},"payment_method":{"type":"CARD","card":{"brand":"VISA","last4":"4242","funding":"CREDIT","wallet":null}},"created_at":"2027-10-01T10:02:00Z"}],"cancellations":[{"id":"can_example","status":"IN_PROGRESS","fee":null,"refund":null,"refund_to":null,"created_at":"2027-10-02T09:01:00Z","canceled_at":null,"error_code":null}],"hotel_confirmation_code":null,"hotel_remarks":null,"offer_expires_at":"2027-10-01T10:15:00Z","due_at_property":null,"cancellation_policy":null,"contact":{"first_name":"Alex","last_name":"Morgan","email":"alex@example.com","phone":"+447700900123"},"loyalty":null,"rooms":[{"id":"room_example1","position":0,"name":"Deluxe Twin","board":"ROOM_ONLY","board_name":"Room Only","adults":2,"children":[],"total":{"amount":300,"currency":"USD"},"due_at_property":null,"cancellation_policy":{"version":1,"refundable":true,"deadline":"2027-11-20T00:00:00Z","penalties":[{"from":"2027-11-20T00:00:00Z","type":"AMOUNT","amount":{"amount":150,"currency":"USD"}}],"restrictions":[]},"promotions":null,"supplier_reference_number":null,"hotel_confirmation_code":null,"canceled_at":null,"guests":[{"id":"guest_example11","first_name":"Alex","last_name":"Morgan","type":"ADULT","is_lead":true},{"id":"guest_example12","first_name":"Sam","last_name":"Morgan","type":"ADULT","is_lead":false}]},{"id":"room_example2","position":1,"name":"Deluxe Double","board":"ROOM_ONLY","board_name":"Room Only","adults":2,"children":[],"total":{"amount":300,"currency":"USD"},"due_at_property":null,"cancellation_policy":{"version":1,"refundable":true,"deadline":"2027-11-20T00:00:00Z","penalties":[{"from":"2027-11-20T00:00:00Z","type":"AMOUNT","amount":{"amount":150,"currency":"USD"}}],"restrictions":[]},"promotions":null,"supplier_reference_number":null,"hotel_confirmation_code":null,"canceled_at":null,"guests":[{"id":"guest_example21","first_name":"Jamie","last_name":"Lee","type":"ADULT","is_lead":true},{"id":"guest_example22","first_name":"Taylor","last_name":"Lee","type":"ADULT","is_lead":false}]}]}}},"canceled":{"summary":"Your released stay with a recorded refund intent","value":{"data":{"id":"bkg_example","reference_id":"order-example","status":"CANCELED","hotel":{"id":"htl_example","name":"Example Marina Hotel","address":"Example Avenue, Dubai, AE"},"check_in":"2027-11-22","check_out":"2027-11-24","total":{"amount":600,"currency":"USD"},"created_at":"2027-10-01T10:01:00Z","updated_at":"2027-10-02T09:02:00Z","confirmed_at":"2027-10-01T10:03:00Z","canceled_at":"2027-10-02T09:02:00Z","payments":[{"id":"pay_example","status":"CAPTURED","amount":{"amount":600,"currency":"USD"},"payment_method":{"type":"CARD","card":{"brand":"VISA","last4":"4242","funding":"CREDIT","wallet":null}},"created_at":"2027-10-01T10:02:00Z"}],"cancellations":[{"id":"can_example","status":"SUCCEEDED","fee":{"amount":0,"currency":"USD"},"refund":{"amount":600,"currency":"USD"},"refund_to":[{"payment_id":"pay_example"}],"created_at":"2027-10-02T09:01:00Z","canceled_at":"2027-10-02T09:02:00Z","error_code":null}],"hotel_confirmation_code":null,"hotel_remarks":null,"offer_expires_at":"2027-10-01T10:15:00Z","due_at_property":null,"cancellation_policy":null,"contact":{"first_name":"Alex","last_name":"Morgan","email":"alex@example.com","phone":"+447700900123"},"loyalty":null,"rooms":[{"id":"room_example1","position":0,"name":"Deluxe Twin","board":"ROOM_ONLY","board_name":"Room Only","adults":2,"children":[],"total":{"amount":300,"currency":"USD"},"due_at_property":null,"cancellation_policy":{"version":1,"refundable":true,"deadline":"2027-11-20T00:00:00Z","penalties":[{"from":"2027-11-20T00:00:00Z","type":"AMOUNT","amount":{"amount":150,"currency":"USD"}}],"restrictions":[]},"promotions":null,"supplier_reference_number":null,"hotel_confirmation_code":null,"canceled_at":"2027-10-02T09:02:00Z","guests":[{"id":"guest_example11","first_name":"Alex","last_name":"Morgan","type":"ADULT","is_lead":true},{"id":"guest_example12","first_name":"Sam","last_name":"Morgan","type":"ADULT","is_lead":false}]},{"id":"room_example2","position":1,"name":"Deluxe Double","board":"ROOM_ONLY","board_name":"Room Only","adults":2,"children":[],"total":{"amount":300,"currency":"USD"},"due_at_property":null,"cancellation_policy":{"version":1,"refundable":true,"deadline":"2027-11-20T00:00:00Z","penalties":[{"from":"2027-11-20T00:00:00Z","type":"AMOUNT","amount":{"amount":150,"currency":"USD"}}],"restrictions":[]},"promotions":null,"supplier_reference_number":null,"hotel_confirmation_code":null,"canceled_at":"2027-10-02T09:02:00Z","guests":[{"id":"guest_example21","first_name":"Jamie","last_name":"Lee","type":"ADULT","is_lead":true},{"id":"guest_example22","first_name":"Taylor","last_name":"Lee","type":"ADULT","is_lead":false}]}]}}},"partial":{"summary":"Your WebBeds stay with one room released","value":{"data":{"id":"bkg_partialexample","reference_id":"order-example","status":"PARTIALLY_CANCELED","hotel":{"id":"htl_webbedsexample","name":"Example Marina Hotel","address":"Example Avenue, Dubai, AE"},"check_in":"2027-11-22","check_out":"2027-11-24","total":{"amount":600,"currency":"USD"},"created_at":"2027-10-01T10:01:00Z","updated_at":"2027-10-02T09:02:00Z","confirmed_at":"2027-10-01T10:03:00Z","canceled_at":null,"payments":[{"id":"pay_example","status":"CAPTURED","amount":{"amount":600,"currency":"USD"},"payment_method":{"type":"CARD","card":{"brand":"VISA","last4":"4242","funding":"CREDIT","wallet":null}},"created_at":"2027-10-01T10:02:00Z"}],"cancellations":[{"id":"can_partialexample","status":"PARTIALLY_SUCCEEDED","fee":{"amount":50,"currency":"USD"},"refund":{"amount":250,"currency":"USD"},"refund_to":[{"payment_id":"pay_example"}],"created_at":"2027-10-02T09:01:00Z","canceled_at":"2027-10-02T09:02:00Z","error_code":null}],"hotel_confirmation_code":null,"hotel_remarks":null,"offer_expires_at":"2027-10-01T10:15:00Z","due_at_property":null,"cancellation_policy":null,"contact":{"first_name":"Alex","last_name":"Morgan","email":"alex@example.com","phone":"+447700900123"},"loyalty":null,"rooms":[{"id":"room_example1","position":0,"name":"Deluxe Twin","board":"ROOM_ONLY","board_name":"Room Only","adults":2,"children":[],"total":{"amount":300,"currency":"USD"},"due_at_property":null,"cancellation_policy":{"version":1,"refundable":true,"deadline":"2027-11-20T00:00:00Z","penalties":[{"from":"2027-11-20T00:00:00Z","type":"AMOUNT","amount":{"amount":150,"currency":"USD"}}],"restrictions":[]},"promotions":null,"supplier_reference_number":"SUPPLIER-ROOM-1","hotel_confirmation_code":null,"canceled_at":"2027-10-02T09:02:00Z","guests":[{"id":"guest_example11","first_name":"Alex","last_name":"Morgan","type":"ADULT","is_lead":true},{"id":"guest_example12","first_name":"Sam","last_name":"Morgan","type":"ADULT","is_lead":false}]},{"id":"room_example2","position":1,"name":"Deluxe Double","board":"ROOM_ONLY","board_name":"Room Only","adults":2,"children":[],"total":{"amount":300,"currency":"USD"},"due_at_property":null,"cancellation_policy":{"version":1,"refundable":true,"deadline":"2027-11-20T00:00:00Z","penalties":[{"from":"2027-11-20T00:00:00Z","type":"AMOUNT","amount":{"amount":150,"currency":"USD"}}],"restrictions":[]},"promotions":null,"supplier_reference_number":"SUPPLIER-ROOM-2","hotel_confirmation_code":null,"canceled_at":null,"guests":[{"id":"guest_example21","first_name":"Jamie","last_name":"Lee","type":"ADULT","is_lead":true},{"id":"guest_example22","first_name":"Taylor","last_name":"Lee","type":"ADULT","is_lead":false}]}]}}},"unknown_refund":{"summary":"Your released stay with an unknown refund","value":{"data":{"id":"bkg_example","reference_id":"order-example","status":"CANCELED","hotel":{"id":"htl_example","name":"Example Marina Hotel","address":"Example Avenue, Dubai, AE"},"check_in":"2027-11-22","check_out":"2027-11-24","total":{"amount":600,"currency":"USD"},"created_at":"2027-10-01T10:01:00Z","updated_at":"2027-10-02T09:02:00Z","confirmed_at":"2027-10-01T10:03:00Z","canceled_at":"2027-10-02T09:02:00Z","payments":[{"id":"pay_example","status":"CAPTURED","amount":{"amount":600,"currency":"USD"},"payment_method":{"type":"CARD","card":{"brand":"VISA","last4":"4242","funding":"CREDIT","wallet":null}},"created_at":"2027-10-01T10:02:00Z"}],"cancellations":[{"id":"can_example","status":"SUCCEEDED","fee":null,"refund":null,"refund_to":null,"created_at":"2027-10-02T09:01:00Z","canceled_at":"2027-10-02T09:02:00Z","error_code":null}],"hotel_confirmation_code":null,"hotel_remarks":null,"offer_expires_at":"2027-10-01T10:15:00Z","due_at_property":null,"cancellation_policy":null,"contact":{"first_name":"Alex","last_name":"Morgan","email":"alex@example.com","phone":"+447700900123"},"loyalty":null,"rooms":[{"id":"room_example1","position":0,"name":"Deluxe Twin","board":"ROOM_ONLY","board_name":"Room Only","adults":2,"children":[],"total":{"amount":300,"currency":"USD"},"due_at_property":null,"cancellation_policy":{"version":1,"refundable":true,"deadline":"2027-11-20T00:00:00Z","penalties":[{"from":"2027-11-20T00:00:00Z","type":"AMOUNT","amount":{"amount":150,"currency":"USD"}}],"restrictions":[]},"promotions":null,"supplier_reference_number":null,"hotel_confirmation_code":null,"canceled_at":"2027-10-02T09:02:00Z","guests":[{"id":"guest_example11","first_name":"Alex","last_name":"Morgan","type":"ADULT","is_lead":true},{"id":"guest_example12","first_name":"Sam","last_name":"Morgan","type":"ADULT","is_lead":false}]},{"id":"room_example2","position":1,"name":"Deluxe Double","board":"ROOM_ONLY","board_name":"Room Only","adults":2,"children":[],"total":{"amount":300,"currency":"USD"},"due_at_property":null,"cancellation_policy":{"version":1,"refundable":true,"deadline":"2027-11-20T00:00:00Z","penalties":[{"from":"2027-11-20T00:00:00Z","type":"AMOUNT","amount":{"amount":150,"currency":"USD"}}],"restrictions":[]},"promotions":null,"supplier_reference_number":null,"hotel_confirmation_code":null,"canceled_at":"2027-10-02T09:02:00Z","guests":[{"id":"guest_example21","first_name":"Jamie","last_name":"Lee","type":"ADULT","is_lead":true},{"id":"guest_example22","first_name":"Taylor","last_name":"Lee","type":"ADULT","is_lead":false}]}]}}}},"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/hotel_HotelBooking"}},"required":["data"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"400":{"description":"Your request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hotel_HotelError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"404":{"description":"You cannot access this booking or it does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hotel_HotelError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"409":{"description":"Your booking is already being processed or cannot enter this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hotel_HotelError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"422":{"description":"You cannot proceed with this offer, guest assignment or payment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hotel_HotelError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"500":{"description":"You must read the booking before taking further action; an unknown purchase outcome must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hotel_HotelError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}}}},"/v1/hotel/bookings/{id}/cancellation-quote":{"get":{"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"operationId":"getHotelCancellationQuote","tags":["Hotel bookings"],"summary":"Estimate your cancellation fee","description":"You receive an advisory quote from fresh supplier data: SUPPLIER_QUOTE uses a cancellation preview (WebBeds), while POLICY_ESTIMATE calculates from a freshly retrieved booking policy (LiteAPI and Duffel Stays). checked_at is the UTC time when the supplier reads completed, not a guaranteed validity deadline. Unreadable or missing booking policies return available=false; failed reads or unusable supplier preview responses return an error instead of stale terms. A local booking change during retrieval returns 409. An active stored WebBeds restriction returns 422 cancellation_restricted before or after the supplier reads. available describes the amount, not whether a new cancellation can start while earlier refund processing remains unfinished. The supplier's cancellation response determines the final fee. Your estimated refund uses the released price; the actual refund is capped by captured funds less previous refund intents.","parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}},{"schema":{"type":"string","maxLength":128,"pattern":"^bkg_[a-zA-Z0-9-]+$"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Your fresh advisory quote or the reason its amount is unavailable.","content":{"application/json":{"examples":{"policy_estimate":{"summary":"Your estimate from a freshly retrieved policy","value":{"data":{"available":true,"source":"POLICY_ESTIMATE","checked_at":"2027-10-02T09:00:00Z","fee":{"amount":0,"currency":"USD"},"refund":{"amount":600,"currency":"USD"},"free_until":"2027-11-20T00:00:00Z","restrictions":[]}}},"supplier_quote":{"summary":"Your WebBeds cancellation preview","value":{"data":{"available":true,"source":"SUPPLIER_QUOTE","checked_at":"2027-10-02T09:00:00Z","fee":{"amount":100,"currency":"USD"},"refund":{"amount":500,"currency":"USD"},"restrictions":[]}}},"unknown_fee":{"summary":"Your fresh policy does not establish a fee","value":{"data":{"available":false,"source":"POLICY_ESTIMATE","checked_at":"2027-10-02T09:00:00Z","reason":"no_policy"}}}},"schema":{"type":"object","properties":{"data":{"oneOf":[{"type":"object","properties":{"available":{"type":"boolean","enum":[true],"description":"You have an advisory fee and refund estimate; this does not authorize cancellation or guarantee the final amount."},"source":{"type":"string","enum":["SUPPLIER_QUOTE","POLICY_ESTIMATE"],"description":"You receive SUPPLIER_QUOTE from a non-canceling supplier preview, or POLICY_ESTIMATE calculated from a freshly retrieved booking policy."},"checked_at":{"type":"string","format":"date-time","description":"You receive the UTC time when the supplier reads completed, not an expiry or guaranteed validity deadline."},"fee":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"description":"Amount in the currency's major units."},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["amount","currency"],"description":"Your advisory fee for canceling all remaining rooms, in major currency units."},"refund":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"description":"Amount in the currency's major units."},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["amount","currency"],"description":"Your released price less the advisory fee. The actual refund is also capped by captured funds less earlier refund intentions; this amount does not establish settlement."},"free_until":{"type":"string","format":"date-time","description":"You reach a paid cancellation tier at this UTC time when the policy establishes it. Omission does not establish free cancellation."},"restrictions":{"type":"array","items":{"type":"object","properties":{"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"},"timezone":{"type":"string"}},"required":["from","to"]}}},"required":["available","source","checked_at","fee","refund","restrictions"]},{"type":"object","properties":{"available":{"type":"boolean","enum":[false],"description":"You cannot display an established fee or refund from this response; neither amount should be treated as zero."},"source":{"type":"string","enum":["SUPPLIER_QUOTE","POLICY_ESTIMATE"],"description":"You receive SUPPLIER_QUOTE from a non-canceling supplier preview, or POLICY_ESTIMATE calculated from a freshly retrieved booking policy."},"checked_at":{"type":"string","format":"date-time","description":"You receive the UTC time when the supplier reads completed, not an expiry or guaranteed validity deadline."},"reason":{"type":"string","enum":["no_policy","no_total","no_live_rooms","currency_mismatch"],"description":"You cannot establish an amount because terms or a price are missing, no rooms remain or currencies differ. Follow the reason before requesting cancellation."}},"required":["available","source","checked_at","reason"]}]}},"required":["data"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"400":{"description":"Your request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hotel_HotelError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"404":{"description":"You cannot access this booking or it does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hotel_HotelError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"409":{"description":"Your booking is already being processed or cannot enter this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hotel_HotelError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"422":{"description":"You cannot receive a quote for this booking now; error.reason says why. With cancellation_restricted, a supplier restriction is active and details.restricted_until gives its end. cancellation_not_quotable, booking_incomplete and supplier_operation_unsupported mean this booking cannot be quoted, and supplier_rejected means the supplier refused the read.","content":{"application/json":{"examples":{"restricted":{"summary":"Your cancellation is currently restricted","value":{"error":{"code":"unprocessable","reason":"cancellation_restricted","message":"Cancellation is currently restricted","request_id":"req_example","details":{"restricted_until":"2027-11-22T00:00:00Z"}}}}},"schema":{"$ref":"#/components/schemas/hotel_HotelError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"500":{"description":"Your quote failed unexpectedly. You can retry this read with bounded backoff and contact support with request_id if it keeps failing; reading a quote never changes your booking, payment or cancellation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hotel_HotelError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}}}},"/v1/hotel/prebook":{"post":{"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"operationId":"prebookHotel","tags":["Hotel bookings"],"summary":"Prebook a hotel stay","description":"You bind an offer to your contact and room guests. Supply one adult lead per room and keep the room order from your offer. Repeat your idempotency key to read the existing booking. A payment SDK token is returned once in meta.payment_sdk.token when you request SDK payment; it is not stored for later retrieval.","parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}},{"schema":{"type":"string","minLength":1,"maxLength":200},"required":true,"name":"x-idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"examples":{"saved_instrument":{"summary":"You will use a saved payment instrument","value":{"offer_reference":"REPLACE_WITH_RETURNED_OFFER_REFERENCE","reference_id":"order-example","use_payment_sdk":false,"contact":{"first_name":"Alex","last_name":"Morgan","email":"alex@example.com","phone":"+447700900123"},"rooms":[{"guests":[{"first_name":"Alex","last_name":"Morgan","type":"ADULT","is_lead":true},{"first_name":"Sam","last_name":"Morgan","type":"ADULT","is_lead":false}]},{"guests":[{"first_name":"Jamie","last_name":"Lee","type":"ADULT","is_lead":true},{"first_name":"Taylor","last_name":"Lee","type":"ADULT","is_lead":false}]}]}},"payment_sdk":{"summary":"You will authorize through the Payment SDK","value":{"offer_reference":"REPLACE_WITH_RETURNED_OFFER_REFERENCE","reference_id":"order-example","use_payment_sdk":true,"contact":{"first_name":"Alex","last_name":"Morgan","email":"alex@example.com","phone":"+447700900123"},"rooms":[{"guests":[{"first_name":"Alex","last_name":"Morgan","type":"ADULT","is_lead":true},{"first_name":"Sam","last_name":"Morgan","type":"ADULT","is_lead":false}]},{"guests":[{"first_name":"Jamie","last_name":"Lee","type":"ADULT","is_lead":true},{"first_name":"Taylor","last_name":"Lee","type":"ADULT","is_lead":false}]}]}}},"schema":{"type":"object","properties":{"offer_reference":{"type":"string","minLength":1,"maxLength":32000},"reference_id":{"type":"string","minLength":1,"maxLength":200},"use_payment_sdk":{"type":"boolean","default":false},"contact":{"type":"object","properties":{"first_name":{"type":"string","minLength":1,"maxLength":100},"last_name":{"type":"string","minLength":1,"maxLength":100},"email":{"type":"string","format":"email"},"phone":{"type":"string","minLength":5,"maxLength":32}},"required":["first_name","last_name","email","phone"],"additionalProperties":false},"rooms":{"type":"array","items":{"type":"object","properties":{"guests":{"type":"array","items":{"type":"object","properties":{"first_name":{"type":"string","minLength":1,"maxLength":100},"last_name":{"type":"string","minLength":1,"maxLength":100},"type":{"type":"string","enum":["ADULT","CHILD"]},"is_lead":{"type":"boolean","default":false}},"required":["first_name","last_name"],"additionalProperties":false},"minItems":1,"maxItems":30}},"required":["guests"],"additionalProperties":false},"minItems":1,"maxItems":8}},"required":["offer_reference","contact","rooms"],"additionalProperties":false}}}},"responses":{"200":{"description":"Your stored booking, including its current state on a repeated key.","content":{"application/json":{"examples":{"saved_instrument":{"summary":"Your ready booking before instrument payment","value":{"data":{"id":"bkg_example","reference_id":"order-example","status":"READY_FOR_COMPLETE","hotel":{"id":"htl_example","name":"Example Marina Hotel","address":"Example Avenue, Dubai, AE"},"check_in":"2027-11-22","check_out":"2027-11-24","total":{"amount":600,"currency":"USD"},"created_at":"2027-10-01T10:01:00Z","updated_at":"2027-10-01T10:01:01Z","confirmed_at":null,"canceled_at":null,"payments":[],"cancellations":[],"hotel_confirmation_code":null,"hotel_remarks":null,"offer_expires_at":"2027-10-01T10:15:00Z","due_at_property":null,"cancellation_policy":null,"contact":{"first_name":"Alex","last_name":"Morgan","email":"alex@example.com","phone":"+447700900123"},"loyalty":null,"rooms":[{"id":"room_example1","position":0,"name":"Deluxe Twin","board":"ROOM_ONLY","board_name":"Room Only","adults":2,"children":[],"total":{"amount":300,"currency":"USD"},"due_at_property":null,"cancellation_policy":{"version":1,"refundable":true,"deadline":"2027-11-20T00:00:00Z","penalties":[{"from":"2027-11-20T00:00:00Z","type":"AMOUNT","amount":{"amount":150,"currency":"USD"}}],"restrictions":[]},"promotions":null,"supplier_reference_number":null,"hotel_confirmation_code":null,"canceled_at":null,"guests":[{"id":"guest_example11","first_name":"Alex","last_name":"Morgan","type":"ADULT","is_lead":true},{"id":"guest_example12","first_name":"Sam","last_name":"Morgan","type":"ADULT","is_lead":false}]},{"id":"room_example2","position":1,"name":"Deluxe Double","board":"ROOM_ONLY","board_name":"Room Only","adults":2,"children":[],"total":{"amount":300,"currency":"USD"},"due_at_property":null,"cancellation_policy":{"version":1,"refundable":true,"deadline":"2027-11-20T00:00:00Z","penalties":[{"from":"2027-11-20T00:00:00Z","type":"AMOUNT","amount":{"amount":150,"currency":"USD"}}],"restrictions":[]},"promotions":null,"supplier_reference_number":null,"hotel_confirmation_code":null,"canceled_at":null,"guests":[{"id":"guest_example21","first_name":"Jamie","last_name":"Lee","type":"ADULT","is_lead":true},{"id":"guest_example22","first_name":"Taylor","last_name":"Lee","type":"ADULT","is_lead":false}]}]}}},"payment_sdk":{"summary":"Your ready booking with a one-time SDK token","value":{"data":{"id":"bkg_example","reference_id":"order-example","status":"READY_FOR_COMPLETE","hotel":{"id":"htl_example","name":"Example Marina Hotel","address":"Example Avenue, Dubai, AE"},"check_in":"2027-11-22","check_out":"2027-11-24","total":{"amount":600,"currency":"USD"},"created_at":"2027-10-01T10:01:00Z","updated_at":"2027-10-01T10:01:01Z","confirmed_at":null,"canceled_at":null,"payments":[{"id":"pay_example","status":"INITIATED","amount":{"amount":600,"currency":"USD"},"payment_method":null,"created_at":"2027-10-01T10:01:00Z"}],"cancellations":[],"hotel_confirmation_code":null,"hotel_remarks":null,"offer_expires_at":"2027-10-01T10:15:00Z","due_at_property":null,"cancellation_policy":null,"contact":{"first_name":"Alex","last_name":"Morgan","email":"alex@example.com","phone":"+447700900123"},"loyalty":null,"rooms":[{"id":"room_example1","position":0,"name":"Deluxe Twin","board":"ROOM_ONLY","board_name":"Room Only","adults":2,"children":[],"total":{"amount":300,"currency":"USD"},"due_at_property":null,"cancellation_policy":{"version":1,"refundable":true,"deadline":"2027-11-20T00:00:00Z","penalties":[{"from":"2027-11-20T00:00:00Z","type":"AMOUNT","amount":{"amount":150,"currency":"USD"}}],"restrictions":[]},"promotions":null,"supplier_reference_number":null,"hotel_confirmation_code":null,"canceled_at":null,"guests":[{"id":"guest_example11","first_name":"Alex","last_name":"Morgan","type":"ADULT","is_lead":true},{"id":"guest_example12","first_name":"Sam","last_name":"Morgan","type":"ADULT","is_lead":false}]},{"id":"room_example2","position":1,"name":"Deluxe Double","board":"ROOM_ONLY","board_name":"Room Only","adults":2,"children":[],"total":{"amount":300,"currency":"USD"},"due_at_property":null,"cancellation_policy":{"version":1,"refundable":true,"deadline":"2027-11-20T00:00:00Z","penalties":[{"from":"2027-11-20T00:00:00Z","type":"AMOUNT","amount":{"amount":150,"currency":"USD"}}],"restrictions":[]},"promotions":null,"supplier_reference_number":null,"hotel_confirmation_code":null,"canceled_at":null,"guests":[{"id":"guest_example21","first_name":"Jamie","last_name":"Lee","type":"ADULT","is_lead":true},{"id":"guest_example22","first_name":"Taylor","last_name":"Lee","type":"ADULT","is_lead":false}]}]},"meta":{"payment_sdk":{"token":"REPLACE_WITH_RETURNED_PAYMENT_SDK_TOKEN"}}}}},"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/hotel_HotelBooking"},"meta":{"type":"object","properties":{"payment_sdk":{"type":"object","properties":{"token":{"type":"string"}},"required":["token"]}},"required":["payment_sdk"]}},"required":["data"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"400":{"description":"Your request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hotel_HotelError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"404":{"description":"You cannot access this booking or it does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hotel_HotelError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"409":{"description":"Your booking is already being processed or cannot enter this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hotel_HotelError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"422":{"description":"You cannot proceed with this offer, guest assignment or payment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hotel_HotelError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"500":{"description":"You must read the booking before taking further action; an unknown purchase outcome must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hotel_HotelError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}}}},"/v1/hotel/bookings/{id}/book":{"post":{"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"operationId":"bookHotel","tags":["Hotel bookings"],"summary":"Complete your hotel booking","description":"You complete a ready booking with your saved payment instrument, or send an empty object after authorizing the SDK payment. A repeated confirmed booking returns its stored result. Read an in-progress booking when the result is unknown; do not create a replacement purchase.","parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}},{"schema":{"type":"string","maxLength":128,"pattern":"^bkg_[a-zA-Z0-9-]+$"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"examples":{"saved_instrument":{"summary":"You pay with a saved instrument","value":{"payment_instrument_id":"REPLACE_WITH_YOUR_PAYMENT_INSTRUMENT_ID"}},"payment_sdk":{"summary":"You have completed SDK authorization","value":{}}},"schema":{"type":"object","properties":{"payment_instrument_id":{"type":"string","minLength":1,"maxLength":200}},"additionalProperties":false}}}},"responses":{"200":{"description":"Your stored booking after completion.","content":{"application/json":{"examples":{"confirmed":{"summary":"Your confirmed reservation","value":{"data":{"id":"bkg_example","reference_id":"order-example","status":"CONFIRMED","hotel":{"id":"htl_example","name":"Example Marina Hotel","address":"Example Avenue, Dubai, AE"},"check_in":"2027-11-22","check_out":"2027-11-24","total":{"amount":600,"currency":"USD"},"created_at":"2027-10-01T10:01:00Z","updated_at":"2027-10-01T10:03:00Z","confirmed_at":"2027-10-01T10:03:00Z","canceled_at":null,"payments":[{"id":"pay_example","status":"CAPTURED","amount":{"amount":600,"currency":"USD"},"payment_method":{"type":"CARD","card":{"brand":"VISA","last4":"4242","funding":"CREDIT","wallet":null}},"created_at":"2027-10-01T10:02:00Z"}],"cancellations":[],"hotel_confirmation_code":null,"hotel_remarks":null,"offer_expires_at":"2027-10-01T10:15:00Z","due_at_property":null,"cancellation_policy":null,"contact":{"first_name":"Alex","last_name":"Morgan","email":"alex@example.com","phone":"+447700900123"},"loyalty":null,"rooms":[{"id":"room_example1","position":0,"name":"Deluxe Twin","board":"ROOM_ONLY","board_name":"Room Only","adults":2,"children":[],"total":{"amount":300,"currency":"USD"},"due_at_property":null,"cancellation_policy":{"version":1,"refundable":true,"deadline":"2027-11-20T00:00:00Z","penalties":[{"from":"2027-11-20T00:00:00Z","type":"AMOUNT","amount":{"amount":150,"currency":"USD"}}],"restrictions":[]},"promotions":null,"supplier_reference_number":null,"hotel_confirmation_code":null,"canceled_at":null,"guests":[{"id":"guest_example11","first_name":"Alex","last_name":"Morgan","type":"ADULT","is_lead":true},{"id":"guest_example12","first_name":"Sam","last_name":"Morgan","type":"ADULT","is_lead":false}]},{"id":"room_example2","position":1,"name":"Deluxe Double","board":"ROOM_ONLY","board_name":"Room Only","adults":2,"children":[],"total":{"amount":300,"currency":"USD"},"due_at_property":null,"cancellation_policy":{"version":1,"refundable":true,"deadline":"2027-11-20T00:00:00Z","penalties":[{"from":"2027-11-20T00:00:00Z","type":"AMOUNT","amount":{"amount":150,"currency":"USD"}}],"restrictions":[]},"promotions":null,"supplier_reference_number":null,"hotel_confirmation_code":null,"canceled_at":null,"guests":[{"id":"guest_example21","first_name":"Jamie","last_name":"Lee","type":"ADULT","is_lead":true},{"id":"guest_example22","first_name":"Taylor","last_name":"Lee","type":"ADULT","is_lead":false}]}]}}},"cancel_in_progress":{"summary":"Your cancellation is processing","value":{"data":{"id":"bkg_example","reference_id":"order-example","status":"CANCEL_IN_PROGRESS","hotel":{"id":"htl_example","name":"Example Marina Hotel","address":"Example Avenue, Dubai, AE"},"check_in":"2027-11-22","check_out":"2027-11-24","total":{"amount":600,"currency":"USD"},"created_at":"2027-10-01T10:01:00Z","updated_at":"2027-10-02T09:01:00Z","confirmed_at":"2027-10-01T10:03:00Z","canceled_at":null,"payments":[{"id":"pay_example","status":"CAPTURED","amount":{"amount":600,"currency":"USD"},"payment_method":{"type":"CARD","card":{"brand":"VISA","last4":"4242","funding":"CREDIT","wallet":null}},"created_at":"2027-10-01T10:02:00Z"}],"cancellations":[{"id":"can_example","status":"IN_PROGRESS","fee":null,"refund":null,"refund_to":null,"created_at":"2027-10-02T09:01:00Z","canceled_at":null,"error_code":null}],"hotel_confirmation_code":null,"hotel_remarks":null,"offer_expires_at":"2027-10-01T10:15:00Z","due_at_property":null,"cancellation_policy":null,"contact":{"first_name":"Alex","last_name":"Morgan","email":"alex@example.com","phone":"+447700900123"},"loyalty":null,"rooms":[{"id":"room_example1","position":0,"name":"Deluxe Twin","board":"ROOM_ONLY","board_name":"Room Only","adults":2,"children":[],"total":{"amount":300,"currency":"USD"},"due_at_property":null,"cancellation_policy":{"version":1,"refundable":true,"deadline":"2027-11-20T00:00:00Z","penalties":[{"from":"2027-11-20T00:00:00Z","type":"AMOUNT","amount":{"amount":150,"currency":"USD"}}],"restrictions":[]},"promotions":null,"supplier_reference_number":null,"hotel_confirmation_code":null,"canceled_at":null,"guests":[{"id":"guest_example11","first_name":"Alex","last_name":"Morgan","type":"ADULT","is_lead":true},{"id":"guest_example12","first_name":"Sam","last_name":"Morgan","type":"ADULT","is_lead":false}]},{"id":"room_example2","position":1,"name":"Deluxe Double","board":"ROOM_ONLY","board_name":"Room Only","adults":2,"children":[],"total":{"amount":300,"currency":"USD"},"due_at_property":null,"cancellation_policy":{"version":1,"refundable":true,"deadline":"2027-11-20T00:00:00Z","penalties":[{"from":"2027-11-20T00:00:00Z","type":"AMOUNT","amount":{"amount":150,"currency":"USD"}}],"restrictions":[]},"promotions":null,"supplier_reference_number":null,"hotel_confirmation_code":null,"canceled_at":null,"guests":[{"id":"guest_example21","first_name":"Jamie","last_name":"Lee","type":"ADULT","is_lead":true},{"id":"guest_example22","first_name":"Taylor","last_name":"Lee","type":"ADULT","is_lead":false}]}]}}},"canceled":{"summary":"Your released stay with a recorded refund intent","value":{"data":{"id":"bkg_example","reference_id":"order-example","status":"CANCELED","hotel":{"id":"htl_example","name":"Example Marina Hotel","address":"Example Avenue, Dubai, AE"},"check_in":"2027-11-22","check_out":"2027-11-24","total":{"amount":600,"currency":"USD"},"created_at":"2027-10-01T10:01:00Z","updated_at":"2027-10-02T09:02:00Z","confirmed_at":"2027-10-01T10:03:00Z","canceled_at":"2027-10-02T09:02:00Z","payments":[{"id":"pay_example","status":"CAPTURED","amount":{"amount":600,"currency":"USD"},"payment_method":{"type":"CARD","card":{"brand":"VISA","last4":"4242","funding":"CREDIT","wallet":null}},"created_at":"2027-10-01T10:02:00Z"}],"cancellations":[{"id":"can_example","status":"SUCCEEDED","fee":{"amount":0,"currency":"USD"},"refund":{"amount":600,"currency":"USD"},"refund_to":[{"payment_id":"pay_example"}],"created_at":"2027-10-02T09:01:00Z","canceled_at":"2027-10-02T09:02:00Z","error_code":null}],"hotel_confirmation_code":null,"hotel_remarks":null,"offer_expires_at":"2027-10-01T10:15:00Z","due_at_property":null,"cancellation_policy":null,"contact":{"first_name":"Alex","last_name":"Morgan","email":"alex@example.com","phone":"+447700900123"},"loyalty":null,"rooms":[{"id":"room_example1","position":0,"name":"Deluxe Twin","board":"ROOM_ONLY","board_name":"Room Only","adults":2,"children":[],"total":{"amount":300,"currency":"USD"},"due_at_property":null,"cancellation_policy":{"version":1,"refundable":true,"deadline":"2027-11-20T00:00:00Z","penalties":[{"from":"2027-11-20T00:00:00Z","type":"AMOUNT","amount":{"amount":150,"currency":"USD"}}],"restrictions":[]},"promotions":null,"supplier_reference_number":null,"hotel_confirmation_code":null,"canceled_at":"2027-10-02T09:02:00Z","guests":[{"id":"guest_example11","first_name":"Alex","last_name":"Morgan","type":"ADULT","is_lead":true},{"id":"guest_example12","first_name":"Sam","last_name":"Morgan","type":"ADULT","is_lead":false}]},{"id":"room_example2","position":1,"name":"Deluxe Double","board":"ROOM_ONLY","board_name":"Room Only","adults":2,"children":[],"total":{"amount":300,"currency":"USD"},"due_at_property":null,"cancellation_policy":{"version":1,"refundable":true,"deadline":"2027-11-20T00:00:00Z","penalties":[{"from":"2027-11-20T00:00:00Z","type":"AMOUNT","amount":{"amount":150,"currency":"USD"}}],"restrictions":[]},"promotions":null,"supplier_reference_number":null,"hotel_confirmation_code":null,"canceled_at":"2027-10-02T09:02:00Z","guests":[{"id":"guest_example21","first_name":"Jamie","last_name":"Lee","type":"ADULT","is_lead":true},{"id":"guest_example22","first_name":"Taylor","last_name":"Lee","type":"ADULT","is_lead":false}]}]}}},"partial":{"summary":"Your WebBeds stay with one room released","value":{"data":{"id":"bkg_partialexample","reference_id":"order-example","status":"PARTIALLY_CANCELED","hotel":{"id":"htl_webbedsexample","name":"Example Marina Hotel","address":"Example Avenue, Dubai, AE"},"check_in":"2027-11-22","check_out":"2027-11-24","total":{"amount":600,"currency":"USD"},"created_at":"2027-10-01T10:01:00Z","updated_at":"2027-10-02T09:02:00Z","confirmed_at":"2027-10-01T10:03:00Z","canceled_at":null,"payments":[{"id":"pay_example","status":"CAPTURED","amount":{"amount":600,"currency":"USD"},"payment_method":{"type":"CARD","card":{"brand":"VISA","last4":"4242","funding":"CREDIT","wallet":null}},"created_at":"2027-10-01T10:02:00Z"}],"cancellations":[{"id":"can_partialexample","status":"PARTIALLY_SUCCEEDED","fee":{"amount":50,"currency":"USD"},"refund":{"amount":250,"currency":"USD"},"refund_to":[{"payment_id":"pay_example"}],"created_at":"2027-10-02T09:01:00Z","canceled_at":"2027-10-02T09:02:00Z","error_code":null}],"hotel_confirmation_code":null,"hotel_remarks":null,"offer_expires_at":"2027-10-01T10:15:00Z","due_at_property":null,"cancellation_policy":null,"contact":{"first_name":"Alex","last_name":"Morgan","email":"alex@example.com","phone":"+447700900123"},"loyalty":null,"rooms":[{"id":"room_example1","position":0,"name":"Deluxe Twin","board":"ROOM_ONLY","board_name":"Room Only","adults":2,"children":[],"total":{"amount":300,"currency":"USD"},"due_at_property":null,"cancellation_policy":{"version":1,"refundable":true,"deadline":"2027-11-20T00:00:00Z","penalties":[{"from":"2027-11-20T00:00:00Z","type":"AMOUNT","amount":{"amount":150,"currency":"USD"}}],"restrictions":[]},"promotions":null,"supplier_reference_number":"SUPPLIER-ROOM-1","hotel_confirmation_code":null,"canceled_at":"2027-10-02T09:02:00Z","guests":[{"id":"guest_example11","first_name":"Alex","last_name":"Morgan","type":"ADULT","is_lead":true},{"id":"guest_example12","first_name":"Sam","last_name":"Morgan","type":"ADULT","is_lead":false}]},{"id":"room_example2","position":1,"name":"Deluxe Double","board":"ROOM_ONLY","board_name":"Room Only","adults":2,"children":[],"total":{"amount":300,"currency":"USD"},"due_at_property":null,"cancellation_policy":{"version":1,"refundable":true,"deadline":"2027-11-20T00:00:00Z","penalties":[{"from":"2027-11-20T00:00:00Z","type":"AMOUNT","amount":{"amount":150,"currency":"USD"}}],"restrictions":[]},"promotions":null,"supplier_reference_number":"SUPPLIER-ROOM-2","hotel_confirmation_code":null,"canceled_at":null,"guests":[{"id":"guest_example21","first_name":"Jamie","last_name":"Lee","type":"ADULT","is_lead":true},{"id":"guest_example22","first_name":"Taylor","last_name":"Lee","type":"ADULT","is_lead":false}]}]}}},"unknown_refund":{"summary":"Your released stay with an unknown refund","value":{"data":{"id":"bkg_example","reference_id":"order-example","status":"CANCELED","hotel":{"id":"htl_example","name":"Example Marina Hotel","address":"Example Avenue, Dubai, AE"},"check_in":"2027-11-22","check_out":"2027-11-24","total":{"amount":600,"currency":"USD"},"created_at":"2027-10-01T10:01:00Z","updated_at":"2027-10-02T09:02:00Z","confirmed_at":"2027-10-01T10:03:00Z","canceled_at":"2027-10-02T09:02:00Z","payments":[{"id":"pay_example","status":"CAPTURED","amount":{"amount":600,"currency":"USD"},"payment_method":{"type":"CARD","card":{"brand":"VISA","last4":"4242","funding":"CREDIT","wallet":null}},"created_at":"2027-10-01T10:02:00Z"}],"cancellations":[{"id":"can_example","status":"SUCCEEDED","fee":null,"refund":null,"refund_to":null,"created_at":"2027-10-02T09:01:00Z","canceled_at":"2027-10-02T09:02:00Z","error_code":null}],"hotel_confirmation_code":null,"hotel_remarks":null,"offer_expires_at":"2027-10-01T10:15:00Z","due_at_property":null,"cancellation_policy":null,"contact":{"first_name":"Alex","last_name":"Morgan","email":"alex@example.com","phone":"+447700900123"},"loyalty":null,"rooms":[{"id":"room_example1","position":0,"name":"Deluxe Twin","board":"ROOM_ONLY","board_name":"Room Only","adults":2,"children":[],"total":{"amount":300,"currency":"USD"},"due_at_property":null,"cancellation_policy":{"version":1,"refundable":true,"deadline":"2027-11-20T00:00:00Z","penalties":[{"from":"2027-11-20T00:00:00Z","type":"AMOUNT","amount":{"amount":150,"currency":"USD"}}],"restrictions":[]},"promotions":null,"supplier_reference_number":null,"hotel_confirmation_code":null,"canceled_at":"2027-10-02T09:02:00Z","guests":[{"id":"guest_example11","first_name":"Alex","last_name":"Morgan","type":"ADULT","is_lead":true},{"id":"guest_example12","first_name":"Sam","last_name":"Morgan","type":"ADULT","is_lead":false}]},{"id":"room_example2","position":1,"name":"Deluxe Double","board":"ROOM_ONLY","board_name":"Room Only","adults":2,"children":[],"total":{"amount":300,"currency":"USD"},"due_at_property":null,"cancellation_policy":{"version":1,"refundable":true,"deadline":"2027-11-20T00:00:00Z","penalties":[{"from":"2027-11-20T00:00:00Z","type":"AMOUNT","amount":{"amount":150,"currency":"USD"}}],"restrictions":[]},"promotions":null,"supplier_reference_number":null,"hotel_confirmation_code":null,"canceled_at":"2027-10-02T09:02:00Z","guests":[{"id":"guest_example21","first_name":"Jamie","last_name":"Lee","type":"ADULT","is_lead":true},{"id":"guest_example22","first_name":"Taylor","last_name":"Lee","type":"ADULT","is_lead":false}]}]}}}},"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/hotel_HotelBooking"}},"required":["data"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"400":{"description":"Your request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hotel_HotelError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"404":{"description":"You cannot access this booking or it does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hotel_HotelError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"409":{"description":"Your booking is already being processed or cannot enter this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hotel_HotelError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"422":{"description":"You cannot proceed with this offer, guest assignment or payment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hotel_HotelError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"500":{"description":"You must read the booking before taking further action; an unknown purchase outcome must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hotel_HotelError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}}}},"/v1/hotel/bookings/{id}":{"get":{"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"operationId":"getHotelBooking","tags":["Hotel bookings"],"summary":"Read your hotel booking","description":"You receive the stay, contact and guests assigned to each room. Money is in major currency units. Room prices and cancellation policies apply only to that room. Due-at-property uses a stated booking total, otherwise a complete same-currency room sum or a list when room currencies differ; null means the total is unknown. Your hotel.id is the service's stable hotel ID. You receive every payment, oldest first, with the card your traveller paid with when it could be read in time.","parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}},{"schema":{"type":"string","maxLength":128,"pattern":"^bkg_[a-zA-Z0-9-]+$"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Your booking details.","content":{"application/json":{"examples":{"confirmed":{"summary":"Your confirmed reservation","value":{"data":{"id":"bkg_example","reference_id":"order-example","status":"CONFIRMED","hotel":{"id":"htl_example","name":"Example Marina Hotel","address":"Example Avenue, Dubai, AE"},"check_in":"2027-11-22","check_out":"2027-11-24","total":{"amount":600,"currency":"USD"},"created_at":"2027-10-01T10:01:00Z","updated_at":"2027-10-01T10:03:00Z","confirmed_at":"2027-10-01T10:03:00Z","canceled_at":null,"payments":[{"id":"pay_example","status":"CAPTURED","amount":{"amount":600,"currency":"USD"},"payment_method":{"type":"CARD","card":{"brand":"VISA","last4":"4242","funding":"CREDIT","wallet":null}},"created_at":"2027-10-01T10:02:00Z"}],"cancellations":[],"hotel_confirmation_code":null,"hotel_remarks":null,"offer_expires_at":"2027-10-01T10:15:00Z","due_at_property":null,"cancellation_policy":null,"contact":{"first_name":"Alex","last_name":"Morgan","email":"alex@example.com","phone":"+447700900123"},"loyalty":null,"rooms":[{"id":"room_example1","position":0,"name":"Deluxe Twin","board":"ROOM_ONLY","board_name":"Room Only","adults":2,"children":[],"total":{"amount":300,"currency":"USD"},"due_at_property":null,"cancellation_policy":{"version":1,"refundable":true,"deadline":"2027-11-20T00:00:00Z","penalties":[{"from":"2027-11-20T00:00:00Z","type":"AMOUNT","amount":{"amount":150,"currency":"USD"}}],"restrictions":[]},"promotions":null,"supplier_reference_number":null,"hotel_confirmation_code":null,"canceled_at":null,"guests":[{"id":"guest_example11","first_name":"Alex","last_name":"Morgan","type":"ADULT","is_lead":true},{"id":"guest_example12","first_name":"Sam","last_name":"Morgan","type":"ADULT","is_lead":false}]},{"id":"room_example2","position":1,"name":"Deluxe Double","board":"ROOM_ONLY","board_name":"Room Only","adults":2,"children":[],"total":{"amount":300,"currency":"USD"},"due_at_property":null,"cancellation_policy":{"version":1,"refundable":true,"deadline":"2027-11-20T00:00:00Z","penalties":[{"from":"2027-11-20T00:00:00Z","type":"AMOUNT","amount":{"amount":150,"currency":"USD"}}],"restrictions":[]},"promotions":null,"supplier_reference_number":null,"hotel_confirmation_code":null,"canceled_at":null,"guests":[{"id":"guest_example21","first_name":"Jamie","last_name":"Lee","type":"ADULT","is_lead":true},{"id":"guest_example22","first_name":"Taylor","last_name":"Lee","type":"ADULT","is_lead":false}]}]}}},"cancel_in_progress":{"summary":"Your cancellation is processing","value":{"data":{"id":"bkg_example","reference_id":"order-example","status":"CANCEL_IN_PROGRESS","hotel":{"id":"htl_example","name":"Example Marina Hotel","address":"Example Avenue, Dubai, AE"},"check_in":"2027-11-22","check_out":"2027-11-24","total":{"amount":600,"currency":"USD"},"created_at":"2027-10-01T10:01:00Z","updated_at":"2027-10-02T09:01:00Z","confirmed_at":"2027-10-01T10:03:00Z","canceled_at":null,"payments":[{"id":"pay_example","status":"CAPTURED","amount":{"amount":600,"currency":"USD"},"payment_method":{"type":"CARD","card":{"brand":"VISA","last4":"4242","funding":"CREDIT","wallet":null}},"created_at":"2027-10-01T10:02:00Z"}],"cancellations":[{"id":"can_example","status":"IN_PROGRESS","fee":null,"refund":null,"refund_to":null,"created_at":"2027-10-02T09:01:00Z","canceled_at":null,"error_code":null}],"hotel_confirmation_code":null,"hotel_remarks":null,"offer_expires_at":"2027-10-01T10:15:00Z","due_at_property":null,"cancellation_policy":null,"contact":{"first_name":"Alex","last_name":"Morgan","email":"alex@example.com","phone":"+447700900123"},"loyalty":null,"rooms":[{"id":"room_example1","position":0,"name":"Deluxe Twin","board":"ROOM_ONLY","board_name":"Room Only","adults":2,"children":[],"total":{"amount":300,"currency":"USD"},"due_at_property":null,"cancellation_policy":{"version":1,"refundable":true,"deadline":"2027-11-20T00:00:00Z","penalties":[{"from":"2027-11-20T00:00:00Z","type":"AMOUNT","amount":{"amount":150,"currency":"USD"}}],"restrictions":[]},"promotions":null,"supplier_reference_number":null,"hotel_confirmation_code":null,"canceled_at":null,"guests":[{"id":"guest_example11","first_name":"Alex","last_name":"Morgan","type":"ADULT","is_lead":true},{"id":"guest_example12","first_name":"Sam","last_name":"Morgan","type":"ADULT","is_lead":false}]},{"id":"room_example2","position":1,"name":"Deluxe Double","board":"ROOM_ONLY","board_name":"Room Only","adults":2,"children":[],"total":{"amount":300,"currency":"USD"},"due_at_property":null,"cancellation_policy":{"version":1,"refundable":true,"deadline":"2027-11-20T00:00:00Z","penalties":[{"from":"2027-11-20T00:00:00Z","type":"AMOUNT","amount":{"amount":150,"currency":"USD"}}],"restrictions":[]},"promotions":null,"supplier_reference_number":null,"hotel_confirmation_code":null,"canceled_at":null,"guests":[{"id":"guest_example21","first_name":"Jamie","last_name":"Lee","type":"ADULT","is_lead":true},{"id":"guest_example22","first_name":"Taylor","last_name":"Lee","type":"ADULT","is_lead":false}]}]}}},"canceled":{"summary":"Your released stay with a recorded refund intent","value":{"data":{"id":"bkg_example","reference_id":"order-example","status":"CANCELED","hotel":{"id":"htl_example","name":"Example Marina Hotel","address":"Example Avenue, Dubai, AE"},"check_in":"2027-11-22","check_out":"2027-11-24","total":{"amount":600,"currency":"USD"},"created_at":"2027-10-01T10:01:00Z","updated_at":"2027-10-02T09:02:00Z","confirmed_at":"2027-10-01T10:03:00Z","canceled_at":"2027-10-02T09:02:00Z","payments":[{"id":"pay_example","status":"CAPTURED","amount":{"amount":600,"currency":"USD"},"payment_method":{"type":"CARD","card":{"brand":"VISA","last4":"4242","funding":"CREDIT","wallet":null}},"created_at":"2027-10-01T10:02:00Z"}],"cancellations":[{"id":"can_example","status":"SUCCEEDED","fee":{"amount":0,"currency":"USD"},"refund":{"amount":600,"currency":"USD"},"refund_to":[{"payment_id":"pay_example"}],"created_at":"2027-10-02T09:01:00Z","canceled_at":"2027-10-02T09:02:00Z","error_code":null}],"hotel_confirmation_code":null,"hotel_remarks":null,"offer_expires_at":"2027-10-01T10:15:00Z","due_at_property":null,"cancellation_policy":null,"contact":{"first_name":"Alex","last_name":"Morgan","email":"alex@example.com","phone":"+447700900123"},"loyalty":null,"rooms":[{"id":"room_example1","position":0,"name":"Deluxe Twin","board":"ROOM_ONLY","board_name":"Room Only","adults":2,"children":[],"total":{"amount":300,"currency":"USD"},"due_at_property":null,"cancellation_policy":{"version":1,"refundable":true,"deadline":"2027-11-20T00:00:00Z","penalties":[{"from":"2027-11-20T00:00:00Z","type":"AMOUNT","amount":{"amount":150,"currency":"USD"}}],"restrictions":[]},"promotions":null,"supplier_reference_number":null,"hotel_confirmation_code":null,"canceled_at":"2027-10-02T09:02:00Z","guests":[{"id":"guest_example11","first_name":"Alex","last_name":"Morgan","type":"ADULT","is_lead":true},{"id":"guest_example12","first_name":"Sam","last_name":"Morgan","type":"ADULT","is_lead":false}]},{"id":"room_example2","position":1,"name":"Deluxe Double","board":"ROOM_ONLY","board_name":"Room Only","adults":2,"children":[],"total":{"amount":300,"currency":"USD"},"due_at_property":null,"cancellation_policy":{"version":1,"refundable":true,"deadline":"2027-11-20T00:00:00Z","penalties":[{"from":"2027-11-20T00:00:00Z","type":"AMOUNT","amount":{"amount":150,"currency":"USD"}}],"restrictions":[]},"promotions":null,"supplier_reference_number":null,"hotel_confirmation_code":null,"canceled_at":"2027-10-02T09:02:00Z","guests":[{"id":"guest_example21","first_name":"Jamie","last_name":"Lee","type":"ADULT","is_lead":true},{"id":"guest_example22","first_name":"Taylor","last_name":"Lee","type":"ADULT","is_lead":false}]}]}}},"partial":{"summary":"Your WebBeds stay with one room released","value":{"data":{"id":"bkg_partialexample","reference_id":"order-example","status":"PARTIALLY_CANCELED","hotel":{"id":"htl_webbedsexample","name":"Example Marina Hotel","address":"Example Avenue, Dubai, AE"},"check_in":"2027-11-22","check_out":"2027-11-24","total":{"amount":600,"currency":"USD"},"created_at":"2027-10-01T10:01:00Z","updated_at":"2027-10-02T09:02:00Z","confirmed_at":"2027-10-01T10:03:00Z","canceled_at":null,"payments":[{"id":"pay_example","status":"CAPTURED","amount":{"amount":600,"currency":"USD"},"payment_method":{"type":"CARD","card":{"brand":"VISA","last4":"4242","funding":"CREDIT","wallet":null}},"created_at":"2027-10-01T10:02:00Z"}],"cancellations":[{"id":"can_partialexample","status":"PARTIALLY_SUCCEEDED","fee":{"amount":50,"currency":"USD"},"refund":{"amount":250,"currency":"USD"},"refund_to":[{"payment_id":"pay_example"}],"created_at":"2027-10-02T09:01:00Z","canceled_at":"2027-10-02T09:02:00Z","error_code":null}],"hotel_confirmation_code":null,"hotel_remarks":null,"offer_expires_at":"2027-10-01T10:15:00Z","due_at_property":null,"cancellation_policy":null,"contact":{"first_name":"Alex","last_name":"Morgan","email":"alex@example.com","phone":"+447700900123"},"loyalty":null,"rooms":[{"id":"room_example1","position":0,"name":"Deluxe Twin","board":"ROOM_ONLY","board_name":"Room Only","adults":2,"children":[],"total":{"amount":300,"currency":"USD"},"due_at_property":null,"cancellation_policy":{"version":1,"refundable":true,"deadline":"2027-11-20T00:00:00Z","penalties":[{"from":"2027-11-20T00:00:00Z","type":"AMOUNT","amount":{"amount":150,"currency":"USD"}}],"restrictions":[]},"promotions":null,"supplier_reference_number":"SUPPLIER-ROOM-1","hotel_confirmation_code":null,"canceled_at":"2027-10-02T09:02:00Z","guests":[{"id":"guest_example11","first_name":"Alex","last_name":"Morgan","type":"ADULT","is_lead":true},{"id":"guest_example12","first_name":"Sam","last_name":"Morgan","type":"ADULT","is_lead":false}]},{"id":"room_example2","position":1,"name":"Deluxe Double","board":"ROOM_ONLY","board_name":"Room Only","adults":2,"children":[],"total":{"amount":300,"currency":"USD"},"due_at_property":null,"cancellation_policy":{"version":1,"refundable":true,"deadline":"2027-11-20T00:00:00Z","penalties":[{"from":"2027-11-20T00:00:00Z","type":"AMOUNT","amount":{"amount":150,"currency":"USD"}}],"restrictions":[]},"promotions":null,"supplier_reference_number":"SUPPLIER-ROOM-2","hotel_confirmation_code":null,"canceled_at":null,"guests":[{"id":"guest_example21","first_name":"Jamie","last_name":"Lee","type":"ADULT","is_lead":true},{"id":"guest_example22","first_name":"Taylor","last_name":"Lee","type":"ADULT","is_lead":false}]}]}}},"unknown_refund":{"summary":"Your released stay with an unknown refund","value":{"data":{"id":"bkg_example","reference_id":"order-example","status":"CANCELED","hotel":{"id":"htl_example","name":"Example Marina Hotel","address":"Example Avenue, Dubai, AE"},"check_in":"2027-11-22","check_out":"2027-11-24","total":{"amount":600,"currency":"USD"},"created_at":"2027-10-01T10:01:00Z","updated_at":"2027-10-02T09:02:00Z","confirmed_at":"2027-10-01T10:03:00Z","canceled_at":"2027-10-02T09:02:00Z","payments":[{"id":"pay_example","status":"CAPTURED","amount":{"amount":600,"currency":"USD"},"payment_method":{"type":"CARD","card":{"brand":"VISA","last4":"4242","funding":"CREDIT","wallet":null}},"created_at":"2027-10-01T10:02:00Z"}],"cancellations":[{"id":"can_example","status":"SUCCEEDED","fee":null,"refund":null,"refund_to":null,"created_at":"2027-10-02T09:01:00Z","canceled_at":"2027-10-02T09:02:00Z","error_code":null}],"hotel_confirmation_code":null,"hotel_remarks":null,"offer_expires_at":"2027-10-01T10:15:00Z","due_at_property":null,"cancellation_policy":null,"contact":{"first_name":"Alex","last_name":"Morgan","email":"alex@example.com","phone":"+447700900123"},"loyalty":null,"rooms":[{"id":"room_example1","position":0,"name":"Deluxe Twin","board":"ROOM_ONLY","board_name":"Room Only","adults":2,"children":[],"total":{"amount":300,"currency":"USD"},"due_at_property":null,"cancellation_policy":{"version":1,"refundable":true,"deadline":"2027-11-20T00:00:00Z","penalties":[{"from":"2027-11-20T00:00:00Z","type":"AMOUNT","amount":{"amount":150,"currency":"USD"}}],"restrictions":[]},"promotions":null,"supplier_reference_number":null,"hotel_confirmation_code":null,"canceled_at":"2027-10-02T09:02:00Z","guests":[{"id":"guest_example11","first_name":"Alex","last_name":"Morgan","type":"ADULT","is_lead":true},{"id":"guest_example12","first_name":"Sam","last_name":"Morgan","type":"ADULT","is_lead":false}]},{"id":"room_example2","position":1,"name":"Deluxe Double","board":"ROOM_ONLY","board_name":"Room Only","adults":2,"children":[],"total":{"amount":300,"currency":"USD"},"due_at_property":null,"cancellation_policy":{"version":1,"refundable":true,"deadline":"2027-11-20T00:00:00Z","penalties":[{"from":"2027-11-20T00:00:00Z","type":"AMOUNT","amount":{"amount":150,"currency":"USD"}}],"restrictions":[]},"promotions":null,"supplier_reference_number":null,"hotel_confirmation_code":null,"canceled_at":"2027-10-02T09:02:00Z","guests":[{"id":"guest_example21","first_name":"Jamie","last_name":"Lee","type":"ADULT","is_lead":true},{"id":"guest_example22","first_name":"Taylor","last_name":"Lee","type":"ADULT","is_lead":false}]}]}}}},"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/hotel_HotelBooking"}},"required":["data"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"400":{"description":"Your request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hotel_HotelError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"404":{"description":"You cannot access this booking or it does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hotel_HotelError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"409":{"description":"Your booking is already being processed or cannot enter this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hotel_HotelError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"422":{"description":"You cannot proceed with this offer, guest assignment or payment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hotel_HotelError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"500":{"description":"You must read the booking before taking further action; an unknown purchase outcome must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hotel_HotelError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}}}},"/v1/hotel/bookings":{"get":{"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"operationId":"listHotelBookings","tags":["Hotel bookings"],"summary":"List your hotel bookings","description":"You receive your booking summaries from newest to oldest, each with its payments but without their cards. You filter by status, your exact reference_id, or both; these filters apply only to bookings owned by your organization and user. A reference is not unique, so keep every matching result. Use limit and offset to request another page with the same filters, and stop when meta.has_more is false. Concurrent changes can shift offset-based pages. Read a booking by ID for its contact, room details and cards.","parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"required":false,"name":"limit","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"maximum":100000,"default":0},"required":false,"name":"offset","in":"query"},{"schema":{"type":"string","enum":["CREATED","PREBOOK_IN_PROGRESS","READY_FOR_COMPLETE","COMPLETE_IN_PROGRESS","CONFIRMED","CANCEL_IN_PROGRESS","PARTIALLY_CANCELED","CANCELED","FAILED","EXPIRED"],"description":"You filter by one current booking status."},"required":false,"description":"You filter by one current booking status.","name":"status","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":200,"description":"You match the reference_id you supplied at prebook exactly, including case. A reference can identify more than one booking."},"required":false,"description":"You match the reference_id you supplied at prebook exactly, including case. A reference can identify more than one booking.","name":"reference_id","in":"query"}],"responses":{"200":{"description":"Your booking summaries and page parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/hotel_HotelBookingSummary"}},"meta":{"type":"object","properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"has_more":{"type":"boolean","description":"You have more matching bookings after this page at the time it is read. Your offset remains capped at 100000."}},"required":["limit","offset","has_more"]}},"required":["data","meta"]},"examples":{"default":{"value":{"data":[{"id":"bkg_example","reference_id":"order-example","status":"CONFIRMED","hotel":{"id":"htl_example","name":"Example Marina Hotel","address":"Example Avenue, Dubai, AE"},"check_in":"2027-11-22","check_out":"2027-11-24","total":{"amount":600,"currency":"USD"},"created_at":"2027-10-01T10:01:00Z","updated_at":"2027-10-01T10:03:00Z","confirmed_at":"2027-10-01T10:03:00Z","canceled_at":null,"payments":[{"id":"pay_example","status":"CAPTURED","amount":{"amount":600,"currency":"USD"},"created_at":"2027-10-01T10:02:00Z"}]}],"meta":{"limit":25,"offset":0,"has_more":false}}}}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"400":{"description":"Your request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hotel_HotelError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"404":{"description":"You cannot access this booking or it does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hotel_HotelError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"409":{"description":"Your booking is already being processed or cannot enter this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hotel_HotelError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"422":{"description":"You cannot proceed with this offer, guest assignment or payment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hotel_HotelError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"500":{"description":"You must read the booking before taking further action; an unknown purchase outcome must not be repeated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/hotel_HotelError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}}}},"/v1/hotel/search":{"post":{"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"operationId":"searchHotels","tags":["Hotel search"],"summary":"Find hotels for your stay","description":"You receive available hotels and their cheapest current prices for your complete party. Supply one occupancy per room with each child's age. Search one city and country, or a point with a radius in metres. Check-out follows check-in by at most 99 nights. Use the returned hotel_id, or supplier_hotel_id with meta.supplier, with offers to get a bookable price; search prices are for comparison. To read the next page, send meta.pagination.next_cursor as cursor with the same search fields; stop when it is omitted rather than at a short or empty page, and expect no estimated total.","parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"check_in":{"type":"string","format":"date"},"check_out":{"type":"string","format":"date"},"occupancy":{"type":"array","items":{"type":"object","properties":{"adults":{"type":"integer","minimum":1,"maximum":20},"children":{"type":"array","items":{"type":"integer","minimum":0,"maximum":17},"maxItems":10,"default":[]}},"required":["adults"],"additionalProperties":false},"minItems":1,"maxItems":8},"guest_nationality":{"type":"string","pattern":"^[A-Z]{2}$"},"guest_residence":{"type":"string","pattern":"^[A-Z]{2}$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"supplier":{"type":"string","enum":["LITEAPI","WEBBEDS","DUFFEL"]},"destination":{"anyOf":[{"type":"object","properties":{"city":{"type":"string","minLength":1,"maxLength":200},"country_code":{"type":"string","pattern":"^[A-Z]{2}$"}},"required":["city","country_code"],"additionalProperties":false},{"type":"object","properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"radius":{"type":"integer","minimum":1000,"maximum":100000,"description":"Search radius in metres."}},"required":["latitude","longitude","radius"],"additionalProperties":false}]},"hotel_name":{"type":"string","minLength":3,"maxLength":100,"description":"Narrow the destination to hotels whose name contains this text, at least three characters and matched case-insensitively. The destination stays required, since a name is ambiguous across cities. A name that matches nothing returns an empty page, the same answer as no availability. When Duffel serves the search (`meta.supplier: \"DUFFEL\"`), the name is resolved to at most ten hotels within the searched area before pricing, so a generic name is clipped there."},"min_guest_rating":{"type":"number","minimum":0,"maximum":10},"star_ratings":{"type":"array","items":{"type":"number","minimum":1,"maximum":5},"minItems":1,"maxItems":9},"limit":{"type":"integer","minimum":1,"maximum":100,"default":10},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"The `meta.pagination.next_cursor` of your previous page. Send it with the same search fields as the first page; you may change `limit`. Omit it for the first page."}},"required":["check_in","check_out","occupancy","guest_nationality","currency","destination"],"additionalProperties":false},"examples":{"default":{"value":{"supplier":"LITEAPI","destination":{"city":"Dubai","country_code":"AE"},"check_in":"2027-11-22","check_out":"2027-11-24","occupancy":[{"adults":2,"children":[]},{"adults":2,"children":[]}],"guest_nationality":"GB","guest_residence":"GB","currency":"USD","limit":10}}}}}},"responses":{"200":{"description":"Your available hotels and page parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"hotel_id":{"type":"string"},"supplier_hotel_id":{"type":"string","description":"The supplier's own ID for this hotel. You can send it to offers in `supplier_hotel_ids`, with `meta.supplier` as `supplier`, instead of `hotel_id`."},"name":{"type":"string"},"description":{"type":"string"},"star_rating":{"type":"number"},"guest_rating":{"type":"number"},"review_count":{"type":"number"},"address":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"zip":{"type":"string"},"latitude":{"type":"number"},"longitude":{"type":"number"},"main_photo":{"type":"string"},"thumbnail":{"type":"string"},"chain":{"type":"string"},"cheapest_price":{"type":"object","properties":{"total":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"description":"Amount in the currency's major units."},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["amount","currency"]},"due_at_property":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"description":"Amount in the currency's major units."},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["amount","currency"]},"public_amount":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"description":"Amount in the currency's major units."},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["amount","currency"],"description":"The public price the supplier states for the same stay. It is not compared with `total` and can sit above, equal or below it; whether to show a difference is your call. Omitted when the supplier states none."}},"required":["total"]}},"required":["hotel_id","supplier_hotel_id","cheapest_price"]}},"meta":{"type":"object","properties":{"supplier":{"type":"string","enum":["LITEAPI","WEBBEDS","DUFFEL"]},"pagination":{"type":"object","properties":{"limit":{"type":"integer"},"next_cursor":{"type":"string","description":"Send it as `cursor` to read the next page. Omitted once the supplier reports no more hotels; a page can come back short or empty before that, so stop only when this is omitted. It keeps your later pages on the supplier that answered the first, and expires after 30 minutes."}},"required":["limit"]}},"required":["supplier","pagination"]}},"required":["data","meta"]},"examples":{"default":{"value":{"data":[{"hotel_id":"htl_example","supplier_hotel_id":"lp1f2e3","name":"Example Marina Hotel","city":"Dubai","country":"AE","cheapest_price":{"total":{"amount":600,"currency":"USD"}}}],"meta":{"supplier":"LITEAPI","pagination":{"limit":10,"next_cursor":"REPLACE_WITH_RETURNED_CURSOR"}}}}}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"400":{"description":"Your destination, stay or pricing inputs are invalid, or your cursor is invalid or belongs to a different search.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["validation_error","unauthorized","not_found","conflict","unprocessable","supplier_unavailable","internal_error"]},"reason":{"type":"string","enum":["offer_expired","cursor_expired","price_changed","guest_mismatch","stay_changed","cancellation_restricted","geo_required","city_required","manual_review_required","payment_method_unsupported","cancellation_policy_unsupported","cancellation_not_quotable","refund_not_cash","payment_failed","supplier_operation_unsupported","booking_incomplete","supplier_rejected","loyalty_membership_rejected","supplier_unreachable","supplier_rate_limited","result_unknown"]},"message":{"type":"string"},"request_id":{"type":"string"},"details":{}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"422":{"description":"Your selected supplier cannot serve the request, or your cursor has expired (cursor_expired).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["validation_error","unauthorized","not_found","conflict","unprocessable","supplier_unavailable","internal_error"]},"reason":{"type":"string","enum":["offer_expired","cursor_expired","price_changed","guest_mismatch","stay_changed","cancellation_restricted","geo_required","city_required","manual_review_required","payment_method_unsupported","cancellation_policy_unsupported","cancellation_not_quotable","refund_not_cash","payment_failed","supplier_operation_unsupported","booking_incomplete","supplier_rejected","loyalty_membership_rejected","supplier_unreachable","supplier_rate_limited","result_unknown"]},"message":{"type":"string"},"request_id":{"type":"string"},"details":{}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"500":{"description":"Your search could not be completed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["validation_error","unauthorized","not_found","conflict","unprocessable","supplier_unavailable","internal_error"]},"reason":{"type":"string","enum":["offer_expired","cursor_expired","price_changed","guest_mismatch","stay_changed","cancellation_restricted","geo_required","city_required","manual_review_required","payment_method_unsupported","cancellation_policy_unsupported","cancellation_not_quotable","refund_not_cash","payment_failed","supplier_operation_unsupported","booking_incomplete","supplier_rejected","loyalty_membership_rejected","supplier_unreachable","supplier_rate_limited","result_unknown"]},"message":{"type":"string"},"request_id":{"type":"string"},"details":{}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}}}},"/v1/hotel/offers":{"post":{"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"operationId":"getHotelOffers","tags":["Hotel offers"],"summary":"Price your selected hotels","description":"You price up to 10 hotels for the same stay and room occupancies; split a longer search page across several requests. You name them by the service's hotel_ids, or by supplier with that supplier's supplier_hotel_ids from search, never both. You request at most 250 offers in total, hotel IDs times max_offers_per_hotel, to bound the response. Request hotels from one supplier at a time. Each returned offer_reference binds the complete room selection, stay, source market and price to your organization. Pass it to prebook before expires_at. You receive every room in rooms, in your requested occupancy order, with its available display and cancellation terms. Top-level room_type and board remain first-room summaries; total and any offer-level policy cover the whole stay and are counted once. You review the confirmed terms again after prebook. Promotions list each promotion once with the room positions it applies to; the total already includes them. Amounts use major currency units.","parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"check_in":{"type":"string","format":"date"},"check_out":{"type":"string","format":"date"},"occupancy":{"type":"array","items":{"type":"object","properties":{"adults":{"type":"integer","minimum":1,"maximum":20},"children":{"type":"array","items":{"type":"integer","minimum":0,"maximum":17},"maxItems":10,"default":[]}},"required":["adults"],"additionalProperties":false},"minItems":1,"maxItems":8},"guest_nationality":{"type":"string","pattern":"^[A-Z]{2}$"},"guest_residence":{"type":"string","pattern":"^[A-Z]{2}$"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"hotel_ids":{"type":"array","items":{"type":"string","maxLength":128,"pattern":"^htl_[a-zA-Z0-9-]+$"},"minItems":1,"maxItems":10,"description":"Your `hotel_id` values from search."},"supplier":{"type":"string","enum":["LITEAPI","WEBBEDS","DUFFEL"],"description":"The `meta.supplier` of the search that returned your `supplier_hotel_ids`."},"supplier_hotel_ids":{"type":"array","items":{"type":"string","maxLength":128,"pattern":"^[a-zA-Z0-9_-]+$"},"minItems":1,"maxItems":10,"description":"Your `supplier_hotel_id` values from search, sent with `supplier` instead of `hotel_ids`. An ID that no search has returned is not found."},"max_offers_per_hotel":{"type":"integer","minimum":1,"default":5,"description":"You receive up to this many offers per hotel, cheapest first. You request at most 250 offers in total, hotel IDs times this value."},"loyalty":{"type":"object","properties":{"program":{"type":"string","enum":["wyndham_rewards","choice_privileges","marriott_bonvoy","best_western_rewards","world_of_hyatt","hilton_honors","ihg_one_rewards","leaders_club","stash_rewards","omni_select_guest","i_prefer","accor_live_limitless","my_6","jumeirah_one","global_hotel_alliance_discovery","duffel_hotel_group_rewards"]},"membership_number":{"type":"string","pattern":"^[A-Za-z0-9-]{1,64}$","description":"The lead guest's membership number in that programme: 1–64 letters, digits or `-`."}},"required":["program","membership_number"],"additionalProperties":false,"description":"The lead guest's hotel loyalty membership. Offers whose supplier will receive it carry `loyalty`. It is submitted to the supplier, not confirmed by the hotel; the hotel decides whether to credit points. It is bound to each offer reference, so search again to change it. You are responsible for the membership being genuine and belonging to the lead guest."}},"required":["check_in","check_out","occupancy","guest_nationality","currency"],"additionalProperties":false},"examples":{"default":{"value":{"hotel_ids":["htl_example"],"check_in":"2027-11-22","check_out":"2027-11-24","occupancy":[{"adults":2,"children":[]},{"adults":2,"children":[]}],"guest_nationality":"GB","guest_residence":"GB","currency":"USD","max_offers_per_hotel":5}}}}}},"responses":{"200":{"description":"Your hotels with bookable offers; hotels without availability are omitted.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"hotel_id":{"type":"string"},"supplier_hotel_id":{"type":"string","description":"The supplier's own ID for this hotel."},"offers":{"type":"array","items":{"type":"object","properties":{"offer_reference":{"type":"string"},"total":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"description":"Amount in the currency's major units."},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["amount","currency"]},"rooms":{"type":"array","items":{"$ref":"#/components/schemas/hotel_HotelOfferRoom"},"minItems":1,"maxItems":8,"description":"One entry per requested occupancy, in the same order. You review each room before prebook; the offer's total is the price for all rooms together."},"public_amount":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"description":"Amount in the currency's major units."},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["amount","currency"],"description":"The public price the supplier states for the same stay. It is not compared with `total` and can sit above, equal or below it; whether to show a difference is your call. Omitted when the supplier states none."},"due_at_property":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"description":"Amount in the currency's major units."},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["amount","currency"]},"taxes_and_fees":{"type":"array","items":{"$ref":"#/components/schemas/hotel_TaxOrFee"},"description":"The taxes and fees the supplier itemises for this offer, for the whole stay. Lines with `included: true` are inside `total`; lines with `included: false` are collected by the property and add up to `due_at_property`. Omitted when the supplier itemises none, or when its lines would not add up to `due_at_property` exactly."},"room_type":{"type":"string"},"room_photos":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"hd_url":{"type":"string"},"caption":{"type":"string"},"order":{"type":"number"},"is_default":{"type":"boolean"}},"required":["url"]},"description":"Photos of the offered room, where the supplier publishes them. From LiteAPI they come from the hotel's cached content, so they appear once its details have been fetched; Hotel Content serves the same images under `rooms`. From Duffel they come with the offer itself. WebBeds publishes none."},"board":{"type":"string","description":"You receive the first room's board as each supplier states it, so values differ between suppliers: WebBeds sends ROOM_ONLY, BREAKFAST, HALF_BOARD, FULL_BOARD or ALL_INCLUSIVE, while LiteAPI and Duffel send their own wording; rooms gives each room's board. Your booking's rooms carry one of those five values when the board is recognized."},"refundable":{"type":"boolean"},"cancellation_policy":{"type":"object","properties":{"version":{"type":"number","enum":[1]},"refundable":{"type":"boolean"},"deadline":{"type":"string","format":"date-time"},"penalties":{"type":"array","items":{"type":"object","properties":{"from":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["AMOUNT"]},"amount":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"description":"Amount in the currency's major units."},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["amount","currency"]},"timezone":{"type":"string"}},"required":["from","type","amount"]}},"restrictions":{"type":"array","items":{"type":"object","properties":{"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"},"timezone":{"type":"string"}},"required":["from","to"]}},"no_show":{"type":"object","properties":{"from":{"type":"string","format":"date-time"},"amount":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"description":"Amount in the currency's major units."},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["amount","currency"]}},"required":["from","amount"]}},"required":["version","refundable","penalties","restrictions"],"description":"The rate's cancellation terms for the whole stay, in the shape your booking carries. Omitted when the supplier states no single fee ladder for the stay: the fee is then unknown, never free, and `refundable` still says whether a refund is possible when every room states it, and is omitted otherwise. Your booking's terms are the ones the supplier confirms when you book."},"promotions":{"type":"array","items":{"$ref":"#/components/schemas/hotel_OfferPromotion"},"description":"Promotions on the rates in this offer, each once with the rooms it applies to. Omitted when there are none."},"loyalty":{"type":"object","properties":{"program":{"type":"string","enum":["wyndham_rewards","choice_privileges","marriott_bonvoy","best_western_rewards","world_of_hyatt","hilton_honors","ihg_one_rewards","leaders_club","stash_rewards","omni_select_guest","i_prefer","accor_live_limitless","my_6","jumeirah_one","global_hotel_alliance_discovery","duffel_hotel_group_rewards"]},"member_rate":{"type":"boolean","description":"True when this price is only valid for a member of the programme. You are responsible for the membership being genuine: the hotel may charge its public rate at check-in if the guest cannot prove membership."}},"required":["program","member_rate"],"description":"Present when the membership you sent is submitted to the supplier with this offer. Submission does not confirm that the hotel receives it or credits points. Omitted when we cannot confirm it is submitted for this offer, or when you sent none; an offer without it is never a member rate."},"expires_at":{"type":"string","format":"date-time"}},"required":["offer_reference","total","rooms","expires_at"]}}},"required":["hotel_id","supplier_hotel_id","offers"]}},"meta":{"type":"object","properties":{"supplier":{"type":"string","enum":["LITEAPI","WEBBEDS","DUFFEL"]}},"required":["supplier"]}},"required":["data","meta"]},"examples":{"default":{"value":{"data":[{"hotel_id":"htl_example","supplier_hotel_id":"lp1f2e3","offers":[{"offer_reference":"REPLACE_WITH_RETURNED_OFFER_REFERENCE","total":{"amount":600,"currency":"USD"},"rooms":[{"position":0,"adults":2,"children":[],"room_type":"Deluxe Twin","board":"Room Only","refundable":true,"cancellation_policy":{"version":1,"refundable":true,"deadline":"2027-11-20T00:00:00Z","penalties":[{"from":"2027-11-20T00:00:00Z","type":"AMOUNT","amount":{"amount":150,"currency":"USD"}}],"restrictions":[]}},{"position":1,"adults":2,"children":[],"room_type":"Deluxe Double","board":"Room Only","refundable":true,"cancellation_policy":{"version":1,"refundable":true,"deadline":"2027-11-20T00:00:00Z","penalties":[{"from":"2027-11-20T00:00:00Z","type":"AMOUNT","amount":{"amount":150,"currency":"USD"}}],"restrictions":[]}}],"room_type":"Deluxe Twin","board":"Room Only","refundable":true,"cancellation_policy":{"version":1,"refundable":true,"deadline":"2027-11-20T00:00:00Z","penalties":[{"from":"2027-11-20T00:00:00Z","type":"AMOUNT","amount":{"amount":300,"currency":"USD"}}],"restrictions":[]},"expires_at":"2027-10-01T10:15:00Z"}]}],"meta":{"supplier":"LITEAPI"}}}}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"400":{"description":"Your hotel selection or stay is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["validation_error","unauthorized","not_found","conflict","unprocessable","supplier_unavailable","internal_error"]},"reason":{"type":"string","enum":["offer_expired","cursor_expired","price_changed","guest_mismatch","stay_changed","cancellation_restricted","geo_required","city_required","manual_review_required","payment_method_unsupported","cancellation_policy_unsupported","cancellation_not_quotable","refund_not_cash","payment_failed","supplier_operation_unsupported","booking_incomplete","supplier_rejected","loyalty_membership_rejected","supplier_unreachable","supplier_rate_limited","result_unknown"]},"message":{"type":"string"},"request_id":{"type":"string"},"details":{}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"404":{"description":"Your hotel ID does not identify a known listing.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["validation_error","unauthorized","not_found","conflict","unprocessable","supplier_unavailable","internal_error"]},"reason":{"type":"string","enum":["offer_expired","cursor_expired","price_changed","guest_mismatch","stay_changed","cancellation_restricted","geo_required","city_required","manual_review_required","payment_method_unsupported","cancellation_policy_unsupported","cancellation_not_quotable","refund_not_cash","payment_failed","supplier_operation_unsupported","booking_incomplete","supplier_rejected","loyalty_membership_rejected","supplier_unreachable","supplier_rate_limited","result_unknown"]},"message":{"type":"string"},"request_id":{"type":"string"},"details":{}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"422":{"description":"Your listing supplier cannot price the request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["validation_error","unauthorized","not_found","conflict","unprocessable","supplier_unavailable","internal_error"]},"reason":{"type":"string","enum":["offer_expired","cursor_expired","price_changed","guest_mismatch","stay_changed","cancellation_restricted","geo_required","city_required","manual_review_required","payment_method_unsupported","cancellation_policy_unsupported","cancellation_not_quotable","refund_not_cash","payment_failed","supplier_operation_unsupported","booking_incomplete","supplier_rejected","loyalty_membership_rejected","supplier_unreachable","supplier_rate_limited","result_unknown"]},"message":{"type":"string"},"request_id":{"type":"string"},"details":{}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"500":{"description":"Your offers could not be priced.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["validation_error","unauthorized","not_found","conflict","unprocessable","supplier_unavailable","internal_error"]},"reason":{"type":"string","enum":["offer_expired","cursor_expired","price_changed","guest_mismatch","stay_changed","cancellation_restricted","geo_required","city_required","manual_review_required","payment_method_unsupported","cancellation_policy_unsupported","cancellation_not_quotable","refund_not_cash","payment_failed","supplier_operation_unsupported","booking_incomplete","supplier_rejected","loyalty_membership_rejected","supplier_unreachable","supplier_rate_limited","result_unknown"]},"message":{"type":"string"},"request_id":{"type":"string"},"details":{}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}}}},"/v1/hotel/price-calendar":{"post":{"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"operationId":"getHotelPriceCalendar","tags":["Hotel price calendar"],"summary":"See a daily price index for your hotels","description":"You read a daily price index for up to 50 hotel IDs from one supplier over a window of up to 365 days: for each calendar day, the average nightly price across the stays the supplier has seen that include that day. It is not the price of checking in on that day, so present it as a trend, such as when a hotel tends to be cheaper, rather than as a price per check-in date. The prices are indicative, in US dollars, not tied to your party and not bookable, so price the stay with offers before you book. Dates without a price are omitted, and so are hotels without any. Only some suppliers publish these prices; for the others you receive 422 supplier_operation_unsupported. The supplier allows only a few of these reads a minute, so cache what you receive and expect 503 supplier_rate_limited when the limit is reached.","parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"hotel_ids":{"type":"array","items":{"type":"string","maxLength":128,"pattern":"^htl_[a-zA-Z0-9-]+$"},"minItems":1,"maxItems":50},"from":{"type":"string","format":"date","description":"First day of the window: today in UTC or later. The day before is also accepted, for callers whose own date is behind UTC."},"to":{"type":"string","format":"date","description":"Last day of the window, inclusive; at most 365 days after `from`."}},"required":["hotel_ids","from","to"],"additionalProperties":false}}}},"responses":{"200":{"description":"Your hotels with indicative nightly prices; hotels without any are omitted.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"hotel_id":{"type":"string"},"prices":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"The calendar day."},"average_nightly_price":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"description":"Amount in the currency's major units."},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["amount","currency"],"description":"The supplier's average price per night across the stays it has seen that include this day, in US dollars. A daily price index, not the price of checking in on this day: indicative only, not tied to your party, not bookable, and not comparable to an offer's total."}},"required":["date","average_nightly_price"]}}},"required":["hotel_id","prices"]}},"meta":{"type":"object","properties":{"supplier":{"type":"string","enum":["LITEAPI","WEBBEDS","DUFFEL"]}},"required":["supplier"]}},"required":["data","meta"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"400":{"description":"Your hotel selection or date window is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["validation_error","unauthorized","not_found","conflict","unprocessable","supplier_unavailable","internal_error"]},"reason":{"type":"string","enum":["offer_expired","cursor_expired","price_changed","guest_mismatch","stay_changed","cancellation_restricted","geo_required","city_required","manual_review_required","payment_method_unsupported","cancellation_policy_unsupported","cancellation_not_quotable","refund_not_cash","payment_failed","supplier_operation_unsupported","booking_incomplete","supplier_rejected","loyalty_membership_rejected","supplier_unreachable","supplier_rate_limited","result_unknown"]},"message":{"type":"string"},"request_id":{"type":"string"},"details":{}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"404":{"description":"Your hotel ID does not identify a known listing.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["validation_error","unauthorized","not_found","conflict","unprocessable","supplier_unavailable","internal_error"]},"reason":{"type":"string","enum":["offer_expired","cursor_expired","price_changed","guest_mismatch","stay_changed","cancellation_restricted","geo_required","city_required","manual_review_required","payment_method_unsupported","cancellation_policy_unsupported","cancellation_not_quotable","refund_not_cash","payment_failed","supplier_operation_unsupported","booking_incomplete","supplier_rejected","loyalty_membership_rejected","supplier_unreachable","supplier_rate_limited","result_unknown"]},"message":{"type":"string"},"request_id":{"type":"string"},"details":{}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"422":{"description":"Your hotels' supplier does not publish a price calendar, or refused the request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["validation_error","unauthorized","not_found","conflict","unprocessable","supplier_unavailable","internal_error"]},"reason":{"type":"string","enum":["offer_expired","cursor_expired","price_changed","guest_mismatch","stay_changed","cancellation_restricted","geo_required","city_required","manual_review_required","payment_method_unsupported","cancellation_policy_unsupported","cancellation_not_quotable","refund_not_cash","payment_failed","supplier_operation_unsupported","booking_incomplete","supplier_rejected","loyalty_membership_rejected","supplier_unreachable","supplier_rate_limited","result_unknown"]},"message":{"type":"string"},"request_id":{"type":"string"},"details":{}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"500":{"description":"Your price calendar could not be read.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["validation_error","unauthorized","not_found","conflict","unprocessable","supplier_unavailable","internal_error"]},"reason":{"type":"string","enum":["offer_expired","cursor_expired","price_changed","guest_mismatch","stay_changed","cancellation_restricted","geo_required","city_required","manual_review_required","payment_method_unsupported","cancellation_policy_unsupported","cancellation_not_quotable","refund_not_cash","payment_failed","supplier_operation_unsupported","booking_incomplete","supplier_rejected","loyalty_membership_rejected","supplier_unreachable","supplier_rate_limited","result_unknown"]},"message":{"type":"string"},"request_id":{"type":"string"},"details":{}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}}}},"/v1/hotel/content/{hotel_id}":{"get":{"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"operationId":"getHotelContent","tags":["Hotel content"],"summary":"Read hotel details and reviews","description":"You retrieve content using a hotel_id returned by the service. You receive cached content while stale sources refresh in the background. A supported source that has never been fetched is retrieved before the response; a failure returns a supplier error while retaining any source successfully saved. Details and reviews refresh independently. Null means a supplier has not provided the value. Images and reviews are capped at twenty each. Reviewer names are omitted.","parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}},{"schema":{"type":"string","maxLength":128,"pattern":"^htl_[a-zA-Z0-9-]+$"},"required":true,"name":"hotel_id","in":"path"}],"responses":{"200":{"description":"Your hotel content.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/hotel_HotelContent"}},"required":["data"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"400":{"description":"Your hotel ID is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["validation_error","unauthorized","not_found","conflict","unprocessable","supplier_unavailable","internal_error"]},"reason":{"type":"string","enum":["offer_expired","cursor_expired","price_changed","guest_mismatch","stay_changed","cancellation_restricted","geo_required","city_required","manual_review_required","payment_method_unsupported","cancellation_policy_unsupported","cancellation_not_quotable","refund_not_cash","payment_failed","supplier_operation_unsupported","booking_incomplete","supplier_rejected","loyalty_membership_rejected","supplier_unreachable","supplier_rate_limited","result_unknown"]},"message":{"type":"string"},"request_id":{"type":"string"},"details":{}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"404":{"description":"Your hotel listing was not found.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["validation_error","unauthorized","not_found","conflict","unprocessable","supplier_unavailable","internal_error"]},"reason":{"type":"string","enum":["offer_expired","cursor_expired","price_changed","guest_mismatch","stay_changed","cancellation_restricted","geo_required","city_required","manual_review_required","payment_method_unsupported","cancellation_policy_unsupported","cancellation_not_quotable","refund_not_cash","payment_failed","supplier_operation_unsupported","booking_incomplete","supplier_rejected","loyalty_membership_rejected","supplier_unreachable","supplier_rate_limited","result_unknown"]},"message":{"type":"string"},"request_id":{"type":"string"},"details":{}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"500":{"description":"Your hotel content could not be read.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["validation_error","unauthorized","not_found","conflict","unprocessable","supplier_unavailable","internal_error"]},"reason":{"type":"string","enum":["offer_expired","cursor_expired","price_changed","guest_mismatch","stay_changed","cancellation_restricted","geo_required","city_required","manual_review_required","payment_method_unsupported","cancellation_policy_unsupported","cancellation_not_quotable","refund_not_cash","payment_failed","supplier_operation_unsupported","booking_incomplete","supplier_rejected","loyalty_membership_rejected","supplier_unreachable","supplier_rate_limited","result_unknown"]},"message":{"type":"string"},"request_id":{"type":"string"},"details":{}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}}}},"/v1/hotel/places":{"get":{"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"operationId":"searchHotelPlace","tags":["Hotel places"],"summary":"Resolve your destination","description":"You receive the best matching place, its coordinates and a suggested search radius in metres. Read the address and alternatives to distinguish similarly named places. Repeat the same query, type filters and language to reuse its saved resolution. A missing id means the result could not be saved; you can still use its coordinates. The radius is bounded to 1–50 kilometres and can under-cover large regions.","parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}},{"schema":{"type":"string","minLength":1,"maxLength":200},"required":true,"name":"query","in":"query"},{"schema":{"type":"string","maxLength":500},"required":false,"name":"types","in":"query"},{"schema":{"type":"string","pattern":"^[a-zA-Z]{2,3}(?:-[a-zA-Z]{2,4})?$"},"required":false,"name":"language","in":"query"}],"responses":{"200":{"description":"Your resolved destination.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"address":{"type":"string"},"location":{"type":"object","properties":{"latitude":{"type":"number"},"longitude":{"type":"number"}},"required":["latitude","longitude"]},"suggested_radius":{"type":"integer","minimum":1000,"maximum":50000},"country_code":{"type":"string"},"city":{"type":"string"},"types":{"type":"array","items":{"type":"string"}},"alternatives":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"address":{"type":"string"}},"required":["name"]}}},"required":["name","location","suggested_radius"]}},"required":["data"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"400":{"description":"Your place query or ID is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["validation_error","unauthorized","not_found","conflict","unprocessable","supplier_unavailable","internal_error"]},"reason":{"type":"string","enum":["offer_expired","cursor_expired","price_changed","guest_mismatch","stay_changed","cancellation_restricted","geo_required","city_required","manual_review_required","payment_method_unsupported","cancellation_policy_unsupported","cancellation_not_quotable","refund_not_cash","payment_failed","supplier_operation_unsupported","booking_incomplete","supplier_rejected","loyalty_membership_rejected","supplier_unreachable","supplier_rate_limited","result_unknown"]},"message":{"type":"string"},"request_id":{"type":"string"},"details":{}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"404":{"description":"Your query has no matching destination or the saved resolution does not exist.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["validation_error","unauthorized","not_found","conflict","unprocessable","supplier_unavailable","internal_error"]},"reason":{"type":"string","enum":["offer_expired","cursor_expired","price_changed","guest_mismatch","stay_changed","cancellation_restricted","geo_required","city_required","manual_review_required","payment_method_unsupported","cancellation_policy_unsupported","cancellation_not_quotable","refund_not_cash","payment_failed","supplier_operation_unsupported","booking_incomplete","supplier_rejected","loyalty_membership_rejected","supplier_unreachable","supplier_rate_limited","result_unknown"]},"message":{"type":"string"},"request_id":{"type":"string"},"details":{}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"422":{"description":"Your place lookup cannot be served.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["validation_error","unauthorized","not_found","conflict","unprocessable","supplier_unavailable","internal_error"]},"reason":{"type":"string","enum":["offer_expired","cursor_expired","price_changed","guest_mismatch","stay_changed","cancellation_restricted","geo_required","city_required","manual_review_required","payment_method_unsupported","cancellation_policy_unsupported","cancellation_not_quotable","refund_not_cash","payment_failed","supplier_operation_unsupported","booking_incomplete","supplier_rejected","loyalty_membership_rejected","supplier_unreachable","supplier_rate_limited","result_unknown"]},"message":{"type":"string"},"request_id":{"type":"string"},"details":{}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"500":{"description":"Your place resolution could not be read.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["validation_error","unauthorized","not_found","conflict","unprocessable","supplier_unavailable","internal_error"]},"reason":{"type":"string","enum":["offer_expired","cursor_expired","price_changed","guest_mismatch","stay_changed","cancellation_restricted","geo_required","city_required","manual_review_required","payment_method_unsupported","cancellation_policy_unsupported","cancellation_not_quotable","refund_not_cash","payment_failed","supplier_operation_unsupported","booking_incomplete","supplier_rejected","loyalty_membership_rejected","supplier_unreachable","supplier_rate_limited","result_unknown"]},"message":{"type":"string"},"request_id":{"type":"string"},"details":{}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}}}},"/v1/hotel/places/{id}":{"get":{"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"operationId":"getHotelPlace","tags":["Hotel places"],"summary":"Read a saved destination","description":"You retrieve the resolution using the service's plc_ ID from your place search. This read makes no supplier request.","parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}},{"schema":{"type":"string","maxLength":128,"pattern":"^plc_[a-zA-Z0-9-]+$"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Your saved destination.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"address":{"type":"string"},"location":{"type":"object","properties":{"latitude":{"type":"number"},"longitude":{"type":"number"}},"required":["latitude","longitude"]},"suggested_radius":{"type":"integer","minimum":1000,"maximum":50000},"country_code":{"type":"string"},"city":{"type":"string"},"types":{"type":"array","items":{"type":"string"}},"alternatives":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"address":{"type":"string"}},"required":["name"]}}},"required":["name","location","suggested_radius"]}},"required":["data"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"400":{"description":"Your place query or ID is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["validation_error","unauthorized","not_found","conflict","unprocessable","supplier_unavailable","internal_error"]},"reason":{"type":"string","enum":["offer_expired","cursor_expired","price_changed","guest_mismatch","stay_changed","cancellation_restricted","geo_required","city_required","manual_review_required","payment_method_unsupported","cancellation_policy_unsupported","cancellation_not_quotable","refund_not_cash","payment_failed","supplier_operation_unsupported","booking_incomplete","supplier_rejected","loyalty_membership_rejected","supplier_unreachable","supplier_rate_limited","result_unknown"]},"message":{"type":"string"},"request_id":{"type":"string"},"details":{}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"404":{"description":"Your query has no matching destination or the saved resolution does not exist.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["validation_error","unauthorized","not_found","conflict","unprocessable","supplier_unavailable","internal_error"]},"reason":{"type":"string","enum":["offer_expired","cursor_expired","price_changed","guest_mismatch","stay_changed","cancellation_restricted","geo_required","city_required","manual_review_required","payment_method_unsupported","cancellation_policy_unsupported","cancellation_not_quotable","refund_not_cash","payment_failed","supplier_operation_unsupported","booking_incomplete","supplier_rejected","loyalty_membership_rejected","supplier_unreachable","supplier_rate_limited","result_unknown"]},"message":{"type":"string"},"request_id":{"type":"string"},"details":{}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"422":{"description":"Your place lookup cannot be served.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["validation_error","unauthorized","not_found","conflict","unprocessable","supplier_unavailable","internal_error"]},"reason":{"type":"string","enum":["offer_expired","cursor_expired","price_changed","guest_mismatch","stay_changed","cancellation_restricted","geo_required","city_required","manual_review_required","payment_method_unsupported","cancellation_policy_unsupported","cancellation_not_quotable","refund_not_cash","payment_failed","supplier_operation_unsupported","booking_incomplete","supplier_rejected","loyalty_membership_rejected","supplier_unreachable","supplier_rate_limited","result_unknown"]},"message":{"type":"string"},"request_id":{"type":"string"},"details":{}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"500":{"description":"Your place resolution could not be read.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["validation_error","unauthorized","not_found","conflict","unprocessable","supplier_unavailable","internal_error"]},"reason":{"type":"string","enum":["offer_expired","cursor_expired","price_changed","guest_mismatch","stay_changed","cancellation_restricted","geo_required","city_required","manual_review_required","payment_method_unsupported","cancellation_policy_unsupported","cancellation_not_quotable","refund_not_cash","payment_failed","supplier_operation_unsupported","booking_incomplete","supplier_rejected","loyalty_membership_rejected","supplier_unreachable","supplier_rate_limited","result_unknown"]},"message":{"type":"string"},"request_id":{"type":"string"},"details":{}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}}}},"/v1/hotel/webhook-subscriptions":{"post":{"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"operationId":"createHotelWebhookSubscription","tags":["Hotel webhooks"],"summary":"Create a subscription","description":"You register an HTTPS endpoint and the events it receives. You receive the signing secret only in this response; store it on your server. Your organization holds at most five subscriptions, one per URL, shared by all its credentials.","parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","maxLength":2048,"description":"Your HTTPS endpoint. It uses a public DNS name of your own, not an IP address, a local name or a host of this platform or its message queue, because requests there would carry this platform's own signature. It carries no user name, password or fragment."},"event_types":{"type":"array","items":{"type":"string","enum":["hotel.booking.confirmed","hotel.booking.failed","hotel.booking.canceled","hotel.booking.partially_canceled","hotel.booking.cancel_failed"]},"minItems":1,"description":"The booking events you receive."}},"required":["url","event_types"],"additionalProperties":false}}}},"responses":{"201":{"description":"Your subscription and its signing secret.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/hotel_HotelWebhookSubscriptionWithSecret"}},"required":["data"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"400":{"description":"Your request is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["validation_error","unauthorized","not_found","conflict","unprocessable","supplier_unavailable","internal_error"]},"reason":{"type":"string","enum":["offer_expired","cursor_expired","price_changed","guest_mismatch","stay_changed","cancellation_restricted","geo_required","city_required","manual_review_required","payment_method_unsupported","cancellation_policy_unsupported","cancellation_not_quotable","refund_not_cash","payment_failed","supplier_operation_unsupported","booking_incomplete","supplier_rejected","loyalty_membership_rejected","supplier_unreachable","supplier_rate_limited","result_unknown"]},"message":{"type":"string"},"request_id":{"type":"string"},"details":{}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"409":{"description":"You already subscribed this URL, or you hold five subscriptions.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["validation_error","unauthorized","not_found","conflict","unprocessable","supplier_unavailable","internal_error"]},"reason":{"type":"string","enum":["offer_expired","cursor_expired","price_changed","guest_mismatch","stay_changed","cancellation_restricted","geo_required","city_required","manual_review_required","payment_method_unsupported","cancellation_policy_unsupported","cancellation_not_quotable","refund_not_cash","payment_failed","supplier_operation_unsupported","booking_incomplete","supplier_rejected","loyalty_membership_rejected","supplier_unreachable","supplier_rate_limited","result_unknown"]},"message":{"type":"string"},"request_id":{"type":"string"},"details":{}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"500":{"description":"Your request could not be completed; read the subscription or delivery before you retry.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["validation_error","unauthorized","not_found","conflict","unprocessable","supplier_unavailable","internal_error"]},"reason":{"type":"string","enum":["offer_expired","cursor_expired","price_changed","guest_mismatch","stay_changed","cancellation_restricted","geo_required","city_required","manual_review_required","payment_method_unsupported","cancellation_policy_unsupported","cancellation_not_quotable","refund_not_cash","payment_failed","supplier_operation_unsupported","booking_incomplete","supplier_rejected","loyalty_membership_rejected","supplier_unreachable","supplier_rate_limited","result_unknown"]},"message":{"type":"string"},"request_id":{"type":"string"},"details":{}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}}},"get":{"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"operationId":"listHotelWebhookSubscriptions","tags":["Hotel webhooks"],"summary":"List your subscriptions","description":"You receive your organization's subscriptions, oldest first, without their signing secrets.","parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}}],"responses":{"200":{"description":"Your subscriptions.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/hotel_HotelWebhookSubscription"}}},"required":["data"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"500":{"description":"Your request could not be completed; read the subscription or delivery before you retry.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["validation_error","unauthorized","not_found","conflict","unprocessable","supplier_unavailable","internal_error"]},"reason":{"type":"string","enum":["offer_expired","cursor_expired","price_changed","guest_mismatch","stay_changed","cancellation_restricted","geo_required","city_required","manual_review_required","payment_method_unsupported","cancellation_policy_unsupported","cancellation_not_quotable","refund_not_cash","payment_failed","supplier_operation_unsupported","booking_incomplete","supplier_rejected","loyalty_membership_rejected","supplier_unreachable","supplier_rate_limited","result_unknown"]},"message":{"type":"string"},"request_id":{"type":"string"},"details":{}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}}}},"/v1/hotel/webhook-subscriptions/{id}":{"patch":{"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"operationId":"updateHotelWebhookSubscription","tags":["Hotel webhooks"],"summary":"Change a subscription","description":"You change the URL, the events or the status. A paused subscription receives no new events, and events that occur while it is paused are not sent later. Requests already queued, including their retries, still arrive at the URL they were queued with.","parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}},{"schema":{"type":"string","maxLength":128,"pattern":"^whs_[a-zA-Z0-9-]+$"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","maxLength":2048,"description":"Your HTTPS endpoint. It uses a public DNS name of your own, not an IP address, a local name or a host of this platform or its message queue, because requests there would carry this platform's own signature. It carries no user name, password or fragment."},"event_types":{"type":"array","items":{"type":"string","enum":["hotel.booking.confirmed","hotel.booking.failed","hotel.booking.canceled","hotel.booking.partially_canceled","hotel.booking.cancel_failed"]},"minItems":1,"description":"The booking events you receive."},"status":{"type":"string","enum":["ACTIVE","PAUSED"],"description":"PAUSED stops new events for this subscription; events that occur while paused are not sent later."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Your subscription.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/hotel_HotelWebhookSubscription"}},"required":["data"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"400":{"description":"Your request is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["validation_error","unauthorized","not_found","conflict","unprocessable","supplier_unavailable","internal_error"]},"reason":{"type":"string","enum":["offer_expired","cursor_expired","price_changed","guest_mismatch","stay_changed","cancellation_restricted","geo_required","city_required","manual_review_required","payment_method_unsupported","cancellation_policy_unsupported","cancellation_not_quotable","refund_not_cash","payment_failed","supplier_operation_unsupported","booking_incomplete","supplier_rejected","loyalty_membership_rejected","supplier_unreachable","supplier_rate_limited","result_unknown"]},"message":{"type":"string"},"request_id":{"type":"string"},"details":{}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"404":{"description":"You have no webhook subscription or delivery with this ID.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["validation_error","unauthorized","not_found","conflict","unprocessable","supplier_unavailable","internal_error"]},"reason":{"type":"string","enum":["offer_expired","cursor_expired","price_changed","guest_mismatch","stay_changed","cancellation_restricted","geo_required","city_required","manual_review_required","payment_method_unsupported","cancellation_policy_unsupported","cancellation_not_quotable","refund_not_cash","payment_failed","supplier_operation_unsupported","booking_incomplete","supplier_rejected","loyalty_membership_rejected","supplier_unreachable","supplier_rate_limited","result_unknown"]},"message":{"type":"string"},"request_id":{"type":"string"},"details":{}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"409":{"description":"You already subscribed this URL.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["validation_error","unauthorized","not_found","conflict","unprocessable","supplier_unavailable","internal_error"]},"reason":{"type":"string","enum":["offer_expired","cursor_expired","price_changed","guest_mismatch","stay_changed","cancellation_restricted","geo_required","city_required","manual_review_required","payment_method_unsupported","cancellation_policy_unsupported","cancellation_not_quotable","refund_not_cash","payment_failed","supplier_operation_unsupported","booking_incomplete","supplier_rejected","loyalty_membership_rejected","supplier_unreachable","supplier_rate_limited","result_unknown"]},"message":{"type":"string"},"request_id":{"type":"string"},"details":{}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"500":{"description":"Your request could not be completed; read the subscription or delivery before you retry.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["validation_error","unauthorized","not_found","conflict","unprocessable","supplier_unavailable","internal_error"]},"reason":{"type":"string","enum":["offer_expired","cursor_expired","price_changed","guest_mismatch","stay_changed","cancellation_restricted","geo_required","city_required","manual_review_required","payment_method_unsupported","cancellation_policy_unsupported","cancellation_not_quotable","refund_not_cash","payment_failed","supplier_operation_unsupported","booking_incomplete","supplier_rejected","loyalty_membership_rejected","supplier_unreachable","supplier_rate_limited","result_unknown"]},"message":{"type":"string"},"request_id":{"type":"string"},"details":{}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}}},"delete":{"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"operationId":"deleteHotelWebhookSubscription","tags":["Hotel webhooks"],"summary":"Delete a subscription","description":"You delete the subscription and its delivery history. Requests already queued can still arrive.","parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}},{"schema":{"type":"string","maxLength":128,"pattern":"^whs_[a-zA-Z0-9-]+$"},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Your subscription is deleted.","headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"400":{"description":"Your request is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["validation_error","unauthorized","not_found","conflict","unprocessable","supplier_unavailable","internal_error"]},"reason":{"type":"string","enum":["offer_expired","cursor_expired","price_changed","guest_mismatch","stay_changed","cancellation_restricted","geo_required","city_required","manual_review_required","payment_method_unsupported","cancellation_policy_unsupported","cancellation_not_quotable","refund_not_cash","payment_failed","supplier_operation_unsupported","booking_incomplete","supplier_rejected","loyalty_membership_rejected","supplier_unreachable","supplier_rate_limited","result_unknown"]},"message":{"type":"string"},"request_id":{"type":"string"},"details":{}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"404":{"description":"You have no webhook subscription or delivery with this ID.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["validation_error","unauthorized","not_found","conflict","unprocessable","supplier_unavailable","internal_error"]},"reason":{"type":"string","enum":["offer_expired","cursor_expired","price_changed","guest_mismatch","stay_changed","cancellation_restricted","geo_required","city_required","manual_review_required","payment_method_unsupported","cancellation_policy_unsupported","cancellation_not_quotable","refund_not_cash","payment_failed","supplier_operation_unsupported","booking_incomplete","supplier_rejected","loyalty_membership_rejected","supplier_unreachable","supplier_rate_limited","result_unknown"]},"message":{"type":"string"},"request_id":{"type":"string"},"details":{}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"500":{"description":"Your request could not be completed; read the subscription or delivery before you retry.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["validation_error","unauthorized","not_found","conflict","unprocessable","supplier_unavailable","internal_error"]},"reason":{"type":"string","enum":["offer_expired","cursor_expired","price_changed","guest_mismatch","stay_changed","cancellation_restricted","geo_required","city_required","manual_review_required","payment_method_unsupported","cancellation_policy_unsupported","cancellation_not_quotable","refund_not_cash","payment_failed","supplier_operation_unsupported","booking_incomplete","supplier_rejected","loyalty_membership_rejected","supplier_unreachable","supplier_rate_limited","result_unknown"]},"message":{"type":"string"},"request_id":{"type":"string"},"details":{}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}}}},"/v1/hotel/webhook-subscriptions/{id}/rotate-secret":{"post":{"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"operationId":"rotateHotelWebhookSubscriptionSecret","tags":["Hotel webhooks"],"summary":"Rotate the signing secret","description":"You receive a new signing secret, only in this response. For 24 hours new requests carry a signature for each secret; keep accepting your previous secret for at least 2 hours 15 minutes, because requests queued before the rotation carry only its signature. Rotating again replaces the previous secret.","parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}},{"schema":{"type":"string","maxLength":128,"pattern":"^whs_[a-zA-Z0-9-]+$"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Your subscription and its signing secret.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/hotel_HotelWebhookSubscriptionWithSecret"}},"required":["data"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"400":{"description":"Your request is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["validation_error","unauthorized","not_found","conflict","unprocessable","supplier_unavailable","internal_error"]},"reason":{"type":"string","enum":["offer_expired","cursor_expired","price_changed","guest_mismatch","stay_changed","cancellation_restricted","geo_required","city_required","manual_review_required","payment_method_unsupported","cancellation_policy_unsupported","cancellation_not_quotable","refund_not_cash","payment_failed","supplier_operation_unsupported","booking_incomplete","supplier_rejected","loyalty_membership_rejected","supplier_unreachable","supplier_rate_limited","result_unknown"]},"message":{"type":"string"},"request_id":{"type":"string"},"details":{}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"404":{"description":"You have no webhook subscription or delivery with this ID.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["validation_error","unauthorized","not_found","conflict","unprocessable","supplier_unavailable","internal_error"]},"reason":{"type":"string","enum":["offer_expired","cursor_expired","price_changed","guest_mismatch","stay_changed","cancellation_restricted","geo_required","city_required","manual_review_required","payment_method_unsupported","cancellation_policy_unsupported","cancellation_not_quotable","refund_not_cash","payment_failed","supplier_operation_unsupported","booking_incomplete","supplier_rejected","loyalty_membership_rejected","supplier_unreachable","supplier_rate_limited","result_unknown"]},"message":{"type":"string"},"request_id":{"type":"string"},"details":{}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"500":{"description":"Your request could not be completed; read the subscription or delivery before you retry.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["validation_error","unauthorized","not_found","conflict","unprocessable","supplier_unavailable","internal_error"]},"reason":{"type":"string","enum":["offer_expired","cursor_expired","price_changed","guest_mismatch","stay_changed","cancellation_restricted","geo_required","city_required","manual_review_required","payment_method_unsupported","cancellation_policy_unsupported","cancellation_not_quotable","refund_not_cash","payment_failed","supplier_operation_unsupported","booking_incomplete","supplier_rejected","loyalty_membership_rejected","supplier_unreachable","supplier_rate_limited","result_unknown"]},"message":{"type":"string"},"request_id":{"type":"string"},"details":{}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}}}},"/v1/hotel/webhook-subscriptions/{id}/deliveries":{"get":{"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"operationId":"listHotelWebhookDeliveries","tags":["Hotel webhooks"],"summary":"List a subscription's deliveries","description":"You receive the subscription's deliveries, newest first, each with its event and your endpoint's responses for the current replay. Filter by status to find failed or stuck deliveries.","parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}},{"schema":{"type":"string","maxLength":128,"pattern":"^whs_[a-zA-Z0-9-]+$"},"required":true,"name":"id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"required":false,"name":"limit","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"maximum":100000,"default":0},"required":false,"name":"offset","in":"query"},{"schema":{"type":"string","enum":["PENDING","PUBLISHED","DELIVERED","FAILED"]},"required":false,"name":"status","in":"query"}],"responses":{"200":{"description":"Your deliveries and page parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/hotel_HotelWebhookDelivery"}},"meta":{"type":"object","properties":{"limit":{"type":"number"},"offset":{"type":"number"}},"required":["limit","offset"]}},"required":["data","meta"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"400":{"description":"Your request is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["validation_error","unauthorized","not_found","conflict","unprocessable","supplier_unavailable","internal_error"]},"reason":{"type":"string","enum":["offer_expired","cursor_expired","price_changed","guest_mismatch","stay_changed","cancellation_restricted","geo_required","city_required","manual_review_required","payment_method_unsupported","cancellation_policy_unsupported","cancellation_not_quotable","refund_not_cash","payment_failed","supplier_operation_unsupported","booking_incomplete","supplier_rejected","loyalty_membership_rejected","supplier_unreachable","supplier_rate_limited","result_unknown"]},"message":{"type":"string"},"request_id":{"type":"string"},"details":{}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"404":{"description":"You have no webhook subscription or delivery with this ID.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["validation_error","unauthorized","not_found","conflict","unprocessable","supplier_unavailable","internal_error"]},"reason":{"type":"string","enum":["offer_expired","cursor_expired","price_changed","guest_mismatch","stay_changed","cancellation_restricted","geo_required","city_required","manual_review_required","payment_method_unsupported","cancellation_policy_unsupported","cancellation_not_quotable","refund_not_cash","payment_failed","supplier_operation_unsupported","booking_incomplete","supplier_rejected","loyalty_membership_rejected","supplier_unreachable","supplier_rate_limited","result_unknown"]},"message":{"type":"string"},"request_id":{"type":"string"},"details":{}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"500":{"description":"Your request could not be completed; read the subscription or delivery before you retry.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["validation_error","unauthorized","not_found","conflict","unprocessable","supplier_unavailable","internal_error"]},"reason":{"type":"string","enum":["offer_expired","cursor_expired","price_changed","guest_mismatch","stay_changed","cancellation_restricted","geo_required","city_required","manual_review_required","payment_method_unsupported","cancellation_policy_unsupported","cancellation_not_quotable","refund_not_cash","payment_failed","supplier_operation_unsupported","booking_incomplete","supplier_rejected","loyalty_membership_rejected","supplier_unreachable","supplier_rate_limited","result_unknown"]},"message":{"type":"string"},"request_id":{"type":"string"},"details":{}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}}}},"/v1/hotel/webhook-subscriptions/{id}/deliveries/{delivery_id}/replay":{"post":{"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"operationId":"replayHotelWebhookDelivery","tags":["Hotel webhooks"],"summary":"Replay a delivery","description":"You send the same event again with a fresh signature. You can replay a delivered or failed delivery, a delivery pending for more than one minute, or one published more than 2 hours 15 minutes ago without a result. Your subscription must be active. Your endpoint can receive the event again, so ignore repeats by event ID.","parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}},{"schema":{"type":"string","maxLength":128,"pattern":"^whs_[a-zA-Z0-9-]+$"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","maxLength":128,"pattern":"^dlv_[a-zA-Z0-9-]+$"},"required":true,"name":"delivery_id","in":"path"}],"responses":{"200":{"description":"Your delivery after the replay. PENDING means queueing was not confirmed and the request may already be on its way; replay it again after one minute if it stays PENDING.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/hotel_HotelWebhookDelivery"}},"required":["data"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"400":{"description":"Your request is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["validation_error","unauthorized","not_found","conflict","unprocessable","supplier_unavailable","internal_error"]},"reason":{"type":"string","enum":["offer_expired","cursor_expired","price_changed","guest_mismatch","stay_changed","cancellation_restricted","geo_required","city_required","manual_review_required","payment_method_unsupported","cancellation_policy_unsupported","cancellation_not_quotable","refund_not_cash","payment_failed","supplier_operation_unsupported","booking_incomplete","supplier_rejected","loyalty_membership_rejected","supplier_unreachable","supplier_rate_limited","result_unknown"]},"message":{"type":"string"},"request_id":{"type":"string"},"details":{}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"404":{"description":"You have no webhook subscription or delivery with this ID.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["validation_error","unauthorized","not_found","conflict","unprocessable","supplier_unavailable","internal_error"]},"reason":{"type":"string","enum":["offer_expired","cursor_expired","price_changed","guest_mismatch","stay_changed","cancellation_restricted","geo_required","city_required","manual_review_required","payment_method_unsupported","cancellation_policy_unsupported","cancellation_not_quotable","refund_not_cash","payment_failed","supplier_operation_unsupported","booking_incomplete","supplier_rejected","loyalty_membership_rejected","supplier_unreachable","supplier_rate_limited","result_unknown"]},"message":{"type":"string"},"request_id":{"type":"string"},"details":{}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"409":{"description":"The delivery is still in flight, it changed while you replayed it, or your subscription is paused.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["validation_error","unauthorized","not_found","conflict","unprocessable","supplier_unavailable","internal_error"]},"reason":{"type":"string","enum":["offer_expired","cursor_expired","price_changed","guest_mismatch","stay_changed","cancellation_restricted","geo_required","city_required","manual_review_required","payment_method_unsupported","cancellation_policy_unsupported","cancellation_not_quotable","refund_not_cash","payment_failed","supplier_operation_unsupported","booking_incomplete","supplier_rejected","loyalty_membership_rejected","supplier_unreachable","supplier_rate_limited","result_unknown"]},"message":{"type":"string"},"request_id":{"type":"string"},"details":{}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"500":{"description":"Your request could not be completed; read the subscription or delivery before you retry.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["validation_error","unauthorized","not_found","conflict","unprocessable","supplier_unavailable","internal_error"]},"reason":{"type":"string","enum":["offer_expired","cursor_expired","price_changed","guest_mismatch","stay_changed","cancellation_restricted","geo_required","city_required","manual_review_required","payment_method_unsupported","cancellation_policy_unsupported","cancellation_not_quotable","refund_not_cash","payment_failed","supplier_operation_unsupported","booking_incomplete","supplier_rejected","loyalty_membership_rejected","supplier_unreachable","supplier_rate_limited","result_unknown"]},"message":{"type":"string"},"request_id":{"type":"string"},"details":{}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}}}},"/v1/hotel/capabilities":{"get":{"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"operationId":"listHotelSupplierCapabilities","tags":["Hotel capabilities"],"summary":"Read supported hotel features and limits","description":"You receive the active, configured suppliers and the features this service implements for each. Use these limits to prepare your requests; the list is shared across organizations and does not select a supplier or describe your routing rules. Read search meta.supplier to identify the supplier used for your stay. Availability, rate restrictions and booking state still determine whether a particular request succeeds. An empty list means no active configured supplier is registered. This read makes no supplier requests and is not a health check; supplier status can change after you read it.","parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}}],"responses":{"200":{"description":"Your available supplier features and limits.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/hotel_HotelSupplierCapabilities"}}},"required":["data"]},"examples":{"default":{"value":{"data":[{"supplier":"LITEAPI","operations":["search","offers","content","price_calendar","prebook","book","cancel"],"limits":{"max_offer_hotels":10,"max_rooms":8,"max_child_age":17},"requires_named_adults":false,"cancellation_may_partially_succeed":false}]}}}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"500":{"description":"Your supplier capabilities could not be read.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["validation_error","unauthorized","not_found","conflict","unprocessable","supplier_unavailable","internal_error"]},"reason":{"type":"string","enum":["offer_expired","cursor_expired","price_changed","guest_mismatch","stay_changed","cancellation_restricted","geo_required","city_required","manual_review_required","payment_method_unsupported","cancellation_policy_unsupported","cancellation_not_quotable","refund_not_cash","payment_failed","supplier_operation_unsupported","booking_incomplete","supplier_rejected","loyalty_membership_rejected","supplier_unreachable","supplier_rate_limited","result_unknown"]},"message":{"type":"string"},"request_id":{"type":"string"},"details":{}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}}}},"/v1/flight/offers":{"post":{"operationId":"getFlightOffers","tags":["Flight Offers"],"summary":"Get flight offers","description":"Price fares for a party and an itinerary. One routed supplier answers; name `supplier` to choose it yourself, and read `meta.supplier` to see who priced the fares. Offers are not stored: prebook from an `offer_reference` before its `expires_at`. `limit` caps the fares returned, and `meta.truncated` appears when more matched.","security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/flight_FlightOffersRequest"}}}},"responses":{"200":{"description":"Priced fares","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/flight_FlightOffer"},"description":"Fares, in the requested sort order."},"meta":{"$ref":"#/components/schemas/flight_FlightOffersMeta"}},"required":["data","meta"],"description":"Priced, bookable fares."}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"409":{"description":"Booking state conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"422":{"description":"Operation refused","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"500":{"description":"Internal or unknown outcome","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}},"parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}}]}},"/v1/flight/offers/{offer_reference}/available-services":{"get":{"operationId":"listFlightOfferServices","tags":["Flight Offers"],"summary":"List an offer's bags","description":"Bags the airline sells with this offer, priced per bag and per passenger. Send the ids you want in prebook's `services`; they are included in the fare's `total_amount` and paid at book. An empty list means the airline sells none for this fare. Seats are not listed here; read the offer's seat maps.","security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}},{"schema":{"type":"string","description":"The `offer_reference` from Flight Offers, unchanged."},"required":true,"description":"The `offer_reference` from Flight Offers, unchanged.","name":"offer_reference","in":"path"}],"responses":{"200":{"description":"Bags the traveller can add to this offer. Empty when the airline sells none.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/flight_FlightOfferService"}}},"required":["data"],"description":"Bags the traveller can add to this offer."}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"409":{"description":"Booking state conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"422":{"description":"Operation refused","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"500":{"description":"Internal or unknown outcome","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}}}},"/v1/flight/offers/{offer_reference}/seat-maps":{"get":{"operationId":"listFlightSeatMaps","tags":["Flight Offers"],"summary":"Get seat maps","description":"The cabin layout of each flight on this offer, read live from the airline, with every seat priced per passenger. Choose a seat by sending the `services[].id` for that passenger in prebook's `services` with `quantity: 1`; it is included in the fare's `total_amount` and paid at book. A seat whose `services` is empty cannot be chosen. An empty list means the airline publishes no map for these flights. Seats cannot be added after the ticket is issued.","security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}},{"schema":{"type":"string","description":"The `offer_reference` from Flight Offers, unchanged."},"required":true,"description":"The `offer_reference` from Flight Offers, unchanged.","name":"offer_reference","in":"path"}],"responses":{"200":{"description":"One seat map per flight. Empty when the airline publishes none.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/flight_FlightSeatMap"},"description":"One map per flight. Empty when the airline publishes none."},"meta":{"type":"object","properties":{"supplier":{"type":"string","description":"Which supplier published these maps.","examples":["DUFFEL"]}},"required":["supplier"]}},"required":["data","meta"],"description":"Seat maps for the offer's flights."}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"409":{"description":"Booking state conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"422":{"description":"Operation refused","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"500":{"description":"Internal or unknown outcome","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}}}},"/v1/flight/prebook":{"post":{"operationId":"prebookFlight","tags":["Flight Bookings"],"summary":"Prebook a flight offer","description":"Re-price the offer and bind it: the itinerary, passengers and contact are stored and the booking answers `READY_FOR_COMPLETE`. A fresh key answers `201`; repeating the same `x-idempotency-key` under the same organisation and user answers `200` with the existing booking. No inventory is held before book, so `expires_at` is a real deadline. `use_payment_sdk` decides how book pays: a saved instrument by default, or a Payment SDK intent whose `token` comes back in `meta.payment_sdk` on the `201`. On Duffel, an airline can grant a member price for a passenger's `loyalty_accounts`, which lowers `total_amount`. A Duffel offer takes one active booking at a time, so prebooking it under a new key answers `409` while an earlier booking of it is unfinished.","security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}},{"schema":{"type":"string","minLength":1,"maxLength":256,"description":"Your key for this prebook. Repeating it with the same organisation and user returns the existing booking rather than placing a second hold. After a failed booking, send a new key.","examples":["trip-2026-11-10-1"]},"required":true,"description":"Your key for this prebook. Repeating it with the same organisation and user returns the existing booking rather than placing a second hold. After a failed booking, send a new key.","in":"header","name":"x-idempotency-key"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/flight_FlightPrebookRequest"}}}},"responses":{"200":{"description":"Repeated idempotency key: the existing booking","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Your booking id.","examples":["bkg_0192f3a4b5c64d7e8f9a0b1c2d3e4f5b"]},"supplier":{"type":"string","description":"Which supplier holds this booking. Fixed when the booking was created, so it stays correct even if the default changes.","examples":["DUFFEL"]},"status":{"$ref":"#/components/schemas/flight_BookingStatus"},"total_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"The booking's price as sold: the fare, the extras charged with it, and later purchases once confirmed. A `FAILED` booking still shows what it tried to sell; cancellation never changes it, the refund is under `cancellation`. OEX collects it at book for Duffel; LiteAPI collects it through its checkout. Absent until the booking is priced.","examples":[{"amount":260.67,"currency":"USD"}]}]},"fare_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"The flights' own price, taxes included: `total_amount − services_amount`. Present whenever `total_amount` is.","examples":[{"amount":220.67,"currency":"USD"}]}]},"fare_tax_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"The taxes inside `fare_amount`, never added to it: 0 when the supplier reported zero, absent when it stated none.","examples":[{"amount":50,"currency":"USD"}]}]},"services_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"The extras' share of `total_amount`: the extras charged with the fare, in any status, plus every later purchase that was confirmed, which stays in after cancellation. 0 when none. Read this for a receipt; do not sum `services`, which also lists a later purchase that failed.","examples":[{"amount":40,"currency":"USD"}]}]},"services":{"type":"array","items":{"$ref":"#/components/schemas/flight_FlightBookingService"},"description":"Every extra ever placed on the booking, each with its `status`. Empty when none."},"payments":{"type":"array","items":{"$ref":"#/components/schemas/flight_FlightBookingPayment"},"description":"Every payment on this booking, oldest first. Empty when none."},"expires_at":{"type":"string","description":"Complete your Duffel booking before this deadline because nothing is reserved with the airline, a chosen seat included. For LiteAPI, the supplier decides validity at book; do not start another checkout merely because this time passed.","examples":["2026-11-01T12:49:56.000Z"]},"cancellation_policy":{"$ref":"#/components/schemas/flight_FlightCancellationPolicy"},"fare_conditions":{"$ref":"#/components/schemas/flight_FareConditions"},"passengers":{"type":"array","items":{"$ref":"#/components/schemas/flight_BookingPassenger"},"description":"The passengers."},"journeys":{"type":"array","items":{"$ref":"#/components/schemas/flight_BookedJourney"},"description":"The persisted itinerary, in travel order. Present after successful prebook."},"supplier_reference":{"type":"string","description":"The supplier's order id.","examples":["ord_0000B9M0HSU2oNVmKw0UKj"]},"airline_pnr":{"type":"string","description":"The airline's record locator — what the passenger quotes at the airport.","examples":["J6AK3S"]},"confirmed_at":{"type":"string","description":"When the airline issued the ticket.","examples":["2026-11-01T12:40:12.000Z"]},"canceled_at":{"type":"string","description":"When the ticket was cancelled.","examples":["2026-11-02T09:15:00.000Z"]},"cancellation":{"$ref":"#/components/schemas/flight_BookingCancellation"},"failure":{"$ref":"#/components/schemas/flight_FlightBookingFailure"},"created_at":{"type":"string","description":"When the booking was created.","examples":["2026-11-01T12:34:56.000Z"]},"updated_at":{"type":"string","description":"When the booking last changed.","examples":["2026-11-01T12:40:12.000Z"]}},"required":["id","supplier","status","services","payments","created_at","updated_at"],"description":"A flight booking at any point in its lifecycle. A ready booking has `expires_at` and `journeys`; a confirmed one has `supplier_reference` and may have `airline_pnr`; a failed one has `failure`; a confirmed one carries `failure` too when its last cancellation was rejected. A cancellation in progress reads `CANCEL_IN_PROGRESS` until the run settles it."},"meta":{"$ref":"#/components/schemas/flight_PrebookMeta"}},"required":["data"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"201":{"description":"Binding price created; complete before expiry","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Your booking id.","examples":["bkg_0192f3a4b5c64d7e8f9a0b1c2d3e4f5b"]},"supplier":{"type":"string","description":"Which supplier holds this booking. Fixed when the booking was created, so it stays correct even if the default changes.","examples":["DUFFEL"]},"status":{"$ref":"#/components/schemas/flight_BookingStatus"},"total_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"The booking's price as sold: the fare, the extras charged with it, and later purchases once confirmed. A `FAILED` booking still shows what it tried to sell; cancellation never changes it, the refund is under `cancellation`. OEX collects it at book for Duffel; LiteAPI collects it through its checkout. Absent until the booking is priced.","examples":[{"amount":260.67,"currency":"USD"}]}]},"fare_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"The flights' own price, taxes included: `total_amount − services_amount`. Present whenever `total_amount` is.","examples":[{"amount":220.67,"currency":"USD"}]}]},"fare_tax_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"The taxes inside `fare_amount`, never added to it: 0 when the supplier reported zero, absent when it stated none.","examples":[{"amount":50,"currency":"USD"}]}]},"services_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"The extras' share of `total_amount`: the extras charged with the fare, in any status, plus every later purchase that was confirmed, which stays in after cancellation. 0 when none. Read this for a receipt; do not sum `services`, which also lists a later purchase that failed.","examples":[{"amount":40,"currency":"USD"}]}]},"services":{"type":"array","items":{"$ref":"#/components/schemas/flight_FlightBookingService"},"description":"Every extra ever placed on the booking, each with its `status`. Empty when none."},"payments":{"type":"array","items":{"$ref":"#/components/schemas/flight_FlightBookingPayment"},"description":"Every payment on this booking, oldest first. Empty when none."},"expires_at":{"type":"string","description":"Complete your Duffel booking before this deadline because nothing is reserved with the airline, a chosen seat included. For LiteAPI, the supplier decides validity at book; do not start another checkout merely because this time passed.","examples":["2026-11-01T12:49:56.000Z"]},"cancellation_policy":{"$ref":"#/components/schemas/flight_FlightCancellationPolicy"},"fare_conditions":{"$ref":"#/components/schemas/flight_FareConditions"},"passengers":{"type":"array","items":{"$ref":"#/components/schemas/flight_BookingPassenger"},"description":"The passengers."},"journeys":{"type":"array","items":{"$ref":"#/components/schemas/flight_BookedJourney"},"description":"The persisted itinerary, in travel order. Present after successful prebook."},"supplier_reference":{"type":"string","description":"The supplier's order id.","examples":["ord_0000B9M0HSU2oNVmKw0UKj"]},"airline_pnr":{"type":"string","description":"The airline's record locator — what the passenger quotes at the airport.","examples":["J6AK3S"]},"confirmed_at":{"type":"string","description":"When the airline issued the ticket.","examples":["2026-11-01T12:40:12.000Z"]},"canceled_at":{"type":"string","description":"When the ticket was cancelled.","examples":["2026-11-02T09:15:00.000Z"]},"cancellation":{"$ref":"#/components/schemas/flight_BookingCancellation"},"failure":{"$ref":"#/components/schemas/flight_FlightBookingFailure"},"created_at":{"type":"string","description":"When the booking was created.","examples":["2026-11-01T12:34:56.000Z"]},"updated_at":{"type":"string","description":"When the booking last changed.","examples":["2026-11-01T12:40:12.000Z"]}},"required":["id","supplier","status","services","payments","created_at","updated_at"],"description":"A flight booking at any point in its lifecycle. A ready booking has `expires_at` and `journeys`; a confirmed one has `supplier_reference` and may have `airline_pnr`; a failed one has `failure`; a confirmed one carries `failure` too when its last cancellation was rejected. A cancellation in progress reads `CANCEL_IN_PROGRESS` until the run settles it."},"meta":{"$ref":"#/components/schemas/flight_PrebookMeta"}},"required":["data"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"409":{"description":"Booking state conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"422":{"description":"Operation refused","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"500":{"description":"Internal or unknown outcome","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}}}},"/v1/flight/bookings":{"get":{"operationId":"listFlightBookings","tags":["Flight Bookings"],"summary":"List bookings","description":"The caller's bookings, newest first, with `meta.pagination`. Filter by `status`, `supplier`, `supplier_reference` and creation date, and sort by `created_at` or `total_amount`. Only bookings created under the calling organisation and user are returned. Each booking's `payments` come without `payment_method`; read the booking for its cards.","security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Rows per page (default 20, max 100)."},"required":false,"description":"Rows per page (default 20, max 100).","name":"limit","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"default":0,"description":"Rows to skip. `meta.pagination.total` is the full count, so the last page is at `total - limit`."},"required":false,"description":"Rows to skip. `meta.pagination.total` is the full count, so the last page is at `total - limit`.","name":"offset","in":"query"},{"schema":{"allOf":[{"$ref":"#/components/schemas/flight_BookingStatus"},{"description":"Keep only bookings in this status."}]},"required":false,"description":"Keep only bookings in this status.","name":"status","in":"query"},{"schema":{"type":"string","enum":["LITEAPI","DUFFEL"],"description":"Keep only bookings held with this supplier. The supplier is fixed when the booking is created and never changes, so this is a stable filter."},"required":false,"description":"Keep only bookings held with this supplier. The supplier is fixed when the booking is created and never changes, so this is a stable filter.","name":"supplier","in":"query"},{"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}],"description":"Earliest booking-creation time, inclusive. When the booking was created, not when you travel. A date (`2026-08-14`) starts at midnight UTC; a full timestamp is used as given."},"required":false,"description":"Earliest booking-creation time, inclusive. When the booking was created, not when you travel. A date (`2026-08-14`) starts at midnight UTC; a full timestamp is used as given.","name":"created_from","in":"query"},{"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"string","format":"date-time"}],"description":"Latest booking-creation time, inclusive. A date (`2026-08-14`) means the end of that day, so `created_from` and `created_to` set to the same date return that whole day. A full timestamp is used as given, to the millisecond. UTC."},"required":false,"description":"Latest booking-creation time, inclusive. A date (`2026-08-14`) means the end of that day, so `created_from` and `created_to` set to the same date return that whole day. A full timestamp is used as given, to the millisecond. UTC.","name":"created_to","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Exact match on the supplier's own reference for the booking — its order id. Returns a page of at most one; no partial or case-insensitive matching."},"required":false,"description":"Exact match on the supplier's own reference for the booking — its order id. Returns a page of at most one; no partial or case-insensitive matching.","name":"supplier_reference","in":"query"},{"schema":{"type":"string","enum":["created_at","total_amount"],"default":"created_at","description":"What to order by. Defaults to `created_at`. `total_amount` compares raw amounts and does not convert currencies, so a mixed-currency page sorts 500 EUR and 500 USD as equal. Bookings with no price yet always sort last, whichever direction you pick. You cannot sort by travel date."},"required":false,"description":"What to order by. Defaults to `created_at`. `total_amount` compares raw amounts and does not convert currencies, so a mixed-currency page sorts 500 EUR and 500 USD as equal. Bookings with no price yet always sort last, whichever direction you pick. You cannot sort by travel date.","name":"sort_by","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc","description":"Defaults to `desc` whichever field you sort by."},"required":false,"description":"Defaults to `desc` whichever field you sort by.","name":"sort_order","in":"query"}],"responses":{"200":{"description":"Owner-scoped booking page","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Your booking id.","examples":["bkg_0192f3a4b5c64d7e8f9a0b1c2d3e4f5b"]},"supplier":{"type":"string","description":"Which supplier holds this booking. Fixed when the booking was created, so it stays correct even if the default changes.","examples":["DUFFEL"]},"status":{"$ref":"#/components/schemas/flight_BookingStatus"},"total_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"The booking's price as sold: the fare, the extras charged with it, and later purchases once confirmed. A `FAILED` booking still shows what it tried to sell; cancellation never changes it, the refund is under `cancellation`. OEX collects it at book for Duffel; LiteAPI collects it through its checkout. Absent until the booking is priced.","examples":[{"amount":260.67,"currency":"USD"}]}]},"fare_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"The flights' own price, taxes included: `total_amount − services_amount`. Present whenever `total_amount` is.","examples":[{"amount":220.67,"currency":"USD"}]}]},"fare_tax_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"The taxes inside `fare_amount`, never added to it: 0 when the supplier reported zero, absent when it stated none.","examples":[{"amount":50,"currency":"USD"}]}]},"services_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"The extras' share of `total_amount`: the extras charged with the fare, in any status, plus every later purchase that was confirmed, which stays in after cancellation. 0 when none. Read this for a receipt; do not sum `services`, which also lists a later purchase that failed.","examples":[{"amount":40,"currency":"USD"}]}]},"services":{"type":"array","items":{"$ref":"#/components/schemas/flight_FlightBookingService"},"description":"Every extra ever placed on the booking, each with its `status`. Empty when none."},"payments":{"type":"array","items":{"$ref":"#/components/schemas/flight_FlightBookingPayment"},"description":"Every payment on this booking, oldest first. Empty when none."},"expires_at":{"type":"string","description":"Complete your Duffel booking before this deadline because nothing is reserved with the airline, a chosen seat included. For LiteAPI, the supplier decides validity at book; do not start another checkout merely because this time passed.","examples":["2026-11-01T12:49:56.000Z"]},"cancellation_policy":{"$ref":"#/components/schemas/flight_FlightCancellationPolicy"},"fare_conditions":{"$ref":"#/components/schemas/flight_FareConditions"},"passengers":{"type":"array","items":{"$ref":"#/components/schemas/flight_BookingPassenger"},"description":"The passengers."},"journeys":{"type":"array","items":{"$ref":"#/components/schemas/flight_BookedJourney"},"description":"The persisted itinerary, in travel order. Present after successful prebook."},"supplier_reference":{"type":"string","description":"The supplier's order id.","examples":["ord_0000B9M0HSU2oNVmKw0UKj"]},"airline_pnr":{"type":"string","description":"The airline's record locator — what the passenger quotes at the airport.","examples":["J6AK3S"]},"confirmed_at":{"type":"string","description":"When the airline issued the ticket.","examples":["2026-11-01T12:40:12.000Z"]},"canceled_at":{"type":"string","description":"When the ticket was cancelled.","examples":["2026-11-02T09:15:00.000Z"]},"cancellation":{"$ref":"#/components/schemas/flight_BookingCancellation"},"failure":{"$ref":"#/components/schemas/flight_FlightBookingFailure"},"created_at":{"type":"string","description":"When the booking was created.","examples":["2026-11-01T12:34:56.000Z"]},"updated_at":{"type":"string","description":"When the booking last changed.","examples":["2026-11-01T12:40:12.000Z"]}},"required":["id","supplier","status","services","payments","created_at","updated_at"],"description":"A flight booking at any point in its lifecycle. A ready booking has `expires_at` and `journeys`; a confirmed one has `supplier_reference` and may have `airline_pnr`; a failed one has `failure`; a confirmed one carries `failure` too when its last cancellation was rejected. A cancellation in progress reads `CANCEL_IN_PROGRESS` until the run settles it."}},"meta":{"$ref":"#/components/schemas/flight_ListMeta"}},"required":["data","meta"],"description":"A page of flight bookings, newest first."}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"409":{"description":"Booking state conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"422":{"description":"Operation refused","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"500":{"description":"Internal or unknown outcome","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}}}},"/v1/flight/bookings/{id}":{"get":{"operationId":"getFlightBooking","tags":["Flight Bookings"],"summary":"Get a booking","description":"One booking with its itinerary, passengers, services, payments and money, in whatever status it has. `expires_at` is present while the booking can still be completed, `failure` when it is `FAILED` or when a cancellation was refused, and `cancellation` once it is `CANCELED`. Each payment carries its card in `payment_method` when the card can be read; a card that could not be read in time can appear when you read the booking again. `airline_initiated_changes` lists the airline's recorded changes to your booked flights, beside the flights you booked in `journeys`. A booking you do not own is a `404`.","security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}},{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Booking","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/flight_FlightBookingDetail"}},"required":["data"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"409":{"description":"Booking state conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"422":{"description":"Operation refused","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"500":{"description":"Internal or unknown outcome","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}}}},"/v1/flight/bookings/{id}/book":{"post":{"operationId":"bookFlight","tags":["Flight Bookings"],"summary":"Book: pay and ticket","description":"Charge the traveller and issue the ticket: the saved `payment_instrument_id` is authorized, the airline issues the order, and the authorization is captured. The `200` is the booking as `CONFIRMED` with `supplier_reference` and, when the airline provides one, `airline_pnr`. Send `{}` when prebook set `use_payment_sdk`. A `202` returns the booking as `COMPLETE_IN_PROGRESS`: LiteAPI is still ticketing. Wait for `flight.booking.confirmed` or read the booking, and do not book again: a repeat book returns the same `202`. If it stays `COMPLETE_IN_PROGRESS`, contact support with your booking id. Booking an already confirmed booking returns it unchanged; a `500 result_unknown` means the outcome could not be established and must not be retried.","security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}},{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/flight_BookRequest"}}}},"responses":{"200":{"description":"Confirmed booking","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/flight_FlightBookingConfirmed"}},"required":["data"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"202":{"description":"LiteAPI is still ticketing. Wait for `flight.booking.confirmed` or read the booking; do not book again.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Your booking id.","examples":["bkg_0192f3a4b5c64d7e8f9a0b1c2d3e4f5b"]},"supplier":{"type":"string","description":"Which supplier holds this booking. Fixed when the booking was created, so it stays correct even if the default changes.","examples":["DUFFEL"]},"status":{"$ref":"#/components/schemas/flight_BookingStatus"},"total_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"The booking's price as sold: the fare, the extras charged with it, and later purchases once confirmed. A `FAILED` booking still shows what it tried to sell; cancellation never changes it, the refund is under `cancellation`. OEX collects it at book for Duffel; LiteAPI collects it through its checkout. Absent until the booking is priced.","examples":[{"amount":260.67,"currency":"USD"}]}]},"fare_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"The flights' own price, taxes included: `total_amount − services_amount`. Present whenever `total_amount` is.","examples":[{"amount":220.67,"currency":"USD"}]}]},"fare_tax_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"The taxes inside `fare_amount`, never added to it: 0 when the supplier reported zero, absent when it stated none.","examples":[{"amount":50,"currency":"USD"}]}]},"services_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"The extras' share of `total_amount`: the extras charged with the fare, in any status, plus every later purchase that was confirmed, which stays in after cancellation. 0 when none. Read this for a receipt; do not sum `services`, which also lists a later purchase that failed.","examples":[{"amount":40,"currency":"USD"}]}]},"services":{"type":"array","items":{"$ref":"#/components/schemas/flight_FlightBookingService"},"description":"Every extra ever placed on the booking, each with its `status`. Empty when none."},"payments":{"type":"array","items":{"$ref":"#/components/schemas/flight_FlightBookingPayment"},"description":"Every payment on this booking, oldest first. Empty when none."},"expires_at":{"type":"string","description":"Complete your Duffel booking before this deadline because nothing is reserved with the airline, a chosen seat included. For LiteAPI, the supplier decides validity at book; do not start another checkout merely because this time passed.","examples":["2026-11-01T12:49:56.000Z"]},"cancellation_policy":{"$ref":"#/components/schemas/flight_FlightCancellationPolicy"},"fare_conditions":{"$ref":"#/components/schemas/flight_FareConditions"},"passengers":{"type":"array","items":{"$ref":"#/components/schemas/flight_BookingPassenger"},"description":"The passengers."},"journeys":{"type":"array","items":{"$ref":"#/components/schemas/flight_BookedJourney"},"description":"The persisted itinerary, in travel order. Present after successful prebook."},"supplier_reference":{"type":"string","description":"The supplier's order id.","examples":["ord_0000B9M0HSU2oNVmKw0UKj"]},"airline_pnr":{"type":"string","description":"The airline's record locator — what the passenger quotes at the airport.","examples":["J6AK3S"]},"confirmed_at":{"type":"string","description":"When the airline issued the ticket.","examples":["2026-11-01T12:40:12.000Z"]},"canceled_at":{"type":"string","description":"When the ticket was cancelled.","examples":["2026-11-02T09:15:00.000Z"]},"cancellation":{"$ref":"#/components/schemas/flight_BookingCancellation"},"failure":{"$ref":"#/components/schemas/flight_FlightBookingFailure"},"created_at":{"type":"string","description":"When the booking was created.","examples":["2026-11-01T12:34:56.000Z"]},"updated_at":{"type":"string","description":"When the booking last changed.","examples":["2026-11-01T12:40:12.000Z"]}},"required":["id","supplier","status","services","payments","created_at","updated_at"],"description":"A flight booking at any point in its lifecycle. A ready booking has `expires_at` and `journeys`; a confirmed one has `supplier_reference` and may have `airline_pnr`; a failed one has `failure`; a confirmed one carries `failure` too when its last cancellation was rejected. A cancellation in progress reads `CANCEL_IN_PROGRESS` until the run settles it."}},"required":["data"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"409":{"description":"Booking state conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"422":{"description":"Operation refused","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"500":{"description":"Internal or unknown outcome","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}}}},"/v1/flight/bookings/{id}/cancel":{"post":{"operationId":"cancelFlightBooking","tags":["Flight Bookings"],"summary":"Cancel a booking","description":"Starts a background cancellation and returns immediately. Poll GET /v1/flight/bookings/{id} for supplier cancellation: CANCELED means the ticket was released; CONFIRMED means it remains valid after a rejected cancellation. The cancellation block contains the supplier fee and intended refund_amount, not refund settlement. After supplier success, the workflow submits refund requests to Payment and completes when they are accepted. Payment owns subsequent processing. A repeated request does not restart an active or completed run; it can restart a failed run, including refund submission for an already canceled booking. Canceled bookings return 200; cancellations in progress return 202. Validation failures return 4xx.","security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}},{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/flight_CancelFlightBookingRequest"}}}},"responses":{"200":{"description":"Already cancelled by an earlier request; the booking as it stands.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Your booking id.","examples":["bkg_0192f3a4b5c64d7e8f9a0b1c2d3e4f5b"]},"supplier":{"type":"string","description":"Which supplier holds this booking. Fixed when the booking was created, so it stays correct even if the default changes.","examples":["DUFFEL"]},"status":{"$ref":"#/components/schemas/flight_BookingStatus"},"total_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"The booking's price as sold: the fare, the extras charged with it, and later purchases once confirmed. A `FAILED` booking still shows what it tried to sell; cancellation never changes it, the refund is under `cancellation`. OEX collects it at book for Duffel; LiteAPI collects it through its checkout. Absent until the booking is priced.","examples":[{"amount":260.67,"currency":"USD"}]}]},"fare_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"The flights' own price, taxes included: `total_amount − services_amount`. Present whenever `total_amount` is.","examples":[{"amount":220.67,"currency":"USD"}]}]},"fare_tax_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"The taxes inside `fare_amount`, never added to it: 0 when the supplier reported zero, absent when it stated none.","examples":[{"amount":50,"currency":"USD"}]}]},"services_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"The extras' share of `total_amount`: the extras charged with the fare, in any status, plus every later purchase that was confirmed, which stays in after cancellation. 0 when none. Read this for a receipt; do not sum `services`, which also lists a later purchase that failed.","examples":[{"amount":40,"currency":"USD"}]}]},"services":{"type":"array","items":{"$ref":"#/components/schemas/flight_FlightBookingService"},"description":"Every extra ever placed on the booking, each with its `status`. Empty when none."},"payments":{"type":"array","items":{"$ref":"#/components/schemas/flight_FlightBookingPayment"},"description":"Every payment on this booking, oldest first. Empty when none."},"expires_at":{"type":"string","description":"Complete your Duffel booking before this deadline because nothing is reserved with the airline, a chosen seat included. For LiteAPI, the supplier decides validity at book; do not start another checkout merely because this time passed.","examples":["2026-11-01T12:49:56.000Z"]},"cancellation_policy":{"$ref":"#/components/schemas/flight_FlightCancellationPolicy"},"fare_conditions":{"$ref":"#/components/schemas/flight_FareConditions"},"passengers":{"type":"array","items":{"$ref":"#/components/schemas/flight_BookingPassenger"},"description":"The passengers."},"journeys":{"type":"array","items":{"$ref":"#/components/schemas/flight_BookedJourney"},"description":"The persisted itinerary, in travel order. Present after successful prebook."},"supplier_reference":{"type":"string","description":"The supplier's order id.","examples":["ord_0000B9M0HSU2oNVmKw0UKj"]},"airline_pnr":{"type":"string","description":"The airline's record locator — what the passenger quotes at the airport.","examples":["J6AK3S"]},"confirmed_at":{"type":"string","description":"When the airline issued the ticket.","examples":["2026-11-01T12:40:12.000Z"]},"canceled_at":{"type":"string","description":"When the ticket was cancelled.","examples":["2026-11-02T09:15:00.000Z"]},"cancellation":{"$ref":"#/components/schemas/flight_BookingCancellation"},"failure":{"$ref":"#/components/schemas/flight_FlightBookingFailure"},"created_at":{"type":"string","description":"When the booking was created.","examples":["2026-11-01T12:34:56.000Z"]},"updated_at":{"type":"string","description":"When the booking last changed.","examples":["2026-11-01T12:40:12.000Z"]}},"required":["id","supplier","status","services","payments","created_at","updated_at"],"description":"A flight booking at any point in its lifecycle. A ready booking has `expires_at` and `journeys`; a confirmed one has `supplier_reference` and may have `airline_pnr`; a failed one has `failure`; a confirmed one carries `failure` too when its last cancellation was rejected. A cancellation in progress reads `CANCEL_IN_PROGRESS` until the run settles it."}},"required":["data"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"202":{"description":"Cancellation started. Poll the booking until it reads `CANCELED`, or `CONFIRMED` with `failure`.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Your booking id.","examples":["bkg_0192f3a4b5c64d7e8f9a0b1c2d3e4f5b"]},"supplier":{"type":"string","description":"Which supplier holds this booking. Fixed when the booking was created, so it stays correct even if the default changes.","examples":["DUFFEL"]},"status":{"$ref":"#/components/schemas/flight_BookingStatus"},"total_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"The booking's price as sold: the fare, the extras charged with it, and later purchases once confirmed. A `FAILED` booking still shows what it tried to sell; cancellation never changes it, the refund is under `cancellation`. OEX collects it at book for Duffel; LiteAPI collects it through its checkout. Absent until the booking is priced.","examples":[{"amount":260.67,"currency":"USD"}]}]},"fare_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"The flights' own price, taxes included: `total_amount − services_amount`. Present whenever `total_amount` is.","examples":[{"amount":220.67,"currency":"USD"}]}]},"fare_tax_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"The taxes inside `fare_amount`, never added to it: 0 when the supplier reported zero, absent when it stated none.","examples":[{"amount":50,"currency":"USD"}]}]},"services_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"The extras' share of `total_amount`: the extras charged with the fare, in any status, plus every later purchase that was confirmed, which stays in after cancellation. 0 when none. Read this for a receipt; do not sum `services`, which also lists a later purchase that failed.","examples":[{"amount":40,"currency":"USD"}]}]},"services":{"type":"array","items":{"$ref":"#/components/schemas/flight_FlightBookingService"},"description":"Every extra ever placed on the booking, each with its `status`. Empty when none."},"payments":{"type":"array","items":{"$ref":"#/components/schemas/flight_FlightBookingPayment"},"description":"Every payment on this booking, oldest first. Empty when none."},"expires_at":{"type":"string","description":"Complete your Duffel booking before this deadline because nothing is reserved with the airline, a chosen seat included. For LiteAPI, the supplier decides validity at book; do not start another checkout merely because this time passed.","examples":["2026-11-01T12:49:56.000Z"]},"cancellation_policy":{"$ref":"#/components/schemas/flight_FlightCancellationPolicy"},"fare_conditions":{"$ref":"#/components/schemas/flight_FareConditions"},"passengers":{"type":"array","items":{"$ref":"#/components/schemas/flight_BookingPassenger"},"description":"The passengers."},"journeys":{"type":"array","items":{"$ref":"#/components/schemas/flight_BookedJourney"},"description":"The persisted itinerary, in travel order. Present after successful prebook."},"supplier_reference":{"type":"string","description":"The supplier's order id.","examples":["ord_0000B9M0HSU2oNVmKw0UKj"]},"airline_pnr":{"type":"string","description":"The airline's record locator — what the passenger quotes at the airport.","examples":["J6AK3S"]},"confirmed_at":{"type":"string","description":"When the airline issued the ticket.","examples":["2026-11-01T12:40:12.000Z"]},"canceled_at":{"type":"string","description":"When the ticket was cancelled.","examples":["2026-11-02T09:15:00.000Z"]},"cancellation":{"$ref":"#/components/schemas/flight_BookingCancellation"},"failure":{"$ref":"#/components/schemas/flight_FlightBookingFailure"},"created_at":{"type":"string","description":"When the booking was created.","examples":["2026-11-01T12:34:56.000Z"]},"updated_at":{"type":"string","description":"When the booking last changed.","examples":["2026-11-01T12:40:12.000Z"]}},"required":["id","supplier","status","services","payments","created_at","updated_at"],"description":"A flight booking at any point in its lifecycle. A ready booking has `expires_at` and `journeys`; a confirmed one has `supplier_reference` and may have `airline_pnr`; a failed one has `failure`; a confirmed one carries `failure` too when its last cancellation was rejected. A cancellation in progress reads `CANCEL_IN_PROGRESS` until the run settles it."}},"required":["data"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"409":{"description":"Booking state conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"422":{"description":"Operation refused","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"500":{"description":"Internal or unknown outcome","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}}}},"/v1/flight/bookings/{id}/cancellation-quote":{"get":{"operationId":"getFlightCancellationQuote","tags":["Flight Bookings"],"summary":"Quote a cancellation","description":"What cancelling right now would cost. It asks the airline for its own quote and moves no money; for a Duffel booking the airline prepares a cancellation that is never confirmed and lapses on its own. When the airline cannot answer, you receive an estimate from the fare terms stored on the booking instead, and `source` says which one you have. The quote is advisory: the airline decides the real fee when the cancel lands. When the money fields are absent, `unavailable_reason` says why; that is not a free cancellation. Every call asks the airline again, so do not poll it.","security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}},{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The airline's quote, or the stored-terms estimate","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"source":{"type":"string","enum":["SUPPLIER_QUOTE","POLICY_ESTIMATE"],"description":"Where the numbers come from: `SUPPLIER_QUOTE` is the airline's own quote, asked for just now; `POLICY_ESTIMATE` is an estimate from the fare terms stored when you booked, which you receive when the airline cannot answer. Neither is a guarantee.","examples":["SUPPLIER_QUOTE"]},"is_free":{"type":"boolean","description":"Whether cancelling now costs nothing and the whole total comes back.","examples":[false]},"fee":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"What cancelling now would cost. Omitted with `unavailable_reason` — do not treat omission as free.","examples":[{"amount":150,"currency":"USD"}]}]},"refundable_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"What would come back: the refund the airline quotes, or the total you paid minus `fee`.","examples":[{"amount":70.67,"currency":"USD"}]}]},"quoted_at":{"type":"string","description":"When this quote was produced.","examples":["2026-11-01T09:12:44.000Z"]},"unavailable_reason":{"allOf":[{"$ref":"#/components/schemas/flight_FlightQuoteUnavailableReason"},{"description":"Why the money fields are omitted. None of these means free.","examples":["no_policy"]}]}},"required":["source","quoted_at"],"description":"What cancelling would cost right now: the airline's own quote when it answers, otherwise an estimate from the fare terms stored when you booked. Advisory: the airline decides the real fee when the cancel lands."}},"required":["data"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"409":{"description":"Booking state conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"422":{"description":"Operation refused","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"500":{"description":"Internal or unknown outcome","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}}}},"/v1/flight/bookings/{id}/available-services":{"get":{"operationId":"getFlightBookingAvailableServices","tags":["Flight Bookings"],"summary":"List a booking's purchasable bags","description":"Bags the airline sells on a confirmed booking right now, asked live. Empty when the airline sells none after booking, or the booking already carries bags. 409 unless the booking is `CONFIRMED`.","security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}},{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Bags the traveller can add to this booking.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/flight_FlightBookingAvailableService"}}},"required":["data"],"description":"Bags the traveller can add to this booking."}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"409":{"description":"Booking state conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"422":{"description":"Operation refused","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"500":{"description":"Internal or unknown outcome","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}}}},"/v1/flight/bookings/{id}/services":{"post":{"operationId":"createFlightBookingServices","tags":["Flight Bookings"],"summary":"Buy bags for a booking","description":"Buys bags on a confirmed booking with a saved card, as its own payment. The call is synchronous: success means the supplier confirmed the bags and Flight saved them and their totals. Payment capture is attempted before confirmation; a capture failure does not undo supplier-confirmed bags. Repeating an `x-idempotency-key` never charges or buys again: a completed purchase returns the current booking, a declined card returns 422 `payment_failed`, and a supplier refusal returns 422 `supplier_rejected`. A purchase that is still pending or has an unknown outcome returns 500 `result_unknown`, including on repeated requests. Do not submit it with a new key; it requires reconciliation. A new attempt after a known refusal or decline needs a new key.","security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}},{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":256,"description":"Your key for this prebook. Repeating it with the same organisation and user returns the existing booking rather than placing a second hold. After a failed booking, send a new key.","examples":["trip-2026-11-10-1"]},"required":true,"description":"Your key for this prebook. Repeating it with the same organisation and user returns the existing booking rather than placing a second hold. After a failed booking, send a new key.","in":"header","name":"x-idempotency-key"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/flight_FlightBookingServicesRequest"}}}},"responses":{"200":{"description":"The booking with the bags, `services_amount` and `total_amount` raised.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Your booking id.","examples":["bkg_0192f3a4b5c64d7e8f9a0b1c2d3e4f5b"]},"supplier":{"type":"string","description":"Which supplier holds this booking. Fixed when the booking was created, so it stays correct even if the default changes.","examples":["DUFFEL"]},"status":{"$ref":"#/components/schemas/flight_BookingStatus"},"total_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"The booking's price as sold: the fare, the extras charged with it, and later purchases once confirmed. A `FAILED` booking still shows what it tried to sell; cancellation never changes it, the refund is under `cancellation`. OEX collects it at book for Duffel; LiteAPI collects it through its checkout. Absent until the booking is priced.","examples":[{"amount":260.67,"currency":"USD"}]}]},"fare_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"The flights' own price, taxes included: `total_amount − services_amount`. Present whenever `total_amount` is.","examples":[{"amount":220.67,"currency":"USD"}]}]},"fare_tax_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"The taxes inside `fare_amount`, never added to it: 0 when the supplier reported zero, absent when it stated none.","examples":[{"amount":50,"currency":"USD"}]}]},"services_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"The extras' share of `total_amount`: the extras charged with the fare, in any status, plus every later purchase that was confirmed, which stays in after cancellation. 0 when none. Read this for a receipt; do not sum `services`, which also lists a later purchase that failed.","examples":[{"amount":40,"currency":"USD"}]}]},"services":{"type":"array","items":{"$ref":"#/components/schemas/flight_FlightBookingService"},"description":"Every extra ever placed on the booking, each with its `status`. Empty when none."},"payments":{"type":"array","items":{"$ref":"#/components/schemas/flight_FlightBookingPayment"},"description":"Every payment on this booking, oldest first. Empty when none."},"expires_at":{"type":"string","description":"Complete your Duffel booking before this deadline because nothing is reserved with the airline, a chosen seat included. For LiteAPI, the supplier decides validity at book; do not start another checkout merely because this time passed.","examples":["2026-11-01T12:49:56.000Z"]},"cancellation_policy":{"$ref":"#/components/schemas/flight_FlightCancellationPolicy"},"fare_conditions":{"$ref":"#/components/schemas/flight_FareConditions"},"passengers":{"type":"array","items":{"$ref":"#/components/schemas/flight_BookingPassenger"},"description":"The passengers."},"journeys":{"type":"array","items":{"$ref":"#/components/schemas/flight_BookedJourney"},"description":"The persisted itinerary, in travel order. Present after successful prebook."},"supplier_reference":{"type":"string","description":"The supplier's order id.","examples":["ord_0000B9M0HSU2oNVmKw0UKj"]},"airline_pnr":{"type":"string","description":"The airline's record locator — what the passenger quotes at the airport.","examples":["J6AK3S"]},"confirmed_at":{"type":"string","description":"When the airline issued the ticket.","examples":["2026-11-01T12:40:12.000Z"]},"canceled_at":{"type":"string","description":"When the ticket was cancelled.","examples":["2026-11-02T09:15:00.000Z"]},"cancellation":{"$ref":"#/components/schemas/flight_BookingCancellation"},"failure":{"$ref":"#/components/schemas/flight_FlightBookingFailure"},"created_at":{"type":"string","description":"When the booking was created.","examples":["2026-11-01T12:34:56.000Z"]},"updated_at":{"type":"string","description":"When the booking last changed.","examples":["2026-11-01T12:40:12.000Z"]}},"required":["id","supplier","status","services","payments","created_at","updated_at"],"description":"A flight booking at any point in its lifecycle. A ready booking has `expires_at` and `journeys`; a confirmed one has `supplier_reference` and may have `airline_pnr`; a failed one has `failure`; a confirmed one carries `failure` too when its last cancellation was rejected. A cancellation in progress reads `CANCEL_IN_PROGRESS` until the run settles it."}},"required":["data"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"409":{"description":"Booking state conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"422":{"description":"Operation refused","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"500":{"description":"Internal or unknown outcome","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}}}},"/v1/flight/airlines":{"get":{"operationId":"listAirlines","tags":["Airlines"],"summary":"List airlines","description":"Search the local airline directory. Results are ordered by IATA code; meta.truncated indicates more matches. Individual airline lookups import missing carriers from the supplier.","security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}},{"schema":{"type":"string","minLength":1,"maxLength":100,"description":"Literal case-insensitive substring of name, IATA code, or ICAO code."},"required":false,"description":"Literal case-insensitive substring of name, IATA code, or ICAO code.","name":"q","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["true","false"],"default":"true","description":"True returns active airlines only. False includes both active and inactive airlines."},"required":false,"description":"True returns active airlines only. False includes both active and inactive airlines.","name":"active_only","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Alliance identifier. Exact match, case-insensitive input.","examples":["oneworld"]},"required":false,"description":"Alliance identifier. Exact match, case-insensitive input.","name":"alliance","in":"query"}],"responses":{"200":{"description":"Airline records","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/flight_Airline"}},"meta":{"type":"object","properties":{"truncated":{"type":"boolean"}},"required":["truncated"]}},"required":["data","meta"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"409":{"description":"Booking state conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"422":{"description":"Operation refused","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"500":{"description":"Internal or unknown outcome","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}}}},"/v1/flight/airlines/iatas":{"get":{"operationId":"listAirlineIatas","tags":["Airlines"],"summary":"List airline IATA codes","description":"All imported airline code/name pairs, sorted by IATA code. No implicit result limit.","security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}},{"schema":{"type":"string","enum":["true","false"],"default":"true","description":"True returns active airlines only. False includes both active and inactive airlines."},"required":false,"description":"True returns active airlines only. False includes both active and inactive airlines.","name":"active_only","in":"query"}],"responses":{"200":{"description":"Airline codes and names","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/flight_AirlineIata"}}},"required":["data"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"409":{"description":"Booking state conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"422":{"description":"Operation refused","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"500":{"description":"Internal or unknown outcome","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}}}},"/v1/flight/airlines/iatas/{iataCode}":{"get":{"operationId":"getAirline","tags":["Airlines"],"summary":"Get airline by IATA code","description":"Read an airline, including inactive airlines. A missing local record is imported from the supplier; an unknown carrier returns 404.","security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}},{"schema":{"type":"string","pattern":"^\\s*[A-Za-z0-9]{2}\\s*$","description":"Two-character airline IATA code; input is trimmed and uppercased.","examples":["AA"]},"required":true,"description":"Two-character airline IATA code; input is trimmed and uppercased.","name":"iataCode","in":"path"}],"responses":{"200":{"description":"Airline record","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/flight_Airline"}},"required":["data"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"409":{"description":"Booking state conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"422":{"description":"Operation refused","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"500":{"description":"Internal or unknown outcome","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}}}},"/v1/flight/airports":{"get":{"operationId":"searchAirports","tags":["Airports"],"summary":"Search airports","description":"Search airports by name, city or IATA code. Every search asks the supplier, within an eight-second budget, and stores the airports it returns to you. Results keep the supplier's order; meta.truncated indicates more matches than `limit`.","security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}},{"schema":{"type":"string","minLength":2,"maxLength":100,"description":"Search text the supplier matches against airport name, city and IATA code. At least two characters.","examples":["New York"]},"required":true,"description":"Search text the supplier matches against airport name, city and IATA code. At least two characters.","name":"q","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Airport records","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/flight_Airport"}},"meta":{"type":"object","properties":{"truncated":{"type":"boolean"}},"required":["truncated"]}},"required":["data","meta"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"409":{"description":"Booking state conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"422":{"description":"Operation refused","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"500":{"description":"Internal or unknown outcome","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}}}},"/v1/flight/airports/iatas/{iataCode}":{"get":{"operationId":"getAirport","tags":["Airports"],"summary":"Get airport by IATA code","description":"Read an airport. A missing local record is imported from the supplier; an unknown code returns 404.","security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}},{"schema":{"type":"string","pattern":"^\\s*[A-Za-z]{3}\\s*$","description":"Three-letter airport IATA code; input is trimmed and uppercased.","examples":["JFK"]},"required":true,"description":"Three-letter airport IATA code; input is trimmed and uppercased.","name":"iataCode","in":"path"}],"responses":{"200":{"description":"Airport record","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/flight_Airport"}},"required":["data"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"409":{"description":"Booking state conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"422":{"description":"Operation refused","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"500":{"description":"Internal or unknown outcome","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}}}},"/v1/flight/webhook-subscriptions":{"post":{"operationId":"createFlightWebhookSubscription","tags":["Flight Webhooks"],"summary":"Create a subscription","description":"Register an HTTPS endpoint and the events it receives. You receive the signing secret only in this response, so store it on your server. Your organisation holds at most five subscriptions, one per URL, shared by all its credentials; a sixth or a repeated URL is a `409`.","security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","maxLength":2048,"description":"Your HTTPS endpoint. It uses a public DNS name of your own, not an IP address, a local name or a host of this platform or its message queue, because requests there would carry this platform's own signature. It carries no user name, password or fragment.","examples":["https://partner.example/hooks/flight"]},"event_types":{"type":"array","items":{"type":"string","enum":["flight.booking.confirmed","flight.booking.failed","flight.booking.canceled","flight.booking.cancel_failed","flight.booking.airline_initiated_change_detected"]},"minItems":1,"description":"The booking events you receive.","examples":[["flight.booking.confirmed","flight.booking.canceled"]]}},"required":["url","event_types"],"additionalProperties":false}}}},"responses":{"201":{"description":"Your subscription and its signing secret","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/flight_FlightWebhookSubscriptionWithSecret"}},"required":["data"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"409":{"description":"Booking state conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"422":{"description":"Operation refused","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"500":{"description":"Internal or unknown outcome","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}},"parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}}]},"get":{"operationId":"listFlightWebhookSubscriptions","tags":["Flight Webhooks"],"summary":"List your subscriptions","description":"Your organisation's subscriptions, oldest first, without their signing secrets.","security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"Your subscriptions","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/flight_FlightWebhookSubscription"}}},"required":["data"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"409":{"description":"Booking state conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"422":{"description":"Operation refused","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"500":{"description":"Internal or unknown outcome","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}},"parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}}]}},"/v1/flight/webhook-subscriptions/{id}":{"patch":{"operationId":"updateFlightWebhookSubscription","tags":["Flight Webhooks"],"summary":"Change a subscription","description":"Change the URL, the events or the status. A paused subscription receives no new events, and events that occur while it is paused are not sent later. Events not yet queued when you pause fail with `subscription_paused`; resume the subscription, then replay them. Requests already queued, including their retries, still arrive at the URL they were queued with.","security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}},{"schema":{"type":"string","maxLength":128,"pattern":"^whs_[a-zA-Z0-9-]+$","examples":["whs_0192f3a4b5c64d7e8f9a0b1c2d3e4f5b"]},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","maxLength":2048,"description":"Your HTTPS endpoint. It uses a public DNS name of your own, not an IP address, a local name or a host of this platform or its message queue, because requests there would carry this platform's own signature. It carries no user name, password or fragment.","examples":["https://partner.example/hooks/flight"]},"event_types":{"type":"array","items":{"type":"string","enum":["flight.booking.confirmed","flight.booking.failed","flight.booking.canceled","flight.booking.cancel_failed","flight.booking.airline_initiated_change_detected"]},"minItems":1,"description":"The booking events you receive.","examples":[["flight.booking.confirmed","flight.booking.canceled"]]},"status":{"type":"string","enum":["ACTIVE","PAUSED"],"description":"PAUSED stops new events for this subscription; events that occur while it is paused are not sent later."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Your subscription","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/flight_FlightWebhookSubscription"}},"required":["data"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"409":{"description":"Booking state conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"422":{"description":"Operation refused","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"500":{"description":"Internal or unknown outcome","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}}},"delete":{"operationId":"deleteFlightWebhookSubscription","tags":["Flight Webhooks"],"summary":"Delete a subscription","description":"Delete the subscription and its delivery history. Requests already queued can still arrive.","security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}},{"schema":{"type":"string","maxLength":128,"pattern":"^whs_[a-zA-Z0-9-]+$","examples":["whs_0192f3a4b5c64d7e8f9a0b1c2d3e4f5b"]},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Your subscription is deleted","headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"409":{"description":"Booking state conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"422":{"description":"Operation refused","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"500":{"description":"Internal or unknown outcome","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}}}},"/v1/flight/webhook-subscriptions/{id}/rotate-secret":{"post":{"operationId":"rotateFlightWebhookSubscriptionSecret","tags":["Flight Webhooks"],"summary":"Rotate the signing secret","description":"Receive a new signing secret, only in this response. For 24 hours new requests carry a signature for each secret. Keep accepting your previous secret for at least 2 hours 15 minutes, because requests queued before the rotation carry only its signature. Rotating again replaces the previous secret.","security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}},{"schema":{"type":"string","maxLength":128,"pattern":"^whs_[a-zA-Z0-9-]+$","examples":["whs_0192f3a4b5c64d7e8f9a0b1c2d3e4f5b"]},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Your subscription and its signing secret","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/flight_FlightWebhookSubscriptionWithSecret"}},"required":["data"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"409":{"description":"Booking state conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"422":{"description":"Operation refused","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"500":{"description":"Internal or unknown outcome","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}}}},"/v1/flight/webhook-subscriptions/{id}/deliveries":{"get":{"operationId":"listFlightWebhookDeliveries","tags":["Flight Webhooks"],"summary":"List a subscription's deliveries","description":"The subscription's deliveries, newest first, with `meta.pagination`, each with its event and your endpoint's responses for the current replay. Filter by `status` to find failed or stuck deliveries.","security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}},{"schema":{"type":"string","maxLength":128,"pattern":"^whs_[a-zA-Z0-9-]+$","examples":["whs_0192f3a4b5c64d7e8f9a0b1c2d3e4f5b"]},"required":true,"name":"id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"required":false,"name":"limit","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"maximum":100000,"default":0},"required":false,"name":"offset","in":"query"},{"schema":{"type":"string","enum":["PENDING","PUBLISHED","DELIVERED","FAILED"]},"required":false,"name":"status","in":"query"}],"responses":{"200":{"description":"Your deliveries","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/flight_FlightWebhookDelivery"}},"meta":{"$ref":"#/components/schemas/flight_ListMeta"}},"required":["data","meta"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"409":{"description":"Booking state conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"422":{"description":"Operation refused","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"500":{"description":"Internal or unknown outcome","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}}}},"/v1/flight/webhook-subscriptions/{id}/deliveries/{delivery_id}/replay":{"post":{"operationId":"replayFlightWebhookDelivery","tags":["Flight Webhooks"],"summary":"Replay a delivery","description":"Send the same event again with a fresh signature. You can replay a delivered or failed delivery, one pending for more than a minute, or one published more than 2 hours 15 minutes ago without a result; anything else is a `409`, as is a paused subscription. Your endpoint can receive the event again, so ignore repeats by event ID.","security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}},{"schema":{"type":"string","maxLength":128,"pattern":"^whs_[a-zA-Z0-9-]+$","examples":["whs_0192f3a4b5c64d7e8f9a0b1c2d3e4f5b"]},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","maxLength":128,"pattern":"^dlv_[a-zA-Z0-9-]+$","examples":["dlv_0192f3a4b5c64d7e8f9a0b1c2d3e4f5b"]},"required":true,"name":"delivery_id","in":"path"}],"responses":{"200":{"description":"Your delivery after the replay. PENDING means queueing was not confirmed and the request may already be on its way; replay it again after a minute if it stays PENDING.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/flight_FlightWebhookDelivery"}},"required":["data"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"409":{"description":"Booking state conflict","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"422":{"description":"Operation refused","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"500":{"description":"Internal or unknown outcome","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}}}},"/v1/mandate/.well-known/jwks.json":{"get":{"tags":["Mandates"],"summary":"Signing keys","operationId":"getMandateJwks","parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/mandate_HTTPValidationError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}},"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]}},"/v1/mandate/categories":{"get":{"tags":["Mandates"],"summary":"Charge categories","operationId":"listMandateCategories","parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/mandate_HTTPValidationError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}},"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]}},"/v1/mandate":{"post":{"tags":["Mandates"],"summary":"Issue a mandate","operationId":"issueMandate","parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/mandate_IssueRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/mandate_HTTPValidationError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}},"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]},"get":{"tags":["Mandates"],"summary":"List a user's mandates","operationId":"listMandates","parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}},{"name":"user_id","in":"query","required":true,"schema":{"type":"string","title":"User Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/mandate_HTTPValidationError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}},"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]}},"/v1/mandate/{mandate_id}/confirm":{"post":{"tags":["Mandates"],"summary":"Confirm a mandate","operationId":"confirmMandate","parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}},{"name":"mandate_id","in":"path","required":true,"schema":{"type":"string","title":"Mandate Id"}}],"requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/mandate_ConfirmRequest"}],"title":"Req","nullable":true}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/mandate_HTTPValidationError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}},"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]}},"/v1/mandate/{mandate_id}":{"get":{"tags":["Mandates"],"summary":"Retrieve a mandate","operationId":"getMandate","parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}},{"name":"mandate_id","in":"path","required":true,"schema":{"type":"string","title":"Mandate Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/mandate_HTTPValidationError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}},"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]}},"/v1/mandate/verify":{"post":{"tags":["Verification"],"summary":"Verify a token against a charge","operationId":"verifyMandate","parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}},{"name":"x-agent-id","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Agent-Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/mandate_VerifyRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/mandate_HTTPValidationError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}},"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]}},"/v1/mandate/{mandate_id}/revoke":{"post":{"tags":["Mandates"],"summary":"Revoke a mandate","operationId":"revokeMandate","parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}},{"name":"mandate_id","in":"path","required":true,"schema":{"type":"string","title":"Mandate Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/mandate_HTTPValidationError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}},"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]}},"/v1/mandate/{mandate_id}/evidence":{"get":{"tags":["Mandates"],"summary":"Evidence pack","operationId":"getMandateEvidence","parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}},{"name":"mandate_id","in":"path","required":true,"schema":{"type":"string","title":"Mandate Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/mandate_HTTPValidationError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}},"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]}},"/v1/watcher/health":{"get":{"tags":["Service"],"summary":"Health","operationId":"watcherHealth","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":{"type":"string"},"type":"object","title":"Response Watcherhealth"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}},"parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}}],"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]}},"/v1/watcher/whoami":{"get":{"tags":["Service"],"summary":"Who am I acting as","operationId":"watcherWhoami","parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Watcherwhoami"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/watcher_HTTPValidationError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}},"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]}},"/v1/watcher/travel/hotel/watches":{"post":{"tags":["Hotel watches"],"summary":"Create a hotel watch","operationId":"createHotelWatch","parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/watcher_WatchCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Createhotelwatch"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/watcher_HTTPValidationError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}},"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]},"get":{"tags":["Hotel watches"],"summary":"List hotel watches","operationId":"listHotelWatches","parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Listhotelwatches"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/watcher_HTTPValidationError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}},"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]}},"/v1/watcher/travel/hotel/watches/{watch_id}":{"get":{"tags":["Hotel watches"],"summary":"Retrieve a hotel watch","operationId":"getHotelWatch","parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}},{"name":"watch_id","in":"path","required":true,"schema":{"type":"string","title":"Watch Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Gethotelwatch"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/watcher_HTTPValidationError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}},"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]},"delete":{"tags":["Hotel watches"],"summary":"Delete a hotel watch","operationId":"deleteHotelWatch","parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}},{"name":"watch_id","in":"path","required":true,"schema":{"type":"string","title":"Watch Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Deletehotelwatch"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/watcher_HTTPValidationError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}},"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]}},"/v1/watcher/travel/hotel/watches/{watch_id}/rearm":{"post":{"tags":["Hotel watches"],"summary":"Rearm a hotel watch","operationId":"rearmHotelWatch","parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}},{"name":"watch_id","in":"path","required":true,"schema":{"type":"string","title":"Watch Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/watcher_Rearm"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Rearmhotelwatch"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/watcher_HTTPValidationError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}},"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]}},"/v1/watcher/travel/hotel/watches/{watch_id}/confirm-purchase":{"post":{"tags":["Hotel watches"],"summary":"Confirm auto-purchase consent","description":"The second half of arming an auto-book watch: seal the mandate draft\nissued at create. Until this succeeds the watch only notifies.","operationId":"confirmHotelWatchPurchase","parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}},{"name":"watch_id","in":"path","required":true,"schema":{"type":"string","title":"Watch Id"}}],"requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/watcher_ConfirmPurchase"}],"title":"Body","nullable":true}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Confirmhotelwatchpurchase"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/watcher_HTTPValidationError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}},"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]}},"/v1/watcher/travel/hotel/trip-watches":{"post":{"tags":["Trip watches"],"summary":"Create a trip watch","operationId":"createTripWatch","parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/watcher_TripWatchCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Createtripwatch"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/watcher_HTTPValidationError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}},"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]},"get":{"tags":["Trip watches"],"summary":"List trip watches","operationId":"listTripWatches","parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Listtripwatches"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/watcher_HTTPValidationError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}},"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]}},"/v1/watcher/travel/hotel/trip-watches/{watch_id}":{"get":{"tags":["Trip watches"],"summary":"Retrieve a trip watch","operationId":"getTripWatch","parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}},{"name":"watch_id","in":"path","required":true,"schema":{"type":"string","title":"Watch Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Gettripwatch"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/watcher_HTTPValidationError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}},"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]},"delete":{"tags":["Trip watches"],"summary":"Delete a trip watch","operationId":"deleteTripWatch","parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}},{"name":"watch_id","in":"path","required":true,"schema":{"type":"string","title":"Watch Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Deletetripwatch"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/watcher_HTTPValidationError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}},"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]}},"/v1/watcher/travel/hotel/trip-watches/{watch_id}/rearm":{"post":{"tags":["Trip watches"],"summary":"Rearm a trip watch","operationId":"rearmTripWatch","parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}},{"name":"watch_id","in":"path","required":true,"schema":{"type":"string","title":"Watch Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/watcher_Rearm"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Rearmtripwatch"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/watcher_HTTPValidationError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}},"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]}},"/v1/watcher/webhooks":{"post":{"tags":["Webhooks"],"summary":"Register the webhook endpoint","description":"One endpoint per org; POSTing again replaces it and rotates the\nsecret. The secret appears in this response and never again.","operationId":"registerWatcherWebhook","parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/watcher_WebhookRegister"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Registerwatcherwebhook"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/watcher_HTTPValidationError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}},"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]},"get":{"tags":["Webhooks"],"summary":"Current webhook registration","operationId":"getWatcherWebhook","parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Getwatcherwebhook"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/watcher_HTTPValidationError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}},"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]}},"/v1/watcher/events":{"get":{"tags":["Events"],"summary":"Event log","description":"Reconciliation fallback: everything the outbox holds for this org,\noldest first, so a consumer who missed webhooks can catch up by id.","operationId":"listWatcherEvents","parameters":[{"name":"x-request-id","in":"header","required":false,"description":"Correlation id echoed to the upstream service and returned on the response. Generated as `req_` when omitted.","schema":{"type":"string"}},{"name":"after","in":"query","required":false,"schema":{"type":["string","null"],"title":"After"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Listwatcherevents"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"401":{"description":"**UnauthenticatedError** — No credential was presented, or the credential is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"UnauthenticatedError":{"summary":"UnauthenticatedError","value":{"error":{"code":"UnauthenticatedError","message":"Authentication required."}}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/watcher_HTTPValidationError"}}},"headers":{"x-request-id":{"description":"Correlation id for this request. Quote it in support requests.","schema":{"type":"string"}}}},"502":{"description":"**BadGatewayError** — The upstream service returned an unusable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"BadGatewayError":{"summary":"BadGatewayError","value":{"error":{"code":"BadGatewayError","message":"An internal error occurred."}}}}}}},"503":{"description":"**ServiceUnavailableError** — The upstream service was unreachable or exceeded the gateway request timeout.\n\n**PlatformUnavailableError** — Credential verification was unavailable. Never returned for a bad key — an outage is not a rejection, so retry rather than re-issuing the key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"},"examples":{"ServiceUnavailableError":{"summary":"ServiceUnavailableError","value":{"error":{"code":"ServiceUnavailableError","message":"An internal error occurred."}}},"PlatformUnavailableError":{"summary":"PlatformUnavailableError","value":{"error":{"code":"PlatformUnavailableError","message":"An internal error occurred."}}}}}}}},"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]}}},"components":{"schemas":{"GatewayError":{"type":"object","title":"GatewayError","description":"Error envelope returned by the gateway itself.","required":["error"],"additionalProperties":false,"properties":{"error":{"type":"object","required":["code","message"],"additionalProperties":false,"properties":{"code":{"type":"string","enum":["UnauthenticatedError","BadGatewayError","ServiceUnavailableError","PlatformUnavailableError","internal_error"],"description":"Stable machine-readable cause. Match on this, not on `message`."},"message":{"type":"string","description":"Human-readable detail. Always the generic \"An internal error occurred.\" for 5xx — the specific cause is logged, not returned."}}}}},"hotel_HotelBooking":{"type":"object","properties":{"id":{"type":"string"},"reference_id":{"type":["string","null"]},"status":{"type":"string","enum":["CREATED","PREBOOK_IN_PROGRESS","READY_FOR_COMPLETE","COMPLETE_IN_PROGRESS","CONFIRMED","CANCEL_IN_PROGRESS","PARTIALLY_CANCELED","CANCELED","FAILED","EXPIRED"]},"hotel":{"type":"object","properties":{"id":{"type":["string","null"]},"name":{"type":["string","null"]},"address":{"type":["string","null"]}},"required":["id","name","address"]},"check_in":{"type":"string","format":"date"},"check_out":{"type":"string","format":"date"},"total":{"type":["object","null"],"properties":{"amount":{"type":"number","minimum":0,"description":"Amount in the currency's major units."},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["amount","currency"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"confirmed_at":{"type":["string","null"],"format":"date-time"},"canceled_at":{"type":["string","null"],"format":"date-time"},"payments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["INITIATED","AUTHORIZED","CAPTURED","FAILED","VOIDED"],"description":"The last outcome recorded for this payment, which can trail the money; FAILED is not always a bank decline, and a refund leaves CAPTURED unchanged."},"amount":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"description":"Amount in the currency's major units."},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["amount","currency"]},"payment_method":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["CARD"],"description":"Always CARD; the card's fields sit under card so that other payment method types can be added."},"card":{"type":"object","properties":{"brand":{"type":"string","description":"The card network in uppercase, such as VISA; open text, because a new network can appear."},"last4":{"type":"string","description":"The card's last four digits."},"funding":{"type":"string","enum":["CREDIT","DEBIT","PREPAID","UNKNOWN"],"description":"UNKNOWN when the card network does not state it."},"wallet":{"type":["string","null"],"description":"The wallet the card was used through, in uppercase, such as APPLE_PAY or GOOGLE_PAY; null when none was used."}},"required":["brand","last4","funding","wallet"]}},"required":["type","card"],"description":"The card your traveller paid with; null when none can be shown: the payment has no outcome yet, the payment provider holds no card for it, or the card could not be read in time."},"created_at":{"type":"string","format":"date-time"}},"required":["id","status","amount","payment_method","created_at"]},"description":"Every payment on your booking, oldest first, so a failed attempt can come before the payment that succeeded."},"cancellations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["IN_PROGRESS","SUCCEEDED","PARTIALLY_SUCCEEDED","REJECTED","FAILED"]},"fee":{"type":["object","null"],"properties":{"amount":{"type":"number","minimum":0,"description":"Amount in the currency's major units."},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["amount","currency"],"description":"Your recorded fee for the rooms released by this attempt. Null means the amount is not established, not zero."},"refund":{"type":["object","null"],"properties":{"amount":{"type":"number","minimum":0,"description":"Amount in the currency's major units."},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["amount","currency"],"description":"Your recorded refund intent; this does not confirm payment settlement."},"refund_to":{"type":["array","null"],"items":{"type":"object","properties":{"payment_id":{"type":"string"}},"required":["payment_id"]},"description":"The payments this refund returns to, oldest first; empty when nothing is refunded, and null while the destination is not established."},"created_at":{"type":"string","format":"date-time"},"canceled_at":{"type":["string","null"],"format":"date-time"},"error_code":{"type":["string","null"]}},"required":["id","status","fee","refund","refund_to","created_at","canceled_at","error_code"]}},"hotel_confirmation_code":{"type":["string","null"],"description":"You receive a booking-level hotel confirmation code when supplied. Read each room for room-specific codes; null alone does not mean the reservation failed."},"hotel_remarks":{"type":["array","null"],"items":{"type":"string"}},"offer_expires_at":{"type":["string","null"],"format":"date-time","description":"You must complete a ready booking before this UTC expiry. An elapsed timestamp does not establish failure of an in-progress purchase."},"due_at_property":{"description":"You pay these charges at the property, separately from total. You receive one amount when a common currency is established, or a list for differing room currencies. Null means the total is unknown.","nullable":true,"anyOf":[{"type":"object","properties":{"amount":{"type":"number","minimum":0,"description":"Amount in the currency's major units."},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["amount","currency"]},{"type":"array","items":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"description":"Amount in the currency's major units."},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["amount","currency"]}}]},"cancellation_policy":{"type":["object","null"],"properties":{"version":{"type":"number","enum":[1]},"refundable":{"type":"boolean"},"deadline":{"type":"string","format":"date-time"},"penalties":{"type":"array","items":{"type":"object","properties":{"from":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["AMOUNT"]},"amount":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"description":"Amount in the currency's major units."},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["amount","currency"]},"timezone":{"type":"string"}},"required":["from","type","amount"]}},"restrictions":{"type":"array","items":{"type":"object","properties":{"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"},"timezone":{"type":"string"}},"required":["from","to"]}},"no_show":{"type":"object","properties":{"from":{"type":"string","format":"date-time"},"amount":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"description":"Amount in the currency's major units."},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["amount","currency"]}},"required":["from","amount"]}},"required":["version","refundable","penalties","restrictions"],"description":"You apply these terms to the whole booking once. When null, review individual room policies; missing terms do not establish free cancellation."},"contact":{"type":["object","null"],"properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"}},"required":["first_name","last_name","email","phone"]},"loyalty":{"type":["object","null"],"properties":{"program":{"type":"string","enum":["wyndham_rewards","choice_privileges","marriott_bonvoy","best_western_rewards","world_of_hyatt","hilton_honors","ihg_one_rewards","leaders_club","stash_rewards","omni_select_guest","i_prefer","accor_live_limitless","my_6","jumeirah_one","global_hotel_alliance_discovery","duffel_hotel_group_rewards"]},"membership_number":{"type":"string","description":"Masked to its last four characters."},"member_rate":{"type":"boolean","description":"True when the booked price was only valid for a member of the programme."}},"required":["program","membership_number","member_rate"],"description":"The loyalty membership submitted to the supplier for the lead guest of the first room: what we sent, not what the hotel accepted. The hotel decides whether to credit points. Null when none is recorded for this booking."},"rooms":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"position":{"type":"integer","minimum":0},"name":{"type":["string","null"]},"board":{"type":["string","null"],"enum":["ROOM_ONLY","BREAKFAST","HALF_BOARD","FULL_BOARD","ALL_INCLUSIVE",null]},"board_name":{"type":["string","null"]},"adults":{"type":"integer","exclusiveMinimum":0},"children":{"type":"array","items":{"type":"integer","minimum":0}},"total":{"type":["object","null"],"properties":{"amount":{"type":"number","minimum":0,"description":"Amount in the currency's major units."},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["amount","currency"],"description":"You receive the supplier's separate price for this room over the complete stay, when available. Null does not authorize dividing the booking total equally."},"due_at_property":{"type":["object","null"],"properties":{"amount":{"type":"number","minimum":0,"description":"Amount in the currency's major units."},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["amount","currency"]},"cancellation_policy":{"type":["object","null"],"properties":{"version":{"type":"number","enum":[1]},"refundable":{"type":"boolean"},"deadline":{"type":"string","format":"date-time"},"penalties":{"type":"array","items":{"type":"object","properties":{"from":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["AMOUNT"]},"amount":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"description":"Amount in the currency's major units."},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["amount","currency"]},"timezone":{"type":"string"}},"required":["from","type","amount"]}},"restrictions":{"type":"array","items":{"type":"object","properties":{"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"},"timezone":{"type":"string"}},"required":["from","to"]}},"no_show":{"type":"object","properties":{"from":{"type":"string","format":"date-time"},"amount":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"description":"Amount in the currency's major units."},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["amount","currency"]}},"required":["from","amount"]}},"required":["version","refundable","penalties","restrictions"],"description":"You apply these terms only to this room. Null means no room-level terms are recorded; check the booking-level policy without counting it once per room."},"promotions":{"type":["array","null"],"items":{"$ref":"#/components/schemas/hotel_RoomPromotion"},"description":"Promotions on the rate you booked for this room. The total already includes them. Null when the rate carried none."},"supplier_reference_number":{"type":["string","null"]},"hotel_confirmation_code":{"type":["string","null"]},"canceled_at":{"type":["string","null"],"format":"date-time","description":"You receive the UTC time the room's release was recorded. Null means no release is recorded for this room."},"guests":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"type":{"type":["string","null"],"enum":["ADULT","CHILD",null]},"is_lead":{"type":"boolean"}},"required":["id","first_name","last_name","type","is_lead"]}}},"required":["id","position","name","board","board_name","adults","children","total","due_at_property","cancellation_policy","promotions","supplier_reference_number","hotel_confirmation_code","canceled_at","guests"]}}},"required":["id","reference_id","status","hotel","check_in","check_out","total","created_at","updated_at","confirmed_at","canceled_at","payments","cancellations","hotel_confirmation_code","hotel_remarks","offer_expires_at","due_at_property","cancellation_policy","contact","loyalty","rooms"]},"hotel_RoomPromotion":{"type":"object","properties":{"name":{"type":"string","description":"The supplier's name for the promotion."},"description":{"type":"string","description":"What the promotion gives you, when the supplier's promotion type is one we can describe."},"conditions":{"type":"string","description":"The supplier's own conditions or notes for the promotion, shown as sent so you do not present a conditional benefit as unconditional."}},"required":["name"],"description":"A promotion the supplier applied to a rate. The total already includes it; show it to your traveller for information."},"hotel_HotelBookingSummary":{"type":"object","properties":{"id":{"type":"string"},"reference_id":{"type":["string","null"]},"status":{"type":"string","enum":["CREATED","PREBOOK_IN_PROGRESS","READY_FOR_COMPLETE","COMPLETE_IN_PROGRESS","CONFIRMED","CANCEL_IN_PROGRESS","PARTIALLY_CANCELED","CANCELED","FAILED","EXPIRED"]},"hotel":{"type":"object","properties":{"id":{"type":["string","null"]},"name":{"type":["string","null"]},"address":{"type":["string","null"]}},"required":["id","name","address"]},"check_in":{"type":"string","format":"date"},"check_out":{"type":"string","format":"date"},"total":{"type":["object","null"],"properties":{"amount":{"type":"number","minimum":0,"description":"Amount in the currency's major units."},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["amount","currency"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"confirmed_at":{"type":["string","null"],"format":"date-time"},"canceled_at":{"type":["string","null"],"format":"date-time"},"payments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["INITIATED","AUTHORIZED","CAPTURED","FAILED","VOIDED"],"description":"The last outcome recorded for this payment, which can trail the money; FAILED is not always a bank decline, and a refund leaves CAPTURED unchanged."},"amount":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"description":"Amount in the currency's major units."},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["amount","currency"]},"created_at":{"type":"string","format":"date-time"}},"required":["id","status","amount","created_at"]},"description":"Every payment on your booking, oldest first, without its card; read the booking by ID for the card."}},"required":["id","reference_id","status","hotel","check_in","check_out","total","created_at","updated_at","confirmed_at","canceled_at","payments"]},"hotel_HotelError":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["validation_error","unauthorized","not_found","conflict","unprocessable","supplier_unavailable","internal_error"]},"reason":{"type":"string","enum":["offer_expired","cursor_expired","price_changed","guest_mismatch","stay_changed","cancellation_restricted","geo_required","city_required","manual_review_required","payment_method_unsupported","cancellation_policy_unsupported","cancellation_not_quotable","refund_not_cash","payment_failed","supplier_operation_unsupported","booking_incomplete","supplier_rejected","loyalty_membership_rejected","supplier_unreachable","supplier_rate_limited","result_unknown"]},"message":{"type":"string"},"request_id":{"type":"string"},"details":{}},"required":["code","message","request_id"]}},"required":["error"]},"hotel_HotelContent":{"type":"object","properties":{"hotel_id":{"type":"string"},"name":{"type":["string","null"]},"description":{"type":["string","null"]},"chain":{"type":["string","null"]},"star_rating":{"type":["number","null"]},"guest_rating":{"type":["number","null"]},"review_count":{"type":["integer","null"]},"address":{"type":["string","null"]},"city":{"type":["string","null"]},"country":{"type":["string","null"]},"zip":{"type":["string","null"]},"latitude":{"type":["number","null"]},"longitude":{"type":["number","null"]},"main_photo":{"type":["string","null"]},"thumbnail":{"type":["string","null"]},"phone":{"type":["string","null"]},"email":{"type":["string","null"]},"time_zone":{"type":["string","null"]},"check_in_start":{"type":["string","null"]},"check_in_end":{"type":["string","null"]},"check_out":{"type":["string","null"]},"important_information":{"type":["string","null"]},"pets_allowed":{"type":["boolean","null"]},"child_allowed":{"type":["boolean","null"]},"parking":{"type":["string","null"]},"amenities":{"type":["array","null"],"items":{"type":"string"}},"images":{"type":["array","null"],"items":{"type":"object","properties":{"url":{"type":"string"},"hd_url":{"type":"string"},"caption":{"type":"string"},"order":{"type":"number"},"is_default":{"type":"boolean"}},"required":["url"]}},"rooms":{"type":["array","null"],"items":{"type":"object","properties":{"name":{"type":"string"},"photos":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"hd_url":{"type":"string"},"caption":{"type":"string"},"order":{"type":"number"},"is_default":{"type":"boolean"}},"required":["url"]}}},"required":["photos"]},"description":"The property's room types with their photos, where the supplier publishes them. Not available from Duffel, whose room photos come only on its offers as `room_photos`."},"policies":{"type":["array","null"],"items":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"}}}},"points_of_interest":{"type":["array","null"],"items":{"type":"object","properties":{"name":{"type":"string"},"category":{"type":"string"},"distance_km":{"type":"number"},"importance":{"type":"string"}},"required":["name"]}},"sentiment":{"type":["object","null"],"properties":{"categories":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"rating":{"type":"number"},"description":{"type":"string"}},"required":["name"]}},"pros":{"type":"array","items":{"type":"string"}},"cons":{"type":"array","items":{"type":"string"}}}},"reviews":{"type":["array","null"],"items":{"type":"object","properties":{"score":{"type":"number"},"headline":{"type":"string"},"pros":{"type":"string"},"cons":{"type":"string"},"date":{"type":"string"},"language":{"type":"string"},"traveler_type":{"type":"string"},"country":{"type":"string"},"source":{"type":"string"}}}}},"required":["hotel_id","name","description","chain","star_rating","guest_rating","review_count","address","city","country","zip","latitude","longitude","main_photo","thumbnail","phone","email","time_zone","check_in_start","check_in_end","check_out","important_information","pets_allowed","child_allowed","parking","amenities","images","rooms","policies","points_of_interest","sentiment","reviews"]},"hotel_HotelWebhookSubscription":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"event_types":{"type":"array","items":{"type":"string","enum":["hotel.booking.confirmed","hotel.booking.failed","hotel.booking.canceled","hotel.booking.partially_canceled","hotel.booking.cancel_failed"]}},"status":{"type":"string","enum":["ACTIVE","PAUSED"]},"previous_secret_expires_at":{"type":["string","null"],"format":"date-time","description":"Until then, your requests also carry a signature made with your previous secret."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","url","event_types","status","previous_secret_expires_at","created_at","updated_at"]},"hotel_HotelWebhookSubscriptionWithSecret":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"event_types":{"type":"array","items":{"type":"string","enum":["hotel.booking.confirmed","hotel.booking.failed","hotel.booking.canceled","hotel.booking.partially_canceled","hotel.booking.cancel_failed"]}},"status":{"type":"string","enum":["ACTIVE","PAUSED"]},"previous_secret_expires_at":{"type":["string","null"],"format":"date-time","description":"Until then, your requests also carry a signature made with your previous secret."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"signing_secret":{"type":"string","description":"Your signing secret. You receive it only in this response; store it on your server."}},"required":["id","url","event_types","status","previous_secret_expires_at","created_at","updated_at","signing_secret"]},"hotel_HotelWebhookEvent":{"type":"object","properties":{"id":{"type":"string","description":"The event ID, also sent as x-oex-event-id. Use it to ignore repeats."},"type":{"type":"string","enum":["hotel.booking.confirmed","hotel.booking.failed","hotel.booking.canceled","hotel.booking.partially_canceled","hotel.booking.cancel_failed"]},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"booking":{"type":"object","properties":{"id":{"type":"string"},"reference_id":{"type":["string","null"]},"status":{"type":"string","enum":["CREATED","PREBOOK_IN_PROGRESS","READY_FOR_COMPLETE","COMPLETE_IN_PROGRESS","CONFIRMED","CANCEL_IN_PROGRESS","PARTIALLY_CANCELED","CANCELED","FAILED","EXPIRED"]},"hotel":{"type":"object","properties":{"id":{"type":["string","null"]},"name":{"type":["string","null"]},"address":{"type":["string","null"]}},"required":["id","name","address"]},"check_in":{"type":"string","format":"date"},"check_out":{"type":"string","format":"date"},"total":{"type":["object","null"],"properties":{"amount":{"type":"number","minimum":0,"description":"Amount in the currency's major units."},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["amount","currency"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"confirmed_at":{"type":["string","null"],"format":"date-time"},"canceled_at":{"type":["string","null"],"format":"date-time"},"version":{"type":"integer","description":"Increases with every change to the booking; keep the highest you have seen for each booking."},"user_id":{"type":"string","description":"The user that owns the booking."}},"required":["id","reference_id","status","hotel","check_in","check_out","total","created_at","updated_at","confirmed_at","canceled_at","version","user_id"]}},"required":["booking"]}},"required":["id","type","created_at","data"]},"hotel_HotelWebhookDelivery":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["PENDING","PUBLISHED","DELIVERED","FAILED"],"description":"PENDING: queueing is not confirmed; the request may already be on its way. PUBLISHED: queued for your endpoint. DELIVERED: your endpoint answered 2xx. FAILED: see failure_reason."},"event":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"created_at":{"type":"string"},"data":{"type":"object","properties":{"booking":{"type":"object","additionalProperties":{}}},"required":["booking"]}},"required":["id","type","created_at","data"],"description":"The event body as it was sent to your endpoint; HotelWebhookEvent describes its fields."},"replay_count":{"type":"integer","description":"How many times you replayed this delivery."},"failure_reason":{"type":["string","null"],"enum":["retries_exhausted","publish_rejected","subscription_paused",null],"description":"retries_exhausted: your endpoint never answered 2xx. publish_rejected: the delivery could not be queued for your URL. subscription_paused: your subscription was paused before the delivery was queued."},"attempts":{"type":"array","items":{"type":"object","properties":{"attempt_number":{"type":"integer","description":"1 for the first request, then one per retry."},"response_status":{"type":["integer","null"],"description":"Your endpoint's HTTP status; null when it gave no response."},"response_body":{"type":["string","null"],"description":"The first 500 characters of your endpoint's response body."},"created_at":{"type":"string","format":"date-time"}},"required":["attempt_number","response_status","response_body","created_at"]},"description":"Your endpoint's responses for the current replay, in order."},"created_at":{"type":"string","format":"date-time"},"published_at":{"type":["string","null"],"format":"date-time"},"delivered_at":{"type":["string","null"],"format":"date-time"},"failed_at":{"type":["string","null"],"format":"date-time"}},"required":["id","status","event","replay_count","failure_reason","attempts","created_at","published_at","delivered_at","failed_at"]},"hotel_HotelOfferRoom":{"type":"object","properties":{"position":{"type":"integer","minimum":0,"description":"Your room's 0-based position in the requested occupancy array. Keep this order at prebook."},"adults":{"type":"integer","minimum":1,"maximum":20},"children":{"type":"array","items":{"type":"integer","minimum":0,"maximum":17},"maxItems":10,"default":[]},"room_type":{"type":"string"},"room_photos":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"hd_url":{"type":"string"},"caption":{"type":"string"},"order":{"type":"number"},"is_default":{"type":"boolean"}},"required":["url"]},"maxItems":1,"description":"One preview photo for this room where available. You can read property room galleries from Hotel Content."},"board":{"type":"string","description":"You receive the board as each supplier states it, so values differ between suppliers: WebBeds sends ROOM_ONLY, BREAKFAST, HALF_BOARD, FULL_BOARD or ALL_INCLUSIVE, while LiteAPI and Duffel send their own wording. Your booking's rooms carry one of those five values when the board is recognized."},"refundable":{"type":"boolean"},"cancellation_policy":{"type":"object","properties":{"version":{"type":"number","enum":[1]},"refundable":{"type":"boolean"},"deadline":{"type":"string","format":"date-time"},"penalties":{"type":"array","items":{"type":"object","properties":{"from":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["AMOUNT"]},"amount":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"description":"Amount in the currency's major units."},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["amount","currency"]},"timezone":{"type":"string"}},"required":["from","type","amount"]}},"restrictions":{"type":"array","items":{"type":"object","properties":{"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"},"timezone":{"type":"string"}},"required":["from","to"]}},"no_show":{"type":"object","properties":{"from":{"type":"string","format":"date-time"},"amount":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"description":"Amount in the currency's major units."},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["amount","currency"]}},"required":["from","amount"]}},"required":["version","refundable","penalties","restrictions"],"description":"Cancellation terms for this room only. Omitted when no readable room-level policy is supplied. Whole-offer terms stay on the offer and must not be counted once per room."}},"required":["position","adults"]},"hotel_TaxOrFee":{"type":"object","properties":{"description":{"type":"string","description":"The line's label: the supplier's own wording where it labels its lines, otherwise the kind of charge, `Taxes`, `Fees` or `Due at accommodation`."},"amount":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"description":"Amount in the currency's major units."},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["amount","currency"],"description":"The line's amount for the whole stay."},"included":{"type":"boolean","description":"`true`: inside `total`, paid when you book. `false`: collected by the property, outside `total`; these lines add up to `due_at_property`."}},"required":["amount","included"],"description":"One itemised tax or fee on an offer, as the supplier reports it."},"hotel_OfferPromotion":{"type":"object","properties":{"name":{"type":"string","description":"The supplier's name for the promotion."},"description":{"type":"string","description":"What the promotion gives you, when the supplier's promotion type is one we can describe."},"conditions":{"type":"string","description":"The supplier's own conditions or notes for the promotion, shown as sent so you do not present a conditional benefit as unconditional."},"room_positions":{"type":"array","items":{"type":"integer","minimum":0},"minItems":1,"description":"The 0-based positions, in your occupancy order, of the rooms whose rate carries this promotion."}},"required":["name","room_positions"],"description":"A promotion on the rates in an offer and the rooms it applies to. The total already includes it."},"hotel_HotelSupplierCapabilities":{"type":"object","properties":{"supplier":{"type":"string","enum":["LITEAPI","WEBBEDS","DUFFEL"]},"operations":{"type":"array","items":{"type":"string","enum":["search","offers","content","price_calendar","prebook","book","cancel"]},"description":"You can use these supplier-backed hotel operations. Shared place lookup and booking weather are separate service features."},"limits":{"type":"object","properties":{"max_offer_hotels":{"type":"integer","exclusiveMinimum":0,"description":"You can send at most this many hotel IDs in one offers request for this supplier. The total offer-count limit also applies."},"max_rooms":{"type":"integer","exclusiveMinimum":0,"description":"You can request up to this many room occupancies for one stay."},"max_child_age":{"type":"integer","minimum":0,"description":"You can include children up to this age in whole years, inclusive."}},"required":["max_offer_hotels","max_rooms","max_child_age"]},"requires_named_adults":{"type":"boolean","description":"When true, you must name every adult at prebook and specify each guest's type. You always name one adult lead per room."},"cancellation_may_partially_succeed":{"type":"boolean","description":"When true, your whole-booking cancellation can leave some rooms confirmed and others canceled. You cannot select rooms to cancel; read the booking's room outcomes."}},"required":["supplier","operations","limits","requires_named_adults","cancellation_may_partially_succeed"]},"flight_Money":{"type":"object","properties":{"amount":{"type":"number","description":"In major units of `currency` — `506.73` is five hundred and six dollars and seventy-three cents.","examples":[506.73]},"currency":{"type":"string","description":"ISO 4217 code.","examples":["USD"]}},"required":["amount","currency"],"description":"A money value in major units. Every amount in a response has this shape."},"flight_Baggage":{"type":"object","properties":{"type":{"type":"string","enum":["CHECKED","CARRY_ON"],"description":"Checked into the hold, or carried into the cabin.","examples":["CHECKED"]},"max_weight_kg":{"type":"number","description":"The airline's weight limit per bag, when it states one.","examples":[23]}},"required":["type"],"description":"What one bag allows."},"flight_FareConditions":{"type":"object","properties":{"refund":{"type":"object","properties":{"allowed":{"type":"boolean","description":"Whether the airline allows it on this fare.","examples":[true]},"penalty":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"What the airline charges, when it states an amount. Omitted does not mean free.","examples":[{"amount":75,"currency":"USD"}]}]}},"required":["allowed"],"description":"Cancelling for a refund before departure. Omitted when the airline publishes no refund terms; omission is not `allowed: false`."},"change":{"type":"object","properties":{"allowed":{"type":"boolean","description":"Whether the airline allows it on this fare.","examples":[true]},"penalty":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"What the airline charges, when it states an amount. Omitted does not mean free.","examples":[{"amount":75,"currency":"USD"}]}]}},"required":["allowed"],"description":"Changing the flights before departure. Omitted when the airline publishes no change terms; omission is not `allowed: false`."}},"description":"The fare's refund and change terms as the airline publishes them. Check them again on the booking: they can change before prebook."},"flight_BookingStatus":{"type":"string","enum":["CREATED","PREBOOK_IN_PROGRESS","READY_FOR_COMPLETE","COMPLETE_IN_PROGRESS","CONFIRMED","CANCEL_IN_PROGRESS","CANCELED","FAILED","EXPIRED"],"description":"Where the booking is in its lifecycle. `CREATED`, `PREBOOK_IN_PROGRESS`, `READY_FOR_COMPLETE`, `COMPLETE_IN_PROGRESS`, `CONFIRMED`, and `CANCEL_IN_PROGRESS` can still move. `CANCELED`, `FAILED` and `EXPIRED` are final. You will only see the first two when a prebook is repeated after its first attempt was interrupted.","x-enum-descriptions":{"CREATED":"The booking was written but the supplier had not yet been asked for the hold. You only see this when a prebook was interrupted before the hold. The idempotency key is spent, so prebook again with a new one; for Duffel, search again first, because this booking keeps its offer.","PREBOOK_IN_PROGRESS":"You cannot book while the prebook outcome is unknown. Replay the same key to read the stored state. For Duffel, search again before another prebook, because this booking keeps its offer; for LiteAPI, contact support before creating another checkout because an airline hold may exist.","READY_FOR_COMPLETE":"You can complete this prebook. On LiteAPI the traveller may already have paid in checkout; this status does not establish payment status.","COMPLETE_IN_PROGRESS":"Re-read your booking because ticketing is running or unresolved. For Duffel, contact support before another book. For LiteAPI, keep the booking id and contact support before another book request because the supplier may already have issued the ticket.","CONFIRMED":"Confirmed by the supplier. Payment capture can still require reconciliation.","CANCEL_IN_PROGRESS":"A cancel is running, or one ended without a known result. Retrying the cancel resumes it.","CANCELED":"Your ticket is released. Read `cancellation.refunded_by` for refund responsibility and `refund_amount` for the intended amount; neither confirms settlement.","EXPIRED":"Your bound offer expired. For LiteAPI, contact support before replacing the checkout because your traveller may already have paid.","FAILED":"Read `failure` for the refused operation. On LiteAPI, your traveller may already have paid; contact support before starting another checkout."}},"flight_BookingCancellation":{"type":"object","properties":{"fee":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"What the supplier kept. Zero means no fee; omitted means unknown.","examples":[{"amount":95,"currency":"USD"}]}]},"refunded_by":{"type":"string","enum":["OEX","SUPPLIER"],"description":"You receive the refund from this merchant, as recorded on your payments. Responsibility does not confirm settlement; omitted when no payment is recorded.","examples":["SUPPLIER"]},"refund_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"The intended refund after the cancellation fee, not confirmation of settlement. Zero means no refund is due; omitted means the amount needs review.","examples":[{"amount":286.14,"currency":"USD"}]}]},"refund_to":{"type":"array","items":{"type":"object","properties":{"payment_id":{"type":"string","description":"One of the `id` values in the booking's `payments`.","examples":["pay_0192f3a4b5c64d7e8f9a0b1c2d3e4f61"]}},"required":["payment_id"]},"description":"The payments the refund returns to, oldest first, each to its original payment method, their cards where known in `payments`; empty when nothing is refunded, and omitted while the refund is not established.","examples":[[{"payment_id":"pay_0192f3a4b5c64d7e8f9a0b1c2d3e4f61"}]]}},"description":"What cancelling this booking did. Present once `status` is `CANCELED`."},"flight_PaymentSdkInit":{"oneOf":[{"type":"object","properties":{"provider":{"type":"string","enum":["oex"],"description":"You use the OEX Payment SDK for this checkout."},"token":{"type":"string","minLength":1,"description":"Pass this opaque token to the OEX Payment SDK; do not store or log it."}},"required":["provider","token"]},{"type":"object","properties":{"provider":{"type":"string","enum":["liteapi"],"description":"You use LiteAPI checkout because LiteAPI collects the payment."},"token":{"type":"string","minLength":1,"description":"Pass this token as LiteAPIPayment secretKey; do not store or log it."},"environment":{"type":"string","enum":["sandbox","live"],"description":"Use this as LiteAPIPayment publicKey so checkout matches the payment environment."}},"required":["provider","token","environment"]}],"description":"Choose your checkout SDK using provider. You receive this metadata on a fresh SDK prebook, or a validated LiteAPI replay while ready to book. You never receive it on get, list or book."},"flight_PrebookMeta":{"type":"object","properties":{"payment_sdk":{"$ref":"#/components/schemas/flight_PaymentSdkInit"}},"required":["payment_sdk"],"description":"Use this metadata to initialize checkout. You may receive it on a 201 SDK prebook or a 200 LiteAPI replay after its stored references and price are checked; OEX replay omits it."},"flight_BookRequest":{"type":"object","properties":{"payment_instrument_id":{"type":"string","minLength":1,"description":"Send your saved instrument for a Duffel booking without SDK checkout. Omit it for either SDK provider and for every LiteAPI booking, because mixing payment methods returns 422.","examples":["pi_01J8Z6Q0M6RVW4B9Z8N3XK2T7A"]}},"additionalProperties":false,"description":"For Duffel, send your saved payment_instrument_id or an empty object after OEX SDK checkout. For LiteAPI, send an empty object after its checkout, because the supplier collects payment."},"flight_Pagination":{"type":"object","properties":{"limit":{"type":"number","description":"The page size applied — your request's, or the default.","examples":[20]},"offset":{"type":"number","description":"Rows skipped to reach this page.","examples":[0]},"has_more":{"type":"boolean","description":"Whether another page exists after this one. Exact — a full page on its own does not imply more.","examples":[false]},"total":{"type":"number","description":"Every row matching your filters, not just this page.","examples":[2]}},"required":["limit","offset","has_more","total"],"description":"Where this page sits in the full result, including the total count matching your filters."},"flight_ListMeta":{"type":"object","properties":{"pagination":{"$ref":"#/components/schemas/flight_Pagination"}},"required":["pagination"],"description":"Everything about a list response that is not a row."},"flight_JourneyDirection":{"type":"string","enum":["OUTBOUND","INBOUND"],"description":"Which way a journey goes. Present only on one-way and return itineraries; on multi-city it is omitted, and that omission is the signal.","x-enum-descriptions":{"OUTBOUND":"Away from the origin.","INBOUND":"Back to the origin."}},"flight_TimeWindow":{"type":"object","properties":{"from":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$","description":"Earliest time, inclusive.","examples":["06:00"]},"to":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$","description":"Latest time, inclusive. Earlier than `from` means the window runs past midnight.","examples":["12:00"]}},"additionalProperties":false,"description":"A window of airport local time, `HH:MM`. A fare whose time the airline does not state is kept."},"flight_JourneySpec":{"type":"object","properties":{"origin":{"type":"string","minLength":3,"maxLength":3,"description":"IATA airport or city code to depart from.","examples":["LHR"]},"destination":{"type":"string","minLength":3,"maxLength":3,"description":"IATA airport or city code to arrive at.","examples":["CDG"]},"date":{"type":"string","format":"date","description":"Departure date, `YYYY-MM-DD`, in the origin's local calendar.","examples":["2026-11-10"]},"direction":{"allOf":[{"$ref":"#/components/schemas/flight_JourneyDirection"},{"description":"Optional; derived when omitted — the first journey outbound, the second inbound."}]},"departure_time":{"allOf":[{"$ref":"#/components/schemas/flight_TimeWindow"},{"description":"Keep fares whose journey departs in this window."}]},"arrival_time":{"allOf":[{"$ref":"#/components/schemas/flight_TimeWindow"},{"description":"Keep fares whose journey arrives in this window."}]}},"required":["origin","destination","date"],"description":"One directional part of the trip you want priced."},"flight_FlightPassengers":{"type":"object","properties":{"adults":{"type":"integer","minimum":1,"description":"Passengers aged 12 or over, at least 1.","examples":[1]},"children":{"type":"integer","minimum":0,"description":"Passengers aged 2–11. Send `children_ages` too.","examples":[1]},"infants":{"type":"integer","minimum":0,"description":"Passengers under 2. Send `infant_ages` too.","examples":[0]},"children_ages":{"type":"array","items":{"type":"integer","minimum":2,"maximum":11},"description":"One age per child, in years.","examples":[[9]]},"infant_ages":{"type":"array","items":{"type":"integer","minimum":0,"maximum":1},"description":"One age per infant, in years (0 or 1).","examples":[[1]]}},"required":["adults"],"description":"Who is travelling. Ages are required for anyone who is not an adult, because fares depend on them."},"flight_FlightFilters":{"type":"object","properties":{"max_stops":{"type":"integer","minimum":0,"maximum":2,"description":"Maximum connections per journey, 0–2. Applied to each journey — `1` means at most one stop each way.","examples":[1]},"max_duration_minutes":{"type":"integer","exclusiveMinimum":0,"description":"Longest total itinerary duration to return.","examples":[720]},"airlines":{"type":"array","items":{"type":"string","pattern":"^[A-Za-z0-9]{2}$"},"minItems":1,"description":"Keep fares where every flight is sold by one of these airlines (IATA codes, matched on `marketing_carrier_code`).","examples":[["BA","AA"]]},"exclude_airlines":{"type":"array","items":{"type":"string","pattern":"^[A-Za-z0-9]{2}$"},"minItems":1,"description":"Drop fares where any flight is sold by one of these airlines.","examples":[["FR"]]},"price":{"type":"object","properties":{"min":{"type":"number","minimum":0,"description":"Lowest `total_amount`, inclusive.","examples":[100]},"max":{"type":"number","minimum":0,"description":"Highest `total_amount`, inclusive.","examples":[500]}},"additionalProperties":false,"description":"Range of `total_amount` in major units of the request `currency`. When a fare is priced in another currency it cannot be compared, and `price` is listed in `meta.unsupported_filters`."},"refundable_only":{"type":"boolean","description":"Keep only fares the airline states are refundable before departure. A fare with unknown refund terms is dropped.","examples":[true]},"changeable_only":{"type":"boolean","description":"Keep only fares the airline states can be changed before departure. A fare with unknown change terms is dropped.","examples":[true]},"checked_bag_included":{"type":"boolean","description":"Keep only fares that include at least one checked bag for every passenger except infants on every flight. A fare with unknown allowances is dropped.","examples":[true]}},"additionalProperties":false,"description":"Narrow the fares. Only the fields listed here are accepted; anything else is a `400`. Every filter holds whichever supplier answers. A filter that cannot be checked for some fares is listed in `meta.unsupported_filters`, and those fares are not narrowed by it. A fare whose duration, airline or cabin the airline does not state is kept by those filters; `refundable_only`, `changeable_only` and `checked_bag_included` drop such a fare."},"flight_FlightSort":{"type":"object","properties":{"sort_by":{"type":"string","enum":["price","duration","departure","arrival","stops"],"description":"What to order by.","x-enum-descriptions":{"price":"By `total_amount`.","duration":"By `total_duration_minutes`.","departure":"By first departure time.","arrival":"By final arrival time.","stops":"By the most stops on any journey."},"examples":["price"]},"sort_order":{"type":"string","enum":["asc","desc"],"description":"Ascending or descending.","examples":["asc"]}},"required":["sort_by","sort_order"],"description":"Order of the returned fares. The default is price ascending."},"flight_CabinClass":{"type":"string","enum":["ECONOMY","PREMIUM_ECONOMY","BUSINESS","FIRST"],"description":"A cabin of service.","x-enum-descriptions":{"ECONOMY":"Economy.","PREMIUM_ECONOMY":"Premium economy.","BUSINESS":"Business.","FIRST":"First."}},"flight_FlightOffersRequest":{"type":"object","properties":{"supplier":{"type":"string","enum":["LITEAPI","DUFFEL"],"description":"Choose the supplier that prices your fares. Omit to use routing rules, falling back to Duffel when no rule matches. LiteAPI bookings use its payment checkout; set `use_payment_sdk: true` when prebooking.","examples":["DUFFEL"]},"journeys":{"type":"array","items":{"$ref":"#/components/schemas/flight_JourneySpec"},"minItems":1,"description":"One entry for a one-way, two for a return, three or more for multi-city."},"passengers":{"$ref":"#/components/schemas/flight_FlightPassengers"},"currency":{"type":"string","minLength":3,"maxLength":3,"default":"USD","description":"ISO 4217 code to price in. Defaults to `USD`. Some suppliers price in a fixed currency regardless — read `total_amount.currency`.","examples":["USD"]},"country":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2 point of sale, where the supplier uses one.","examples":["GB"]},"cabin_class":{"allOf":[{"$ref":"#/components/schemas/flight_CabinClass"},{"description":"The cabin to price. Every flight of a returned fare is in this cabin; mixed-cabin fares are dropped. Omit for any."}]},"filters":{"$ref":"#/components/schemas/flight_FlightFilters"},"sort":{"$ref":"#/components/schemas/flight_FlightSort"},"limit":{"type":"integer","minimum":1,"maximum":199,"default":100,"description":"Maximum fares to return, default 100, max 199. When more matched, `meta.truncated` is present.","examples":[20]}},"required":["journeys","passengers"],"description":"The itinerary as journeys, the party, and how to narrow and order the fares."},"flight_Segment":{"type":"object","properties":{"origin":{"type":"string","description":"IATA code.","examples":["LHR"]},"destination":{"type":"string","description":"IATA code.","examples":["CDG"]},"departure_time":{"type":"string","description":"Local time at the origin airport, no offset.","examples":["2026-11-10T06:58:00"]},"arrival_time":{"type":"string","description":"Local time at the destination airport, no offset.","examples":["2026-11-10T09:15:00"]},"marketing_flight":{"type":"string","description":"Carrier code plus unpadded number.","examples":["AF1681"]},"marketing_carrier":{"type":"string","description":"The name of the airline selling the seat, whose code is on `marketing_flight`. You receive the code here when no name is known.","examples":["Air France"]},"marketing_carrier_code":{"type":"string","description":"IATA code of the airline selling the seat. Use it for `filters.airlines`.","examples":["AF"]},"marketing_carrier_logo_url":{"type":"string","description":"Hosted by the supplier, not by us, and not guaranteed past the offer. Omitted for airlines the supplier has no logo for — a large minority — so always have a fallback.","examples":["https://assets.duffel.com/img/airlines/for-light-background/full-color-logo/AF.svg"]},"operating_carrier":{"type":"string","description":"The airline flying this segment, present only when it differs from `marketing_carrier`. Its presence means a codeshare; show it, so the passenger goes to the right desk.","examples":["KLM"]},"operating_carrier_logo_url":{"type":"string","description":"As `marketing_carrier_logo_url`, for the operating carrier.","examples":["https://assets.duffel.com/img/airlines/for-light-background/full-color-logo/KL.svg"]},"cabin_class":{"allOf":[{"$ref":"#/components/schemas/flight_CabinClass"},{"description":"The cabin of this flight, when the supplier states one cabin for its passengers. Omitted when it states none, or different cabins for different passengers."}]},"duration_minutes":{"type":"number","description":"Gate to gate.","examples":[137]}},"description":"One flight, gate to gate."},"flight_Journey":{"type":"object","properties":{"origin":{"type":"string","description":"IATA code of the first departure.","examples":["LHR"]},"destination":{"type":"string","description":"IATA code of the final arrival.","examples":["CDG"]},"direction":{"$ref":"#/components/schemas/flight_JourneyDirection"},"departure_time":{"type":"string","description":"First departure, local time at the origin airport, no offset.","examples":["2026-11-10T06:58:00"]},"arrival_time":{"type":"string","description":"Final arrival, local time at the destination airport, no offset.","examples":["2026-11-10T09:15:00"]},"duration_minutes":{"type":"number","description":"Flying plus connecting time within this journey.","examples":[137]},"stops":{"type":"number","description":"Connection points within this journey (`segments.length - 1`), never a trip-wide sum. Same unit as the `max_stops` filter, so `max_stops: 1` reads back as `stops: 1` on each journey.","examples":[0]},"segments":{"type":"array","items":{"$ref":"#/components/schemas/flight_Segment"},"description":"The flights of this journey, in order. Two or more segments means a connection."}},"required":["stops","segments"],"description":"One directional part of the itinerary — the outbound, the return, or one hop of a multi-city trip. Segments within a journey are connections."},"flight_FlightOffer":{"type":"object","properties":{"offer_reference":{"type":"string","description":"Opaque signed token identifying this fare. Pass it unchanged to create a booking; never parse or build one. Expires at `expires_at`.","examples":["eyJzdXBwbGllciI6ImR1ZmZlbCIsIm9mZmVyIjoib2ZmXzAwMDBC…"]},"total_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"What we charge for the whole party, all journeys.","examples":[{"amount":220.67,"currency":"USD"}]}]},"expires_at":{"type":"string","description":"When this reference stops being accepted. Flight offers are short-lived — create the booking promptly.","examples":["2026-11-01T12:34:56.000Z"]},"fare_family":{"type":"string","description":"The airline's brand name for this fare, when it publishes one.","examples":["Basic"]},"refundable":{"type":"boolean","description":"Whether the fare can be cancelled for less than its full price. Omitted when the airline publishes no refund terms — which is common — and omission is not `false`.","examples":[false]},"fare_conditions":{"$ref":"#/components/schemas/flight_FareConditions"},"documents_required":{"type":"boolean","description":"Whether every passenger needs an identity `document` at prebook. When `false`, such as on many US domestic fares, you may omit it.","examples":[false]},"included_baggage":{"type":"object","properties":{"checked":{"type":"boolean","description":"Whether every passenger except infants has at least one checked bag on every flight.","examples":[true]},"carry_on":{"type":"boolean","description":"Whether every passenger except infants has at least one carry-on bag on every flight.","examples":[true]}},"description":"Bags the fare includes. Omitted, or a field omitted, when the airline does not state it."},"journeys":{"type":"array","items":{"$ref":"#/components/schemas/flight_Journey"},"description":"In travel order."},"total_duration_minutes":{"type":"number","description":"Sum of the journeys' durations. Excludes time between journeys.","examples":[274]}},"required":["offer_reference","total_amount","documents_required","journeys"],"description":"One fare for the whole itinerary. Fares on the same flights are separate offers with identical `journeys`."},"flight_FlightOffersMeta":{"type":"object","properties":{"supplier":{"type":"string","description":"Which supplier priced these offers. Always present.","examples":["DUFFEL"]},"truncated":{"type":"boolean","description":"Present only when results were cut at `limit`, or when filters were applied to a supplier page that had more fares beyond it. There is no way to fetch the remainder — raise `limit` (max 199) or narrow the search.","examples":[true]},"unsupported_filters":{"type":"array","items":{"type":"string"},"description":"Filters that could not be checked for some fares, such as `price` on a fare in another currency, or `max_stops` and journey time windows on a multi-city fare whose legs the supplier grouped. Those fares are not narrowed by them.","examples":[["price"]]}},"required":["supplier"],"description":"Everything about the offers response that is not a fare."},"flight_FlightPassengerSlot":{"type":"object","properties":{"type":{"type":"string","enum":["ADULT","CHILD","INFANT"]},"number":{"type":"integer","minimum":1}},"required":["type","number"],"description":"Which traveller an extra is for: the Nth passenger of this type in your prebook `passengers`, counting from 1.","examples":[{"type":"ADULT","number":1}]},"flight_FlightOfferService":{"type":"object","properties":{"id":{"type":"string","description":"Send this id in the prebook request's `services`.","examples":["ase_00009UhD4ongolulWd9123"]},"type":{"type":"string","enum":["BAGGAGE"]},"baggage":{"$ref":"#/components/schemas/flight_Baggage"},"passenger":{"$ref":"#/components/schemas/flight_FlightPassengerSlot"},"segments":{"type":"array","items":{"type":"object","properties":{"journey":{"type":"integer"},"segment":{"type":"integer"}},"required":["journey","segment"]},"description":"The flights the bag covers, as positions in the offer's `journeys[].segments[]`, from 0."},"maximum_quantity":{"type":"integer","minimum":1},"unit_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"Price for one bag. Prebook re-checks it with the airline; the booking shows what was charged.","examples":[{"amount":40,"currency":"USD"}]}]}},"required":["id","type","baggage","passenger","segments","maximum_quantity","unit_amount"],"description":"A bag the traveller can add before prebook."},"flight_FlightSeatService":{"type":"object","properties":{"id":{"type":"string","description":"Send this id in the prebook request's `services` with `quantity: 1` to give this passenger this seat.","examples":["ase_00009UhD4ongolulWAAA1A"]},"passenger":{"$ref":"#/components/schemas/flight_FlightPassengerSlot"},"unit_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"This passenger's price for the seat; 0 when the airline sells it free. Prebook re-checks it with the airline.","examples":[{"amount":30,"currency":"USD"}]}]}},"required":["id","passenger","unit_amount"],"description":"One passenger's option to take this seat."},"flight_FlightSeatMapElement":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["SEAT"]},"designator":{"type":"string","description":"The airline's label for the seat.","examples":["12A"]},"disclosures":{"type":"array","items":{"type":"string"},"description":"The airline's conditions for this seat, in its words, for you to show.","examples":[["Passenger must be an adult"]]},"services":{"type":"array","items":{"$ref":"#/components/schemas/flight_FlightSeatService"},"description":"One entry per passenger who may take this seat. Empty means the seat cannot be chosen: it is taken, or not sold to this party."}},"required":["type","designator","disclosures","services"]},{"type":"object","properties":{"type":{"type":"string","enum":["EXIT_ROW","LAVATORY","GALLEY","BASSINET","STAIRS","CLOSET","EMPTY","OTHER"],"description":"Something that is not a seat, to draw in its place. `OTHER` is a fixture the airline named that this API does not; draw a blank."}},"required":["type"]}],"description":"One position across the fuselage: a seat, or a fixture."},"flight_FlightSeatMapCabin":{"type":"object","properties":{"cabin_class":{"allOf":[{"$ref":"#/components/schemas/flight_CabinClass"},{"description":"The cabin these seats are in, when the airline states it."}]},"deck":{"type":"integer","description":"0 for the lower deck.","examples":[0]},"aisles":{"type":"integer","description":"How many aisles run through this cabin.","examples":[1]},"wings":{"type":"object","properties":{"first_row_index":{"type":"integer"},"last_row_index":{"type":"integer"}},"required":["first_row_index","last_row_index"],"description":"Positions in `rows`, from 0, of the first and last row over the wings, when the airline states them."},"rows":{"type":"array","items":{"type":"object","properties":{"sections":{"type":"array","items":{"type":"object","properties":{"elements":{"type":"array","items":{"$ref":"#/components/schemas/flight_FlightSeatMapElement"}}},"required":["elements"]},"description":"Left to right across the fuselage; an aisle runs between sections."}},"required":["sections"]},"description":"Front to back."}},"required":["deck","aisles","rows"],"description":"One cabin of the aircraft."},"flight_FlightSeatMap":{"type":"object","properties":{"journey":{"type":"integer","description":"Position in the offer's `journeys`, from 0.","examples":[0]},"segment":{"type":"integer","description":"Position in that journey's `segments`, from 0.","examples":[0]},"cabins":{"type":"array","items":{"$ref":"#/components/schemas/flight_FlightSeatMapCabin"}}},"required":["journey","segment","cabins"],"description":"The cabin layout of one flight, with each seat priced per passenger."},"flight_BookedSegmentPassenger":{"type":"object","properties":{"passenger_id":{"type":"string","description":"The passenger this applies to: one of the `id` values in the booking's `passengers`.","examples":["psg_0192f3a4b5c64d7e8f9a0b1c2d3e4f5c"]},"cabin_class":{"allOf":[{"$ref":"#/components/schemas/flight_CabinClass"},{"description":"The cabin this passenger flies on this segment. Omitted when the airline does not say.","examples":["BUSINESS"]}]},"cabin_name":{"type":"string","description":"The airline's own name for that cabin.","examples":["Business"]},"checked_bags":{"type":"integer","description":"Checked bags the fare includes for this passenger on this segment. `0` means none; omitted when the airline does not say.","examples":[1]},"carry_on_bags":{"type":"integer","description":"Carry-on bags the fare includes for this passenger on this segment. `0` means none; omitted when the airline does not say.","examples":[1]}},"required":["passenger_id"],"description":"What one passenger has on one segment: the cabin and the bags the fare includes."},"flight_BookedSegment":{"type":"object","properties":{"id":{"type":"string","description":"Stable segment id."},"origin":{"type":"string","description":"IATA code.","examples":["LHR"]},"destination":{"type":"string","description":"IATA code.","examples":["CDG"]},"departure_time":{"type":"string","description":"Local time at the origin airport, no offset.","examples":["2026-11-10T06:58:00"]},"arrival_time":{"type":"string","description":"Local time at the destination airport, no offset.","examples":["2026-11-10T09:15:00"]},"marketing_flight":{"type":"string","description":"Carrier code plus unpadded number.","examples":["AF1681"]},"marketing_carrier":{"type":"string","description":"The name of the airline selling the seat, whose code is on `marketing_flight`. You receive the code here when no name is known.","examples":["Air France"]},"marketing_carrier_logo_url":{"type":"string","description":"Airline directory logo. Omitted when the directory has no logo for this carrier.","examples":["https://assets.duffel.com/img/airlines/for-light-background/full-color-logo/AF.svg"]},"operating_carrier":{"type":"string","description":"The airline flying this segment, present only when it differs from `marketing_carrier` — a codeshare. When omitted, one airline operates the segment.","examples":["KLM"]},"operating_carrier_logo_url":{"type":"string","description":"As `marketing_carrier_logo_url`, for the operating carrier.","examples":["https://assets.duffel.com/img/airlines/for-light-background/full-color-logo/KL.svg"]},"duration_minutes":{"type":"number","description":"Gate to gate.","examples":[137]},"passengers":{"type":"array","items":{"$ref":"#/components/schemas/flight_BookedSegmentPassenger"},"description":"Each passenger's cabin and included bags on this segment. They can differ between passengers on one flight and between the segments of one trip."}},"required":["id"],"description":"One persisted flight, gate to gate."},"flight_IdentityDocument":{"type":"object","properties":{"type":{"type":"string","enum":["PASSPORT","ID"],"description":"The kind of document.","x-enum-descriptions":{"PASSPORT":"A passport.","ID":"A national identity card, where the route accepts one."},"examples":["PASSPORT"]},"number":{"type":"string","minLength":1,"description":"Document number as printed.","examples":["123456789"]},"issue_country":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2.","examples":["GB"]},"expiry":{"type":"string","format":"date","description":"`YYYY-MM-DD`. Must be after the last flight.","examples":["2031-04-11"]}},"required":["type","number","issue_country","expiry"],"description":"The travel document the passenger will fly on. Sent to the airline only when it requires one."},"flight_FlightLoyaltyAccount":{"type":"object","properties":{"airline_iata_code":{"type":"string","pattern":"^[A-Z0-9]{2}$","description":"The airline that runs the programme, which can differ from the airline you fly.","examples":["BA"]},"membership_number":{"type":"string","pattern":"^[A-Za-z0-9-]{1,64}$","description":"The number the programme issued: letters, digits and `-`, up to 64 characters.","examples":["12901014"]}},"required":["airline_iata_code","membership_number"],"description":"One airline loyalty account."},"flight_Passenger":{"type":"object","properties":{"first_name":{"type":"string","minLength":1,"description":"Given name, as on the document.","examples":["Amira"]},"last_name":{"type":"string","minLength":1,"description":"Family name, as on the document.","examples":["Haddad"]},"middle_name":{"type":"string","description":"Middle name, when the document shows one.","examples":["Noor"]},"birthday":{"type":"string","format":"date","description":"`YYYY-MM-DD`. Must agree with `type`.","examples":["1988-04-12"]},"type":{"type":"string","enum":["ADULT","CHILD","INFANT"],"description":"The fare category the passenger travels under.","x-enum-descriptions":{"ADULT":"12 and over.","CHILD":"2–11.","INFANT":"Under 2, on an adult's lap."},"examples":["ADULT"]},"gender":{"type":"string","enum":["M","F"],"description":"As on the document.","x-enum-descriptions":{"M":"Male, as on the document.","F":"Female, as on the document."},"examples":["F"]},"nationality":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2.","examples":["GB"]},"document":{"allOf":[{"$ref":"#/components/schemas/flight_IdentityDocument"},{"description":"Required when the offer's `documents_required` is `true`; otherwise you may omit it."}]},"loyalty_accounts":{"type":"array","items":{"$ref":"#/components/schemas/flight_FlightLoyaltyAccount"},"maxItems":5,"description":"Your passenger's airline loyalty accounts: up to 5, one per airline, and none shared with another passenger, whatever its letter case. Each is sent when the offer can carry it; the response lists those the supplier accepted."}},"required":["first_name","last_name","birthday","type","gender","nationality"],"description":"One passenger, exactly as on their document. Details reach the airline as given; placeholder values are refused."},"flight_FlightContact":{"type":"object","properties":{"first_name":{"type":"string","minLength":1,"description":"Given name.","examples":["Amira"]},"last_name":{"type":"string","minLength":1,"description":"Family name.","examples":["Haddad"]},"middle_name":{"type":"string","description":"Middle name, optional.","examples":["Noor"]},"email":{"type":"string","format":"email","description":"Where confirmations are sent.","examples":["amira.haddad@example.com"]},"phone_number":{"type":"string","minLength":1,"description":"National number without the country code, digits only.","examples":["2080160509"]},"phone_country_code":{"type":"string","minLength":1,"description":"Country calling code without `+`.","examples":["44"]}},"required":["first_name","last_name","email","phone_number","phone_country_code"],"description":"The person contacted about the booking. Stored, never returned on a read."},"flight_FlightPrebookRequest":{"type":"object","properties":{"offer_reference":{"type":"string","minLength":1,"description":"The `offer_reference` from Flight Offers, unchanged.","examples":["eyJzdXBwbGllciI6ImR1ZmZlbCIsIm9mZmVyIjoib2ZmXzAwMDBC…"]},"contact":{"allOf":[{"$ref":"#/components/schemas/flight_FlightContact"},{"description":"Who to contact about the booking."}]},"passengers":{"type":"array","items":{"$ref":"#/components/schemas/flight_Passenger"},"minItems":1,"description":"Must match the party the offer was searched for — the same number of adults, children and infants."},"services":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"An `id` from the available services.","examples":["ase_00009UhD4ongolulWd9123"]},"quantity":{"type":"integer","minimum":1,"description":"How many of this bag, up to its `maximum_quantity`. Always 1 for a seat.","examples":[1]}},"required":["id","quantity"]},"description":"Bags and seats to add: bag ids from the offer's available services, seat ids from its seat maps. Priced at the airline's current price and included in `total_amount`. Omit for none."},"use_payment_sdk":{"type":"boolean","default":false,"description":"For Duffel, omit or set false to pay with a saved instrument at book, or set true to use the OEX Payment SDK. For LiteAPI, you must set true and use the returned SDK provider and environment; book takes no instrument.","examples":[false]}},"required":["offer_reference","contact","passengers"],"description":"You bind an offer with the contact and passengers. Duffel reserves nothing before book; LiteAPI creates a checkout and may hold the itinerary during prebook."},"flight_FlightBookingServicesRequest":{"type":"object","properties":{"services":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"An `id` from the available services.","examples":["ase_00009UhD4ongolulWd9123"]},"quantity":{"type":"integer","minimum":1,"description":"How many of this bag, up to its `maximum_quantity`. Always 1 for a seat.","examples":[1]}},"required":["id","quantity"]},"minItems":1,"description":"Bags to buy, from the booking's available services. Priced at the airline's current price."},"payment_instrument_id":{"type":"string","minLength":1,"description":"The saved card to charge. The purchase is its own payment, separate from the fare's.","examples":["inst_78a44f9bb56641a1a8196fba0174c25d"]}},"required":["services","payment_instrument_id"],"description":"Bags to add to a confirmed booking."},"flight_CancelFlightBookingRequest":{"type":"object","properties":{},"additionalProperties":false,"description":"Empty on purpose. Cancelling is unconditional; get a cancellation quote first if the cost matters. Any field is a `400`."},"flight_FlightCancellationPolicy":{"type":"object","properties":{"refundable":{"type":"boolean","description":"Whether the ticket can be cancelled for less than its full price. The whole `cancellation_policy` block is omitted when the airline published no terms.","examples":[false]},"penalty":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"What the airline keeps on cancellation, when it states an amount. Omitted does not mean free.","examples":[{"amount":150,"currency":"USD"}]}]}},"required":["refundable"],"description":"The latest recorded fare refund terms. Flights carry one flat penalty rather than a tier ladder."},"flight_BookingPassenger":{"type":"object","properties":{"id":{"type":"string","description":"Stable passenger id."},"first_name":{"type":"string","description":"Given name.","examples":["Amira"]},"last_name":{"type":"string","description":"Family name.","examples":["Haddad"]},"loyalty_accounts":{"type":"array","items":{"type":"object","properties":{"airline_iata_code":{"type":"string","examples":["BA"]},"membership_number":{"type":"string","description":"Masked to its last 4 characters; a number of 4 characters or fewer is fully masked.","examples":["•••••1014"]}},"required":["airline_iata_code","membership_number"]},"description":"The loyalty accounts the supplier received, on single-booking reads. The airline decides whether to credit them. Once the booking is `READY_FOR_COMPLETE`, an account you sent that is missing here was not passed on, because the offer cannot carry it or the supplier refused it."}},"required":["id","first_name","last_name"],"description":"A passenger on the booking."},"flight_BookedJourney":{"type":"object","properties":{"id":{"type":"string","description":"Stable journey id."},"origin":{"type":"string","description":"IATA code of the first departure.","examples":["LHR"]},"destination":{"type":"string","description":"IATA code of the final arrival.","examples":["CDG"]},"direction":{"$ref":"#/components/schemas/flight_JourneyDirection"},"fare_brand":{"type":"string","description":"The fare brand the airline sold for this journey, such as Basic or Premium. Omitted when the airline names none.","examples":["Premium"]},"departure_time":{"type":"string","description":"First departure, local time at the origin airport, no offset.","examples":["2026-11-10T06:58:00"]},"arrival_time":{"type":"string","description":"Final arrival, local time at the destination airport, no offset.","examples":["2026-11-10T09:15:00"]},"duration_minutes":{"type":"number","description":"Flying plus connecting time within this journey.","examples":[137]},"stops":{"type":"number","description":"Connection points within this journey (`segments.length - 1`), never a trip-wide sum.","examples":[0]},"segments":{"type":"array","items":{"$ref":"#/components/schemas/flight_BookedSegment"},"description":"The flights of this journey, in order. Two or more segments means a connection."}},"required":["id"],"description":"One directional part of the persisted itinerary — the outbound, the return, or one hop of a multi-city trip."},"flight_FlightBookingFailure":{"type":"object","properties":{"code":{"type":"string","description":"Which step failed: `supplier_operation_unsupported`, `supplier_unreachable`, `prebook_failed`, `offer_expired`, `price_changed`, `passenger_mismatch`, `services_unavailable`, `document_required`, `payment_method_unsupported`, `payment_failed`, `authorize_failed`, `book_failed`, `loyalty_membership_rejected` or `passenger_name_rejected` on a failed booking; `supplier_rejected`, `refund_not_cash` or `cancellation_not_quotable` on a confirmed booking whose cancellation the supplier rejected.","examples":["book_failed"]},"description":{"type":"string","description":"A summary of what went wrong at that step.","examples":["The offer is no longer available."]}},"description":"Why the last lifecycle operation failed. Present when `status` is `FAILED`, and on a `CONFIRMED` booking whose most recent cancellation the supplier rejected: the ticket stays valid then, and this says why the cancellation did not happen. Cleared when a new cancellation is accepted."},"flight_FlightBookingService":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","examples":["svc_0192f3a4b5c6"]},"status":{"type":"string","enum":["PENDING","IN_PROGRESS","CONFIRMED","FAILED","CANCELED"],"description":"`PENDING` until the booking completes, then `CONFIRMED`, `FAILED` or `CANCELED` with it. An extra bought after booking is `IN_PROGRESS` while its purchase runs, then `CONFIRMED` on its own, or `FAILED` when its purchase was refused."},"passenger_id":{"type":"string"},"segment_ids":{"type":"array","items":{"type":"string"}},"quantity":{"type":"integer","minimum":1},"unit_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"The price of one: one bag, the seat, or the cover.","examples":[{"amount":40,"currency":"USD"}]}]},"total_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"`unit_amount × quantity`.","examples":[{"amount":40,"currency":"USD"}]}]},"payment_id":{"type":"string","description":"The payment this extra was charged to, one of the `id` values in `payments`: the booking's own payment for an extra chosen at prebook, or its own payment for a bag bought later, which reads `FAILED` or `VOIDED` if that purchase failed. Omitted when it has none.","examples":["pay_0192f3a4b5c64d7e8f9a0b1c2d3e4f61"]},"type":{"type":"string","enum":["BAGGAGE"]},"baggage":{"$ref":"#/components/schemas/flight_Baggage"}},"required":["id","status","segment_ids","quantity","unit_amount","total_amount","type","baggage"],"description":"A bag on the booking."},{"type":"object","properties":{"id":{"type":"string","examples":["svc_0192f3a4b5c6"]},"status":{"type":"string","enum":["PENDING","IN_PROGRESS","CONFIRMED","FAILED","CANCELED"],"description":"`PENDING` until the booking completes, then `CONFIRMED`, `FAILED` or `CANCELED` with it. An extra bought after booking is `IN_PROGRESS` while its purchase runs, then `CONFIRMED` on its own, or `FAILED` when its purchase was refused."},"passenger_id":{"type":"string"},"segment_ids":{"type":"array","items":{"type":"string"}},"quantity":{"type":"number","enum":[1]},"unit_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"The price of one: one bag, the seat, or the cover.","examples":[{"amount":40,"currency":"USD"}]}]},"total_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"`unit_amount × quantity`.","examples":[{"amount":40,"currency":"USD"}]}]},"payment_id":{"type":"string","description":"The payment this extra was charged to, one of the `id` values in `payments`: the booking's own payment for an extra chosen at prebook, or its own payment for a bag bought later, which reads `FAILED` or `VOIDED` if that purchase failed. Omitted when it has none.","examples":["pay_0192f3a4b5c64d7e8f9a0b1c2d3e4f61"]},"type":{"type":"string","enum":["SEAT"]},"seat":{"type":"object","properties":{"designator":{"type":"string","description":"The airline's label for the seat.","examples":["12A"]}},"required":["designator"]}},"required":["id","status","passenger_id","segment_ids","quantity","unit_amount","total_amount","type","seat"],"description":"A seat for one passenger on one flight: `quantity` is 1 and `segment_ids` has one entry."},{"type":"object","properties":{"id":{"type":"string","examples":["svc_0192f3a4b5c6"]},"status":{"type":"string","enum":["PENDING","IN_PROGRESS","CONFIRMED","FAILED","CANCELED"],"description":"`PENDING` until the booking completes, then `CONFIRMED`, `FAILED` or `CANCELED` with it. An extra bought after booking is `IN_PROGRESS` while its purchase runs, then `CONFIRMED` on its own, or `FAILED` when its purchase was refused."},"passenger_id":{"type":"string"},"segment_ids":{"type":"array","items":{"type":"string"}},"quantity":{"type":"integer","minimum":1},"unit_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"The price of one: one bag, the seat, or the cover.","examples":[{"amount":40,"currency":"USD"}]}]},"total_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"`unit_amount × quantity`.","examples":[{"amount":40,"currency":"USD"}]}]},"payment_id":{"type":"string","description":"The payment this extra was charged to, one of the `id` values in `payments`: the booking's own payment for an extra chosen at prebook, or its own payment for a bag bought later, which reads `FAILED` or `VOIDED` if that purchase failed. Omitted when it has none.","examples":["pay_0192f3a4b5c64d7e8f9a0b1c2d3e4f61"]},"type":{"type":"string","enum":["CANCEL_FOR_ANY_REASON"]}},"required":["id","status","segment_ids","quantity","unit_amount","total_amount","type"],"description":"Cover that lets the traveller cancel for any reason; it carries no further details."}],"description":"One extra on the booking. `type` says which details it carries."},"flight_FlightPaymentMethod":{"type":"object","properties":{"type":{"type":"string","enum":["CARD"],"description":"`CARD`, the only type. The card's details sit under `card`, so another type can be added beside it without changing them."},"card":{"type":"object","properties":{"brand":{"type":"string","description":"The card network in upper case, such as `VISA`, `MASTERCARD` or `AMEX`. Read it as open text, because a new network can appear.","examples":["VISA"]},"last4":{"type":"string","description":"The last four digits of the card number.","examples":["4242"]},"funding":{"type":"string","enum":["CREDIT","DEBIT","PREPAID","UNKNOWN"],"description":"Whether it is a credit, debit or prepaid card; `UNKNOWN` when the card network does not say.","examples":["CREDIT"]},"wallet":{"type":"string","description":"The wallet the card was used through, in upper case, such as `APPLE_PAY` or `GOOGLE_PAY`. Omitted when the card was used directly.","examples":["APPLE_PAY"]}},"required":["brand","last4","funding"],"description":"The card's network and last four digits."}},"required":["type","card"],"description":"How a payment was made."},"flight_FlightBookingPayment":{"type":"object","properties":{"id":{"type":"string","description":"The payment's id. Each extra names the payment that paid for it in `payment_id`, and a cancellation the payments its refund returns to in `refund_to`.","examples":["pay_0192f3a4b5c64d7e8f9a0b1c2d3e4f60"]},"status":{"type":"string","enum":["INITIATED","AUTHORIZED","CAPTURED","FAILED","VOIDED"],"description":"The last outcome recorded for this payment, not a live reading. It can trail the money: a capture that went through while saving its result failed leaves `AUTHORIZED`, and the booking stays confirmed.","x-enum-descriptions":{"INITIATED":"The payment has started and has no recorded outcome yet: an SDK payment waits for your traveller, and a LiteAPI checkout payment waits for LiteAPI.","AUTHORIZED":"The last recorded outcome is a hold on the card.","CAPTURED":"The last recorded outcome is that the amount was taken. A refund does not change it; read the booking's `cancellation` for the refund.","FAILED":"The payment did not go through. This is not always a decline by the card's bank: a card that asks for an authentication step OEX does not support fails too.","VOIDED":"The last recorded outcome is that the hold was released."},"examples":["CAPTURED"]},"amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"The payment's amount.","examples":[{"amount":180.67,"currency":"USD"}]}]},"collected_by":{"type":"string","enum":["OEX","SUPPLIER"],"description":"Who took the payment: `OEX`, or `SUPPLIER` when LiteAPI collected it in its checkout.","examples":["OEX"]},"payment_method":{"allOf":[{"$ref":"#/components/schemas/flight_FlightPaymentMethod"},{"description":"The card the payment was made with. Omitted when LiteAPI collected the payment, while it is `INITIATED`, when Payment holds no card for it, in a list of bookings, and when its card could not be read; read the booking again later in that last case."}]},"created_at":{"type":"string","description":"When the payment started.","examples":["2026-11-01T12:40:12.000Z"]}},"required":["id","status","amount","collected_by","created_at"],"description":"One payment on your booking: its own payment, an attempt that failed before it, or a bag bought later."},"flight_FlightAirlineInitiatedChangeJourney":{"type":"object","properties":{"origin":{"type":"string","examples":["LHR"]},"destination":{"type":"string","examples":["LTN"]},"segments":{"type":"array","items":{"type":"object","properties":{"origin":{"type":"string","examples":["LHR"]},"destination":{"type":"string","examples":["LTN"]},"marketing_flight":{"type":"string","examples":["ZZ1221"]},"operating_flight":{"type":["string","null"],"description":"The operating airline's flight, or null when the airline did not report it.","examples":["ZZ1221"]},"departure_time":{"type":"string","description":"Local time at the origin airport, no offset.","examples":["2026-11-20T15:42:00"]},"arrival_time":{"type":"string","description":"Local time at the destination airport, no offset.","examples":["2026-11-20T16:20:00"]},"duration_minutes":{"type":["integer","null"],"description":"Flight time in minutes, or null when the airline did not report it.","examples":[38]}},"required":["origin","destination","marketing_flight","operating_flight","departure_time","arrival_time","duration_minutes"]}}},"required":["origin","destination","segments"]},"flight_FlightAirlineInitiatedChange":{"type":"object","properties":{"id":{"type":"string","examples":["chg_0192f3a4b5c64d7e8f9a0b1c2d3e4f5b"]},"detected_at":{"type":"string","description":"When the airline's change was reported, in UTC."},"removed":{"type":"array","items":{"$ref":"#/components/schemas/flight_FlightAirlineInitiatedChangeJourney"},"description":"The flights the airline took away."},"added":{"type":"array","items":{"$ref":"#/components/schemas/flight_FlightAirlineInitiatedChangeJourney"},"description":"The flights the airline put in their place."}},"required":["id","detected_at","removed","added"],"description":"A change the airline made to your booked flights. Your booking's `journeys` keep the flights you booked. You cannot yet accept, refuse or change it through this API."},"flight_FlightQuoteUnavailableReason":{"type":"string","enum":["no_policy","no_total","fee_unknown","currency_mismatch","refund_not_cash"],"description":"Why a cancellation quote has no money fields. None of these means free.","x-enum-descriptions":{"no_policy":"The airline published no refund terms. Common, and not an error.","no_total":"No captured total to price the fee against.","fee_unknown":"The fare is refundable, but the airline did not say what it keeps.","currency_mismatch":"The fee and the total are in different currencies.","refund_not_cash":"The airline would not refund to your traveller's original payment, and a cancel is refused for the same reason."}},"flight_FlightBookingAvailableService":{"type":"object","properties":{"id":{"type":"string","description":"Send this id in `POST /v1/flight/bookings/{id}/services`.","examples":["ase_00009UhD4ongolulWd9123"]},"type":{"type":"string","enum":["BAGGAGE"]},"baggage":{"$ref":"#/components/schemas/flight_Baggage"},"passenger_id":{"type":"string","description":"The booking passenger the bag is for.","examples":["psg_0192f3a4b5c6"]},"segment_ids":{"type":"array","items":{"type":"string"},"description":"The booking's segments the bag covers."},"maximum_quantity":{"type":"integer","minimum":1},"unit_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"Price for one bag, checked again when you buy it.","examples":[{"amount":40,"currency":"USD"}]}]}},"required":["id","type","baggage","passenger_id","segment_ids","maximum_quantity","unit_amount"],"description":"A bag the traveller can add after booking."},"flight_Airline":{"type":"object","properties":{"id":{"type":"string"},"iata_code":{"type":"string","pattern":"^[A-Z0-9]{2}$"},"icao_code":{"type":["string","null"]},"name":{"type":"string"},"country":{"type":["string","null"],"description":"Country name, not an ISO code."},"alliance":{"type":["string","null"]},"logo_url":{"type":["string","null"],"format":"uri"},"is_active":{"type":"boolean"}},"required":["id","iata_code","icao_code","name","country","alliance","logo_url","is_active"]},"flight_AirlineIata":{"type":"object","properties":{"iata_code":{"type":"string"},"name":{"type":"string"}},"required":["iata_code","name"]},"flight_Airport":{"type":"object","properties":{"id":{"type":"string"},"iata_code":{"type":"string","pattern":"^[A-Z]{3}$"},"icao_code":{"type":["string","null"]},"name":{"type":"string"},"city":{"type":["string","null"]},"state":{"type":["string","null"]},"country":{"type":["string","null"],"description":"Country name, not an ISO code."},"latitude":{"type":["number","null"]},"longitude":{"type":["number","null"]},"time_zone":{"type":["string","null"],"description":"IANA time zone name.","examples":["America/New_York"]}},"required":["id","iata_code","icao_code","name","city","state","country","latitude","longitude","time_zone"]},"flight_FlightWebhookSubscription":{"type":"object","properties":{"id":{"type":"string","examples":["whs_0192f3a4b5c64d7e8f9a0b1c2d3e4f5b"]},"url":{"type":"string","examples":["https://partner.example/hooks/flight"]},"event_types":{"type":"array","items":{"type":"string","enum":["flight.booking.confirmed","flight.booking.failed","flight.booking.canceled","flight.booking.cancel_failed","flight.booking.airline_initiated_change_detected"]}},"status":{"type":"string","enum":["ACTIVE","PAUSED"]},"previous_secret_expires_at":{"type":["string","null"],"description":"Until then, your requests also carry a signature made with your previous secret."},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","url","event_types","status","previous_secret_expires_at","created_at","updated_at"],"description":"An endpoint that receives your organisation's booking events."},"flight_FlightWebhookSubscriptionWithSecret":{"type":"object","properties":{"id":{"type":"string","examples":["whs_0192f3a4b5c64d7e8f9a0b1c2d3e4f5b"]},"url":{"type":"string","examples":["https://partner.example/hooks/flight"]},"event_types":{"type":"array","items":{"type":"string","enum":["flight.booking.confirmed","flight.booking.failed","flight.booking.canceled","flight.booking.cancel_failed","flight.booking.airline_initiated_change_detected"]}},"status":{"type":"string","enum":["ACTIVE","PAUSED"]},"previous_secret_expires_at":{"type":["string","null"],"description":"Until then, your requests also carry a signature made with your previous secret."},"created_at":{"type":"string"},"updated_at":{"type":"string"},"signing_secret":{"type":"string","description":"Your signing secret. You receive it only in this response; store it on your server."}},"required":["id","url","event_types","status","previous_secret_expires_at","created_at","updated_at","signing_secret"],"description":"Your subscription with the signing secret it signs with."},"flight_FlightWebhookBooking":{"type":"object","properties":{"id":{"type":"string","description":"Your booking id.","examples":["bkg_0192f3a4b5c64d7e8f9a0b1c2d3e4f5b"]},"supplier":{"type":"string","description":"Which supplier holds this booking. Fixed when the booking was created, so it stays correct even if the default changes.","examples":["DUFFEL"]},"status":{"$ref":"#/components/schemas/flight_BookingStatus"},"total_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"The booking's price as sold: the fare, the extras charged with it, and later purchases once confirmed. A `FAILED` booking still shows what it tried to sell; cancellation never changes it, the refund is under `cancellation`. OEX collects it at book for Duffel; LiteAPI collects it through its checkout. Absent until the booking is priced.","examples":[{"amount":260.67,"currency":"USD"}]}]},"fare_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"The flights' own price, taxes included: `total_amount − services_amount`. Present whenever `total_amount` is.","examples":[{"amount":220.67,"currency":"USD"}]}]},"fare_tax_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"The taxes inside `fare_amount`, never added to it: 0 when the supplier reported zero, absent when it stated none.","examples":[{"amount":50,"currency":"USD"}]}]},"services_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"The extras' share of `total_amount`: the extras charged with the fare, in any status, plus every later purchase that was confirmed, which stays in after cancellation. 0 when none. Read this for a receipt; do not sum `services`, which also lists a later purchase that failed.","examples":[{"amount":40,"currency":"USD"}]}]},"cancellation_policy":{"$ref":"#/components/schemas/flight_FlightCancellationPolicy"},"fare_conditions":{"$ref":"#/components/schemas/flight_FareConditions"},"supplier_reference":{"type":"string","description":"The supplier's order id.","examples":["ord_0000B9M0HSU2oNVmKw0UKj"]},"airline_pnr":{"type":"string","description":"The airline's record locator — what the passenger quotes at the airport.","examples":["J6AK3S"]},"confirmed_at":{"type":"string","description":"When the airline issued the ticket.","examples":["2026-11-01T12:40:12.000Z"]},"canceled_at":{"type":"string","description":"When the ticket was cancelled.","examples":["2026-11-02T09:15:00.000Z"]},"cancellation":{"$ref":"#/components/schemas/flight_BookingCancellation"},"failure":{"$ref":"#/components/schemas/flight_FlightBookingFailure"},"created_at":{"type":"string","description":"When the booking was created.","examples":["2026-11-01T12:34:56.000Z"]},"updated_at":{"type":"string","description":"When the booking last changed.","examples":["2026-11-01T12:40:12.000Z"]},"version":{"type":"integer","description":"Increases with every change to the booking; keep the highest you have seen for each booking.","examples":[9]},"user_id":{"type":"string","description":"The user that owns the booking."}},"required":["id","supplier","status","created_at","updated_at","version","user_id"],"description":"The booking as `GET /v1/flight/bookings/{id}` serves it, without passengers, journeys, extras, payments and airline changes."},"flight_FlightWebhookEvent":{"type":"object","properties":{"id":{"type":"string","description":"The event ID, also sent as `x-oex-event-id`. Use it to ignore repeats.","examples":["evt_0192f3a4b5c64d7e8f9a0b1c2d3e4f5b"]},"type":{"type":"string","enum":["flight.booking.confirmed","flight.booking.failed","flight.booking.canceled","flight.booking.cancel_failed","flight.booking.airline_initiated_change_detected"]},"created_at":{"type":"string"},"data":{"type":"object","properties":{"booking":{"$ref":"#/components/schemas/flight_FlightWebhookBooking"},"airline_initiated_change":{"allOf":[{"$ref":"#/components/schemas/flight_FlightAirlineInitiatedChange"},{"description":"Present on `flight.booking.airline_initiated_change_detected` only."}]}},"required":["booking"]}},"required":["id","type","created_at","data"],"description":"The body of each request to your endpoint."},"flight_FlightWebhookDelivery":{"type":"object","properties":{"id":{"type":"string","examples":["dlv_0192f3a4b5c64d7e8f9a0b1c2d3e4f5b"]},"status":{"type":"string","enum":["PENDING","PUBLISHED","DELIVERED","FAILED"],"description":"PENDING: queueing is not confirmed; the request may already be on its way. PUBLISHED: queued for your endpoint. DELIVERED: your endpoint answered 2xx. FAILED: see failure_reason."},"event":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","examples":["flight.booking.confirmed"]},"created_at":{"type":"string"},"data":{"type":"object","properties":{"booking":{"type":"object","additionalProperties":{}}},"required":["booking"],"additionalProperties":{}}},"required":["id","type","created_at","data"],"additionalProperties":{},"description":"The event body as it was sent to your endpoint; FlightWebhookEvent describes its fields."},"replay_count":{"type":"integer","description":"How many times you replayed this delivery."},"failure_reason":{"type":["string","null"],"enum":["retries_exhausted","publish_rejected","subscription_paused",null],"description":"retries_exhausted: your endpoint never answered 2xx. publish_rejected: the delivery could not be queued for your URL. subscription_paused: your subscription was paused before the delivery was queued."},"attempts":{"type":"array","items":{"type":"object","properties":{"attempt_number":{"type":"integer","description":"1 for the first request, then one per retry."},"response_status":{"type":["integer","null"],"description":"Your endpoint's HTTP status; null when it gave no response."},"response_body":{"type":["string","null"],"description":"The first 500 characters of your endpoint's response body."},"created_at":{"type":"string"}},"required":["attempt_number","response_status","response_body","created_at"]},"description":"Your endpoint's responses for the current replay, in order."},"created_at":{"type":"string"},"published_at":{"type":["string","null"]},"delivered_at":{"type":["string","null"]},"failed_at":{"type":["string","null"]}},"required":["id","status","event","replay_count","failure_reason","attempts","created_at","published_at","delivered_at","failed_at"],"description":"One event sent, or to be sent, to your endpoint."},"flight_FlightBookingDetail":{"type":"object","properties":{"id":{"type":"string","description":"Your booking id.","examples":["bkg_0192f3a4b5c64d7e8f9a0b1c2d3e4f5b"]},"supplier":{"type":"string","description":"Which supplier holds this booking. Fixed when the booking was created, so it stays correct even if the default changes.","examples":["DUFFEL"]},"status":{"$ref":"#/components/schemas/flight_BookingStatus"},"total_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"The booking's price as sold: the fare, the extras charged with it, and later purchases once confirmed. A `FAILED` booking still shows what it tried to sell; cancellation never changes it, the refund is under `cancellation`. OEX collects it at book for Duffel; LiteAPI collects it through its checkout. Absent until the booking is priced.","examples":[{"amount":260.67,"currency":"USD"}]}]},"fare_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"The flights' own price, taxes included: `total_amount − services_amount`. Present whenever `total_amount` is.","examples":[{"amount":220.67,"currency":"USD"}]}]},"fare_tax_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"The taxes inside `fare_amount`, never added to it: 0 when the supplier reported zero, absent when it stated none.","examples":[{"amount":50,"currency":"USD"}]}]},"services_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"The extras' share of `total_amount`: the extras charged with the fare, in any status, plus every later purchase that was confirmed, which stays in after cancellation. 0 when none. Read this for a receipt; do not sum `services`, which also lists a later purchase that failed.","examples":[{"amount":40,"currency":"USD"}]}]},"services":{"type":"array","items":{"$ref":"#/components/schemas/flight_FlightBookingService"},"description":"Every extra ever placed on the booking, each with its `status`. Empty when none."},"payments":{"type":"array","items":{"$ref":"#/components/schemas/flight_FlightBookingPayment"},"description":"Every payment on this booking, oldest first. Empty when none."},"expires_at":{"type":"string","description":"Complete your Duffel booking before this deadline because nothing is reserved with the airline, a chosen seat included. For LiteAPI, the supplier decides validity at book; do not start another checkout merely because this time passed.","examples":["2026-11-01T12:49:56.000Z"]},"cancellation_policy":{"$ref":"#/components/schemas/flight_FlightCancellationPolicy"},"fare_conditions":{"$ref":"#/components/schemas/flight_FareConditions"},"passengers":{"type":"array","items":{"$ref":"#/components/schemas/flight_BookingPassenger"},"description":"The passengers."},"journeys":{"type":"array","items":{"$ref":"#/components/schemas/flight_BookedJourney"},"description":"The persisted itinerary, in travel order. Present after successful prebook."},"supplier_reference":{"type":"string","description":"The supplier's order id.","examples":["ord_0000B9M0HSU2oNVmKw0UKj"]},"airline_pnr":{"type":"string","description":"The airline's record locator — what the passenger quotes at the airport.","examples":["J6AK3S"]},"confirmed_at":{"type":"string","description":"When the airline issued the ticket.","examples":["2026-11-01T12:40:12.000Z"]},"canceled_at":{"type":"string","description":"When the ticket was cancelled.","examples":["2026-11-02T09:15:00.000Z"]},"cancellation":{"$ref":"#/components/schemas/flight_BookingCancellation"},"failure":{"$ref":"#/components/schemas/flight_FlightBookingFailure"},"created_at":{"type":"string","description":"When the booking was created.","examples":["2026-11-01T12:34:56.000Z"]},"updated_at":{"type":"string","description":"When the booking last changed.","examples":["2026-11-01T12:40:12.000Z"]},"airline_initiated_changes":{"type":"array","items":{"$ref":"#/components/schemas/flight_FlightAirlineInitiatedChange"},"description":"The airline's changes to your booked flights, in the order they were recorded; empty when none was recorded."}},"required":["id","supplier","status","services","payments","created_at","updated_at","airline_initiated_changes"],"description":"A flight booking at any point in its lifecycle. A ready booking has `expires_at` and `journeys`; a confirmed one has `supplier_reference` and may have `airline_pnr`; a failed one has `failure`; a confirmed one carries `failure` too when its last cancellation was rejected. A cancellation in progress reads `CANCEL_IN_PROGRESS` until the run settles it."},"flight_FlightBookingConfirmed":{"type":"object","properties":{"id":{"type":"string","description":"Your booking id.","examples":["bkg_0192f3a4b5c64d7e8f9a0b1c2d3e4f5b"]},"supplier":{"type":"string","description":"Which supplier holds this booking. Fixed when the booking was created, so it stays correct even if the default changes.","examples":["DUFFEL"]},"status":{"type":"string","enum":["CONFIRMED"]},"total_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"The booking's price as sold: the fare, the extras charged with it, and later purchases once confirmed. A `FAILED` booking still shows what it tried to sell; cancellation never changes it, the refund is under `cancellation`. OEX collects it at book for Duffel; LiteAPI collects it through its checkout. Absent until the booking is priced.","examples":[{"amount":260.67,"currency":"USD"}]}]},"fare_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"The flights' own price, taxes included: `total_amount − services_amount`. Present whenever `total_amount` is.","examples":[{"amount":220.67,"currency":"USD"}]}]},"fare_tax_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"The taxes inside `fare_amount`, never added to it: 0 when the supplier reported zero, absent when it stated none.","examples":[{"amount":50,"currency":"USD"}]}]},"services_amount":{"allOf":[{"$ref":"#/components/schemas/flight_Money"},{"description":"The extras' share of `total_amount`: the extras charged with the fare, in any status, plus every later purchase that was confirmed, which stays in after cancellation. 0 when none. Read this for a receipt; do not sum `services`, which also lists a later purchase that failed.","examples":[{"amount":40,"currency":"USD"}]}]},"services":{"type":"array","items":{"$ref":"#/components/schemas/flight_FlightBookingService"},"description":"Every extra ever placed on the booking, each with its `status`. Empty when none."},"payments":{"type":"array","items":{"$ref":"#/components/schemas/flight_FlightBookingPayment"},"description":"Every payment on this booking, oldest first. Empty when none."},"cancellation_policy":{"$ref":"#/components/schemas/flight_FlightCancellationPolicy"},"fare_conditions":{"$ref":"#/components/schemas/flight_FareConditions"},"passengers":{"type":"array","items":{"$ref":"#/components/schemas/flight_BookingPassenger"},"description":"The passengers."},"journeys":{"type":"array","items":{"$ref":"#/components/schemas/flight_BookedJourney"},"description":"The persisted itinerary, in travel order. Present after successful prebook."},"supplier_reference":{"type":"string","description":"The supplier's order id.","examples":["ord_0000B9M0HSU2oNVmKw0UKj"]},"airline_pnr":{"type":"string","description":"The airline's record locator — what the passenger quotes at the airport.","examples":["J6AK3S"]},"confirmed_at":{"type":"string","description":"When the airline issued the ticket.","examples":["2026-11-01T12:40:12.000Z"]},"canceled_at":{"type":"string","description":"When the ticket was cancelled.","examples":["2026-11-02T09:15:00.000Z"]},"cancellation":{"$ref":"#/components/schemas/flight_BookingCancellation"},"created_at":{"type":"string","description":"When the booking was created.","examples":["2026-11-01T12:34:56.000Z"]},"updated_at":{"type":"string","description":"When the booking last changed.","examples":["2026-11-01T12:40:12.000Z"]}},"required":["id","supplier","status","services","payments","created_at","updated_at"]},"mandate_Charge":{"properties":{"amount":{"type":"integer","title":"Amount"},"currency":{"type":"string","title":"Currency"},"payee_id":{"type":"string","title":"Payee Id"},"category":{"type":["string","null"],"title":"Category"},"at":{"type":["string","null"],"title":"At"}},"type":"object","required":["amount","currency","payee_id"],"title":"Charge"},"mandate_ConfirmRequest":{"properties":{"confirmation":{"additionalProperties":true,"type":["object","null"],"title":"Confirmation"}},"type":"object","title":"ConfirmRequest"},"mandate_Evidence":{"properties":{"source":{"type":["string","null"],"title":"Source"},"presented":{"additionalProperties":true,"type":["object","null"],"title":"Presented"},"interaction":{"items":{"type":"string"},"type":"array","title":"Interaction","default":[]},"context":{"type":["string","null"],"title":"Context"},"confidence_score":{"type":["number","null"],"maximum":1,"minimum":0,"title":"Confidence Score"}},"type":"object","title":"Evidence","description":"Consent trail from whatever gathered it — LLM agent, watcher, or other service."},"mandate_ExerciseRequest":{"properties":{"token":{"type":"string","title":"Token"},"charge":{"$ref":"#/components/schemas/mandate_Charge"},"reference_id":{"type":["string","null"],"title":"Reference Id"}},"type":"object","required":["token","charge"],"title":"ExerciseRequest"},"mandate_HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/mandate_ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"mandate_IssueRequest":{"properties":{"user_id":{"type":"string","title":"User Id"},"mode":{"type":"string","enum":["closed","open"],"title":"Mode","default":"closed"},"payee":{"allOf":[{"$ref":"#/components/schemas/mandate_Payee"}],"nullable":true},"payment_amount":{"$ref":"#/components/schemas/mandate_PaymentAmount"},"payment_instrument":{"$ref":"#/components/schemas/mandate_PaymentInstrument"},"agent_id":{"type":["string","null"],"title":"Agent Id"},"expires_in_seconds":{"type":"integer","maximum":7776000,"exclusiveMinimum":0,"title":"Expires In Seconds","default":3600},"constraints":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Constraints","default":[]},"evidence":{"allOf":[{"$ref":"#/components/schemas/mandate_Evidence"}],"nullable":true}},"type":"object","required":["user_id","payment_amount","payment_instrument"],"title":"IssueRequest"},"mandate_Payee":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":["string","null"],"title":"Name"}},"type":"object","required":["id"],"title":"Payee"},"mandate_PaymentAmount":{"properties":{"currency":{"type":"string","pattern":"^[A-Z]{3}$","title":"Currency"},"amount":{"type":"integer","exclusiveMinimum":0,"title":"Amount","description":"Minor units (cents)"}},"type":"object","required":["currency","amount"],"title":"PaymentAmount"},"mandate_PaymentInstrument":{"properties":{"id":{"type":"string","title":"Id"},"type":{"type":"string","title":"Type"},"description":{"type":["string","null"],"title":"Description"}},"type":"object","required":["id","type"],"title":"PaymentInstrument"},"mandate_ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"mandate_VerifyRequest":{"properties":{"token":{"type":"string","title":"Token"},"charge":{"allOf":[{"$ref":"#/components/schemas/mandate_Charge"}],"nullable":true}},"type":"object","required":["token"],"title":"VerifyRequest"},"watcher_ConfirmPurchase":{"properties":{"confirmation":{"additionalProperties":true,"type":["object","null"],"title":"Confirmation"}},"type":"object","title":"ConfirmPurchase","description":"Passed to the mandate service verbatim — it, not the watcher, decides\nwhat a confirmation record needs to say."},"watcher_Contact":{"properties":{"first_name":{"type":"string","maxLength":64,"minLength":1,"title":"First Name"},"last_name":{"type":"string","maxLength":64,"minLength":1,"title":"Last Name"},"email":{"type":"string","maxLength":254,"minLength":3,"title":"Email"},"phone":{"type":"string","maxLength":32,"minLength":3,"title":"Phone"}},"type":"object","required":["first_name","last_name","email","phone"],"title":"Contact"},"watcher_HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/watcher_ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"watcher_Purchase":{"properties":{"payment_instrument_id":{"type":"string","maxLength":64,"minLength":1,"title":"Payment Instrument Id"},"travelers":{"items":{"$ref":"#/components/schemas/watcher_Traveler"},"type":"array","maxItems":8,"minItems":1,"title":"Travelers"},"contact":{"$ref":"#/components/schemas/watcher_Contact"},"evidence":{"allOf":[{"$ref":"#/components/schemas/watcher_PurchaseEvidence"}],"nullable":true}},"type":"object","required":["payment_instrument_id","travelers","contact"],"title":"Purchase","description":"Opt-in auto-book: who pays, who stays, who to reach — plus the consent\ntrail the mandate service records as evidence."},"watcher_PurchaseEvidence":{"properties":{"human_messages":{"items":{"type":"string"},"type":["array","null"],"title":"Human Messages"},"conversation_context":{"type":["string","null"],"title":"Conversation Context"}},"type":"object","title":"PurchaseEvidence"},"watcher_Rearm":{"properties":{"trigger":{"allOf":[{"$ref":"#/components/schemas/watcher_Trigger"}],"nullable":true}},"type":"object","title":"Rearm"},"watcher_Room":{"properties":{"adults":{"type":"integer","maximum":8,"minimum":1,"title":"Adults"}},"type":"object","required":["adults"],"title":"Room"},"watcher_Traveler":{"properties":{"first_name":{"type":"string","maxLength":64,"minLength":1,"title":"First Name"},"last_name":{"type":"string","maxLength":64,"minLength":1,"title":"Last Name"},"email":{"type":["string","null"],"maxLength":254,"title":"Email"},"is_lead":{"type":["boolean","null"],"title":"Is Lead"}},"type":"object","required":["first_name","last_name"],"title":"Traveler"},"watcher_Trigger":{"properties":{"type":{"type":"string","title":"Type","enum":["below_total"]},"amount":{"type":"number","exclusiveMinimum":0,"title":"Amount"}},"type":"object","required":["type","amount"],"title":"Trigger"},"watcher_TripWatchCreate":{"properties":{"id":{"type":["string","null"],"maxLength":40,"pattern":"^twc_[A-Za-z0-9]+$","title":"Id"},"destination":{"type":"string","maxLength":120,"minLength":1,"title":"Destination"},"email":{"type":["string","null"],"maxLength":254,"minLength":3,"title":"Email","description":"Where outcome emails go."},"check_in":{"type":"string","format":"date","title":"Check In"},"check_out":{"type":"string","format":"date","title":"Check Out"},"occupancy":{"items":{"$ref":"#/components/schemas/watcher_Room"},"type":"array","maxItems":4,"minItems":1,"title":"Occupancy","default":[{"adults":2}]},"currency":{"type":"string","maxLength":3,"minLength":3,"title":"Currency"},"guest_nationality":{"type":"string","maxLength":2,"minLength":2,"title":"Guest Nationality"},"min_rating":{"type":["number","null"],"maximum":10,"minimum":0,"title":"Min Rating"},"stars":{"items":{"type":"number"},"type":["array","null"],"maxItems":5,"minItems":1,"title":"Stars"},"trigger":{"$ref":"#/components/schemas/watcher_Trigger"}},"type":"object","required":["destination","check_in","check_out","currency","guest_nationality","trigger"],"title":"TripWatchCreate"},"watcher_ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"watcher_WatchCreate":{"properties":{"id":{"type":["string","null"],"maxLength":40,"pattern":"^wtc_[A-Za-z0-9]+$","title":"Id"},"hotel_id":{"type":"string","maxLength":64,"minLength":1,"title":"Hotel Id"},"hotel_name":{"type":["string","null"],"maxLength":160,"title":"Hotel Name","description":"Named in the outcome email; the id alone otherwise."},"email":{"type":["string","null"],"maxLength":254,"minLength":3,"title":"Email","description":"Where outcome emails go. Auto-book defaults to the contact email."},"check_in":{"type":"string","format":"date","title":"Check In"},"check_out":{"type":"string","format":"date","title":"Check Out"},"occupancy":{"items":{"$ref":"#/components/schemas/watcher_Room"},"type":"array","maxItems":4,"minItems":1,"title":"Occupancy","default":[{"adults":2}]},"currency":{"type":"string","maxLength":3,"minLength":3,"title":"Currency"},"guest_nationality":{"type":"string","maxLength":2,"minLength":2,"title":"Guest Nationality"},"trigger":{"$ref":"#/components/schemas/watcher_Trigger"},"purchase":{"allOf":[{"$ref":"#/components/schemas/watcher_Purchase"}],"nullable":true}},"type":"object","required":["hotel_id","check_in","check_out","currency","guest_nationality","trigger"],"title":"WatchCreate"},"watcher_WebhookRegister":{"properties":{"url":{"type":"string","maxLength":2000,"minLength":8,"pattern":"^https?://","title":"Url"},"events":{"items":{"type":"string"},"type":"array","maxItems":10,"title":"Events","default":["travel.hotel.watch.triggered","travel.hotel.trip_watch.triggered","travel.hotel.watch.purchased","travel.hotel.watch.purchase_failed"]}},"type":"object","required":["url"],"title":"WebhookRegister"}},"parameters":{},"securitySchemes":{"apiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key. Issued and revoked from the TrustPixel dashboard; the gateway resolves it to an owning organization on every request."},"bearerAuth":{"type":"http","scheme":"bearer","description":"The same API key presented as `Authorization: Bearer `, for clients that only speak bearer auth. A value shaped like a JWT is instead verified as a dashboard token — a Platform-internal flow, not a developer credential. Browser session cookies are never accepted."}}}},"proxyUrl":"/api/proxy"},"document":"gateway","operations":[{"method":"get","path":"/v1/mandate/{mandate_id}","tags":["Mandates"]}],"showDescription":true}]}]]}]

Retrieve a mandate

Authorization

Path Parameters

Header Parameters

Response Body

200application/json

401application/json

422application/json

502application/json

503application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`