> 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/airbnb-api/promotions-api.md).

# Promotions API

## List promotions of a listing

> List the promotions of a mapped Airbnb listing: every promotion type,\
> whether it can be enabled, is enabled, or has expired.\
> \
> For Airbnb channel connections; other channels receive \`403 Forbidden\`.\
> A mapping that is not one of the channel connection's listing mappings\
> receives \`404 Not Found\`.

```json
{"openapi":"3.1.0","info":{"title":"Channex.io — Channels","version":"0.0.0"},"tags":[{"name":"Airbnb","description":"Airbnb-specific operations of channel connections: the authorization, the rate plan mappings that carry the listings, the listing settings stored on them (pricing, availability, and booking settings), and the actions over a mapped listing — publishing, checkout tasks, promotions, and opportunities."}],"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"},"Airbnb.MappingPromotionResource":{"type":"object","required":["type","attributes"],"properties":{"type":{"type":"string","enum":["promotion"]},"attributes":{"$ref":"#/components/schemas/Airbnb.MappingPromotion"}},"description":"A promotion resource of a mapped Airbnb listing."},"Airbnb.MappingPromotion":{"type":"object","required":["type","status","blackout_dates_allowed","blackout_dates_quota","discount","blackout_dates"],"properties":{"type":{"allOf":[{"$ref":"#/components/schemas/Airbnb.PromotionType"}],"description":"Type of the promotion."},"status":{"allOf":[{"$ref":"#/components/schemas/Airbnb.PromotionStatus"}],"description":"Status of the promotion for the listing."},"blackout_dates_allowed":{"type":"boolean","description":"Whether the promotion accepts `blackout_dates`. When `false`, the promotion cannot be updated."},"blackout_dates_quota":{"anyOf":[{"type":"object","unevaluatedProperties":{"$ref":"#/components/schemas/Airbnb.MappingPromotionBlackoutDatesQuota"}},{"type":"null"}],"description":"Blackout date usage per calendar year, keyed by year (`YYYY`): from the current year through the year of the last date that can be set. `null` when `blackout_dates_allowed` is `false`."},"discount":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.decimalString"}],"description":"Discount percentage of the promotion. Fixed for the promotion type; it cannot be changed through the API."},"blackout_dates":{"type":"array","items":{"type":"string","format":"date"},"description":"Dates on which the promotion does not apply, past ones included. A date sent is today or later in the property's time zone — a past date only if the promotion already holds it — and less than two years ahead, and appears once. At most 30 per calendar year, past dates included — see the promotion's `blackout_dates_quota`. Accepted only when the promotion's `blackout_dates_allowed` is `true`."}},"description":"A promotion of a mapped Airbnb listing: an available, enabled or expired promotion of one type."},"Airbnb.PromotionType":{"type":"string","enum":["NEW_LISTING_PROMOTION","HIGH_RATED_GUEST_DISCOUNT","MOBILE_ONLY_DISCOUNT"],"description":"Type of an Airbnb promotion."},"Airbnb.PromotionStatus":{"type":"string","enum":["AVAILABLE","ONGOING","EXPIRED"],"description":"Status of a promotion for a listing:\n- `AVAILABLE` — the promotion can be enabled;\n- `ONGOING` — the promotion is enabled;\n- `EXPIRED` — the promotion is no longer available."},"Airbnb.MappingPromotionBlackoutDatesQuota":{"type":"object","required":["dates_used_count","dates_available_count"],"properties":{"dates_used_count":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.nonNegativeInt"}],"description":"Number of blackout dates the promotion holds in the year, past ones included."},"dates_available_count":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.nonNegativeInt"}],"description":"Number of blackout dates that can still be set in the year."}},"description":"Blackout date usage of a promotion within one calendar year."},"Common.Scalars.nonNegativeInt":{"type":"integer","format":"int32","minimum":0},"Common.Scalars.decimalString":{"type":"string","description":"A decimal number as a string, e.g. `100.00`. Every monetary amount the API returns takes this form."},"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/{channel_id}/mappings/{mapping_id}/promotions":{"get":{"operationId":"AirbnbMappingPromotions_list","summary":"List promotions of a listing","description":"List the promotions of a mapped Airbnb listing: every promotion type,\nwhether it can be enabled, is enabled, or has expired.\n\nFor Airbnb channel connections; other channels receive `403 Forbidden`.\nA mapping that is not one of the channel connection's listing mappings\nreceives `404 Not Found`.","parameters":[{"name":"channel_id","in":"path","required":true,"description":"Channel connection ID.","schema":{"$ref":"#/components/schemas/Common.Scalars.id"}},{"name":"mapping_id","in":"path","required":true,"description":"Mapping ID — see `rate_plans[].id` of the channel connection.","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":"array","items":{"$ref":"#/components/schemas/Airbnb.MappingPromotionResource"}}},"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"}}}},"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":["Airbnb"]}}}}
```

## Enable a promotion on a listing

> Enable a promotion on a mapped Airbnb listing. \`blackout\_dates\` replaces\
> the dates the promotion holds, and an empty list clears them; without it,\
> the promotion is enabled with the dates it already holds. The response\
> reports the promotion as \`ONGOING\`.\
> \
> Enabling a promotion that is already \`ONGOING\` returns it unchanged and\
> leaves its dates as they are: to change them, update the promotion. An\
> \`EXPIRED\` promotion cannot be enabled.\
> \
> A refusal is answered with \`422 Unprocessable Entity\`, \`details\` keyed by\
> what it concerns: \`blackout\_dates\` (one message per refused date, naming\
> the date), \`type\` when the type is unknown or the promotion cannot be\
> enabled, or \`promotion\` for any other reason, a refusal by Airbnb\
> included.

```json
{"openapi":"3.1.0","info":{"title":"Channex.io — Channels","version":"0.0.0"},"tags":[{"name":"Airbnb","description":"Airbnb-specific operations of channel connections: the authorization, the rate plan mappings that carry the listings, the listing settings stored on them (pricing, availability, and booking settings), and the actions over a mapped listing — publishing, checkout tasks, promotions, and opportunities."}],"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"},"Airbnb.MappingPromotionResource":{"type":"object","required":["type","attributes"],"properties":{"type":{"type":"string","enum":["promotion"]},"attributes":{"$ref":"#/components/schemas/Airbnb.MappingPromotion"}},"description":"A promotion resource of a mapped Airbnb listing."},"Airbnb.MappingPromotion":{"type":"object","required":["type","status","blackout_dates_allowed","blackout_dates_quota","discount","blackout_dates"],"properties":{"type":{"allOf":[{"$ref":"#/components/schemas/Airbnb.PromotionType"}],"description":"Type of the promotion."},"status":{"allOf":[{"$ref":"#/components/schemas/Airbnb.PromotionStatus"}],"description":"Status of the promotion for the listing."},"blackout_dates_allowed":{"type":"boolean","description":"Whether the promotion accepts `blackout_dates`. When `false`, the promotion cannot be updated."},"blackout_dates_quota":{"anyOf":[{"type":"object","unevaluatedProperties":{"$ref":"#/components/schemas/Airbnb.MappingPromotionBlackoutDatesQuota"}},{"type":"null"}],"description":"Blackout date usage per calendar year, keyed by year (`YYYY`): from the current year through the year of the last date that can be set. `null` when `blackout_dates_allowed` is `false`."},"discount":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.decimalString"}],"description":"Discount percentage of the promotion. Fixed for the promotion type; it cannot be changed through the API."},"blackout_dates":{"type":"array","items":{"type":"string","format":"date"},"description":"Dates on which the promotion does not apply, past ones included. A date sent is today or later in the property's time zone — a past date only if the promotion already holds it — and less than two years ahead, and appears once. At most 30 per calendar year, past dates included — see the promotion's `blackout_dates_quota`. Accepted only when the promotion's `blackout_dates_allowed` is `true`."}},"description":"A promotion of a mapped Airbnb listing: an available, enabled or expired promotion of one type."},"Airbnb.PromotionType":{"type":"string","enum":["NEW_LISTING_PROMOTION","HIGH_RATED_GUEST_DISCOUNT","MOBILE_ONLY_DISCOUNT"],"description":"Type of an Airbnb promotion."},"Airbnb.PromotionStatus":{"type":"string","enum":["AVAILABLE","ONGOING","EXPIRED"],"description":"Status of a promotion for a listing:\n- `AVAILABLE` — the promotion can be enabled;\n- `ONGOING` — the promotion is enabled;\n- `EXPIRED` — the promotion is no longer available."},"Airbnb.MappingPromotionBlackoutDatesQuota":{"type":"object","required":["dates_used_count","dates_available_count"],"properties":{"dates_used_count":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.nonNegativeInt"}],"description":"Number of blackout dates the promotion holds in the year, past ones included."},"dates_available_count":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.nonNegativeInt"}],"description":"Number of blackout dates that can still be set in the year."}},"description":"Blackout date usage of a promotion within one calendar year."},"Common.Scalars.nonNegativeInt":{"type":"integer","format":"int32","minimum":0},"Common.Scalars.decimalString":{"type":"string","description":"A decimal number as a string, e.g. `100.00`. Every monetary amount the API returns takes this form."},"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."},"Airbnb.MappingPromotionEnableRequest":{"type":"object","required":["promotion"],"properties":{"promotion":{"$ref":"#/components/schemas/Airbnb.MappingPromotionEnable"}},"description":"Request body of the promotion enable action."},"Airbnb.MappingPromotionEnable":{"type":"object","required":["type"],"properties":{"type":{"allOf":[{"$ref":"#/components/schemas/Airbnb.PromotionType"}],"description":"Type of the promotion."},"blackout_dates":{"type":"array","items":{"type":"string","format":"date"},"description":"Dates on which the promotion does not apply, past ones included. A date sent is today or later in the property's time zone — a past date only if the promotion already holds it — and less than two years ahead, and appears once. At most 30 per calendar year, past dates included — see the promotion's `blackout_dates_quota`. Accepted only when the promotion's `blackout_dates_allowed` is `true`."}},"description":"The promotion to enable."}}},"paths":{"/channels/{channel_id}/mappings/{mapping_id}/promotions/enable":{"post":{"operationId":"AirbnbMappingPromotions_enable","summary":"Enable a promotion on a listing","description":"Enable a promotion on a mapped Airbnb listing. `blackout_dates` replaces\nthe dates the promotion holds, and an empty list clears them; without it,\nthe promotion is enabled with the dates it already holds. The response\nreports the promotion as `ONGOING`.\n\nEnabling a promotion that is already `ONGOING` returns it unchanged and\nleaves its dates as they are: to change them, update the promotion. An\n`EXPIRED` promotion cannot be enabled.\n\nA refusal is answered with `422 Unprocessable Entity`, `details` keyed by\nwhat it concerns: `blackout_dates` (one message per refused date, naming\nthe date), `type` when the type is unknown or the promotion cannot be\nenabled, or `promotion` for any other reason, a refusal by Airbnb\nincluded.","parameters":[{"name":"channel_id","in":"path","required":true,"description":"Channel connection ID.","schema":{"$ref":"#/components/schemas/Common.Scalars.id"}},{"name":"mapping_id","in":"path","required":true,"description":"Mapping ID — see `rate_plans[].id` of the channel connection.","schema":{"$ref":"#/components/schemas/Common.Scalars.id"}}],"responses":{"200":{"description":"The request has succeeded.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Airbnb.MappingPromotionResource"}},"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 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":["Airbnb"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Airbnb.MappingPromotionEnableRequest"}}}}}}}}
```

## Disable a promotion on a listing

> Disable a promotion on a mapped Airbnb listing. The response reports the\
> promotion as \`AVAILABLE\` again; disabling a promotion that is not\
> \`ONGOING\` returns it unchanged. The promotion keeps its blackout dates,\
> and enabling it again without \`blackout\_dates\` applies them.\
> \
> A refusal is answered with \`422 Unprocessable Entity\`, \`details\` keyed by\
> \`type\` when the type is missing or unknown, or \`promotion\` for any other\
> reason, a refusal by Airbnb included.

```json
{"openapi":"3.1.0","info":{"title":"Channex.io — Channels","version":"0.0.0"},"tags":[{"name":"Airbnb","description":"Airbnb-specific operations of channel connections: the authorization, the rate plan mappings that carry the listings, the listing settings stored on them (pricing, availability, and booking settings), and the actions over a mapped listing — publishing, checkout tasks, promotions, and opportunities."}],"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"},"Airbnb.MappingPromotionResource":{"type":"object","required":["type","attributes"],"properties":{"type":{"type":"string","enum":["promotion"]},"attributes":{"$ref":"#/components/schemas/Airbnb.MappingPromotion"}},"description":"A promotion resource of a mapped Airbnb listing."},"Airbnb.MappingPromotion":{"type":"object","required":["type","status","blackout_dates_allowed","blackout_dates_quota","discount","blackout_dates"],"properties":{"type":{"allOf":[{"$ref":"#/components/schemas/Airbnb.PromotionType"}],"description":"Type of the promotion."},"status":{"allOf":[{"$ref":"#/components/schemas/Airbnb.PromotionStatus"}],"description":"Status of the promotion for the listing."},"blackout_dates_allowed":{"type":"boolean","description":"Whether the promotion accepts `blackout_dates`. When `false`, the promotion cannot be updated."},"blackout_dates_quota":{"anyOf":[{"type":"object","unevaluatedProperties":{"$ref":"#/components/schemas/Airbnb.MappingPromotionBlackoutDatesQuota"}},{"type":"null"}],"description":"Blackout date usage per calendar year, keyed by year (`YYYY`): from the current year through the year of the last date that can be set. `null` when `blackout_dates_allowed` is `false`."},"discount":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.decimalString"}],"description":"Discount percentage of the promotion. Fixed for the promotion type; it cannot be changed through the API."},"blackout_dates":{"type":"array","items":{"type":"string","format":"date"},"description":"Dates on which the promotion does not apply, past ones included. A date sent is today or later in the property's time zone — a past date only if the promotion already holds it — and less than two years ahead, and appears once. At most 30 per calendar year, past dates included — see the promotion's `blackout_dates_quota`. Accepted only when the promotion's `blackout_dates_allowed` is `true`."}},"description":"A promotion of a mapped Airbnb listing: an available, enabled or expired promotion of one type."},"Airbnb.PromotionType":{"type":"string","enum":["NEW_LISTING_PROMOTION","HIGH_RATED_GUEST_DISCOUNT","MOBILE_ONLY_DISCOUNT"],"description":"Type of an Airbnb promotion."},"Airbnb.PromotionStatus":{"type":"string","enum":["AVAILABLE","ONGOING","EXPIRED"],"description":"Status of a promotion for a listing:\n- `AVAILABLE` — the promotion can be enabled;\n- `ONGOING` — the promotion is enabled;\n- `EXPIRED` — the promotion is no longer available."},"Airbnb.MappingPromotionBlackoutDatesQuota":{"type":"object","required":["dates_used_count","dates_available_count"],"properties":{"dates_used_count":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.nonNegativeInt"}],"description":"Number of blackout dates the promotion holds in the year, past ones included."},"dates_available_count":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.nonNegativeInt"}],"description":"Number of blackout dates that can still be set in the year."}},"description":"Blackout date usage of a promotion within one calendar year."},"Common.Scalars.nonNegativeInt":{"type":"integer","format":"int32","minimum":0},"Common.Scalars.decimalString":{"type":"string","description":"A decimal number as a string, e.g. `100.00`. Every monetary amount the API returns takes this form."},"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."},"Airbnb.MappingPromotionDisableRequest":{"type":"object","required":["promotion"],"properties":{"promotion":{"$ref":"#/components/schemas/Airbnb.MappingPromotionDisable"}},"description":"Request body of the promotion disable action."},"Airbnb.MappingPromotionDisable":{"type":"object","required":["type"],"properties":{"type":{"allOf":[{"$ref":"#/components/schemas/Airbnb.PromotionType"}],"description":"Type of the promotion."}},"description":"The promotion to disable."}}},"paths":{"/channels/{channel_id}/mappings/{mapping_id}/promotions/disable":{"post":{"operationId":"AirbnbMappingPromotions_disable","summary":"Disable a promotion on a listing","description":"Disable a promotion on a mapped Airbnb listing. The response reports the\npromotion as `AVAILABLE` again; disabling a promotion that is not\n`ONGOING` returns it unchanged. The promotion keeps its blackout dates,\nand enabling it again without `blackout_dates` applies them.\n\nA refusal is answered with `422 Unprocessable Entity`, `details` keyed by\n`type` when the type is missing or unknown, or `promotion` for any other\nreason, a refusal by Airbnb included.","parameters":[{"name":"channel_id","in":"path","required":true,"description":"Channel connection ID.","schema":{"$ref":"#/components/schemas/Common.Scalars.id"}},{"name":"mapping_id","in":"path","required":true,"description":"Mapping ID — see `rate_plans[].id` of the channel connection.","schema":{"$ref":"#/components/schemas/Common.Scalars.id"}}],"responses":{"200":{"description":"The request has succeeded.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Airbnb.MappingPromotionResource"}},"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 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":["Airbnb"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Airbnb.MappingPromotionDisableRequest"}}}}}}}}
```

## Update a promotion of a listing

> Replace the blackout dates of a promotion of a mapped Airbnb listing; an\
> empty list clears them. Only a promotion whose \`blackout\_dates\_allowed\` is\
> \`true\` can be updated. The dates of an \`AVAILABLE\` promotion are stored\
> without enabling it and apply once it is enabled; an \`EXPIRED\` promotion\
> cannot be updated.\
> \
> A refusal is answered with \`422 Unprocessable Entity\`, \`details\` keyed by\
> what it concerns: \`blackout\_dates\` (one message per refused date, naming\
> the date), \`type\` when the type is unknown or the promotion cannot be\
> updated, or \`promotion\` for any other reason, a refusal by Airbnb\
> included.

```json
{"openapi":"3.1.0","info":{"title":"Channex.io — Channels","version":"0.0.0"},"tags":[{"name":"Airbnb","description":"Airbnb-specific operations of channel connections: the authorization, the rate plan mappings that carry the listings, the listing settings stored on them (pricing, availability, and booking settings), and the actions over a mapped listing — publishing, checkout tasks, promotions, and opportunities."}],"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"},"Airbnb.MappingPromotionResource":{"type":"object","required":["type","attributes"],"properties":{"type":{"type":"string","enum":["promotion"]},"attributes":{"$ref":"#/components/schemas/Airbnb.MappingPromotion"}},"description":"A promotion resource of a mapped Airbnb listing."},"Airbnb.MappingPromotion":{"type":"object","required":["type","status","blackout_dates_allowed","blackout_dates_quota","discount","blackout_dates"],"properties":{"type":{"allOf":[{"$ref":"#/components/schemas/Airbnb.PromotionType"}],"description":"Type of the promotion."},"status":{"allOf":[{"$ref":"#/components/schemas/Airbnb.PromotionStatus"}],"description":"Status of the promotion for the listing."},"blackout_dates_allowed":{"type":"boolean","description":"Whether the promotion accepts `blackout_dates`. When `false`, the promotion cannot be updated."},"blackout_dates_quota":{"anyOf":[{"type":"object","unevaluatedProperties":{"$ref":"#/components/schemas/Airbnb.MappingPromotionBlackoutDatesQuota"}},{"type":"null"}],"description":"Blackout date usage per calendar year, keyed by year (`YYYY`): from the current year through the year of the last date that can be set. `null` when `blackout_dates_allowed` is `false`."},"discount":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.decimalString"}],"description":"Discount percentage of the promotion. Fixed for the promotion type; it cannot be changed through the API."},"blackout_dates":{"type":"array","items":{"type":"string","format":"date"},"description":"Dates on which the promotion does not apply, past ones included. A date sent is today or later in the property's time zone — a past date only if the promotion already holds it — and less than two years ahead, and appears once. At most 30 per calendar year, past dates included — see the promotion's `blackout_dates_quota`. Accepted only when the promotion's `blackout_dates_allowed` is `true`."}},"description":"A promotion of a mapped Airbnb listing: an available, enabled or expired promotion of one type."},"Airbnb.PromotionType":{"type":"string","enum":["NEW_LISTING_PROMOTION","HIGH_RATED_GUEST_DISCOUNT","MOBILE_ONLY_DISCOUNT"],"description":"Type of an Airbnb promotion."},"Airbnb.PromotionStatus":{"type":"string","enum":["AVAILABLE","ONGOING","EXPIRED"],"description":"Status of a promotion for a listing:\n- `AVAILABLE` — the promotion can be enabled;\n- `ONGOING` — the promotion is enabled;\n- `EXPIRED` — the promotion is no longer available."},"Airbnb.MappingPromotionBlackoutDatesQuota":{"type":"object","required":["dates_used_count","dates_available_count"],"properties":{"dates_used_count":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.nonNegativeInt"}],"description":"Number of blackout dates the promotion holds in the year, past ones included."},"dates_available_count":{"allOf":[{"$ref":"#/components/schemas/Common.Scalars.nonNegativeInt"}],"description":"Number of blackout dates that can still be set in the year."}},"description":"Blackout date usage of a promotion within one calendar year."},"Common.Scalars.nonNegativeInt":{"type":"integer","format":"int32","minimum":0},"Common.Scalars.decimalString":{"type":"string","description":"A decimal number as a string, e.g. `100.00`. Every monetary amount the API returns takes this form."},"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."},"Airbnb.MappingPromotionUpdateRequest":{"type":"object","required":["promotion"],"properties":{"promotion":{"$ref":"#/components/schemas/Airbnb.MappingPromotionUpdate"}},"description":"Request body of the promotion update."},"Airbnb.MappingPromotionUpdate":{"type":"object","required":["type","blackout_dates"],"properties":{"type":{"allOf":[{"$ref":"#/components/schemas/Airbnb.PromotionType"}],"description":"Type of the promotion."},"blackout_dates":{"type":"array","items":{"type":"string","format":"date"},"description":"Dates on which the promotion does not apply, past ones included. A date sent is today or later in the property's time zone — a past date only if the promotion already holds it — and less than two years ahead, and appears once. At most 30 per calendar year, past dates included — see the promotion's `blackout_dates_quota`. Accepted only when the promotion's `blackout_dates_allowed` is `true`."}},"description":"The promotion to update and its new blackout dates. The list replaces the current one as a whole; an empty list clears it."}}},"paths":{"/channels/{channel_id}/mappings/{mapping_id}/promotions":{"put":{"operationId":"AirbnbMappingPromotions_update","summary":"Update a promotion of a listing","description":"Replace the blackout dates of a promotion of a mapped Airbnb listing; an\nempty list clears them. Only a promotion whose `blackout_dates_allowed` is\n`true` can be updated. The dates of an `AVAILABLE` promotion are stored\nwithout enabling it and apply once it is enabled; an `EXPIRED` promotion\ncannot be updated.\n\nA refusal is answered with `422 Unprocessable Entity`, `details` keyed by\nwhat it concerns: `blackout_dates` (one message per refused date, naming\nthe date), `type` when the type is unknown or the promotion cannot be\nupdated, or `promotion` for any other reason, a refusal by Airbnb\nincluded.","parameters":[{"name":"channel_id","in":"path","required":true,"description":"Channel connection ID.","schema":{"$ref":"#/components/schemas/Common.Scalars.id"}},{"name":"mapping_id","in":"path","required":true,"description":"Mapping ID — see `rate_plans[].id` of the channel connection.","schema":{"$ref":"#/components/schemas/Common.Scalars.id"}}],"responses":{"200":{"description":"The request has succeeded.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Airbnb.MappingPromotionResource"}},"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 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":["Airbnb"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Airbnb.MappingPromotionUpdateRequest"}}}}}}}}
```
