> For the complete documentation index, see [llms.txt](https://docs.channex.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.channex.io/api-v.1-documentation/channel-api.md). # Channel API This guide describes the core API methods for building a channel mapping UI inside your application. ## Connecting a channel: the common flow Connecting a channel means creating a **channel connection** — the link between one or more properties and a booking channel, carrying the channel's connection settings and the mappings between the properties' rate plans and the channel's rooms and rates. Every channel defines its own settings and mapping fields, but the connection is built the same way for almost all of them. {% stepper %} {% step %} ### Get the adapter descriptor Every channel is described by an adapter descriptor: the connection settings it needs (`params`), the fields each mapping needs (`rate_params`), its restrictions, and whether it connects to a single property or several (`property_mapping`). ``` GET /api/v1/channels/adapter?code={code} ``` The catalog of all supported adapters is available at `GET /api/v1/channels/list`. {% endstep %} {% step %} ### Collect the connection settings Collect a value for each field in `params` — typically the property's identifier on the channel side (a hotel ID or hotel code), for some channels the account credentials or an access token. Some channels report the available values themselves: for them, call `POST /api/v1/channels/connection_details` with the account credentials and let the user pick the property or contract from the response. {% endstep %} {% step %} ### Test the settings ``` POST /api/v1/channels/test_connection ``` Send the adapter code and the collected settings as `{"channel": "...", "settings": {...}}`. The settings are sent to the channel, and the response reports whether the channel accepted them. No connection is created — if the response is `success: false`, correct the settings and test again. {% endstep %} {% step %} ### Read both sides of the mapping **The channel side.** Request the rooms and rates the channel exposes for the given settings: `POST /api/v1/channels/mapping_details` The request body is the same as for the test connection. For some channels, `POST /api/v1/channels/connection_details` additionally reports connection-level details to take into account when mapping — the currency the property trades in, for example. **The Channex side.** Pick the property (or properties) to connect, then list its room types and rate plans: ``` GET /api/v1/room_types/options?filter[property_id]={property_id} GET /api/v1/rate_plans/options?filter[property_id]={property_id}&multi_occupancy=true ``` {% endstep %} {% step %} ### Build the mapping For each Channex rate plan to be sold on the channel, build a mapping item: the `rate_plan_id` and a `settings` object with the fields listed in the adapter's `rate_params`, filled with the codes returned by the mapping details — the channel-side room and rate identifiers, the occupancy, the pricing type. {% endstep %} {% step %} ### Create the connection ``` POST /api/v1/channels ``` Send the adapter code, a title, the group and property IDs, the connection settings, and the mapping items as `rate_plans`. The connection is created disabled and exchanges no data until it is activated. {% endstep %} {% step %} ### Check readiness and activate ``` POST /api/v1/channels/{id}/check_readiness POST /api/v1/channels/{id}/activate ``` The readiness check lists the problems blocking activation; an empty list means the connection is ready. Activation starts the data exchange: a full synchronisation pushes availability, rates and restrictions to the channel, and bookings begin to flow back. {% endstep %} {% endstepper %} #### After the connection is live * `PUT /api/v1/channels/{id}`\ Update the settings or the mapping.\ A mapping is removed by sending it with `settings: null`. * `POST /api/v1/channels/{id}/deactivate`\ Stop the exchange with the channel. * `DELETE /api/v1/channels/{id}`\ Remove deactivated channel. {% hint style="warning" %} **Channels are different!** Some channels follow a different pipeline. Individual steps may be skipped (a channel with nothing to map has no mapping details), reordered (some channels report their available properties and contracts through the connection details before the settings can be collected), or replaced entirely — Airbnb requires an OAuth authorization instead of connection settings and is covered by its own guide. Always check the channel's own guide for the exact flow. {% endhint %} ## Channel-specific guides * [Agoda](/channel-api-examples/agoda.md) * [Airbnb](/channel-api-examples/airbnb.md) * [Bed-and-Breakfast.it](/channel-api-examples/bed-and-breakfast.it.md) * [Booking.com](/channel-api-examples/booking.com.md) * [Check24](/channel-api-examples/check24.md) * [eDreams](/channel-api-examples/edreams.md) * [Emerging Travel Group (Ostrovok)](/channel-api-examples/emerging-travel-group-ostrovok.md) * [Expedia](/channel-api-examples/expedia.md) * [Hopper](/channel-api-examples/hopper.md) * [Hotelbeds](/channel-api-examples/hotelbeds.md) * [HotelTonight](/channel-api-examples/hoteltonight.md) * [Lido](/channel-api-examples/lido.md) * [Klook](/channel-api-examples/klook.md) * [Mr and Mrs Smith](/channel-api-examples/mr-and-mrs-smith.md) * [Pitchup](/channel-api-examples/pitchup.md) * [Reconline](/channel-api-examples/reconline.md) * [Roibos](/channel-api-examples/roibos.md) * [VacanceSelect](/channel-api-examples/vacanceselect.md) * [World2Meet](/channel-api-examples/world2meet.md) ## API References ### Channel Adapters info ## List booking channel codes > List the short codes and names of known booking channels. ```json {"openapi":"3.1.0","info":{"title":"Channex.io — Channels","version":"0.0.0"},"tags":[{"name":"Channels","description":"Channel connections of Properties to booking channels (OTAs and channel managers), and the catalog of supported channel adapters."}],"servers":[{"url":"https://app.channex.io/api/v1","description":"Production server","variables":{}},{"url":"https://staging.channex.io/api/v1","description":"Staging server","variables":{}}],"security":[{"UserApiKeyAuth":[]}],"components":{"securitySchemes":{"UserApiKeyAuth":{"type":"apiKey","in":"header","name":"user-api-key","description":"API key for programmatic access, sent in the `user-api-key` header."}},"schemas":{"Channels.ChannelCode":{"type":"object","required":["code","name"],"properties":{"code":{"type":"string","description":"Short channel code."},"name":{"type":"string","description":"Channel display name."}},"description":"A known booking channel: short code and display name."},"Common.Errors.Unauthorized":{"type":"object","required":["errors"],"properties":{"errors":{"type":"object","required":["code","title"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"title":{"type":"string","enum":["Unauthorized"]}},"description":"Shape of a single JSON:API error object: a stable machine code plus a human-readable title."}},"description":"Authentication credentials are missing or invalid."}}},"paths":{"/channels/codes":{"get":{"operationId":"Channels_codes","summary":"List booking channel codes","description":"List the short codes and names of known booking channels.","parameters":[],"responses":{"200":{"description":"The request has succeeded.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Channels.ChannelCode"}}},"description":"A plain data-array envelope without pagination — used by reference/dictionary endpoints."}}}},"401":{"description":"Authentication credentials are missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.Unauthorized"}}}}},"tags":["Channels"]}}}} ``` ## List the supported channel adapters > List the descriptors of every supported channel adapter. ```json {"openapi":"3.1.0","info":{"title":"Channex.io — Channels","version":"0.0.0"},"tags":[{"name":"Channels","description":"Channel connections of Properties to booking channels (OTAs and channel managers), and the catalog of supported channel adapters."}],"servers":[{"url":"https://app.channex.io/api/v1","description":"Production server","variables":{}},{"url":"https://staging.channex.io/api/v1","description":"Staging server","variables":{}}],"security":[{"UserApiKeyAuth":[]}],"components":{"securitySchemes":{"UserApiKeyAuth":{"type":"apiKey","in":"header","name":"user-api-key","description":"API key for programmatic access, sent in the `user-api-key` header."}},"schemas":{"Channels.ChannelAdapter":{"type":"object","required":["code","title","params","kind","actions","mapping_mode","message_support","property_mapping"],"properties":{"code":{"type":"string","description":"Adapter code."},"title":{"type":"string","description":"Channel display name."},"params":{"type":"object","unevaluatedProperties":{"$ref":"#/components/schemas/Channels.ChannelAdapterParam"},"description":"Connection form fields of the channel, by field name."},"kind":{"allOf":[{"$ref":"#/components/schemas/Channels.ChannelKind"}],"description":"Kind of the channel."},"actions":{"type":"array","items":{"type":"string"},"description":"Extra actions the channel supports. Possible values: `load_future_reservations`."},"mapping_mode":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"How rooms and rates are mapped to the channel. Possible values: `room_rate_multioccupancy`, `direct`, `listing`, `tree`."},"message_support":{"type":"boolean","description":"Whether the channel supports guest messaging."},"property_mapping":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Whether one connection serves a single property or multiple. Possible values: `single`, `multiple`."},"rate_params":{"anyOf":[{"type":"object","unevaluatedProperties":{"$ref":"#/components/schemas/Channels.ChannelAdapterParam"}},{"type":"null"}],"description":"Rate mapping form fields, by field name."}},"description":"Descriptor of a channel adapter: identity, connection form fields, and mapping capabilities."},"Channels.ChannelAdapterParam":{"type":"object","required":["position","type"],"properties":{"position":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.nonNegativeInt"}],"description":"Order of the field in the form, counted from 0."},"type":{"allOf":[{"$ref":"#/components/schemas/Channels.ChannelAdapterParamType"}],"description":"Field control type."},"title":{"type":"string","description":"Human-readable field label."},"default":{"anyOf":[{"type":"string"},{"type":"boolean"},{"type":"integer"}],"description":"Default value of the field. Its type matches the field control type."},"options":{"type":"array","items":{"type":"string"},"description":"Allowed values of `select` and `switch` fields."},"rules":{"type":"array","items":{"$ref":"#/components/schemas/Channels.ChannelAdapterParamRule"},"description":"Conditional rules depending on the values of other fields."}},"description":"Descriptor of a single form field of a channel connection or rate mapping."},"Common.Scalars.nonNegativeInt":{"type":"integer","format":"int32","minimum":0},"Channels.ChannelAdapterParamType":{"type":"string","enum":["string","boolean","integer","number","select","switch","password","hidden","slug"],"description":"Control type of a channel adapter form field."},"Channels.ChannelAdapterParamRule":{"type":"object","required":["apply","when","influence_field","with_value"],"properties":{"apply":{"type":"string","description":"Effect applied to the field. Possible values: `hidden`."},"when":{"anyOf":[{"type":"boolean"},{"type":"string"}],"description":"Value of the influencing field at which the rule applies."},"influence_field":{"type":"string","description":"Name of the field whose value the rule depends on."},"with_value":{"type":"string","description":"Value assigned to the field while the rule applies."}},"description":"A conditional rule of a form field: the effect applied while another field holds a given value."},"Channels.ChannelKind":{"type":"string","enum":["ota","meta","cm"],"description":"Kind of a channel: an online travel agency, a metasearch engine, or a channel manager."},"Common.Errors.Unauthorized":{"type":"object","required":["errors"],"properties":{"errors":{"type":"object","required":["code","title"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"title":{"type":"string","enum":["Unauthorized"]}},"description":"Shape of a single JSON:API error object: a stable machine code plus a human-readable title."}},"description":"Authentication credentials are missing or invalid."}}},"paths":{"/channels/list":{"get":{"operationId":"Channels_adapters","summary":"List the supported channel adapters","description":"List the descriptors of every supported channel adapter.","parameters":[],"responses":{"200":{"description":"The request has succeeded.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Channels.ChannelAdapter"}}},"description":"A plain data-array envelope without pagination — used by reference/dictionary endpoints."}}}},"401":{"description":"Authentication credentials are missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.Unauthorized"}}}}},"tags":["Channels"]}}}} ``` ## Retrieve a channel adapter > Return the descriptor of a single channel adapter. ```json {"openapi":"3.1.0","info":{"title":"Channex.io — Channels","version":"0.0.0"},"tags":[{"name":"Channels","description":"Channel connections of Properties to booking channels (OTAs and channel managers), and the catalog of supported channel adapters."}],"servers":[{"url":"https://app.channex.io/api/v1","description":"Production server","variables":{}},{"url":"https://staging.channex.io/api/v1","description":"Staging server","variables":{}}],"security":[{"UserApiKeyAuth":[]}],"components":{"securitySchemes":{"UserApiKeyAuth":{"type":"apiKey","in":"header","name":"user-api-key","description":"API key for programmatic access, sent in the `user-api-key` header."}},"schemas":{"Channels.ChannelAdapter":{"type":"object","required":["code","title","params","kind","actions","mapping_mode","message_support","property_mapping"],"properties":{"code":{"type":"string","description":"Adapter code."},"title":{"type":"string","description":"Channel display name."},"params":{"type":"object","unevaluatedProperties":{"$ref":"#/components/schemas/Channels.ChannelAdapterParam"},"description":"Connection form fields of the channel, by field name."},"kind":{"allOf":[{"$ref":"#/components/schemas/Channels.ChannelKind"}],"description":"Kind of the channel."},"actions":{"type":"array","items":{"type":"string"},"description":"Extra actions the channel supports. Possible values: `load_future_reservations`."},"mapping_mode":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"How rooms and rates are mapped to the channel. Possible values: `room_rate_multioccupancy`, `direct`, `listing`, `tree`."},"message_support":{"type":"boolean","description":"Whether the channel supports guest messaging."},"property_mapping":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Whether one connection serves a single property or multiple. Possible values: `single`, `multiple`."},"rate_params":{"anyOf":[{"type":"object","unevaluatedProperties":{"$ref":"#/components/schemas/Channels.ChannelAdapterParam"}},{"type":"null"}],"description":"Rate mapping form fields, by field name."}},"description":"Descriptor of a channel adapter: identity, connection form fields, and mapping capabilities."},"Channels.ChannelAdapterParam":{"type":"object","required":["position","type"],"properties":{"position":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.nonNegativeInt"}],"description":"Order of the field in the form, counted from 0."},"type":{"allOf":[{"$ref":"#/components/schemas/Channels.ChannelAdapterParamType"}],"description":"Field control type."},"title":{"type":"string","description":"Human-readable field label."},"default":{"anyOf":[{"type":"string"},{"type":"boolean"},{"type":"integer"}],"description":"Default value of the field. Its type matches the field control type."},"options":{"type":"array","items":{"type":"string"},"description":"Allowed values of `select` and `switch` fields."},"rules":{"type":"array","items":{"$ref":"#/components/schemas/Channels.ChannelAdapterParamRule"},"description":"Conditional rules depending on the values of other fields."}},"description":"Descriptor of a single form field of a channel connection or rate mapping."},"Common.Scalars.nonNegativeInt":{"type":"integer","format":"int32","minimum":0},"Channels.ChannelAdapterParamType":{"type":"string","enum":["string","boolean","integer","number","select","switch","password","hidden","slug"],"description":"Control type of a channel adapter form field."},"Channels.ChannelAdapterParamRule":{"type":"object","required":["apply","when","influence_field","with_value"],"properties":{"apply":{"type":"string","description":"Effect applied to the field. Possible values: `hidden`."},"when":{"anyOf":[{"type":"boolean"},{"type":"string"}],"description":"Value of the influencing field at which the rule applies."},"influence_field":{"type":"string","description":"Name of the field whose value the rule depends on."},"with_value":{"type":"string","description":"Value assigned to the field while the rule applies."}},"description":"A conditional rule of a form field: the effect applied while another field holds a given value."},"Channels.ChannelKind":{"type":"string","enum":["ota","meta","cm"],"description":"Kind of a channel: an online travel agency, a metasearch engine, or a channel manager."},"Common.Errors.BadRequest":{"type":"object","required":["errors"],"properties":{"errors":{"type":"object","required":["code","title"],"properties":{"code":{"type":"string","enum":["bad_request"]},"title":{"type":"string","enum":["Bad Request"]}},"description":"Shape of a single JSON:API error object: a stable machine code plus a human-readable title."}},"description":"The request cannot be processed in the current state."},"Common.Errors.Unauthorized":{"type":"object","required":["errors"],"properties":{"errors":{"type":"object","required":["code","title"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"title":{"type":"string","enum":["Unauthorized"]}},"description":"Shape of a single JSON:API error object: a stable machine code plus a human-readable title."}},"description":"Authentication credentials are missing or invalid."}}},"paths":{"/channels/adapter":{"get":{"operationId":"Channels_adapter","summary":"Retrieve a channel adapter","description":"Return the descriptor of a single channel adapter.","parameters":[{"name":"code","in":"query","required":true,"description":"Adapter code.","schema":{"type":"string"},"explode":false}],"responses":{"200":{"description":"The request has succeeded.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Channels.ChannelAdapter"}},"description":"JSON:API document wrapping a single resource."}}}},"400":{"description":"The request cannot be processed in the current state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.BadRequest"}}}},"401":{"description":"Authentication credentials are missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.Unauthorized"}}}}},"tags":["Channels"]}}}} ``` ### Pre-connection Check and Probes ## Test channel credentials > Test a set of channel credentials. The credentials are sent to the channel,\ > and the response reports whether the channel accepted them.\ > \ > No channel connection is created or changed, and none is needed — the\ > credentials are supplied in the request, so they can be tested before the\ > connection is created. Credentials the channel rejects, and a channel that\ > cannot be reached, are reported as \`success: false\` in the response body\ > rather than as an error.\ > \ > Channels that identify a property by a single code also require that code to\ > be free: the test fails when another channel connection already uses it. ```json {"openapi":"3.1.0","info":{"title":"Channex.io — Channels","version":"0.0.0"},"tags":[{"name":"Channels","description":"Channel connections of Properties to booking channels (OTAs and channel managers), and the catalog of supported channel adapters."}],"servers":[{"url":"https://app.channex.io/api/v1","description":"Production server","variables":{}},{"url":"https://staging.channex.io/api/v1","description":"Staging server","variables":{}}],"security":[{"UserApiKeyAuth":[]}],"components":{"securitySchemes":{"UserApiKeyAuth":{"type":"apiKey","in":"header","name":"user-api-key","description":"API key for programmatic access, sent in the `user-api-key` header."}},"schemas":{"Channels.ChannelConnectionTest":{"type":"object","required":["success","errors"],"properties":{"success":{"type":"boolean","description":"Whether the channel accepted the credentials."},"errors":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"object","unevaluatedProperties":{}},{"type":"null"}],"description":"Why the test failed, as reported by the channel; `null` when the test succeeded, and when the channel gave no reason."}},"description":"Result of a channel credentials test."},"Common.Errors.Unauthorized":{"type":"object","required":["errors"],"properties":{"errors":{"type":"object","required":["code","title"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"title":{"type":"string","enum":["Unauthorized"]}},"description":"Shape of a single JSON:API error object: a stable machine code plus a human-readable title."}},"description":"Authentication credentials are missing or invalid."},"Common.Errors.InvalidArguments":{"type":"object","required":["errors"],"properties":{"errors":{"$ref":"#/components/schemas/Common.Errors.InvalidArgumentsObject"}},"description":"The request has missing or invalid arguments; `details` lists the messages per argument."},"Common.Errors.InvalidArgumentsObject":{"type":"object","required":["code","title","details"],"properties":{"code":{"type":"string","enum":["bad_request"]},"title":{"type":"string","enum":["Bad Request"]},"details":{"type":"object","unevaluatedProperties":{"type":"array","items":{"type":"string"}},"description":"Maps each invalid argument to the list of validation messages for that argument."}},"description":"Error object for invalid request arguments, adding per-argument messages."},"Channels.ChannelSettingsProbeRequest":{"type":"object","required":["channel","settings"],"properties":{"channel":{"type":"string","description":"Adapter code of the channel. See the `/channels/list` endpoint for supported values."},"settings":{"type":"object","unevaluatedProperties":{},"description":"Connection settings of the channel: the credentials and identifiers the\nchannel needs, such as `hotel_id` for Booking.com. The keys are specific to\nthe channel adapter — see `params` in the adapter descriptor returned by\n`GET /channels/adapter`."}},"description":"Channel credentials to probe."}}},"paths":{"/channels/test_connection":{"post":{"operationId":"Channels_testConnection","summary":"Test channel credentials","description":"Test a set of channel credentials. The credentials are sent to the channel,\nand the response reports whether the channel accepted them.\n\nNo channel connection is created or changed, and none is needed — the\ncredentials are supplied in the request, so they can be tested before the\nconnection is created. Credentials the channel rejects, and a channel that\ncannot be reached, are reported as `success: false` in the response body\nrather than as an error.\n\nChannels that identify a property by a single code also require that code to\nbe free: the test fails when another channel connection already uses it.","parameters":[],"responses":{"200":{"description":"The request has succeeded.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Channels.ChannelConnectionTest"}},"description":"JSON:API document wrapping a single resource."}}}},"401":{"description":"Authentication credentials are missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.Unauthorized"}}}},"422":{"description":"The request has missing or invalid arguments; `details` lists the messages per argument.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.InvalidArguments"}}}}},"tags":["Channels"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Channels.ChannelSettingsProbeRequest"}}}}}}}} ``` ## Retrieve the connection details of a channel > Retrieve the connection details a channel reports for the given credentials.\ > Supported for Booking.com, Expedia and Agoda channels; they report the\ > currency the property trades in, and Booking.com additionally reports the\ > state of each connection type it exchanges data over — reservations, rates\ > and availability, guest reviews, content and reporting.\ > \ > The credentials are supplied in the request, so the details can be fetched\ > before the channel connection is created. They are requested from the\ > channel on every call, and the fields of \`attributes\` are defined by the\ > channel. ```json {"openapi":"3.1.0","info":{"title":"Channex.io — Channels","version":"0.0.0"},"tags":[{"name":"Channels","description":"Channel connections of Properties to booking channels (OTAs and channel managers), and the catalog of supported channel adapters."}],"servers":[{"url":"https://app.channex.io/api/v1","description":"Production server","variables":{}},{"url":"https://staging.channex.io/api/v1","description":"Staging server","variables":{}}],"security":[{"UserApiKeyAuth":[]}],"components":{"securitySchemes":{"UserApiKeyAuth":{"type":"apiKey","in":"header","name":"user-api-key","description":"API key for programmatic access, sent in the `user-api-key` header."}},"schemas":{"Channels.ChannelConnectionDetailsResource":{"type":"object","required":["type","attributes"],"properties":{"type":{"type":"string","enum":["connection_details"]},"attributes":{"anyOf":[{"type":"object","unevaluatedProperties":{}},{"type":"null"}],"description":"Connection details as reported by the channel, in the shape defined by that channel; `null` when the channel reported no details."}},"description":"Connection details of a channel."},"Channels.ChannelProbeError":{"type":"object","required":["errors"],"properties":{"errors":{"$ref":"#/components/schemas/Channels.ChannelProbeErrorObject"}},"description":"The channel rejected the credentials."},"Channels.ChannelProbeErrorObject":{"type":"object","required":["code","title"],"properties":{"code":{"type":"string","enum":["bad_request"]},"title":{"type":"string","enum":["Bad Request"]},"details":{"description":"The error reported by the channel, when it gave one."}},"description":"Error object for credentials the channel rejected, relaying the channel's own error."},"Common.Errors.Unauthorized":{"type":"object","required":["errors"],"properties":{"errors":{"type":"object","required":["code","title"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"title":{"type":"string","enum":["Unauthorized"]}},"description":"Shape of a single JSON:API error object: a stable machine code plus a human-readable title."}},"description":"Authentication credentials are missing or invalid."},"Common.Errors.InvalidArguments":{"type":"object","required":["errors"],"properties":{"errors":{"$ref":"#/components/schemas/Common.Errors.InvalidArgumentsObject"}},"description":"The request has missing or invalid arguments; `details` lists the messages per argument."},"Common.Errors.InvalidArgumentsObject":{"type":"object","required":["code","title","details"],"properties":{"code":{"type":"string","enum":["bad_request"]},"title":{"type":"string","enum":["Bad Request"]},"details":{"type":"object","unevaluatedProperties":{"type":"array","items":{"type":"string"}},"description":"Maps each invalid argument to the list of validation messages for that argument."}},"description":"Error object for invalid request arguments, adding per-argument messages."},"Channels.ChannelSettingsProbeRequest":{"type":"object","required":["channel","settings"],"properties":{"channel":{"type":"string","description":"Adapter code of the channel. See the `/channels/list` endpoint for supported values."},"settings":{"type":"object","unevaluatedProperties":{},"description":"Connection settings of the channel: the credentials and identifiers the\nchannel needs, such as `hotel_id` for Booking.com. The keys are specific to\nthe channel adapter — see `params` in the adapter descriptor returned by\n`GET /channels/adapter`."}},"description":"Channel credentials to probe."}}},"paths":{"/channels/connection_details":{"post":{"operationId":"Channels_connectionDetails","summary":"Retrieve the connection details of a channel","description":"Retrieve the connection details a channel reports for the given credentials.\nSupported for Booking.com, Expedia and Agoda channels; they report the\ncurrency the property trades in, and Booking.com additionally reports the\nstate of each connection type it exchanges data over — reservations, rates\nand availability, guest reviews, content and reporting.\n\nThe credentials are supplied in the request, so the details can be fetched\nbefore the channel connection is created. They are requested from the\nchannel on every call, and the fields of `attributes` are defined by the\nchannel.","parameters":[],"responses":{"200":{"description":"The request has succeeded.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Channels.ChannelConnectionDetailsResource"}},"description":"JSON:API document wrapping a single resource."}}}},"400":{"description":"The channel rejected the credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Channels.ChannelProbeError"}}}},"401":{"description":"Authentication credentials are missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.Unauthorized"}}}},"422":{"description":"The request has missing or invalid arguments; `details` lists the messages per argument.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.InvalidArguments"}}}}},"tags":["Channels"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Channels.ChannelSettingsProbeRequest"}}}}}}}} ``` ## Retrieve the mapping details of a channel > Retrieve the mapping details of a channel: the rooms and rates the channel\ > exposes for the given credentials, which the property's room types and rate\ > plans are then mapped to.\ > \ > The credentials are supplied in the request, so the details can be fetched\ > before the channel connection is created. They are requested from the\ > channel on every call. The shape of the response is defined by the channel:\ > channels that organise their inventory differently report their own entities\ > instead — Airbnb its listings, for one — and a channel that exposes nothing\ > to map returns an empty object. ```json {"openapi":"3.1.0","info":{"title":"Channex.io — Channels","version":"0.0.0"},"tags":[{"name":"Channels","description":"Channel connections of Properties to booking channels (OTAs and channel managers), and the catalog of supported channel adapters."}],"servers":[{"url":"https://app.channex.io/api/v1","description":"Production server","variables":{}},{"url":"https://staging.channex.io/api/v1","description":"Staging server","variables":{}}],"security":[{"UserApiKeyAuth":[]}],"components":{"securitySchemes":{"UserApiKeyAuth":{"type":"apiKey","in":"header","name":"user-api-key","description":"API key for programmatic access, sent in the `user-api-key` header."}},"schemas":{"Channels.ChannelMappingDetails":{"type":"object","unevaluatedProperties":{},"description":"Mapping details of a channel: the rooms and rates the channel exposes for the\ngiven credentials, in the shape defined by that channel. A channel that\nexposes nothing to map returns an empty object."},"Common.Errors.BadRequest":{"type":"object","required":["errors"],"properties":{"errors":{"type":"object","required":["code","title"],"properties":{"code":{"type":"string","enum":["bad_request"]},"title":{"type":"string","enum":["Bad Request"]}},"description":"Shape of a single JSON:API error object: a stable machine code plus a human-readable title."}},"description":"The request cannot be processed in the current state."},"Common.Errors.Unauthorized":{"type":"object","required":["errors"],"properties":{"errors":{"type":"object","required":["code","title"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"title":{"type":"string","enum":["Unauthorized"]}},"description":"Shape of a single JSON:API error object: a stable machine code plus a human-readable title."}},"description":"Authentication credentials are missing or invalid."},"Common.Errors.NotFound":{"type":"object","required":["errors"],"properties":{"errors":{"type":"object","required":["code","title"],"properties":{"code":{"type":"string","enum":["resource_not_found"]},"title":{"type":"string","enum":["Resource Not Found"]}},"description":"Shape of a single JSON:API error object: a stable machine code plus a human-readable title."}},"description":"The requested resource does not exist."},"Common.Errors.InvalidArguments":{"type":"object","required":["errors"],"properties":{"errors":{"$ref":"#/components/schemas/Common.Errors.InvalidArgumentsObject"}},"description":"The request has missing or invalid arguments; `details` lists the messages per argument."},"Common.Errors.InvalidArgumentsObject":{"type":"object","required":["code","title","details"],"properties":{"code":{"type":"string","enum":["bad_request"]},"title":{"type":"string","enum":["Bad Request"]},"details":{"type":"object","unevaluatedProperties":{"type":"array","items":{"type":"string"}},"description":"Maps each invalid argument to the list of validation messages for that argument."}},"description":"Error object for invalid request arguments, adding per-argument messages."},"Channels.ChannelActionFailure":{"type":"object","required":["errors"],"properties":{"errors":{}},"description":"The channel could not return the details; `errors` carries the reason the channel reported, or `null` when it gave none."},"Common.Errors.ServiceUnavailable":{"type":"object","required":["errors"],"properties":{"errors":{"type":"object","required":["code","title"],"properties":{"code":{"type":"string","enum":["service_unavailable"]},"title":{"type":"string","enum":["Service Temporary Unavailable"]}},"description":"Shape of a single JSON:API error object: a stable machine code plus a human-readable title."}},"description":"A backing service is temporarily unavailable; retry the request later."},"Channels.ChannelSettingsProbeRequest":{"type":"object","required":["channel","settings"],"properties":{"channel":{"type":"string","description":"Adapter code of the channel. See the `/channels/list` endpoint for supported values."},"settings":{"type":"object","unevaluatedProperties":{},"description":"Connection settings of the channel: the credentials and identifiers the\nchannel needs, such as `hotel_id` for Booking.com. The keys are specific to\nthe channel adapter — see `params` in the adapter descriptor returned by\n`GET /channels/adapter`."}},"description":"Channel credentials to probe."}}},"paths":{"/channels/mapping_details":{"post":{"operationId":"Channels_mappingDetails","summary":"Retrieve the mapping details of a channel","description":"Retrieve the mapping details of a channel: the rooms and rates the channel\nexposes for the given credentials, which the property's room types and rate\nplans are then mapped to.\n\nThe credentials are supplied in the request, so the details can be fetched\nbefore the channel connection is created. They are requested from the\nchannel on every call. The shape of the response is defined by the channel:\nchannels that organise their inventory differently report their own entities\ninstead — Airbnb its listings, for one — and a channel that exposes nothing\nto map returns an empty object.","parameters":[],"responses":{"200":{"description":"The request has succeeded.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Channels.ChannelMappingDetails"}},"description":"JSON:API document wrapping a single resource."}}}},"400":{"description":"The request cannot be processed in the current state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.BadRequest"}}}},"401":{"description":"Authentication credentials are missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.Unauthorized"}}}},"404":{"description":"The requested resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.NotFound"}}}},"422":{"description":"The request has missing or invalid arguments; `details` lists the messages per argument.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Common.Errors.InvalidArguments"},{"$ref":"#/components/schemas/Channels.ChannelActionFailure"}]}}}},"503":{"description":"A backing service is temporarily unavailable; retry the request later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.ServiceUnavailable"}}}}},"tags":["Channels"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Channels.ChannelSettingsProbeRequest"}}}}}}}} ``` ### Channel CRUD Operations ## List channel connections > List the channel connections of the user's properties. Results are scoped to the properties and groups the user has access to. ```json {"openapi":"3.1.0","info":{"title":"Channex.io — Channels","version":"0.0.0"},"tags":[{"name":"Channels","description":"Channel connections of Properties to booking channels (OTAs and channel managers), and the catalog of supported channel adapters."}],"servers":[{"url":"https://app.channex.io/api/v1","description":"Production server","variables":{}},{"url":"https://staging.channex.io/api/v1","description":"Staging server","variables":{}}],"security":[{"UserApiKeyAuth":[]}],"components":{"securitySchemes":{"UserApiKeyAuth":{"type":"apiKey","in":"header","name":"user-api-key","description":"API key for programmatic access, sent in the `user-api-key` header."}},"schemas":{"Common.Scalars.id":{"type":"string","format":"uuid"},"Common.Scalars.currency":{"type":"string","minLength":3,"maxLength":3,"description":"ISO 4217 alphabetic currency code. See the `/currencies` endpoint for supported values."},"Common.Scalars.positiveInt":{"type":"integer","format":"int32","minimum":1},"Common.Pagination.OrderDirection":{"type":"string","enum":["asc","desc"],"description":"Sort direction for list results."},"Channels.Channel":{"type":"object","required":["id","title","channel","currency","is_active","settings","rate_plans","properties","actions","expected_removal_date","inserted_at","updated_at"],"properties":{"id":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.id"}]},"title":{"type":"string","description":"Title of the channel connection."},"channel":{"type":"string","description":"Adapter code of the channel. See the `/channels/list` endpoint for supported values."},"currency":{"anyOf":[{"$ref":"#/components/schemas/Common.Scalars.currency"},{"type":"null"}],"description":"Currency the channel connection trades in; `null` when the connection does not define one."},"is_active":{"type":"boolean","description":"Whether the channel connection is enabled. Disabled connections do not send updates to the channel. Read-only: use `POST /channels/{id}/activate` and `POST /channels/{id}/deactivate` to change it."},"settings":{"allOf":[{"$ref":"#/components/schemas/Channels.ChannelConnectionSettings"}],"description":"Connection settings. Apart from `derived_option`, the keys are defined by the channel adapter — see `params` in the adapter descriptor returned by `GET /channels/adapter`."},"rate_plans":{"type":"array","items":{"$ref":"#/components/schemas/Channels.ChannelRatePlanMapping"},"description":"Rate plans of the property mapped to rates of the channel. Empty while the connection is unmapped."},"properties":{"type":"array","items":{"$ref":"#/components/schemas/Common.Scalars.id"},"description":"UUIDs of the properties connected through this channel connection. Channel Adapters with `property_mapping` equal to `single` accept only 1 Property."},"actions":{"type":"array","items":{"type":"string"},"description":"Actions the channel adapter supports on this connection, invoked through `POST /channels/{id}/execute/{action}`. Possible values: `load_future_reservations`."},"expected_removal_date":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date","description":"Date the channel connection is scheduled to be removed on. `null` while no removal is scheduled. Get more information about retention period at [our docs](https://docs.channex.io/guides/channex-retention-periods)."},"inserted_at":{"type":"string","format":"date-time","description":"When the channel connection was created (ISO 8601, no timezone offset)."},"updated_at":{"type":"string","format":"date-time","description":"When the channel connection was last changed (ISO 8601, no timezone offset)."},"status":{"allOf":[{"$ref":"#/components/schemas/Channels.ChannelStatus"}],"description":"Connection status. Present on Google Hotel ARI channel connections only."}},"description":"A channel connection: the link between a property and a booking channel."},"Channels.ChannelConnectionSettings":{"type":"object","properties":{"derived_option":{"allOf":[{"$ref":"#/components/schemas/RatePlans.DerivedOption"}],"description":"Value-modification rules applied to the values pushed to the channel: each\nlisted restriction is sent with the rules applied to the mapped rate\nplan's value. The rules take effect when a rate plan mapping is created or\nupdated. A `derived_option` in a mapping's own settings overrides the\nconnection-level rules restriction by restriction."}},"unevaluatedProperties":{},"description":"Connection settings of a channel connection. Apart from `derived_option`, the keys are defined by the channel adapter — see `params` in the adapter descriptor returned by `GET /channels/adapter`."},"RatePlans.DerivedOption":{"type":"object","unevaluatedProperties":{"type":"array","items":{"type":"array","prefixItems":[{"type":"string","enum":["increase_by_amount","increase_by_percent","decrease_by_amount","decrease_by_percent"],"description":"A value-modification rule applied to the original value."},{"type":"string"}]}},"description":"Value-modification rules for the `rate` restriction, keyed by restriction\nname. Each value is a list of modification steps applied to the original\nvalue in order, left to right; a step is a `[rule, argument]` pair whose\nargument is the amount or percent as a decimal string, e.g.\n`[\"increase_by_percent\", \"5.00\"]`."},"Channels.ChannelRatePlanMapping":{"type":"object","required":["id","rate_plan_id","settings"],"properties":{"id":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.id"}],"description":"UUID of the mapping."},"rate_plan_id":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.id"}],"description":"UUID of the mapped rate plan."},"settings":{"type":"object","unevaluatedProperties":{},"description":"Mapping settings. The keys are defined by the channel adapter — see `rate_params` in the adapter descriptor returned by `GET /channels/adapter`."}},"description":"A rate plan of the property mapped to a rate of the channel."},"Channels.ChannelStatus":{"type":"string","enum":["active","pending","temporal_error","permanent_error"],"description":"Connection status of a channel connection."},"Channels.ChannelRelationships":{"type":"object","required":["group","properties"],"properties":{"group":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.id"}]},"type":{"type":"string","enum":["group"]}},"required":["id","type"]}},"required":["data"],"description":"Group the channel connection belongs to."},"properties":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.id"}]},"type":{"type":"string","enum":["property"]}},"required":["id","type"]}}},"required":["data"],"description":"Properties connected through this channel connection."}},"description":"Relationships of a channel connection resource."},"Common.Pagination.PaginationMeta":{"type":"object","required":["page","limit","total","order_by","order_direction"],"properties":{"page":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.positiveInt"}],"description":"Page returned, counted from 1."},"limit":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.positiveInt"}],"maximum":100,"description":"Number of items per page. At most 100 — requests with `pagination[limit]` above 100 are rejected with `400 Bad Request`."},"total":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.nonNegativeInt"}]},"order_by":{"type":"string","description":"Field the results are ordered by."},"order_direction":{"allOf":[{"$ref":"#/components/schemas/Common.Pagination.OrderDirection"}],"description":"Direction the results are ordered in."}},"description":"Pagination and ordering metadata attached to list responses."},"Common.Scalars.nonNegativeInt":{"type":"integer","format":"int32","minimum":0},"Common.Errors.Unauthorized":{"type":"object","required":["errors"],"properties":{"errors":{"type":"object","required":["code","title"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"title":{"type":"string","enum":["Unauthorized"]}},"description":"Shape of a single JSON:API error object: a stable machine code plus a human-readable title."}},"description":"Authentication credentials are missing or invalid."},"Common.Errors.Forbidden":{"type":"object","required":["errors"],"properties":{"errors":{"type":"object","required":["code","title"],"properties":{"code":{"type":"string","enum":["forbidden"]},"title":{"type":"string","enum":["Forbidden"]}},"description":"Shape of a single JSON:API error object: a stable machine code plus a human-readable title."}},"description":"The authenticated user lacks permission to perform this action."},"Common.Errors.ServiceUnavailable":{"type":"object","required":["errors"],"properties":{"errors":{"type":"object","required":["code","title"],"properties":{"code":{"type":"string","enum":["service_unavailable"]},"title":{"type":"string","enum":["Service Temporary Unavailable"]}},"description":"Shape of a single JSON:API error object: a stable machine code plus a human-readable title."}},"description":"A backing service is temporarily unavailable; retry the request later."}},"parameters":{"Common.Pagination.PaginationParams.page":{"name":"pagination[page]","in":"query","required":false,"description":"Page to return, counted from 1.","schema":{"$ref":"#/components/schemas/Common.Scalars.positiveInt"},"explode":false},"Common.Pagination.PaginationParams.limit":{"name":"pagination[limit]","in":"query","required":false,"description":"Number of items per page. Maximum is 100.","schema":{"$ref":"#/components/schemas/Common.Scalars.positiveInt","maximum":100},"explode":false}}},"paths":{"/channels":{"get":{"operationId":"Channels_list","summary":"List channel connections","description":"List the channel connections of the user's properties. Results are scoped to the properties and groups the user has access to.","parameters":[{"name":"filter[property_id]","in":"query","required":false,"description":"Return only channel connections of this property.","schema":{"$ref":"#/components/schemas/Common.Scalars.id"},"explode":false},{"name":"filter[room_type_id]","in":"query","required":false,"description":"Return only channel connections this room type is mapped to.","schema":{"$ref":"#/components/schemas/Common.Scalars.id"},"explode":false},{"name":"filter[group_id]","in":"query","required":false,"description":"Return only channel connections of this group.","schema":{"$ref":"#/components/schemas/Common.Scalars.id"},"explode":false},{"name":"filter[channel]","in":"query","required":false,"description":"Return only channel connections of this adapter. See the `/channels/list` endpoint for supported values.","schema":{"type":"string"},"explode":false},{"name":"filter[title]","in":"query","required":false,"description":"Return only channel connections with this exact title.","schema":{"type":"string"},"explode":false},{"name":"filter[currency]","in":"query","required":false,"description":"Return only channel connections trading in this currency.","schema":{"$ref":"#/components/schemas/Common.Scalars.currency"},"explode":false},{"name":"filter[is_active]","in":"query","required":false,"description":"Return only enabled or only disabled channel connections.","schema":{"type":"boolean"},"explode":false},{"$ref":"#/components/parameters/Common.Pagination.PaginationParams.page"},{"$ref":"#/components/parameters/Common.Pagination.PaginationParams.limit"},{"name":"order[title]","in":"query","required":false,"description":"Order channel connections by title. Applied by default, ascending.","schema":{"$ref":"#/components/schemas/Common.Pagination.OrderDirection"},"explode":false},{"name":"order[inserted_at]","in":"query","required":false,"description":"Order channel connections by creation time.","schema":{"$ref":"#/components/schemas/Common.Pagination.OrderDirection"},"explode":false}],"responses":{"200":{"description":"The request has succeeded.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","required":["type","id","attributes","relationships"],"properties":{"type":{"type":"string","enum":["channel"]},"id":{"$ref":"#/components/schemas/Common.Scalars.id"},"attributes":{"$ref":"#/components/schemas/Channels.Channel"},"relationships":{"$ref":"#/components/schemas/Channels.ChannelRelationships"}},"description":"A JSON:API resource object with typed attributes and relationships."}},"meta":{"$ref":"#/components/schemas/Common.Pagination.PaginationMeta"}},"description":"JSON:API document wrapping a collection of resources with pagination meta."}}}},"401":{"description":"Authentication credentials are missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.Unauthorized"}}}},"403":{"description":"The authenticated user lacks permission to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.Forbidden"}}}},"503":{"description":"A backing service is temporarily unavailable; retry the request later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.ServiceUnavailable"}}}}},"tags":["Channels"]}}}} ``` ## List channel connection options > List the user's channel connections as lightweight items: id, title and adapter code. ```json {"openapi":"3.1.0","info":{"title":"Channex.io — Channels","version":"0.0.0"},"tags":[{"name":"Channels","description":"Channel connections of Properties to booking channels (OTAs and channel managers), and the catalog of supported channel adapters."}],"servers":[{"url":"https://app.channex.io/api/v1","description":"Production server","variables":{}},{"url":"https://staging.channex.io/api/v1","description":"Staging server","variables":{}}],"security":[{"UserApiKeyAuth":[]}],"components":{"securitySchemes":{"UserApiKeyAuth":{"type":"apiKey","in":"header","name":"user-api-key","description":"API key for programmatic access, sent in the `user-api-key` header."}},"schemas":{"Channels.ChannelOptionResource":{"type":"object","required":["id","type","attributes"],"properties":{"id":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.id"}]},"type":{"type":"string","enum":["channel"]},"attributes":{"$ref":"#/components/schemas/Channels.ChannelOptionAttributes"}},"description":"A lightweight channel connection item: id, title and adapter code. No relationships."},"Common.Scalars.id":{"type":"string","format":"uuid"},"Channels.ChannelOptionAttributes":{"type":"object","required":["id","title","channel"],"properties":{"id":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.id"}]},"title":{"type":"string","description":"Channel connection title."},"channel":{"type":"string","description":"Adapter code of the channel."}},"description":"Attributes of a channel option item."},"Common.Errors.Unauthorized":{"type":"object","required":["errors"],"properties":{"errors":{"type":"object","required":["code","title"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"title":{"type":"string","enum":["Unauthorized"]}},"description":"Shape of a single JSON:API error object: a stable machine code plus a human-readable title."}},"description":"Authentication credentials are missing or invalid."}}},"paths":{"/channels/options":{"get":{"operationId":"Channels_options","summary":"List channel connection options","description":"List the user's channel connections as lightweight items: id, title and adapter code.","parameters":[],"responses":{"200":{"description":"The request has succeeded.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Channels.ChannelOptionResource"}}},"description":"A plain data-array envelope without pagination — used by reference/dictionary endpoints."}}}},"401":{"description":"Authentication credentials are missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.Unauthorized"}}}}},"tags":["Channels"]}}}} ``` ## Retrieve a channel connection > Retrieve a single channel connection.\ > \ > Unlike the list, the response carries the connection's known mappings —\ > see the \`known\_mappings\` relationship. ```json {"openapi":"3.1.0","info":{"title":"Channex.io — Channels","version":"0.0.0"},"tags":[{"name":"Channels","description":"Channel connections of Properties to booking channels (OTAs and channel managers), and the catalog of supported channel adapters."}],"servers":[{"url":"https://app.channex.io/api/v1","description":"Production server","variables":{}},{"url":"https://staging.channex.io/api/v1","description":"Staging server","variables":{}}],"security":[{"UserApiKeyAuth":[]}],"components":{"securitySchemes":{"UserApiKeyAuth":{"type":"apiKey","in":"header","name":"user-api-key","description":"API key for programmatic access, sent in the `user-api-key` header."}},"schemas":{"Common.Scalars.id":{"type":"string","format":"uuid"},"Channels.Channel":{"type":"object","required":["id","title","channel","currency","is_active","settings","rate_plans","properties","actions","expected_removal_date","inserted_at","updated_at"],"properties":{"id":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.id"}]},"title":{"type":"string","description":"Title of the channel connection."},"channel":{"type":"string","description":"Adapter code of the channel. See the `/channels/list` endpoint for supported values."},"currency":{"anyOf":[{"$ref":"#/components/schemas/Common.Scalars.currency"},{"type":"null"}],"description":"Currency the channel connection trades in; `null` when the connection does not define one."},"is_active":{"type":"boolean","description":"Whether the channel connection is enabled. Disabled connections do not send updates to the channel. Read-only: use `POST /channels/{id}/activate` and `POST /channels/{id}/deactivate` to change it."},"settings":{"allOf":[{"$ref":"#/components/schemas/Channels.ChannelConnectionSettings"}],"description":"Connection settings. Apart from `derived_option`, the keys are defined by the channel adapter — see `params` in the adapter descriptor returned by `GET /channels/adapter`."},"rate_plans":{"type":"array","items":{"$ref":"#/components/schemas/Channels.ChannelRatePlanMapping"},"description":"Rate plans of the property mapped to rates of the channel. Empty while the connection is unmapped."},"properties":{"type":"array","items":{"$ref":"#/components/schemas/Common.Scalars.id"},"description":"UUIDs of the properties connected through this channel connection. Channel Adapters with `property_mapping` equal to `single` accept only 1 Property."},"actions":{"type":"array","items":{"type":"string"},"description":"Actions the channel adapter supports on this connection, invoked through `POST /channels/{id}/execute/{action}`. Possible values: `load_future_reservations`."},"expected_removal_date":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date","description":"Date the channel connection is scheduled to be removed on. `null` while no removal is scheduled. Get more information about retention period at [our docs](https://docs.channex.io/guides/channex-retention-periods)."},"inserted_at":{"type":"string","format":"date-time","description":"When the channel connection was created (ISO 8601, no timezone offset)."},"updated_at":{"type":"string","format":"date-time","description":"When the channel connection was last changed (ISO 8601, no timezone offset)."},"status":{"allOf":[{"$ref":"#/components/schemas/Channels.ChannelStatus"}],"description":"Connection status. Present on Google Hotel ARI channel connections only."}},"description":"A channel connection: the link between a property and a booking channel."},"Common.Scalars.currency":{"type":"string","minLength":3,"maxLength":3,"description":"ISO 4217 alphabetic currency code. See the `/currencies` endpoint for supported values."},"Channels.ChannelConnectionSettings":{"type":"object","properties":{"derived_option":{"allOf":[{"$ref":"#/components/schemas/RatePlans.DerivedOption"}],"description":"Value-modification rules applied to the values pushed to the channel: each\nlisted restriction is sent with the rules applied to the mapped rate\nplan's value. The rules take effect when a rate plan mapping is created or\nupdated. A `derived_option` in a mapping's own settings overrides the\nconnection-level rules restriction by restriction."}},"unevaluatedProperties":{},"description":"Connection settings of a channel connection. Apart from `derived_option`, the keys are defined by the channel adapter — see `params` in the adapter descriptor returned by `GET /channels/adapter`."},"RatePlans.DerivedOption":{"type":"object","unevaluatedProperties":{"type":"array","items":{"type":"array","prefixItems":[{"type":"string","enum":["increase_by_amount","increase_by_percent","decrease_by_amount","decrease_by_percent"],"description":"A value-modification rule applied to the original value."},{"type":"string"}]}},"description":"Value-modification rules for the `rate` restriction, keyed by restriction\nname. Each value is a list of modification steps applied to the original\nvalue in order, left to right; a step is a `[rule, argument]` pair whose\nargument is the amount or percent as a decimal string, e.g.\n`[\"increase_by_percent\", \"5.00\"]`."},"Channels.ChannelRatePlanMapping":{"type":"object","required":["id","rate_plan_id","settings"],"properties":{"id":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.id"}],"description":"UUID of the mapping."},"rate_plan_id":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.id"}],"description":"UUID of the mapped rate plan."},"settings":{"type":"object","unevaluatedProperties":{},"description":"Mapping settings. The keys are defined by the channel adapter — see `rate_params` in the adapter descriptor returned by `GET /channels/adapter`."}},"description":"A rate plan of the property mapped to a rate of the channel."},"Channels.ChannelStatus":{"type":"string","enum":["active","pending","temporal_error","permanent_error"],"description":"Connection status of a channel connection."},"Channels.ChannelReadRelationships":{"type":"object","required":["group","properties","known_mappings"],"properties":{"group":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.id"}]},"type":{"type":"string","enum":["group"]}},"required":["id","type"]}},"required":["data"],"description":"Group the channel connection belongs to."},"properties":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.id"}]},"type":{"type":"string","enum":["property"]}},"required":["id","type"]}}},"required":["data"],"description":"Properties connected through this channel connection."},"known_mappings":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Channels.KnownMappingResource"}}},"required":["data"],"description":"Known mappings of the channel connection. Empty for channels that do not collect them."}},"description":"Relationships of a single retrieved channel connection resource."},"Channels.KnownMappingResource":{"type":"object","required":["id","type","attributes"],"properties":{"id":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.id"}]},"type":{"type":"string","enum":["known_mapping"]},"attributes":{"$ref":"#/components/schemas/Channels.KnownMappingAttributes"}},"description":"A known mapping of a channel connection: a remembered link between a rate of\nthe channel — identified by its rate and room codes — and a rate plan and\nroom type of the property. Known mappings are used to map incoming bookings;\nthey are collected automatically for channels that expose derived rates, and\nwhen unmapped bookings are resolved."},"Channels.KnownMappingAttributes":{"type":"object","required":["id","type","rate_plan_code","room_type_code","rate_plan_id","room_type_id"],"properties":{"id":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.id"}],"description":"UUID of the known mapping."},"type":{"type":"string","enum":["auto","manual"],"description":"How the mapping was established: derived from the channel's rate tree automatically, or set manually."},"rate_plan_code":{"type":"string","description":"Rate code on the channel side."},"room_type_code":{"type":"string","description":"Room code on the channel side."},"rate_plan_id":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.id"}],"description":"UUID of the mapped rate plan."},"room_type_id":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.id"}],"description":"UUID of the mapped room type."}},"description":"Attributes of a known mapping."},"Common.Errors.Unauthorized":{"type":"object","required":["errors"],"properties":{"errors":{"type":"object","required":["code","title"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"title":{"type":"string","enum":["Unauthorized"]}},"description":"Shape of a single JSON:API error object: a stable machine code plus a human-readable title."}},"description":"Authentication credentials are missing or invalid."},"Common.Errors.Forbidden":{"type":"object","required":["errors"],"properties":{"errors":{"type":"object","required":["code","title"],"properties":{"code":{"type":"string","enum":["forbidden"]},"title":{"type":"string","enum":["Forbidden"]}},"description":"Shape of a single JSON:API error object: a stable machine code plus a human-readable title."}},"description":"The authenticated user lacks permission to perform this action."},"Common.Errors.NotFound":{"type":"object","required":["errors"],"properties":{"errors":{"type":"object","required":["code","title"],"properties":{"code":{"type":"string","enum":["resource_not_found"]},"title":{"type":"string","enum":["Resource Not Found"]}},"description":"Shape of a single JSON:API error object: a stable machine code plus a human-readable title."}},"description":"The requested resource does not exist."},"Common.Errors.ServiceUnavailable":{"type":"object","required":["errors"],"properties":{"errors":{"type":"object","required":["code","title"],"properties":{"code":{"type":"string","enum":["service_unavailable"]},"title":{"type":"string","enum":["Service Temporary Unavailable"]}},"description":"Shape of a single JSON:API error object: a stable machine code plus a human-readable title."}},"description":"A backing service is temporarily unavailable; retry the request later."}}},"paths":{"/channels/{id}":{"get":{"operationId":"Channels_read","summary":"Retrieve a channel connection","description":"Retrieve a single channel connection.\n\nUnlike the list, the response carries the connection's known mappings —\nsee the `known_mappings` relationship.","parameters":[{"name":"id","in":"path","required":true,"description":"Channel connection ID.","schema":{"$ref":"#/components/schemas/Common.Scalars.id"}}],"responses":{"200":{"description":"The request has succeeded.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["type","id","attributes","relationships"],"properties":{"type":{"type":"string","enum":["channel"]},"id":{"$ref":"#/components/schemas/Common.Scalars.id"},"attributes":{"$ref":"#/components/schemas/Channels.Channel"},"relationships":{"$ref":"#/components/schemas/Channels.ChannelReadRelationships"}},"description":"A JSON:API resource object with typed attributes and relationships."}},"description":"JSON:API document wrapping a single resource."}}}},"401":{"description":"Authentication credentials are missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.Unauthorized"}}}},"403":{"description":"The authenticated user lacks permission to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.Forbidden"}}}},"404":{"description":"The requested resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.NotFound"}}}},"503":{"description":"A backing service is temporarily unavailable; retry the request later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.ServiceUnavailable"}}}}},"tags":["Channels"]}}}} ``` ## Create a channel connection > Create a channel connection: the link between one or more properties and a\ > booking channel, carrying the channel's connection settings and the\ > mappings between the properties' rate plans and the channel's rates.\ > \ > The connection is created disabled and exchanges no data until it is\ > activated — see \`POST /channels/{id}/activate\`. Channels that identify a\ > property by a single code allow only one connection per code. For channels\ > that expose derived rates, known mappings are recorded automatically — see\ > the \`known\_mappings\` relationship.\ > \ > The connection settings and the mapping settings are defined by the\ > channel adapter — see \`params\` and \`rate\_params\` in the descriptor\ > returned by \`GET /channels/adapter\`. ```json {"openapi":"3.1.0","info":{"title":"Channex.io — Channels","version":"0.0.0"},"tags":[{"name":"Channels","description":"Channel connections of Properties to booking channels (OTAs and channel managers), and the catalog of supported channel adapters."}],"servers":[{"url":"https://app.channex.io/api/v1","description":"Production server","variables":{}},{"url":"https://staging.channex.io/api/v1","description":"Staging server","variables":{}}],"security":[{"UserApiKeyAuth":[]}],"components":{"securitySchemes":{"UserApiKeyAuth":{"type":"apiKey","in":"header","name":"user-api-key","description":"API key for programmatic access, sent in the `user-api-key` header."}},"schemas":{"Common.Scalars.id":{"type":"string","format":"uuid"},"Channels.Channel":{"type":"object","required":["id","title","channel","currency","is_active","settings","rate_plans","properties","actions","expected_removal_date","inserted_at","updated_at"],"properties":{"id":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.id"}]},"title":{"type":"string","description":"Title of the channel connection."},"channel":{"type":"string","description":"Adapter code of the channel. See the `/channels/list` endpoint for supported values."},"currency":{"anyOf":[{"$ref":"#/components/schemas/Common.Scalars.currency"},{"type":"null"}],"description":"Currency the channel connection trades in; `null` when the connection does not define one."},"is_active":{"type":"boolean","description":"Whether the channel connection is enabled. Disabled connections do not send updates to the channel. Read-only: use `POST /channels/{id}/activate` and `POST /channels/{id}/deactivate` to change it."},"settings":{"allOf":[{"$ref":"#/components/schemas/Channels.ChannelConnectionSettings"}],"description":"Connection settings. Apart from `derived_option`, the keys are defined by the channel adapter — see `params` in the adapter descriptor returned by `GET /channels/adapter`."},"rate_plans":{"type":"array","items":{"$ref":"#/components/schemas/Channels.ChannelRatePlanMapping"},"description":"Rate plans of the property mapped to rates of the channel. Empty while the connection is unmapped."},"properties":{"type":"array","items":{"$ref":"#/components/schemas/Common.Scalars.id"},"description":"UUIDs of the properties connected through this channel connection. Channel Adapters with `property_mapping` equal to `single` accept only 1 Property."},"actions":{"type":"array","items":{"type":"string"},"description":"Actions the channel adapter supports on this connection, invoked through `POST /channels/{id}/execute/{action}`. Possible values: `load_future_reservations`."},"expected_removal_date":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date","description":"Date the channel connection is scheduled to be removed on. `null` while no removal is scheduled. Get more information about retention period at [our docs](https://docs.channex.io/guides/channex-retention-periods)."},"inserted_at":{"type":"string","format":"date-time","description":"When the channel connection was created (ISO 8601, no timezone offset)."},"updated_at":{"type":"string","format":"date-time","description":"When the channel connection was last changed (ISO 8601, no timezone offset)."},"status":{"allOf":[{"$ref":"#/components/schemas/Channels.ChannelStatus"}],"description":"Connection status. Present on Google Hotel ARI channel connections only."}},"description":"A channel connection: the link between a property and a booking channel."},"Common.Scalars.currency":{"type":"string","minLength":3,"maxLength":3,"description":"ISO 4217 alphabetic currency code. See the `/currencies` endpoint for supported values."},"Channels.ChannelConnectionSettings":{"type":"object","properties":{"derived_option":{"allOf":[{"$ref":"#/components/schemas/RatePlans.DerivedOption"}],"description":"Value-modification rules applied to the values pushed to the channel: each\nlisted restriction is sent with the rules applied to the mapped rate\nplan's value. The rules take effect when a rate plan mapping is created or\nupdated. A `derived_option` in a mapping's own settings overrides the\nconnection-level rules restriction by restriction."}},"unevaluatedProperties":{},"description":"Connection settings of a channel connection. Apart from `derived_option`, the keys are defined by the channel adapter — see `params` in the adapter descriptor returned by `GET /channels/adapter`."},"RatePlans.DerivedOption":{"type":"object","unevaluatedProperties":{"type":"array","items":{"type":"array","prefixItems":[{"type":"string","enum":["increase_by_amount","increase_by_percent","decrease_by_amount","decrease_by_percent"],"description":"A value-modification rule applied to the original value."},{"type":"string"}]}},"description":"Value-modification rules for the `rate` restriction, keyed by restriction\nname. Each value is a list of modification steps applied to the original\nvalue in order, left to right; a step is a `[rule, argument]` pair whose\nargument is the amount or percent as a decimal string, e.g.\n`[\"increase_by_percent\", \"5.00\"]`."},"Channels.ChannelRatePlanMapping":{"type":"object","required":["id","rate_plan_id","settings"],"properties":{"id":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.id"}],"description":"UUID of the mapping."},"rate_plan_id":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.id"}],"description":"UUID of the mapped rate plan."},"settings":{"type":"object","unevaluatedProperties":{},"description":"Mapping settings. The keys are defined by the channel adapter — see `rate_params` in the adapter descriptor returned by `GET /channels/adapter`."}},"description":"A rate plan of the property mapped to a rate of the channel."},"Channels.ChannelStatus":{"type":"string","enum":["active","pending","temporal_error","permanent_error"],"description":"Connection status of a channel connection."},"Channels.ChannelRelationships":{"type":"object","required":["group","properties"],"properties":{"group":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.id"}]},"type":{"type":"string","enum":["group"]}},"required":["id","type"]}},"required":["data"],"description":"Group the channel connection belongs to."},"properties":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.id"}]},"type":{"type":"string","enum":["property"]}},"required":["id","type"]}}},"required":["data"],"description":"Properties connected through this channel connection."}},"description":"Relationships of a channel connection resource."},"Common.Errors.Unauthorized":{"type":"object","required":["errors"],"properties":{"errors":{"type":"object","required":["code","title"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"title":{"type":"string","enum":["Unauthorized"]}},"description":"Shape of a single JSON:API error object: a stable machine code plus a human-readable title."}},"description":"Authentication credentials are missing or invalid."},"Common.Errors.InvalidArguments":{"type":"object","required":["errors"],"properties":{"errors":{"$ref":"#/components/schemas/Common.Errors.InvalidArgumentsObject"}},"description":"The request has missing or invalid arguments; `details` lists the messages per argument."},"Common.Errors.InvalidArgumentsObject":{"type":"object","required":["code","title","details"],"properties":{"code":{"type":"string","enum":["bad_request"]},"title":{"type":"string","enum":["Bad Request"]},"details":{"type":"object","unevaluatedProperties":{"type":"array","items":{"type":"string"}},"description":"Maps each invalid argument to the list of validation messages for that argument."}},"description":"Error object for invalid request arguments, adding per-argument messages."},"Common.Errors.ValidationError":{"type":"object","required":["errors"],"properties":{"errors":{"$ref":"#/components/schemas/Common.Errors.ValidationErrorObject"}},"description":"The request body failed validation."},"Common.Errors.ValidationErrorObject":{"type":"object","required":["code","title","details"],"properties":{"code":{"type":"string","enum":["validation_error"]},"title":{"type":"string","enum":["Validation Error"]},"details":{"type":"object","unevaluatedProperties":{"type":"array","items":{"type":"string"}},"description":"Maps each invalid field to the list of validation messages for that field."}},"description":"Error object for a failed validation, adding per-field messages."},"Common.Errors.ServiceUnavailable":{"type":"object","required":["errors"],"properties":{"errors":{"type":"object","required":["code","title"],"properties":{"code":{"type":"string","enum":["service_unavailable"]},"title":{"type":"string","enum":["Service Temporary Unavailable"]}},"description":"Shape of a single JSON:API error object: a stable machine code plus a human-readable title."}},"description":"A backing service is temporarily unavailable; retry the request later."},"Channels.ChannelCreateInput":{"type":"object","required":["channel","group_id","settings"],"properties":{"channel":{"type":"string","description":"Code of the channel adapter the connection uses. See the `/channels/list` endpoint for the supported adapters."},"group_id":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.id"}],"description":"UUID of the group the connection belongs to. The user must have access to the group, or to at least one of the connected properties."},"title":{"type":"string","description":"Title of the channel connection. Generated from the channel and property names when omitted."},"properties":{"type":"array","items":{"$ref":"#/components/schemas/Common.Scalars.id"},"description":"UUIDs of the properties connected through this channel connection. Channel Adapters with `property_mapping` equal to `single` accept only 1 Property."},"currency":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.currency"}],"description":"Currency the channel connection trades in. For channels that report their own currency, the reported currency wins."},"is_active":{"type":"boolean","description":"Has no effect: a new connection is always created disabled. Enable it with `POST /channels/{id}/activate`."},"settings":{"allOf":[{"$ref":"#/components/schemas/Channels.ChannelConnectionSettings"}],"description":"Connection settings. Apart from derived_option, the keys are defined by the channel adapter — see params in the adapter descriptor returned by GET /channels/adapter."},"rate_plans":{"type":"array","items":{"$ref":"#/components/schemas/Channels.RateMappingInput"},"description":"Rate plans of the properties mapped to rates of the channel. Mappings can also be added later, by updating the connection."}},"description":"A new channel connection. The connection settings and the mapping settings are defined by the channel adapter — see `params` and `rate_params` in the descriptor returned by `GET /channels/adapter`."},"Channels.RateMappingInput":{"type":"object","required":["rate_plan_id","settings"],"properties":{"rate_plan_id":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.id"}],"description":"UUID of the rate plan of the property."},"settings":{"type":"object","unevaluatedProperties":{},"description":"Mapping settings. The keys are defined by the channel adapter — see `rate_params` in the adapter descriptor returned by `GET /channels/adapter`."}},"description":"A rate plan mapping to create."}}},"paths":{"/channels":{"post":{"operationId":"Channels_create","summary":"Create a channel connection","description":"Create a channel connection: the link between one or more properties and a\nbooking channel, carrying the channel's connection settings and the\nmappings between the properties' rate plans and the channel's rates.\n\nThe connection is created disabled and exchanges no data until it is\nactivated — see `POST /channels/{id}/activate`. Channels that identify a\nproperty by a single code allow only one connection per code. For channels\nthat expose derived rates, known mappings are recorded automatically — see\nthe `known_mappings` relationship.\n\nThe connection settings and the mapping settings are defined by the\nchannel adapter — see `params` and `rate_params` in the descriptor\nreturned by `GET /channels/adapter`.","parameters":[],"responses":{"201":{"description":"201 Created response wrapping a resource body.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["type","id","attributes","relationships"],"properties":{"type":{"type":"string","enum":["channel"]},"id":{"$ref":"#/components/schemas/Common.Scalars.id"},"attributes":{"$ref":"#/components/schemas/Channels.Channel"},"relationships":{"$ref":"#/components/schemas/Channels.ChannelRelationships"}},"description":"A JSON:API resource object with typed attributes and relationships."}},"description":"JSON:API document wrapping a single resource."}}}},"401":{"description":"Authentication credentials are missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.Unauthorized"}}}},"422":{"description":"The request has missing or invalid arguments; `details` lists the messages per argument.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Common.Errors.InvalidArguments"},{"$ref":"#/components/schemas/Common.Errors.ValidationError"}]}}}},"503":{"description":"A backing service is temporarily unavailable; retry the request later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.ServiceUnavailable"}}}}},"tags":["Channels"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"channel":{"$ref":"#/components/schemas/Channels.ChannelCreateInput"}},"required":["channel"]}}}}}}}} ``` ## Update a channel connection > Update a channel connection. Fields absent from the request keep their\ > stored values; see the request fields for the replace semantics of the\ > connection settings and of the mapping set.\ > \ > Updating an active connection pushes a full synchronisation to the channel\ > in the background. Mapping and settings changes are recorded as channel\ > events — see the Channel Events resource. ```json {"openapi":"3.1.0","info":{"title":"Channex.io — Channels","version":"0.0.0"},"tags":[{"name":"Channels","description":"Channel connections of Properties to booking channels (OTAs and channel managers), and the catalog of supported channel adapters."}],"servers":[{"url":"https://app.channex.io/api/v1","description":"Production server","variables":{}},{"url":"https://staging.channex.io/api/v1","description":"Staging server","variables":{}}],"security":[{"UserApiKeyAuth":[]}],"components":{"securitySchemes":{"UserApiKeyAuth":{"type":"apiKey","in":"header","name":"user-api-key","description":"API key for programmatic access, sent in the `user-api-key` header."}},"schemas":{"Common.Scalars.id":{"type":"string","format":"uuid"},"Channels.Channel":{"type":"object","required":["id","title","channel","currency","is_active","settings","rate_plans","properties","actions","expected_removal_date","inserted_at","updated_at"],"properties":{"id":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.id"}]},"title":{"type":"string","description":"Title of the channel connection."},"channel":{"type":"string","description":"Adapter code of the channel. See the `/channels/list` endpoint for supported values."},"currency":{"anyOf":[{"$ref":"#/components/schemas/Common.Scalars.currency"},{"type":"null"}],"description":"Currency the channel connection trades in; `null` when the connection does not define one."},"is_active":{"type":"boolean","description":"Whether the channel connection is enabled. Disabled connections do not send updates to the channel. Read-only: use `POST /channels/{id}/activate` and `POST /channels/{id}/deactivate` to change it."},"settings":{"allOf":[{"$ref":"#/components/schemas/Channels.ChannelConnectionSettings"}],"description":"Connection settings. Apart from `derived_option`, the keys are defined by the channel adapter — see `params` in the adapter descriptor returned by `GET /channels/adapter`."},"rate_plans":{"type":"array","items":{"$ref":"#/components/schemas/Channels.ChannelRatePlanMapping"},"description":"Rate plans of the property mapped to rates of the channel. Empty while the connection is unmapped."},"properties":{"type":"array","items":{"$ref":"#/components/schemas/Common.Scalars.id"},"description":"UUIDs of the properties connected through this channel connection. Channel Adapters with `property_mapping` equal to `single` accept only 1 Property."},"actions":{"type":"array","items":{"type":"string"},"description":"Actions the channel adapter supports on this connection, invoked through `POST /channels/{id}/execute/{action}`. Possible values: `load_future_reservations`."},"expected_removal_date":{"anyOf":[{"type":"string"},{"type":"null"}],"format":"date","description":"Date the channel connection is scheduled to be removed on. `null` while no removal is scheduled. Get more information about retention period at [our docs](https://docs.channex.io/guides/channex-retention-periods)."},"inserted_at":{"type":"string","format":"date-time","description":"When the channel connection was created (ISO 8601, no timezone offset)."},"updated_at":{"type":"string","format":"date-time","description":"When the channel connection was last changed (ISO 8601, no timezone offset)."},"status":{"allOf":[{"$ref":"#/components/schemas/Channels.ChannelStatus"}],"description":"Connection status. Present on Google Hotel ARI channel connections only."}},"description":"A channel connection: the link between a property and a booking channel."},"Common.Scalars.currency":{"type":"string","minLength":3,"maxLength":3,"description":"ISO 4217 alphabetic currency code. See the `/currencies` endpoint for supported values."},"Channels.ChannelConnectionSettings":{"type":"object","properties":{"derived_option":{"allOf":[{"$ref":"#/components/schemas/RatePlans.DerivedOption"}],"description":"Value-modification rules applied to the values pushed to the channel: each\nlisted restriction is sent with the rules applied to the mapped rate\nplan's value. The rules take effect when a rate plan mapping is created or\nupdated. A `derived_option` in a mapping's own settings overrides the\nconnection-level rules restriction by restriction."}},"unevaluatedProperties":{},"description":"Connection settings of a channel connection. Apart from `derived_option`, the keys are defined by the channel adapter — see `params` in the adapter descriptor returned by `GET /channels/adapter`."},"RatePlans.DerivedOption":{"type":"object","unevaluatedProperties":{"type":"array","items":{"type":"array","prefixItems":[{"type":"string","enum":["increase_by_amount","increase_by_percent","decrease_by_amount","decrease_by_percent"],"description":"A value-modification rule applied to the original value."},{"type":"string"}]}},"description":"Value-modification rules for the `rate` restriction, keyed by restriction\nname. Each value is a list of modification steps applied to the original\nvalue in order, left to right; a step is a `[rule, argument]` pair whose\nargument is the amount or percent as a decimal string, e.g.\n`[\"increase_by_percent\", \"5.00\"]`."},"Channels.ChannelRatePlanMapping":{"type":"object","required":["id","rate_plan_id","settings"],"properties":{"id":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.id"}],"description":"UUID of the mapping."},"rate_plan_id":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.id"}],"description":"UUID of the mapped rate plan."},"settings":{"type":"object","unevaluatedProperties":{},"description":"Mapping settings. The keys are defined by the channel adapter — see `rate_params` in the adapter descriptor returned by `GET /channels/adapter`."}},"description":"A rate plan of the property mapped to a rate of the channel."},"Channels.ChannelStatus":{"type":"string","enum":["active","pending","temporal_error","permanent_error"],"description":"Connection status of a channel connection."},"Channels.ChannelRelationships":{"type":"object","required":["group","properties"],"properties":{"group":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.id"}]},"type":{"type":"string","enum":["group"]}},"required":["id","type"]}},"required":["data"],"description":"Group the channel connection belongs to."},"properties":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.id"}]},"type":{"type":"string","enum":["property"]}},"required":["id","type"]}}},"required":["data"],"description":"Properties connected through this channel connection."}},"description":"Relationships of a channel connection resource."},"Common.Errors.Unauthorized":{"type":"object","required":["errors"],"properties":{"errors":{"type":"object","required":["code","title"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"title":{"type":"string","enum":["Unauthorized"]}},"description":"Shape of a single JSON:API error object: a stable machine code plus a human-readable title."}},"description":"Authentication credentials are missing or invalid."},"Common.Errors.Forbidden":{"type":"object","required":["errors"],"properties":{"errors":{"type":"object","required":["code","title"],"properties":{"code":{"type":"string","enum":["forbidden"]},"title":{"type":"string","enum":["Forbidden"]}},"description":"Shape of a single JSON:API error object: a stable machine code plus a human-readable title."}},"description":"The authenticated user lacks permission to perform this action."},"Common.Errors.NotFound":{"type":"object","required":["errors"],"properties":{"errors":{"type":"object","required":["code","title"],"properties":{"code":{"type":"string","enum":["resource_not_found"]},"title":{"type":"string","enum":["Resource Not Found"]}},"description":"Shape of a single JSON:API error object: a stable machine code plus a human-readable title."}},"description":"The requested resource does not exist."},"Common.Errors.InvalidArguments":{"type":"object","required":["errors"],"properties":{"errors":{"$ref":"#/components/schemas/Common.Errors.InvalidArgumentsObject"}},"description":"The request has missing or invalid arguments; `details` lists the messages per argument."},"Common.Errors.InvalidArgumentsObject":{"type":"object","required":["code","title","details"],"properties":{"code":{"type":"string","enum":["bad_request"]},"title":{"type":"string","enum":["Bad Request"]},"details":{"type":"object","unevaluatedProperties":{"type":"array","items":{"type":"string"}},"description":"Maps each invalid argument to the list of validation messages for that argument."}},"description":"Error object for invalid request arguments, adding per-argument messages."},"Common.Errors.ValidationError":{"type":"object","required":["errors"],"properties":{"errors":{"$ref":"#/components/schemas/Common.Errors.ValidationErrorObject"}},"description":"The request body failed validation."},"Common.Errors.ValidationErrorObject":{"type":"object","required":["code","title","details"],"properties":{"code":{"type":"string","enum":["validation_error"]},"title":{"type":"string","enum":["Validation Error"]},"details":{"type":"object","unevaluatedProperties":{"type":"array","items":{"type":"string"}},"description":"Maps each invalid field to the list of validation messages for that field."}},"description":"Error object for a failed validation, adding per-field messages."},"Common.Errors.ServiceUnavailable":{"type":"object","required":["errors"],"properties":{"errors":{"type":"object","required":["code","title"],"properties":{"code":{"type":"string","enum":["service_unavailable"]},"title":{"type":"string","enum":["Service Temporary Unavailable"]}},"description":"Shape of a single JSON:API error object: a stable machine code plus a human-readable title."}},"description":"A backing service is temporarily unavailable; retry the request later."},"Channels.ChannelUpdateInput":{"type":"object","required":["channel"],"properties":{"channel":{"type":"string","description":"Code of the channel adapter the connection uses. Cannot be changed — a different code is rejected."},"group_id":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.id"}],"description":"UUID of the group the connection belongs to."},"title":{"type":"string","description":"Title of the channel connection."},"properties":{"type":"array","items":{"$ref":"#/components/schemas/Common.Scalars.id"},"description":"UUIDs of the properties connected through this channel connection. Channel Adapters with `property_mapping` equal to `single` accept only 1 Property. When omitted, the connected properties are kept. A property whose rate plans are still mapped cannot be removed."},"currency":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.currency"}],"description":"Currency the channel connection trades in. Available to administrators."},"settings":{"allOf":[{"$ref":"#/components/schemas/Channels.ChannelConnectionSettings"}],"description":"Connection settings of the channel. When present, the stored settings are replaced as a whole."},"rate_plans":{"type":"array","items":{"$ref":"#/components/schemas/Channels.RateMappingReplaceInput"},"description":"The new mapping set of the connection. When present, it replaces the stored\nmappings as a whole: a stored mapping missing from the set is removed, and\none sent with `settings: null` is removed as well. When omitted, the stored\nmappings are kept."}},"description":"Changes to a channel connection. The connection settings and the mapping settings are defined by the channel adapter — see `params` and `rate_params` in the descriptor returned by `GET /channels/adapter`."},"Channels.RateMappingReplaceInput":{"type":"object","required":["rate_plan_id","settings"],"properties":{"rate_plan_id":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.id"}],"description":"UUID of the rate plan of the property."},"settings":{"anyOf":[{"type":"object","unevaluatedProperties":{}},{"type":"null"}],"description":"Mapping settings. The keys are defined by the channel adapter — see `rate_params` in the adapter descriptor returned by `GET /channels/adapter`. `null` removes the mapping."}},"description":"A rate plan mapping of a connection's new mapping set."}}},"paths":{"/channels/{id}":{"put":{"operationId":"Channels_update","summary":"Update a channel connection","description":"Update a channel connection. Fields absent from the request keep their\nstored values; see the request fields for the replace semantics of the\nconnection settings and of the mapping set.\n\nUpdating an active connection pushes a full synchronisation to the channel\nin the background. Mapping and settings changes are recorded as channel\nevents — see the Channel Events resource.","parameters":[{"name":"id","in":"path","required":true,"description":"Channel connection ID.","schema":{"$ref":"#/components/schemas/Common.Scalars.id"}}],"responses":{"200":{"description":"The request has succeeded.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["type","id","attributes","relationships"],"properties":{"type":{"type":"string","enum":["channel"]},"id":{"$ref":"#/components/schemas/Common.Scalars.id"},"attributes":{"$ref":"#/components/schemas/Channels.Channel"},"relationships":{"$ref":"#/components/schemas/Channels.ChannelRelationships"}},"description":"A JSON:API resource object with typed attributes and relationships."}},"description":"JSON:API document wrapping a single resource."}}}},"401":{"description":"Authentication credentials are missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.Unauthorized"}}}},"403":{"description":"The authenticated user lacks permission to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.Forbidden"}}}},"404":{"description":"The requested resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.NotFound"}}}},"422":{"description":"The request has missing or invalid arguments; `details` lists the messages per argument.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Common.Errors.InvalidArguments"},{"$ref":"#/components/schemas/Common.Errors.ValidationError"}]}}}},"503":{"description":"A backing service is temporarily unavailable; retry the request later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.ServiceUnavailable"}}}}},"tags":["Channels"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"channel":{"$ref":"#/components/schemas/Channels.ChannelUpdateInput"}},"required":["channel"]}}}}}}}} ``` ## Delete a channel connection > Delete a channel connection. Deactivate the connection first — an active\ > connection cannot be deleted.\ > \ > Deletion is permanent: the connection, its property and rate plan mappings,\ > and its channel events are all removed. Bookings received through the\ > connection are kept, but no longer reference it. ```json {"openapi":"3.1.0","info":{"title":"Channex.io — Channels","version":"0.0.0"},"tags":[{"name":"Channels","description":"Channel connections of Properties to booking channels (OTAs and channel managers), and the catalog of supported channel adapters."}],"servers":[{"url":"https://app.channex.io/api/v1","description":"Production server","variables":{}},{"url":"https://staging.channex.io/api/v1","description":"Staging server","variables":{}}],"security":[{"UserApiKeyAuth":[]}],"components":{"securitySchemes":{"UserApiKeyAuth":{"type":"apiKey","in":"header","name":"user-api-key","description":"API key for programmatic access, sent in the `user-api-key` header."}},"schemas":{"Common.Scalars.id":{"type":"string","format":"uuid"},"Common.JsonApi.SuccessMessage":{"type":"object","required":["meta"],"properties":{"meta":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}},"description":"Success response carrying only a meta message (no resource body)."},"Common.Errors.Unauthorized":{"type":"object","required":["errors"],"properties":{"errors":{"type":"object","required":["code","title"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"title":{"type":"string","enum":["Unauthorized"]}},"description":"Shape of a single JSON:API error object: a stable machine code plus a human-readable title."}},"description":"Authentication credentials are missing or invalid."},"Common.Errors.Forbidden":{"type":"object","required":["errors"],"properties":{"errors":{"type":"object","required":["code","title"],"properties":{"code":{"type":"string","enum":["forbidden"]},"title":{"type":"string","enum":["Forbidden"]}},"description":"Shape of a single JSON:API error object: a stable machine code plus a human-readable title."}},"description":"The authenticated user lacks permission to perform this action."},"Common.Errors.NotFound":{"type":"object","required":["errors"],"properties":{"errors":{"type":"object","required":["code","title"],"properties":{"code":{"type":"string","enum":["resource_not_found"]},"title":{"type":"string","enum":["Resource Not Found"]}},"description":"Shape of a single JSON:API error object: a stable machine code plus a human-readable title."}},"description":"The requested resource does not exist."},"Common.Errors.ValidationError":{"type":"object","required":["errors"],"properties":{"errors":{"$ref":"#/components/schemas/Common.Errors.ValidationErrorObject"}},"description":"The request body failed validation."},"Common.Errors.ValidationErrorObject":{"type":"object","required":["code","title","details"],"properties":{"code":{"type":"string","enum":["validation_error"]},"title":{"type":"string","enum":["Validation Error"]},"details":{"type":"object","unevaluatedProperties":{"type":"array","items":{"type":"string"}},"description":"Maps each invalid field to the list of validation messages for that field."}},"description":"Error object for a failed validation, adding per-field messages."},"Common.Errors.ServiceUnavailable":{"type":"object","required":["errors"],"properties":{"errors":{"type":"object","required":["code","title"],"properties":{"code":{"type":"string","enum":["service_unavailable"]},"title":{"type":"string","enum":["Service Temporary Unavailable"]}},"description":"Shape of a single JSON:API error object: a stable machine code plus a human-readable title."}},"description":"A backing service is temporarily unavailable; retry the request later."}}},"paths":{"/channels/{id}":{"delete":{"operationId":"Channels_delete","summary":"Delete a channel connection","description":"Delete a channel connection. Deactivate the connection first — an active\nconnection cannot be deleted.\n\nDeletion is permanent: the connection, its property and rate plan mappings,\nand its channel events are all removed. Bookings received through the\nconnection are kept, but no longer reference it.","parameters":[{"name":"id","in":"path","required":true,"description":"Channel connection ID.","schema":{"$ref":"#/components/schemas/Common.Scalars.id"}}],"responses":{"200":{"description":"The request has succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.JsonApi.SuccessMessage"}}}},"401":{"description":"Authentication credentials are missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.Unauthorized"}}}},"403":{"description":"The authenticated user lacks permission to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.Forbidden"}}}},"404":{"description":"The requested resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.NotFound"}}}},"422":{"description":"The request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.ValidationError"}}}},"503":{"description":"A backing service is temporarily unavailable; retry the request later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.ServiceUnavailable"}}}}},"tags":["Channels"]}}}} ``` ## Activate a channel connection > Activate a channel connection. The connection starts exchanging data with\ > the channel: a full synchronisation pushes availability, rates and\ > restrictions, and any scheduled removal date is cleared. Reviews and\ > scores begin to be collected for Airbnb, Booking.com and Expedia\ > connections.\ > \ > The connection must be mapped first — it needs at least one property, and\ > at least one mapped rate plan unless the channel does not require rate\ > mapping. Activating an already active connection succeeds without changes. ```json {"openapi":"3.1.0","info":{"title":"Channex.io — Channels","version":"0.0.0"},"tags":[{"name":"Channels","description":"Channel connections of Properties to booking channels (OTAs and channel managers), and the catalog of supported channel adapters."}],"servers":[{"url":"https://app.channex.io/api/v1","description":"Production server","variables":{}},{"url":"https://staging.channex.io/api/v1","description":"Staging server","variables":{}}],"security":[{"UserApiKeyAuth":[]}],"components":{"securitySchemes":{"UserApiKeyAuth":{"type":"apiKey","in":"header","name":"user-api-key","description":"API key for programmatic access, sent in the `user-api-key` header."}},"schemas":{"Common.Scalars.id":{"type":"string","format":"uuid"},"Common.JsonApi.SuccessMessage":{"type":"object","required":["meta"],"properties":{"meta":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}},"description":"Success response carrying only a meta message (no resource body)."},"Common.Errors.Unauthorized":{"type":"object","required":["errors"],"properties":{"errors":{"type":"object","required":["code","title"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"title":{"type":"string","enum":["Unauthorized"]}},"description":"Shape of a single JSON:API error object: a stable machine code plus a human-readable title."}},"description":"Authentication credentials are missing or invalid."},"Common.Errors.Forbidden":{"type":"object","required":["errors"],"properties":{"errors":{"type":"object","required":["code","title"],"properties":{"code":{"type":"string","enum":["forbidden"]},"title":{"type":"string","enum":["Forbidden"]}},"description":"Shape of a single JSON:API error object: a stable machine code plus a human-readable title."}},"description":"The authenticated user lacks permission to perform this action."},"Common.Errors.NotFound":{"type":"object","required":["errors"],"properties":{"errors":{"type":"object","required":["code","title"],"properties":{"code":{"type":"string","enum":["resource_not_found"]},"title":{"type":"string","enum":["Resource Not Found"]}},"description":"Shape of a single JSON:API error object: a stable machine code plus a human-readable title."}},"description":"The requested resource does not exist."},"Common.Errors.ValidationError":{"type":"object","required":["errors"],"properties":{"errors":{"$ref":"#/components/schemas/Common.Errors.ValidationErrorObject"}},"description":"The request body failed validation."},"Common.Errors.ValidationErrorObject":{"type":"object","required":["code","title","details"],"properties":{"code":{"type":"string","enum":["validation_error"]},"title":{"type":"string","enum":["Validation Error"]},"details":{"type":"object","unevaluatedProperties":{"type":"array","items":{"type":"string"}},"description":"Maps each invalid field to the list of validation messages for that field."}},"description":"Error object for a failed validation, adding per-field messages."},"Common.Errors.ServiceUnavailable":{"type":"object","required":["errors"],"properties":{"errors":{"type":"object","required":["code","title"],"properties":{"code":{"type":"string","enum":["service_unavailable"]},"title":{"type":"string","enum":["Service Temporary Unavailable"]}},"description":"Shape of a single JSON:API error object: a stable machine code plus a human-readable title."}},"description":"A backing service is temporarily unavailable; retry the request later."}}},"paths":{"/channels/{id}/activate":{"post":{"operationId":"Channels_activate","summary":"Activate a channel connection","description":"Activate a channel connection. The connection starts exchanging data with\nthe channel: a full synchronisation pushes availability, rates and\nrestrictions, and any scheduled removal date is cleared. Reviews and\nscores begin to be collected for Airbnb, Booking.com and Expedia\nconnections.\n\nThe connection must be mapped first — it needs at least one property, and\nat least one mapped rate plan unless the channel does not require rate\nmapping. Activating an already active connection succeeds without changes.","parameters":[{"name":"id","in":"path","required":true,"description":"Channel connection ID.","schema":{"$ref":"#/components/schemas/Common.Scalars.id"}}],"responses":{"200":{"description":"The request has succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.JsonApi.SuccessMessage"}}}},"401":{"description":"Authentication credentials are missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.Unauthorized"}}}},"403":{"description":"The authenticated user lacks permission to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.Forbidden"}}}},"404":{"description":"The requested resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.NotFound"}}}},"422":{"description":"The request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.ValidationError"}}}},"503":{"description":"A backing service is temporarily unavailable; retry the request later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.ServiceUnavailable"}}}}},"tags":["Channels"]}}}} ``` ## Deactivate a channel connection > Deactivate a channel connection. The connection stops sending updates to\ > the channel, and its removal is scheduled for 30 days later — see\ > \`expected\_removal\_date\`. No synchronisation is sent to the channel.\ > \ > Existing mappings are kept. A connection spanning more than one property,\ > and an Airbnb connection, must have its rate plan mappings removed before\ > it can be deactivated. Deactivating an already inactive connection succeeds\ > without changes. ```json {"openapi":"3.1.0","info":{"title":"Channex.io — Channels","version":"0.0.0"},"tags":[{"name":"Channels","description":"Channel connections of Properties to booking channels (OTAs and channel managers), and the catalog of supported channel adapters."}],"servers":[{"url":"https://app.channex.io/api/v1","description":"Production server","variables":{}},{"url":"https://staging.channex.io/api/v1","description":"Staging server","variables":{}}],"security":[{"UserApiKeyAuth":[]}],"components":{"securitySchemes":{"UserApiKeyAuth":{"type":"apiKey","in":"header","name":"user-api-key","description":"API key for programmatic access, sent in the `user-api-key` header."}},"schemas":{"Common.Scalars.id":{"type":"string","format":"uuid"},"Common.JsonApi.SuccessMessage":{"type":"object","required":["meta"],"properties":{"meta":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}},"description":"Success response carrying only a meta message (no resource body)."},"Common.Errors.Unauthorized":{"type":"object","required":["errors"],"properties":{"errors":{"type":"object","required":["code","title"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"title":{"type":"string","enum":["Unauthorized"]}},"description":"Shape of a single JSON:API error object: a stable machine code plus a human-readable title."}},"description":"Authentication credentials are missing or invalid."},"Common.Errors.Forbidden":{"type":"object","required":["errors"],"properties":{"errors":{"type":"object","required":["code","title"],"properties":{"code":{"type":"string","enum":["forbidden"]},"title":{"type":"string","enum":["Forbidden"]}},"description":"Shape of a single JSON:API error object: a stable machine code plus a human-readable title."}},"description":"The authenticated user lacks permission to perform this action."},"Common.Errors.NotFound":{"type":"object","required":["errors"],"properties":{"errors":{"type":"object","required":["code","title"],"properties":{"code":{"type":"string","enum":["resource_not_found"]},"title":{"type":"string","enum":["Resource Not Found"]}},"description":"Shape of a single JSON:API error object: a stable machine code plus a human-readable title."}},"description":"The requested resource does not exist."},"Common.Errors.ValidationError":{"type":"object","required":["errors"],"properties":{"errors":{"$ref":"#/components/schemas/Common.Errors.ValidationErrorObject"}},"description":"The request body failed validation."},"Common.Errors.ValidationErrorObject":{"type":"object","required":["code","title","details"],"properties":{"code":{"type":"string","enum":["validation_error"]},"title":{"type":"string","enum":["Validation Error"]},"details":{"type":"object","unevaluatedProperties":{"type":"array","items":{"type":"string"}},"description":"Maps each invalid field to the list of validation messages for that field."}},"description":"Error object for a failed validation, adding per-field messages."},"Common.Errors.ServiceUnavailable":{"type":"object","required":["errors"],"properties":{"errors":{"type":"object","required":["code","title"],"properties":{"code":{"type":"string","enum":["service_unavailable"]},"title":{"type":"string","enum":["Service Temporary Unavailable"]}},"description":"Shape of a single JSON:API error object: a stable machine code plus a human-readable title."}},"description":"A backing service is temporarily unavailable; retry the request later."},"Channels.ChannelDeactivateRequest":{"type":"object","properties":{"send_notification":{"type":"boolean","description":"Email the owners of the billing accounts behind the connection's properties about the deactivation. Available to administrators."}},"description":"Options for deactivating a channel connection."}}},"paths":{"/channels/{id}/deactivate":{"post":{"operationId":"Channels_deactivate","summary":"Deactivate a channel connection","description":"Deactivate a channel connection. The connection stops sending updates to\nthe channel, and its removal is scheduled for 30 days later — see\n`expected_removal_date`. No synchronisation is sent to the channel.\n\nExisting mappings are kept. A connection spanning more than one property,\nand an Airbnb connection, must have its rate plan mappings removed before\nit can be deactivated. Deactivating an already inactive connection succeeds\nwithout changes.","parameters":[{"name":"id","in":"path","required":true,"description":"Channel connection ID.","schema":{"$ref":"#/components/schemas/Common.Scalars.id"}}],"responses":{"200":{"description":"The request has succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.JsonApi.SuccessMessage"}}}},"401":{"description":"Authentication credentials are missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.Unauthorized"}}}},"403":{"description":"The authenticated user lacks permission to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.Forbidden"}}}},"404":{"description":"The requested resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.NotFound"}}}},"422":{"description":"The request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.ValidationError"}}}},"503":{"description":"A backing service is temporarily unavailable; retry the request later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.ServiceUnavailable"}}}}},"tags":["Channels"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Channels.ChannelDeactivateRequest"}}}}}}}} ``` ## Check a channel connection's readiness > Check whether a channel connection is ready to be activated. The response\ > lists the problems blocking activation — a mapping that has not been set\ > up, for example; an empty list means the connection is ready. Resolve every\ > reported problem before activating the connection. ```json {"openapi":"3.1.0","info":{"title":"Channex.io — Channels","version":"0.0.0"},"tags":[{"name":"Channels","description":"Channel connections of Properties to booking channels (OTAs and channel managers), and the catalog of supported channel adapters."}],"servers":[{"url":"https://app.channex.io/api/v1","description":"Production server","variables":{}},{"url":"https://staging.channex.io/api/v1","description":"Staging server","variables":{}}],"security":[{"UserApiKeyAuth":[]}],"components":{"securitySchemes":{"UserApiKeyAuth":{"type":"apiKey","in":"header","name":"user-api-key","description":"API key for programmatic access, sent in the `user-api-key` header."}},"schemas":{"Common.Scalars.id":{"type":"string","format":"uuid"},"Channels.ChannelReadinessResult":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Channels.ChannelReadinessIssue"}},"meta":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}},"description":"Result of a channel connection readiness check. `data` lists the problems\nkeeping the connection from being activated; an empty list means the\nconnection is ready."},"Channels.ChannelReadinessIssue":{"type":"object","required":["id","type","entity","relation","error_code"],"properties":{"id":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.id"}],"description":"UUID of the entity the problem refers to."},"type":{"type":"string","enum":["entity"]},"entity":{"type":"string","description":"Kind of entity the problem refers to, e.g. `Channel`."},"relation":{"type":"string","description":"Part of the entity that is not ready, e.g. `Mapping`."},"error_code":{"type":"string","description":"Reason the entity is not ready, e.g. `required`."}},"description":"A problem that keeps a channel connection from being activated."},"Common.Errors.Unauthorized":{"type":"object","required":["errors"],"properties":{"errors":{"type":"object","required":["code","title"],"properties":{"code":{"type":"string","enum":["unauthorized"]},"title":{"type":"string","enum":["Unauthorized"]}},"description":"Shape of a single JSON:API error object: a stable machine code plus a human-readable title."}},"description":"Authentication credentials are missing or invalid."},"Common.Errors.Forbidden":{"type":"object","required":["errors"],"properties":{"errors":{"type":"object","required":["code","title"],"properties":{"code":{"type":"string","enum":["forbidden"]},"title":{"type":"string","enum":["Forbidden"]}},"description":"Shape of a single JSON:API error object: a stable machine code plus a human-readable title."}},"description":"The authenticated user lacks permission to perform this action."},"Common.Errors.NotFound":{"type":"object","required":["errors"],"properties":{"errors":{"type":"object","required":["code","title"],"properties":{"code":{"type":"string","enum":["resource_not_found"]},"title":{"type":"string","enum":["Resource Not Found"]}},"description":"Shape of a single JSON:API error object: a stable machine code plus a human-readable title."}},"description":"The requested resource does not exist."},"Common.Errors.ServiceUnavailable":{"type":"object","required":["errors"],"properties":{"errors":{"type":"object","required":["code","title"],"properties":{"code":{"type":"string","enum":["service_unavailable"]},"title":{"type":"string","enum":["Service Temporary Unavailable"]}},"description":"Shape of a single JSON:API error object: a stable machine code plus a human-readable title."}},"description":"A backing service is temporarily unavailable; retry the request later."}}},"paths":{"/channels/{id}/check_readiness":{"post":{"operationId":"Channels_checkReadiness","summary":"Check a channel connection's readiness","description":"Check whether a channel connection is ready to be activated. The response\nlists the problems blocking activation — a mapping that has not been set\nup, for example; an empty list means the connection is ready. Resolve every\nreported problem before activating the connection.","parameters":[{"name":"id","in":"path","required":true,"description":"Channel connection ID.","schema":{"$ref":"#/components/schemas/Common.Scalars.id"}}],"responses":{"200":{"description":"The request has succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Channels.ChannelReadinessResult"}}}},"401":{"description":"Authentication credentials are missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.Unauthorized"}}}},"403":{"description":"The authenticated user lacks permission to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.Forbidden"}}}},"404":{"description":"The requested resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.NotFound"}}}},"503":{"description":"A backing service is temporarily unavailable; retry the request later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.ServiceUnavailable"}}}}},"tags":["Channels"]}}}} ```