{"components":{"callbacks":{},"examples":{},"headers":{},"links":{},"parameters":{"AccountIdHeaderOptional":{"description":"The identifier of an Amazon Ads Advertiser Account.","in":"header","name":"Amazon-Ads-AccountId","schema":{"type":"string"}},"ClientIdHeader":{"description":"The identifier of a client associated with a \u0027Login with Amazon\u0027 account.","in":"header","name":"Amazon-Ads-ClientId","required":true,"schema":{"type":"string"}},"ScopeHeaderOptional":{"description":"The identifier of a profile associated with the advertiser account. Use GET method on Profiles resource to list profiles associated with the access token passed in the HTTP Authorization header and choose profile id profileId from the response to pass it as input.","in":"header","name":"Amazon-Advertising-API-Scope","schema":{"type":"string"}}},"requestBodies":{},"responses":{},"schemas":{"BadGatewayResponseContent":{"properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"type":"object"},"BadRequestResponseContent":{"properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string"}},"required":["code","message"],"type":"object"},"CommunicationCategoryPreference":{"description":"An advertiser\u0027s subscription preference for a specific communication category.","properties":{"categoryDescription":{"description":"Description of the communications covered by this category.","type":"string"},"categoryId":{"description":"The communication category this preference applies to. Values are static configuration keys defined outside the domain model.","type":"string"},"categoryTitle":{"description":"Display name of the communication category.","type":"string"},"isCategorySubscribed":{"description":"Whether the advertiser is subscribed to this communication category. Effective only when communicationsEnabled is true.","type":"boolean"}},"required":["categoryId","isCategorySubscribed"],"type":"object"},"CommunicationChannel":{"description":"Channels through which communications can be delivered.\n**CommunicationChannel Enum:**\n\n| CommunicationChannel | Description |\n|------|------|\n| `EMAIL` | Email communications. |\n| `UI` | In-app communications. |\n","enum":["EMAIL","UI"],"type":"string"},"CommunicationPreference":{"properties":{"categoryPreferences":{"description":"Subscription preferences for individual communication categories on this channel.","items":{"$ref":"#/components/schemas/CommunicationCategoryPreference"},"maxItems":25,"minItems":0,"type":"array"},"channel":{"$ref":"#/components/schemas/CommunicationChannel"},"communicationPreferenceId":{"description":"Unique identifier for this communication preference.","type":"string"},"communicationsEnabled":{"description":"Whether communications are enabled for this channel. When false, all communications on this channel are suppressed regardless of individual category subscriptions.","type":"boolean"},"lastUpdateSource":{"$ref":"#/components/schemas/UpdateSource"},"lastUpdatedDateTime":{"description":"UTC timestamp of the most recent preference change.","format":"date-time","type":"string"}},"required":["channel","communicationPreferenceId","communicationsEnabled"],"type":"object"},"CommunicationPreferenceCommunicationChannelFilter":{"properties":{"include":{"description":"**Channel Enum:**\n| Channel | Description |\n| --- | --- |\n| `EMAIL` | Email communications. |\n| `UI` | In-app communications. |","items":{"$ref":"#/components/schemas/CommunicationChannel"},"maxItems":1,"minItems":1,"type":"array"}},"required":["include"],"type":"object"},"CommunicationPreferenceMultiStatusResponse":{"properties":{"error":{"items":{"$ref":"#/components/schemas/ErrorsIndex"},"maxItems":1,"minItems":0,"type":"array"},"success":{"items":{"$ref":"#/components/schemas/CommunicationPreferenceMultiStatusSuccess"},"maxItems":1,"minItems":0,"type":"array"}},"type":"object"},"CommunicationPreferenceMultiStatusSuccess":{"properties":{"communicationPreference":{"$ref":"#/components/schemas/CommunicationPreference"},"index":{"format":"int32","maximum":0,"minimum":0,"type":"integer"}},"required":["communicationPreference","index"],"type":"object"},"CommunicationPreferenceSuccessResponse":{"properties":{"communicationPreferences":{"items":{"$ref":"#/components/schemas/CommunicationPreference"},"maxItems":100,"minItems":0,"type":"array"},"nextToken":{"type":"string"}},"type":"object"},"CommunicationPreferenceUpdate":{"properties":{"categoryPreferences":{"description":"Subscription preferences for individual communication categories on this channel.","items":{"$ref":"#/components/schemas/CreateCommunicationCategoryPreference"},"maxItems":25,"minItems":0,"type":"array"},"communicationPreferenceId":{"description":"Unique identifier for this communication preference.","type":"string"},"communicationsEnabled":{"description":"Whether communications are enabled for this channel. When false, all communications on this channel are suppressed regardless of individual category subscriptions.","type":"boolean"}},"required":["communicationPreferenceId"],"type":"object"},"ContentTooLargeResponseContent":{"properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string"}},"required":["code","message"],"type":"object"},"CreateCommunicationCategoryPreference":{"description":"An advertiser\u0027s subscription preference for a specific communication category.","properties":{"categoryId":{"description":"The communication category this preference applies to. Values are static configuration keys defined outside the domain model.","type":"string"},"isCategorySubscribed":{"description":"Whether the advertiser is subscribed to this communication category. Effective only when communicationsEnabled is true.","type":"boolean"}},"required":["categoryId","isCategorySubscribed"],"type":"object"},"Error":{"properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"fieldLocation":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"type":"object"},"ErrorCode":{"description":"**ErrorCode Enum:**\n\n| ErrorCode | Description |\n|------|------|\n| `BAD_REQUEST` | The request is not valid considering the documented schema. |\n| `CONTENT_TOO_LARGE` | The request is too large. Consider splitting it into multiple requests. |\n| `FORBIDDEN` | The caller is not authorized to make the given request. |\n| `INTERNAL_ERROR` | The server encountered an unexpected condition that prevented it from fulfilling the request. |\n| `NOT_FOUND` | The requested resource does not exist. |\n| `TOO_MANY_REQUESTS` | There have been too many requests, please slow down your call rate. |\n| `UNAUTHORIZED` | The request lacks the necessary credentials. |\n","enum":["BAD_REQUEST","CONTENT_TOO_LARGE","FORBIDDEN","INTERNAL_ERROR","NOT_FOUND","TOO_MANY_REQUESTS","UNAUTHORIZED"],"type":"string"},"ErrorsIndex":{"properties":{"errors":{"items":{"$ref":"#/components/schemas/Error"},"maxItems":20,"minItems":1,"type":"array"},"index":{"format":"int32","maximum":9,"minimum":0,"type":"integer"}},"required":["errors","index"],"type":"object"},"ForbiddenResponseContent":{"properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string"}},"required":["code","message"],"type":"object"},"GatewayTimeoutResponseContent":{"properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"type":"object"},"InternalServerErrorResponseContent":{"properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"type":"object"},"NotFoundResponseContent":{"properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string"}},"required":["code","message"],"type":"object"},"QueryCommunicationPreferenceRequest":{"properties":{"channelFilter":{"$ref":"#/components/schemas/CommunicationPreferenceCommunicationChannelFilter"},"maxResults":{"default":100,"format":"int32","maximum":100,"minimum":1,"type":"integer"},"nextToken":{"type":"string"}},"required":["channelFilter"],"type":"object"},"ServiceUnavailableErrorResponseContent":{"properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"type":"object"},"TooManyRequestsResponseContent":{"properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string"}},"required":["code","message"],"type":"object"},"UnauthorizedResponseContent":{"properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string"}},"required":["code","message"],"type":"object"},"UpdateCommunicationPreferenceRequest":{"properties":{"communicationPreferences":{"items":{"$ref":"#/components/schemas/CommunicationPreferenceUpdate"},"maxItems":1,"minItems":1,"type":"array"}},"required":["communicationPreferences"],"type":"object"},"UpdateSource":{"description":"Origins from which preference changes can be made.\n**UpdateSource Enum:**\n\n| UpdateSource | Description |\n|------|------|\n| `ADS_CONSOLE` | Changed via the Ads Console. |\n| `EMAIL` | Changed via the email unsubscribe link. |\n","enum":["ADS_CONSOLE","EMAIL"],"type":"string"}},"securitySchemes":{"OAuth2":{"flows":{"authorizationCode":{"authorizationUrl":"https://www.amazon.com/ap/oa","scopes":{"advertising::audiences":"Grants access to data provider APIs","advertising::campaign_management":"Grants write access to campaign management.","advertising::test:create_account":"Grants write access to create test accounts functionality","cpc_advertising:campaign_management":"Grants write access to campaign management. Legacy name (no difference from advertising::campaign_management)"},"tokenUrl":"https://api.amazon.com/auth/o2/token"}},"type":"oauth2"}}},"info":{"description":"Amazon Ads API v1 is a reimagined approach to our Ads API, built to provide a seamless experience across all Amazon advertising products through a common model. [Learn more about Ads API v1.](https://advertising.amazon.com/API/docs/en-us/reference/amazon-ads/overview) To learn about prerequisites and header values, see [Getting started with Amazon Ads API v1](https://advertising.amazon.com/API/docs/en-us/reference/amazon-ads/getting-started).\n\n**Download Amazon Ads API V1 OpenAPI Spec** ([All Products](https://d1y2lf8k3vrkfu.cloudfront.net/openapi/en-us/dest/AmazonAdsAPIALLMerged_prod_3p_ALL.json) | [SP](https://d1y2lf8k3vrkfu.cloudfront.net/openapi/en-us/dest/AmazonAdsAPISPMerged_prod_3p_ALL.json) | [SP Global](https://d1y2lf8k3vrkfu.cloudfront.net/openapi/en-us/dest/AmazonAdsAPISPGLOBALMerged_prod_3p_ALL.json) | [SB](https://d1y2lf8k3vrkfu.cloudfront.net/openapi/en-us/dest/AmazonAdsAPISBMerged_prod_3p_ALL.json) | [DSP](https://d1y2lf8k3vrkfu.cloudfront.net/openapi/en-us/dest/AmazonAdsAPIDSPMerged_prod_3p_ALL.json) | [ST](https://d1y2lf8k3vrkfu.cloudfront.net/openapi/en-us/dest/AmazonAdsAPISTMerged_prod_3p_ALL.json) | [SD](https://d1y2lf8k3vrkfu.cloudfront.net/openapi/en-us/dest/AmazonAdsAPISDMerged_prod_3p_ALL.json))","title":"CommunicationPreferences API","version":"3.0"},"openapi":"3.0.1","paths":{"/adsApi/v1/query/communicationPreferences":{"post":{"description":"Returns communication preferences for the authenticated advertiser, optionally filtered by channel.\n\n**Requires one of these permissions**:\n[\"account_view\", \"account_edit\"]","operationId":"QueryCommunicationPreference","parameters":[{"$ref":"#/components/parameters/AccountIdHeaderOptional"},{"$ref":"#/components/parameters/ClientIdHeader"},{"$ref":"#/components/parameters/ScopeHeaderOptional"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryCommunicationPreferenceRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommunicationPreferenceSuccessResponse"}}},"description":"QueryCommunicationPreference 200 response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResponseContent"}}},"description":"BadRequest 400 response"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedResponseContent"}}},"description":"Unauthorized 401 response"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenResponseContent"}}},"description":"Forbidden 403 response"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundResponseContent"}}},"description":"NotFound 404 response"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentTooLargeResponseContent"}}},"description":"ContentTooLarge 413 response"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsResponseContent"}}},"description":"TooManyRequests 429 response"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorResponseContent"}}},"description":"InternalServerError 500 response"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadGatewayResponseContent"}}},"description":"BadGateway 502 response"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceUnavailableErrorResponseContent"}}},"description":"ServiceUnavailableError 503 response"},"504":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayTimeoutResponseContent"}}},"description":"GatewayTimeout 504 response"}},"security":[{"OAuth2":["advertising::campaign_management"]}],"tags":["CommunicationPreferences"]}},"/adsApi/v1/update/communicationPreferences":{"post":{"description":"Updates communication preferences for the authenticated advertiser. Supports updating notification toggles and category subscriptions.\n\n**Requires one of these permissions**:\n[\"account_edit\"]","operationId":"UpdateCommunicationPreference","parameters":[{"$ref":"#/components/parameters/AccountIdHeaderOptional"},{"$ref":"#/components/parameters/ClientIdHeader"},{"$ref":"#/components/parameters/ScopeHeaderOptional"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCommunicationPreferenceRequest"}}},"required":true},"responses":{"207":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommunicationPreferenceMultiStatusResponse"}}},"description":"UpdateCommunicationPreference 207 response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResponseContent"}}},"description":"BadRequest 400 response"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedResponseContent"}}},"description":"Unauthorized 401 response"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenResponseContent"}}},"description":"Forbidden 403 response"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundResponseContent"}}},"description":"NotFound 404 response"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentTooLargeResponseContent"}}},"description":"ContentTooLarge 413 response"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsResponseContent"}}},"description":"TooManyRequests 429 response"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorResponseContent"}}},"description":"InternalServerError 500 response"},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadGatewayResponseContent"}}},"description":"BadGateway 502 response"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceUnavailableErrorResponseContent"}}},"description":"ServiceUnavailableError 503 response"},"504":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayTimeoutResponseContent"}}},"description":"GatewayTimeout 504 response"}},"security":[{"OAuth2":["advertising::campaign_management"]}],"tags":["CommunicationPreferences"]}}},"servers":[{"description":"Production server for NA","url":"https://advertising-api.amazon.com"},{"description":"Production server for EU","url":"https://advertising-api-eu.amazon.com"},{"description":"Production server for FE","url":"https://advertising-api-fe.amazon.com"}]}