Amazon Ads API MCP

{"openapi":"3.0.1","info":{"version":"3.0","title":"Amazon Ads API for Data Providers.","description":"Use to create, read, or update audience metadata and to add or remove audience records. For onboarding information, see [_setting up for the Amazon Ads API_](../guides/onboarding/overview).","contact":{"name":"Amazon Ads API Support","url":"https://amzn-clicks.atlassian.net/servicedesk/customer/portals"},"license":{"name":"Amazon Ads Data Provider Agreement","url":"https://advertising.amazon.com/dsp/agreement/dataProviderApi/en"}},"tags":[{"name":"Metadata"},{"name":"Add or remove records"},{"name":"User deletion"}],"paths":{"/v2/dp/audiencemetadata/":{"post":{"tags":["Metadata"],"summary":"Creates a new data provider audience. Note that the API call rate is limited to 1 transaction per second (TPS). Calls exceeding this rate are throttled.","parameters":[{"$ref":"#/components/parameters/authorizationHeader"},{"$ref":"#/components/parameters/clientHeader"},{"$ref":"#/components/parameters/contentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","description","advertiserId","metadata"],"properties":{"name":{"$ref":"#/components/schemas/audienceName"},"description":{"$ref":"#/components/schemas/audienceDescription"},"advertiserId":{"$ref":"#/components/schemas/advertiserId"},"metadata":{"type":"object","required":["type","externalAudienceId","dataSourceCountry"],"properties":{"type":{"$ref":"#/components/schemas/metadataType"},"externalAudienceId":{"$ref":"#/components/schemas/externalAudienceId"},"ttl":{"$ref":"#/components/schemas/recordTtl"},"audienceFees":{"$ref":"#/components/schemas/audienceFees"},"dataSourceCountry":{"$ref":"#/components/schemas/dataSourceCountry"}}}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"$ref":"#/components/schemas/requestId"},"audience":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/audienceId"},"name":{"$ref":"#/components/schemas/audienceName"},"description":{"$ref":"#/components/schemas/audienceDescription"},"advertiserId":{"$ref":"#/components/schemas/advertiserId"},"metadata":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/metadataType"},"externalAudienceId":{"$ref":"#/components/schemas/externalAudienceId"},"ttl":{"$ref":"#/components/schemas/recordTtl"},"audienceFees":{"$ref":"#/components/schemas/audienceFees"},"dataSourceCountry":{"$ref":"#/components/schemas/dataSourceCountry"}}}}}}}}}},"400":{"$ref":"#/components/responses/400BadRequest"},"403":{"$ref":"#/components/responses/403NotAllowed"},"404":{"$ref":"#/components/responses/404NotFound"},"429":{"$ref":"#/components/responses/429TooManyRequests"},"500":{"$ref":"#/components/responses/500InternalError"},"503":{"$ref":"#/components/responses/503ServiceUnavailable"}}}},"/v2/dp/audiencemetadata/{audienceId}":{"put":{"tags":["Metadata"],"summary":"Updates metadata of an existing audience specified by identifier. Note that the API call rate is limited to 1 transaction per second (TPS). Calls exceeding this rate are throttled.","parameters":[{"$ref":"#/components/parameters/authorizationHeader"},{"$ref":"#/components/parameters/clientHeader"},{"$ref":"#/components/parameters/contentTypeHeader"},{"$ref":"#/components/parameters/audienceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"A data provider audience object with updated values.","properties":{"description":{"$ref":"#/components/schemas/audienceDescription"},"metadata":{"type":"object","properties":{"ttl":{"$ref":"#/components/schemas/recordTtl"},"audienceFees":{"$ref":"#/components/schemas/audienceFees"},"dataSourceCountry":{"$ref":"#/components/schemas/dataSourceCountry"}}}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"$ref":"#/components/schemas/requestId"},"audience":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/audienceId"},"name":{"$ref":"#/components/schemas/audienceName"},"description":{"$ref":"#/components/schemas/audienceDescription"},"advertiserId":{"$ref":"#/components/schemas/advertiserId"},"metadata":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/metadataType"},"externalAudienceId":{"$ref":"#/components/schemas/externalAudienceId"},"ttl":{"$ref":"#/components/schemas/recordTtl"},"audienceFees":{"$ref":"#/components/schemas/audienceFees"},"dataSourceCountry":{"$ref":"#/components/schemas/dataSourceCountry"}}}}}}}}}},"400":{"$ref":"#/components/responses/400BadRequest"},"403":{"$ref":"#/components/responses/403NotAllowed"},"404":{"$ref":"#/components/responses/404NotFound"},"429":{"$ref":"#/components/responses/429TooManyRequests"},"500":{"$ref":"#/components/responses/500InternalError"},"503":{"$ref":"#/components/responses/503ServiceUnavailable"}}},"get":{"tags":["Metadata"],"summary":"Gets metadata for an audience specified by identifier. Note that the API call rate is limited to 1 transaction per second (TPS). Calls exceeding this rate are throttled.","parameters":[{"$ref":"#/components/parameters/authorizationHeader"},{"$ref":"#/components/parameters/clientHeader"},{"$ref":"#/components/parameters/contentTypeHeader"},{"$ref":"#/components/parameters/audienceId"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"$ref":"#/components/schemas/requestId"},"audience":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/audienceId"},"name":{"$ref":"#/components/schemas/audienceName"},"description":{"$ref":"#/components/schemas/audienceDescription"},"advertiserId":{"$ref":"#/components/schemas/advertiserId"},"metadata":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/metadataType"},"externalAudienceId":{"$ref":"#/components/schemas/externalAudienceId"},"ttl":{"$ref":"#/components/schemas/recordTtl"},"audienceFees":{"$ref":"#/components/schemas/audienceFees"},"audienceSize":{"type":"object","description":"Information about the size of the audience.","properties":{"receivedRecordSize":{"type":"integer","description":"The number of received records."},"matchedRecordSize":{"type":"integer","description":"The number of matched records."},"matchRate":{"type":"number","format":"float","description":"The match rate.","minimum":0,"maximum":1}}},"dataSourceCountry":{"$ref":"#/components/schemas/dataSourceCountry"}}}}}}}}}},"403":{"$ref":"#/components/responses/403NotAllowed"},"404":{"$ref":"#/components/responses/404NotFound"},"429":{"$ref":"#/components/responses/429TooManyRequests"},"500":{"$ref":"#/components/responses/500InternalError"},"503":{"$ref":"#/components/responses/503ServiceUnavailable"}}}},"/v2/dp/audience":{"patch":{"summary":"Associates or disassociates a record with an audience. Note that the API call rate is limited to 100 transactions per second (TPS). Calls exceeding this rate are throttled. Payload size is limited to a maximum of 6MB or 2000 records. Calls with a payload exceeding limit receive a 413 response.","tags":["Add or remove records"],"parameters":[{"$ref":"#/components/parameters/authorizationHeader"},{"$ref":"#/components/parameters/clientHeader"},{"$ref":"#/components/parameters/contentTypeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"patches":{"type":"array","items":{"type":"object","properties":{"op":{"type":"string","description":"Specifies the type of operation. Valid operations are `add` or `remove`.","enum":["add","remove"]},"path":{"type":"string","format":"/<recordIdType>-<recordIdValue>/audiences","example":"/COOKIE-EMpBAI0GRcK4nBNGpPGg5g/audiences","description":"A formatted string that specifies the URL of the record. The format of the string is `/<recordIdType>-<recordIdValue>/audiences`, where 'recordIdType' specifies the record's origin and 'recordIdValue' specifies the record's Id. Valid 'recordIdType' values are `COOKIE`, a cookie Id sent from a data provider to Amazon by a cookie sync; `MAID`, a mobile advertising identifier; `EXTERNAL_USER_ID`, an external id defined by data providers."},"value":{"type":"array","items":{"type":"integer","format":"int64","description":"An integer value representing the Amazon audience identifer. This is the identifier that is returned during audience creation.","example":72057594038053890}},"consent":{"type":"object","description":"An object that contains user consent. Only one type of consent(TCF, GPP, amazonConsent) should be provided.","discriminator":{"propertyName":"consentType","mapping":{"TCF":"#/components/schemas/tcf","GPP":"#/components/schemas/gpp","Amazon":"#/components/schemas/amazonConsent"}},"properties":{"consentType":{"type":"string","description":"The type of consent provided.","enum":["TCF","GPP","Amazon"]},"tcf":{"$ref":"#/components/schemas/tcf"},"gpp":{"$ref":"#/components/schemas/gpp"},"amazonConsent":{"$ref":"#/components/schemas/amazonConsent"}}}}}}}}}}},"responses":{"200":{"description":"The request to add or remove an audience was submitted. Note that requests can take up to two hours to be processed.","content":{"application/json":{"schema":{"type":"object","properties":{"jobId":{"type":"string","description":"A unique identifier representing the workflow of the submitted request.","example":"f076ddd9-3f84-44e8-b5cf-742b08f2bc9f"},"requestId":{"type":"string","description":"A unique identifier representing the request.","example":"F88750355N-B70JY53CSD"}}}}}},"400":{"$ref":"#/components/responses/400BadRequest"},"413":{"description":"Input Too Large.","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"description":"Identifier associated with the request.","type":"string","example":"F88750355N-B70JY53CSD"},"error":{"description":"Detailed error messages associated with the request.","type":"object","properties":{"httpStatusCode":{"description":"HTTP status code associated with the response.","type":"string","example":413},"description":{"description":"Description of the error.","type":"string","example":"Input Too Large"},"errors":{"description":"An array of property objects that include more information about the request.","type":"array","items":{"type":"object","properties":{"errorType":{"description":"Type of error.","type":"string","example":"INPUT_TOO_LARGE"},"message":{"description":"Error message","type":"string","example":"The input payload exceeds 1MB limit."}}}}}}}}}}},"429":{"$ref":"#/components/responses/429TooManyRequests"},"500":{"$ref":"#/components/responses/500InternalError"},"503":{"$ref":"#/components/responses/503ServiceUnavailable"}}}},"/v2/dp/users":{"patch":{"description":"Deletes user data sourced from data providers. Deletes users scoped either to an advertiser or for the data provider. The SLA for data deletion is 30 days.","summary":"Deletes user data originally sourced from the client. The API call rate is limited to 1 transactions per second (TPS). Calls exceeding this rate are throttled. Payload size is limited to 1000 users or 1MB. Calls with a more than 1000 users or 1MB will receive a 413 response.","tags":["User deletion"],"parameters":[{"in":"header","name":"Authorization","schema":{"type":"string"},"description":"A valid access token. ","example":"Bearer Atza|IQEBLjAsAhRmHjNgHpi0UDme37rR6CuUpSR","required":true},{"in":"header","name":"Amazon-Advertising-API-ClientID","schema":{"type":"string"},"description":"The client identifier.","example":"amzn1.application-oa2-client.8baa9caa3eac48eab89780e73ce03b19","required":true},{"in":"header","name":"Content-Type","schema":{"type":"string"},"description":"The Content-Type is `application/json`.","example":"application/json","required":true}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"users":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"object","properties":{"type":{"type":"string","description":"Specifies the type of the user identifier.","enum":["COOKIE","MAID","EXTERNAL_USER_ID"]},"value":{"type":"string","description":"The user identifer."}}},"advertiserId":{"type":"string","description":"The advertiser identifier. If present, the user data for the specified advertiser is deleted. Otherwise, all data about this user sourced from this client is deleted.","example":205759403805},"consentTime":{"type":"integer","format":"int64","description":"User consent time in epoch milliseconds","example":1581557890000}}}},"operation":{"type":"string","enum":["DELETE"]}}},"example":{"users":[{"userId":{"type":"COOKIE","value":"EMpBAI0GRcK4nBNGpPGg5g"},"advertiserId":205759403805,"consentTime":1581557890000},{"userId":{"type":"COOKIE","value":"EMpBAI0GRcK4nBNGpPGg5g"},"advertiserId":305759403805,"consentTime":1581557900000}],"operation":"DELETE"}}}},"responses":{"202":{"description":"The request to delete user data was submitted.","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"string","description":"A unique identifier representing the request.","example":"F88750355N-B70JY53CSD"}}}}}},"400":{"description":"Bad Request.","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"description":"Identifier associated with the request.","type":"string","example":"F88750355N-B70JY53CSD"},"error":{"description":"Detailed error messages associated with the request.","type":"object","properties":{"httpStatusCode":{"description":"HTTP status code associated with the response.","type":"string","example":400},"description":{"description":"Description of the error.","type":"string","example":"Bad Request"},"errors":{"description":"An array of property objects that include more information about the request.","type":"array","items":{"type":"object","properties":{"errorType":{"description":"Type of error.","type":"string","example":"INVALID_INPUT"},"message":{"description":"Error message","type":"string","example":"The inputs that you provided are not valid."}}}}}}}}}}},"413":{"description":"Input Too Large.","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"description":"Identifier associated with the request.","type":"string","example":"F88750355N-B70JY53CSD"},"error":{"description":"Detailed error messages associated with the request.","type":"object","properties":{"httpStatusCode":{"description":"HTTP status code associated with the response.","type":"string","example":413},"description":{"description":"Description of the error.","type":"string","example":"Input Too Large"},"errors":{"description":"An array of property objects that include more information about the request.","type":"array","items":{"type":"object","properties":{"errorType":{"description":"Type of error.","type":"string","example":"INPUT_TOO_LARGE"},"message":{"description":"Error message","type":"string","example":"The input payload exceeds 1MB limit."}}}}}}}}}}},"429":{"description":"Too Many Requests.","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"description":"Identifier associated with the request.","type":"string","example":"F88750355N-B70JY53CSD"},"error":{"description":"Detailed error messages associated with the request.","type":"object","properties":{"httpStatusCode":{"description":"HTTP status code associated with the response.","type":"string","example":429},"description":{"description":"Description of the error.","type":"string","example":"Too Many Requests"},"errors":{"description":"An array of property objects that include more information about the request.","type":"array","items":{"type":"object","properties":{"errorType":{"description":"Type of error.","type":"string","example":"TOO_MANY_REQUESTS"},"message":{"description":"Error message","type":"string","example":"The number of requests exceeded 100 TPS."}}}}}}}}}}},"500":{"description":"Internal Server Error.","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"description":"Identifier associated with the request.","type":"string","example":"F88750355N-B70JY53CSD"},"error":{"description":"Detailed error messages associated with the request.","type":"object","properties":{"httpStatusCode":{"description":"HTTP status code associated with the response.","type":"string","example":500},"description":{"description":"Description of the error.","type":"string","example":"Internal Error"},"errors":{"description":"An array of property objects that include more information about the request.","type":"array","items":{"type":"object","properties":{"errorType":{"description":"Type of error.","type":"string","example":"INTERNAL_ERROR"},"message":{"description":"Error message","type":"string","example":"Internal error."}}}}}}}}}}},"503":{"description":"Server Unavailable.","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"description":"Identifier associated with the request.","type":"string","example":"F88750355N-B70JY53CSD"},"error":{"description":"Detailed error messages associated with the request.","type":"object","properties":{"httpStatusCode":{"description":"HTTP status code associated with the response.","type":"string","example":503},"description":{"description":"Description of the error.","type":"string","example":"Service unavailable"},"errors":{"description":"An array of property objects that include more information about the request.","type":"array","items":{"type":"object","properties":{"errorType":{"description":"Type of error.","type":"string","example":"SERVICE_UNAVAILABLE"},"message":{"description":"Error message","type":"string","example":"Service unavailable."}}}}}}}}}}}}}}},"components":{"schemas":{"audienceName":{"type":"string","description":"The audience name. Must be an alphanumeric string between 10 to 128 characters in length."},"audienceDescription":{"type":"string","description":"The audience description. Must be an alphanumeric, non-null string between 0 to 1000 characters in length."},"audienceId":{"type":"integer","format":"int64","description":"The"},"advertiserId":{"type":"integer","format":"int64","description":"The advertiser identifier."},"metadataType":{"type":"string","description":"The audience metadata type. Only 'DATA_PROVIDER' is currently supported.","enum":["DATA_PROVIDER"]},"externalAudienceId":{"type":"string","description":"The user-defined audience identifier."},"recordTtl":{"type":"integer","description":"Time-to-live (ttl), in seconds. The amount of time the record is associated with the audience.","minimum":0,"maximum":34300800},"audienceFees":{"type":"array","items":{"type":"object","required":["cpmCents","currency"],"description":"Object describing the audience fee.","properties":{"cpmCents":{"type":"integer","description":"Cost per thousand impressions (CPM) in cents. For example, $1.00 = 100 cents."},"currency":{"type":"string","description":"Currency key as defined in https://en.wikipedia.org/wiki/ISO_4217. Note that the currency key is required to match the default currency associated with the Amazon DSP account.","enum":["USD","CAD","JPY","GBP","EUR","AUD","AED","SAR","MXN","INR","SEK","TRY","BRL"]}}}},"dataSourceCountry":{"type":"array","description":"A list of country codes describing where data in an audience is collected from. Country code is defined in https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2.","example":["US","CA"],"items":{"type":"string","description":"Country code is defined in https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2.","example":"GB"}},"requestId":{"description":"The request identifier.","type":"string","example":"a1b1234c-d11d-4e5f-82gh-c609c22255bd"},"httpStatusCode":{"description":"The HTTP status code.","type":"string","example":400},"errorDescription":{"description":"A human-readable description of the error.","type":"string","example":"Bad Request"},"subError":{"type":"array","items":{"type":"object","properties":{"errorType":{"description":"The type of error.","type":"string","example":"INVALID_INPUT"},"message":{"description":"A human-readable description of the error.","type":"string","example":"The input field 'name' cannot be updated"},"fieldName":{"description":"The field name.","type":"string","example":"name"}}}},"tcf":{"type":"string","description":"TCF(Transparency & Consent Framework) consent string that wraps privacy consent information from user.","example":"CQB4ySFQB4ySFBlAAAENCZCAAAAAAAAAAAAAAAAAAAAA.II7Nd_X__bX9n-_7_6ft0eY1f9_r37uQzDhfNs-8F3L_W_LwX32E7NF36tq4KmR4ku1bBIQNtHMnUDUmxaolVrzHsak2cpyNKJ_JkknsZe2dYGF9Pn9lD-YKZ7_5_9_f52T_9_9_-39z3_9f___dv_-__-vjf_599n_v9fV_78_Kf9______-____________8A"},"gpp":{"type":"string","description":"GPP(Global Privacy Platform) consent string that wraps privacy consent information from user.","example":"DBADMZg~CQB2TAAQB2TAAPoABABGA9EAAAAAAAAAAAAAAAAAAAAA.QAAA.IAAA~BQB2TAAQB2TAAPoABABGBZCAAAAAAAgAAAAAAAAAAA.YAAAAAAAAAA~BAAAAAAAAQA.QA"},"amazonConsent":{"type":"object","properties":{"amazonAdStorage":{"type":"string","description":"Set consent for advertising related storage such as cookies(web) or device identifiers(apps).","enum":["GRANTED","DENIED"]},"amazonUserData":{"type":"string","description":"Set consent to use personal data for online advertising purposes.","enum":["GRANTED","DENIED"]}},"required":["amazonAdStorage","amazonUserData"],"example":{"amazonAdStorage":"GRANTED","amazonUserData":"GRANTED"}}},"parameters":{"audienceId":{"name":"audienceId","in":"path","required":true,"description":"The audience identifier.","schema":{"type":"integer","format":"int64"}},"authorizationHeader":{"in":"header","name":"Authorization","description":"A valid access token.","schema":{"type":"string"},"example":"Bearer Atza|IQEBLjAsAhRmHjNgHpi0UDme37rR6CuUpSR","required":true},"clientHeader":{"name":"Amazon-Advertising-API-ClientId","in":"header","description":"The identifier of a client associated with a \"Login with Amazon\" account.","required":true,"schema":{"type":"string"}},"contentTypeHeader":{"in":"header","name":"Content-Type","schema":{"type":"string"},"description":"The `Content-Type` is application/json.","example":"application/json","required":true}},"responses":{"400BadRequest":{"description":"Bad Request.","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"$ref":"#/components/schemas/requestId"},"error":{"type":"object","properties":{"httpStatusCode":{"$ref":"#/components/schemas/httpStatusCode"},"description":{"$ref":"#/components/schemas/errorDescription"},"errors":{"$ref":"#/components/schemas/subError"}}}}}}}},"403NotAllowed":{"description":"The client is not allowed to update the audience.","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"$ref":"#/components/schemas/requestId"},"error":{"type":"object","properties":{"httpStatusCode":{"$ref":"#/components/schemas/httpStatusCode"},"description":{"$ref":"#/components/schemas/errorDescription"},"errors":{"$ref":"#/components/schemas/subError"}}}}}}}},"404NotFound":{"description":"The specified identifier was not found.","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"$ref":"#/components/schemas/requestId"},"error":{"type":"object","properties":{"httpStatusCode":{"$ref":"#/components/schemas/httpStatusCode"},"description":{"$ref":"#/components/schemas/errorDescription"},"errors":{"$ref":"#/components/schemas/subError"}}}}}}}},"429TooManyRequests":{"description":"The client exceeded the allowed number of requests..","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"$ref":"#/components/schemas/requestId"},"error":{"type":"object","properties":{"httpStatusCode":{"$ref":"#/components/schemas/httpStatusCode"},"description":{"$ref":"#/components/schemas/errorDescription"},"errors":{"$ref":"#/components/schemas/subError"}}}}}}}},"500InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"$ref":"#/components/schemas/requestId"},"error":{"type":"object","properties":{"httpStatusCode":{"$ref":"#/components/schemas/httpStatusCode"},"description":{"$ref":"#/components/schemas/errorDescription"},"errors":{"$ref":"#/components/schemas/subError"}}}}}}}},"503ServiceUnavailable":{"description":"The service is unavailable.","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"$ref":"#/components/schemas/requestId"},"error":{"type":"object","properties":{"httpStatusCode":{"$ref":"#/components/schemas/httpStatusCode"},"description":{"$ref":"#/components/schemas/errorDescription"},"errors":{"$ref":"#/components/schemas/subError"}}}}}}}}}}}