Amazon Ads API MCP

{"components":{"callbacks":{},"examples":{},"headers":{},"links":{},"parameters":{},"requestBodies":{},"responses":{},"schemas":{"AdvertiserResponse":{"properties":{"advertisers":{"items":{"$ref":"#/components/schemas/advertiser"},"type":"array"}},"type":"object"},"AttributionTagResponse":{"properties":{"advertiserAttributionTagMap":{"additionalProperties":{"$ref":"#/components/schemas/attributionTagMap"},"description":"A list of advertisers and associated attribution tags.","example":{"advertiserA":{"1":"tag1A","2":"tag2A"},"advertiserB":{"1":"tag2B","2":"tag2B"}},"type":"object"}},"type":"object"},"MaaSError":{"description":"The error response object.","properties":{"code":{"description":"The HTTP status code of the response. Possible value of code is \"200\", \"207\", \"400\", \"401\", \"429\", \"403\", or \"500\".","type":"string"},"details":{"description":"A human-readable description of the response.","type":"string"}},"type":"object"},"Publisher":{"properties":{"id":{"allOf":[{"description":"The identifier of a macro publisher.","type":"string","x-amazon-advertising-package":"MaaSPublicAPIAPISwagger"},{"description":"The identifier of a publisher that does not support macros.","type":"string","x-amazon-advertising-package":"MaaSPublicAPIAPISwagger"}],"description":"The identifier of a publisher.","type":"object"},"macroEnabled":{"description":"Set to 'true' if Amazon Attribution provides macro tags for the given publisher.","type":"boolean"},"name":{"description":"The name of the publisher.","type":"string"}},"type":"object"},"PublishersResponse":{"properties":{"publisher":{"description":"A list of publishers.","items":{"$ref":"#/components/schemas/Publisher"},"type":"array"}},"type":"object"},"ReportEntry":{"description":"Report entry object in GetReport reports list.","properties":{"adGroupId":{"description":"An ad group external identifier. Applies to `PERFORMANCE` and `PRODUCTS` reportType.","type":"string"},"advertiserName":{"description":"Name of advertiser. Applies to `PERFORMANCE` and `PRODUCTS` reportType.","type":"string"},"brandName":{"description":"Name of the advertiser's brand. Applies only to `PRODUCTS` reportType.","type":"string"},"campaignId":{"description":"A campaign external identifier. Applies to `PERFORMANCE` and `PRODUCTS` reportType.","type":"string"},"creativeId":{"description":"A creative external identifier. Applies only to `PERFORMANCE` reportType","type":"string"},"date":{"description":"Date on which the events took place. Applies to `PERFORMANCE` and `PRODUCTS` reportType.","type":"string"},"marketplace":{"description":"The Amazon-owned site the product is sold on. Applies only to `PRODUCTS` reportType.","type":"string"},"productAsin":{"description":"A unique block of letters and/or numbers that identify all products sold on Amazon. Applies only to `PRODUCTS` reportType.","type":"string"},"productCategory":{"description":"A classification for the type of product being sold which determines its place in the Amazon retail catalog. Contains categories of products. Applies only to `PRODUCTS` reportType.","type":"string"},"productConversionType":{"description":"The conversion type describes whether the conversion happened on a promoted or a brand halo ASIN. Applies only to `PRODUCTS` reportType.","type":"string"},"productGroup":{"description":"A distinct product grouping distinguishing products like watches from video games from toys. Contains groups of products. Applies only to `PRODUCTS` reportType.","type":"string"},"productName":{"description":"The name of the product. Applies only to `PRODUCTS` reportType.","type":"string"},"productSubcategory":{"description":"A classification for the type of product being sold which determines its place in the Amazon retail catalog. Contains subcategories of products. Applies only to `PRODUCTS` reportType","type":"string"},"publisher":{"description":"The publisher name. Applies to `PERFORMANCE` and `PRODUCTS` reportType","type":"string"}},"type":"object"},"ReportRequestBody":{"description":"Report request body. \nTwo types of reports are available: Performance or Products - choose by including the `reportType` property. Performance report may be aggregated at any of three levels: campaign, ad group, or creative - choose by including the `groupBy` property. Products report is always aggregated at ad group level - when requesting a Products report, do not include the `groupBy` property or an error will occur.\n\nPagination is recommended - include the `count` and `cursorId` properties.\n\nPass a list of metrics to control which metrics appear in the response, or omit this list to receive all available metrics (except brb_bonus_amount).\n\nDimensions available within each report type and aggregation level:\n| reportType | groupBy | Dimensions|\n|-------------|-------------------|-----------|\n|PERFORMANCE|CREATIVE|campaignId, adgroupId, creativeid, publisher|\n|PERFORMANCE|ADGROUP|campaignId, adgroupId, publisher|\n|PERFORMANCE|CAMPAIGN|campaignId|\n|PRODUCTS|N/A|campaignId, adgroupId, publisher, productName, productGroup, productCategory, productSubcategory, brandName, productAsin, productConversionType|\nExample requests:\n```\n # PerformanceReportGroupedAtCampaignLevel\n{\n \"reportType\": \"PERFORMANCE\",\n \"endDate\": \"20220601\",\n \"count\": 1000,\n \"startDate\": \"20220525\",\n \"groupBy\":\"CAMPAIGN\"\n}\n # ProductsReport \n{\n \"reportType\": \"PRODUCTS\",\n \"endDate\": \"20220601\",\n \"count\": 1000,\n \"startDate\": \"20220525\"\n}\n```","properties":{"advertiserIds":{"description":"One or more advertiser Ids to filter reporting by. If requesting reporting for multiple advertiser Ids, input via a comma-delimited list.","type":"string"},"count":{"description":"The number of entries to include in the report.","maximum":5000.0,"minimum":1,"type":"integer"},"cursorId":{"description":"The value of `cursorId` must be set to `null` without `\"\"`, or set to `\"\"` for the first request. For each following request, the value of `cursorId` from the previous response must be included in the current request. Note that for the cursorId values the `\"` character must be escaped with `\\`.","type":"string"},"endDate":{"description":"The end date for the report, form as \"YYYYMMDD\"","type":"string"},"groupBy":{"description":"For Performance report only - controls level of aggregation. Value can be `CAMPAIGN`, `ADGROUP`, or `CREATIVE`. Default is `CREATIVE`.","enum":["ADGROUP","CAMPAIGN","CREATIVE"],"type":"string"},"metrics":{"description":"A comma-delimited list of metrics to include in the report. In the report, each metric’s value reflects the events which took place on the row’s date; in other words, events are reported on the date they occurred, not on the date of the attributed click. Attribution is calculated using a 14-day last-click model. For more detail on attribution methodology, see the [Measurement](https://advertising.amazon.com/API/docs/en-us/amazon-attribution/how-to#measurement) section of the API guide. View the list of available metrics for each report type below.\"Promoted products\" refers to products associated with the campaign.\n|Metrics for reportType`PERFORMANCE`|\n|-------------------|\n\n|Metric |Description|\n|--------|-----------|\n|Click-throughs|Ad clicks.|\n|attributedDetailPageViewsClicks14d|Ad click-attributed detail page views for promoted product.|\n|attributedAddToCartClicks14d|Ad click-attributed add to carts for promoted products.|\n|attributedPurchases14d|Ad click-attributed purchases for promoted products.|\n|unitsSold14d|Ad click-attributed units sold for promoted products.|\n|attributedSales14d|Ad click-attributed sales for promoted products in local currency.|\n|attributedTotalDetailPageViewsClicks14d|Ad click-attributed detail page views for promoted products plus brand halo products.|\n|attributedTotalAddToCartClicks14d|Ad click-attributed add to carts for promoted products plus brand halo products.|\n|attributedTotalPurchases14d|Ad click-attributed purchases for promoted products plus brand halo products.|\n|totalUnitsSold14d|Ad click-attributed units sold for promoted products plus brand halo products.|\n|totalAttributedSales14d|Ad click-attributed attributed sales for promoted products plus brand halo products.|\n|brb_bonus_amount|Estimated ad-attributed Brand Referral Bonus credit amount in local currency. Will be omitted from response if advertiser is not a BRB-enrolled seller or request does not include a ‘metrics’ list. Requests for this metric must groupBy ADGROUP or CAMPAIGN, or will result in an error 400. Please refer to <https://sellercentral.amazon.com/gp/help/external/L9HPJ34VBFP76HX> to learn more about BRB program.|\n|kindleEditionNormalizedPagesRead14d| Number of attributed Kindle edition pages read within 14 days of ad click.|\n|kindleEditionNormalizedPagesRoyalties14d|The estimated royalties of attributed estimated Kindle edition normalized pages within 14 days of ad click.|\n\n|Metrics for reportType`PRODUCTS`|\n|-------------------|\n\n|Metric |Description|\n|--------|-----------|\n|attributedDetailPageViewsClicks14d|Ad click-attributed detail page views for promoted products.|\n|attributedAddToCartClicks14d|Ad click-attributed add to carts for promoted products.|\n|attributedPurchases14d|Ad click-attributed purchases for promoted products.|\n|unitsSold14d|Ad click-attributed units sold for promoted products.|\n|attributedSales14d|Ad click-attributed sales for promoted products in local currency.|\n|brandHaloDetailPageViewsClicks14d|Ad click-attributed detail page views for brand halo products.|\n|brandHaloAttributedAddToCartClicks14d|Ad click-attributed add to carts for brand halo products.|\n|brandHaloAttributedPurchases14d|Ad click-attributed purchases for brand halo products.|\n|brandHaloUnitsSold14d|Ad click-attributed units sold for brand halo products.|\n|brandHaloAttributedSales14d|Ad click-attributed attributed sales for brand halo products.|\n|attributedNewToBrandPurchases14d|Ad click-attributed new-to-brand purchases for promoted products. A purchase is new-to-brand when a shopper purchases a product from the brand for the first time in the past year.|\n|attributedNewToBrandUnitsSold14d|Ad click-attributed units sold in new-to-brand purchases for promoted products. A purchase is new-to-brand when a shopper purchases a product from the brand for the first time in the past year.|\n|attributedNewToBrandSales14d|Ad click-attributed sales of new-to-brand purchases for promoted products in local currency. A purchase is new-to-brand when a shopper purchases a product from the brand for the first time in the past year.|\n|brandHaloNewToBrandPurchases14d|Ad click-attributed new-to-brand purchases for brand halo products. A purchase is new-to-brand when a shopper purchases a product from the brand for the first time in the past year.|\n|brandHaloNewToBrandUnitsSold14d|Ad click-attributed units sold in new-to-brand purchases for brand halo products. A purchase is new-to-brand when a shopper purchases a product from the brand for the first time in the past year.|\n|brandHaloNewToBrandSales14d|Ad click-attributed sales of new-to-brand purchases for brand halo products in local currency. A purchase is new-to-brand when a shopper purchases a product from the brand for the first time in the past year.|\n|kindleEditionNormalizedPagesRead14d| The no of pages read attributed to ad click-throughs within 14 days.|\n|kindleEditionNormalizedPagesRoyalties14d|The estimated royalties of attributed estimated Kindle edition normalized pages within 14 days of ad click.|","type":"string"},"reportType":{"description":"The type of report. Either `PERFORMANCE` or `PRODUCTS`. It is an optional parameter. If not used in request body, default reportType is `PERFORMANCE`.","type":"string"},"startDate":{"description":"The start date for the report, in \"YYYYMMDD\" format. For reportType `PRODUCTS`, startDate can only be within last 90 days from current date.","type":"string"}},"type":"object"},"ReportResponse":{"properties":{"cursorId":{"description":"The identifier of the pagination cursor.","type":"string"},"reports":{"items":{"$ref":"#/components/schemas/ReportEntry"},"type":"array"},"size":{"description":"The size of the report.","type":"integer"}},"type":"object"},"advertiser":{"properties":{"advertiserId":{"type":"string"},"advertiserName":{"type":"string"}},"type":"object"},"attributionTagMap":{"additionalProperties":{"type":"string"},"description":"An object representing the association between a publisher identifier and an attribution tag.","type":"object"}},"securitySchemes":{}},"info":{"description":"**Amazon Attribution**<br/> Amazon Attribution is an advertising measurement product that enables advertisers to understand the impact that their non-Amazon ads (i.e. Google Ads, Facebook, Microsoft Ads) have in driving shopping activity on Amazon. Measuring ads using Amazon Attribution is done through implementing Attribution tags on non-Amazon ads. Amazon Attribution is currently available in beta for US, CA, UK, DE, FR, IT, and ES vendors and professional sellers enrolled in Brand Registry.<br/><br/> **Amazon Attribution API**<br/> The Amazon Attribution API enables agencies and integrators to easily retrieve their advertiser client's non-Amazon publisher attribution tags to automate tag implementation on their non-Amazon ads that link to an Amazon product or Stores page. The API also enables agencies and integrators to create and retrieve reporting on behalf of their advertiser clients to better understand Amazon conversion performance on their campaigns.<br/><br/> Note that you must pass a header named **Amazon-Advertising-Api-Scope** with each call to an Amazon Attribution API URI, including GET /advertisers. The value for this header is the **profileId** available from the **Profiles resource (/v2/profiles)**.<br/><br/> For more information on the functionality, see the [Amazon Attribution API help topic](amazon-attribution/overview). For API onboarding information, see the [account setup](setting-up/account-setup) topic.<br/><br/>**</br></br>[Amazon Advertising API Support JIRA Service Desk - Website](https://amzn-clicks.atlassian.net/servicedesk/customer/user/login?destination=portals)</br>[Amazon Advertising API License Agreement](https://advertising.amazon.com/API/docs/license-agreement)","title":"Amazon Attribution","version":"3.0"},"openapi":"3.0.1","paths":{"/attribution/advertisers":{"get":{"description":"For sellers, an attribution profile has one associated advertiser. For vendors, an attribution profile may have more than one associated advertiser.","operationId":"getAdvertisersByProfile","parameters":[{"description":"The identifier of a client associated with a \"Login with Amazon\" account.","in":"header","name":"Amazon-Advertising-API-ClientId","required":true,"schema":{"type":"string"}},{"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.","in":"header","name":"Amazon-Advertising-API-Scope","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdvertiserResponse"}}},"description":"success"}},"summary":"Gets a list of advertisers associated with an Amazon Attribution account.","tags":["Advertisers"]}},"/attribution/publishers":{"get":{"description":"Use the response to determine whether to use either the macroTags or nonMacroTemplateTags resource to get tags for a certain publisher.","operationId":"getPublishers","parameters":[{"description":"The identifier of a client associated with a \"Login with Amazon\" account.","in":"header","name":"Amazon-Advertising-API-ClientId","required":true,"schema":{"type":"string"}},{"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.","in":"header","name":"Amazon-Advertising-API-Scope","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublishersResponse"}}},"description":"Success."}},"summary":"Gets a list of all available publishers.","tags":["Publishers"]}},"/attribution/report":{"post":{"operationId":"getAttributionTagsByCampaign","parameters":[{"description":"The identifier of a client associated with a \"Login with Amazon\" account.","in":"header","name":"Amazon-Advertising-API-ClientId","required":true,"schema":{"type":"string"}},{"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.","in":"header","name":"Amazon-Advertising-API-Scope","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportRequestBody"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportResponse"}}},"description":"Successful operation."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MaaSError"}}},"description":"Invalid request."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MaaSError"}}},"description":"Forbidden. Request failed because user does not have access to a specified resource."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MaaSError"}}},"description":"Internal Server Error. Something went wrong on the server. Retry later and report an error if unresolved."}},"summary":"Gets an attribution report for a specified list of advertisers.","tags":["Reports"]}},"/attribution/tags/macroTag":{"get":{"description":"Third-party publishers, such as Google Ads, Facebook, Microsoft Ads, and Pinterest support tags that include macro parameters. Using macro parameters, campaign tracking information is dynamically inserted into the click-through URL when an ad is clicked. This resource is a tag pre-populated with campaign, ad group, and ad level publisher macros with the values associated with your campaign. <br/><br/> For example, a Google Ads macro tag is \"?maas=maas_adg_api_123456789_1_99&ref_=aa_maas&tag=maas&aa_campaignid={campaignid}&aa_adgroupid={adgroupid}&aa_creativeid=ad-{creative}_{targetid}\"","operationId":"getPublisherAttributionTagTemplate","parameters":[{"description":"The identifier of a client associated with a \"Login with Amazon\" account.","in":"header","name":"Amazon-Advertising-API-ClientId","required":true,"schema":{"type":"string"}},{"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.","in":"header","name":"Amazon-Advertising-API-Scope","required":true,"schema":{"type":"string"}},{"description":"A list of publisher identifiers for which to request tags.","explode":true,"in":"query","name":"publisherIds","required":true,"schema":{"items":{"type":"string"},"type":"array"},"style":"form"},{"description":"List of advertiser identifiers for which to request tags.\nIf no values are passed, all advertisers are returned.","explode":true,"in":"query","name":"advertiserIds","schema":{"items":{"format":"int64","type":"integer"},"type":"array"},"style":"form"}],"responses":{"200":{"content":{"application/json":{"example":{"advertiserA":{"1":"tag1A","2":"tag2A","3":"tag3A"},"advertiserB":{"1":"tag2B","2":"tag2B","3":"tag3B"}},"schema":{"$ref":"#/components/schemas/AttributionTagResponse"}}},"description":"Successful operation."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MaaSError"}}},"description":"Invalid request, publisher not supported, or invalid advertiser identifier."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MaaSError"}}},"description":"Unauthorized. Request failed because user is not authenticated or is not allowed to invoke the operation."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MaaSError"}}},"description":"Forbidden. Request failed because user does not have access to a specified resource."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MaaSError"}}},"description":"Too Many Requests. Request was rate-limited. Retry later."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MaaSError"}}},"description":"Internal Server Error. Something went wrong on the server. Retry later and report an error if unresolved."}},"summary":"Gets a list of attribution tags for third-party publisher campaigns that support macros.","tags":["Attribution Tags"]}},"/attribution/tags/nonMacroTemplateTag":{"get":{"description":"Some third-party publishers do not support tags that include macro parameters. In this case, the attribution tag includes a set of '**insertValue**' placeholder values. Replace these placeholder values with your campaign, ad group, and ad identifiers to create unique ad-level tags.<br/><br/> For example: \"?maas=maas_adg_api_123456789_static_9_99&ref_=aa_maas&tag=maas&aa_campaignid={**insertCampaignId**}&aa_adgroupid={**insertAdGroupId**}&aa_creativeid={**insertAdiD**}\"<br/><br/> An example of an integrator nonMacro tag with filled campaign, ad group, and ad ID values is \"?maas=maas_adg_api_123456789_static_9_99&ref_=aa_maas&tag=maas&aa_campaignid=**12345**&aa_adgroupid=**5678**&aa_creativeid=**1357**\"","operationId":"getPublisherMacroAttributionTag","parameters":[{"description":"The identifier of a client associated with a \"Login with Amazon\" account.","in":"header","name":"Amazon-Advertising-API-ClientId","required":true,"schema":{"type":"string"}},{"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.","in":"header","name":"Amazon-Advertising-API-Scope","required":true,"schema":{"type":"string"}},{"description":"A list of publisher identifiers for which to request tags.","explode":true,"in":"query","name":"publisherIds","required":true,"schema":{"items":{"type":"string"},"type":"array"},"style":"form"},{"description":"List of advertiser identifiers for which to request tags.\nIf no values are passed, all advertisers are returned.","explode":true,"in":"query","name":"advertiserIds","schema":{"items":{"type":"string"},"type":"array"},"style":"form"}],"responses":{"200":{"content":{"application/json":{"example":{"advertiserA":{"5":"tag1A","6":"tag2A","7":"tag3A"},"advertiserB":{"5":"tag2B","6":"tag2B","7":"tag3B"}},"schema":{"$ref":"#/components/schemas/AttributionTagResponse"}}},"description":"Successful operation."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MaaSError"}}},"description":"Invalid request, publisher not supported, or invalid advertiser identifier."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MaaSError"}}},"description":"Unauthorized. Request failed because user is not authenticated or is not allowed to invoke the operation."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MaaSError"}}},"description":"Forbidden. Request failed because user does not have access to a specified resource."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MaaSError"}}},"description":"Too Many Requests. Request was rate-limited. Retry later."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MaaSError"}}},"description":"Internal Server Error. Something went wrong on the server. Retry later and report an error if unresolved."}},"summary":"Gets a list of attribution tags for third-party publisher campaigns that do not support macros.","tags":["Attribution Tags"]}}}}