Amazon Ads API MCP

{"components":{"callbacks":{},"examples":{},"headers":{},"links":{},"parameters":{},"requestBodies":{},"responses":{},"schemas":{"AsinEngagementDetail":{"additionalProperties":{"oneOf":[{"properties":{},"type":"string"},{"properties":{},"type":"integer"},{"properties":{},"type":"number"}]},"description":"A key-value pair map which contains the dimension and metric information. The key is either dimension name or metric name, while the value is the corresponding dimension value or metric value.","type":"object"},"AsinEngagementDimension":{"description":"User can use dimensions to aggregate the engagement metrics. Supported dimension types:\n * `ASIN` - Amazon Standard Identification Number.\n\n When *dimension* is omitted, user can retrieve select metrics aggregated at the store level. See *metrics* for details.","enum":["ASIN"],"type":"string"},"AsinEngagementMetric":{"description":"Store Metric Types: Metrics aggregated at the store level. To be used with *dimension* omitted, otherwise a 422 response is returned.","enum":["ADD_TO_CARTS","AVERAGE_IN_STOCK_PRICE","AVERAGE_SALE_PRICE","CLICKS","CLICK_RATE","CONVERSION_RATE","IN_STOCK_RATE","IN_STOCK_VIEWS","ORDERS","RENDERS","TOTAL_CLICKS","TOTAL_VIEWS","UNITS","VIEWS"],"type":"string"},"GetAsinEngagementForStoreRequest":{"properties":{"dimension":{"$ref":"#/components/schemas/AsinEngagementDimension"},"endDate":{"description":"The end date (inclusive) in YYYY-MM-DD format for the time period from when to fetch the insights.","format":"date","type":"string"},"metrics":{"description":"List of the engagement metrics to be fetched. At least one metric should be specified.","items":{"$ref":"#/components/schemas/AsinEngagementMetric"},"maxItems":12,"minItems":0,"type":"array"},"orderBy":{"$ref":"#/components/schemas/SortOrder"},"sortBy":{"description":"Nullable metric to sort on. If a value is provided, it must also appear in the metrics list. If no value is provided, the result is not guaranteed to be sorted. This field is only valid when the dimension is ASIN."},"startDate":{"description":"The start date (inclusive) in YYYY-MM-DD format for the time period from when to fetch the insights.","format":"date","type":"string"}},"required":["endDate","metrics","startDate"],"type":"object"},"GetAsinEngagementForStoreResponse":{"properties":{"dimension":{"$ref":"#/components/schemas/AsinEngagementDimension"},"metricsDetails":{"items":{"$ref":"#/components/schemas/AsinEngagementDetail","properties":{}},"maxItems":1500,"minItems":0,"type":"array"}},"type":"object"},"GetInsightsForStoreRequest":{"properties":{"dimension":{"$ref":"#/components/schemas/InsightDimension"},"endDate":{"description":"The end date (inclusive) in YYYY-MM-DD format for the time period from when to fetch the insights.","format":"date","type":"string"},"filter":{"allOf":[{"$ref":"#/components/schemas/InsightFilter"}]},"language":{"description":"This parameter is only available for Insights Metrics request for Store Quality(SQS). The language parameter is to request RECOMMENDATIONS and CONTRIBUTORS metrics in the requested language.","type":"string"},"maxResult":{"description":"The max number of result that will be returned in one response. The max allowed value will be 1500. If the parameter is not presented, it will be default to 1500.","maximum":1500,"minimum":1,"type":"integer"},"metrics":{"description":"List of the insight metrics to be fetched. Only one metric should be specified.","items":{"$ref":"#/components/schemas/InsightMetric"},"maxItems":20,"minItems":1,"type":"array"},"paginationToken":{"description":"The token that last request returned. It will be used to fetch next page of response.","type":"string"},"startDate":{"description":"The start date (inclusive) in YYYY-MM-DD format for the time period from when to fetch the insights. The earliest date will be 2018-09-01, if the input is earlier, it will be default to 2018-09-01","format":"date","type":"string"}},"required":["dimension","endDate","metrics","startDate"],"type":"object"},"GetInsightsForStoreResponse":{"properties":{"dimension":{"$ref":"#/components/schemas/InsightDimension"},"filter":{"$ref":"#/components/schemas/InsightFilter"},"metricsDetails":{"items":{"$ref":"#/components/schemas/InsightMetricsDetail","properties":{}},"maxItems":1500,"minItems":0,"type":"array"},"paginationToken":{"description":"The token can be directly used to fetch next page of the result. The token can only been used when the token is been created less than 24 hours and the request input is same as last request","type":"string"}},"type":"object"},"InsightDimension":{"description":"User can use dimensions to aggregate the insight metrics. Supported dimension types:\n * `DATE` - For aggregation by date.\n * `PAGE` - For aggregation by page.","enum":["DATE","PAGE","SOURCE","STORE","TAG"],"type":"string"},"InsightFilter":{"description":"The filter to restrict the return data. Users can specifiy the pages/source/tags they feel interested in for the insights. The relationship between each field is 'AND'. E.g.","properties":{"pageIds":{"description":"List of pages to be fetched for insight metrics. Users can first make request to the API with the same parameters but without the filter to retrieve all the available page ids.","items":{"type":"string"},"maxItems":200,"minItems":0,"type":"array"},"sources":{"description":"List of sources to be fetched for insight metrics.","items":{"$ref":"#/components/schemas/TrafficSource"},"maxItems":200,"minItems":0,"type":"array"},"tags":{"description":"List of tags to be fetched for insight metrics. Users can first make request to the API with the same parameters but without the filter to retrieve all the available tag names.","items":{"type":"string"},"maxItems":200,"minItems":0,"type":"array"}},"type":"object"},"InsightMetric":{"description":"Insight Metric Type:\n * `VIEWS` - Number of page views. Data is available from August 30, 2017. <br> \"VIEW\" metric can be aggregated by all InsightDimensions.","enum":["ACTIONS_TAKEN_BY_PEERS","BOUNCE_RATE","COMPLETED_RECOMMENDATIONS","CONTRIBUTORS","DWELL","DWELL_TIME","NEW_TO_STORE","ORDERS","PEER_DWELL","RECOMMENDATIONS","SALES","SCORE_LEVEL","UNITS","VIDEO_10S_PLAYED","VIDEO_25P_PLAYED","VIDEO_50P_PLAYED","VIDEO_75P_PLAYED","VIDEO_COMPLETED","VIDEO_STARTED","VIEWS","VISITORS","VISITS"],"type":"string"},"InsightMetricsDetail":{"additionalProperties":{"oneOf":[{"properties":{},"type":"string"},{"properties":{},"type":"integer"},{"properties":{},"type":"number"},{"properties":{},"type":"boolean"},{"description":"List of CONTRIBUTORS to the store quality in requested language. English is default language.","items":{"type":"string"},"properties":{},"type":"array"},{"description":"List of RECOMMENDATIONS to increase the store quality in requested language. English is default language.","items":{"$ref":"#/components/schemas/StoreQualityRecommendation"},"properties":{},"type":"array"},{"description":"List of COMPLETED_RECOMMENDATIONS which resulted in increase of the store quality. It can be provided in requested language. English is default language.","items":{"$ref":"#/components/schemas/StoreQualityCompletedRecommendation"},"properties":{},"type":"array"}]},"description":"A key-value pair map which contains the dimension and metric information. The key is either dimension name or metric name, while the value is the corresponding dimension value or metric value. Addition of boolean,Array and Object is solely for the Store Quality metrics.","type":"object"},"SortOrder":{"description":"Describes whether a sort should be ascending (ASC) or descending (DESC).","enum":["ASC","DESC"],"type":"string"},"StoreQualityCompletedRecommendation":{"description":"The Object containing recommendations to improve store quality.","properties":{"category":{"description":"The category in which the store owners could see improvment by this recommendation.","type":"string"},"exampleLink":{"description":"Link to the example store with a sample to showcase a recommended action.","type":"string"},"exampleText":{"description":"The text to describe the example to showcase the recommended action.","type":"string"},"observedAverageDwellTimeIncrease":{"description":"The percentage by which store quality could improve by this recommendation.","type":"string"},"recommendedAction":{"description":"description of the recommendation.","type":"string"}},"type":"object"},"StoreQualityRecommendation":{"description":"The Object containing recommendations to improve store quality.","properties":{"category":{"description":"The category in which the store owners could see improvment by this recommendation.","type":"string"},"ctaLink":{"description":"Call to Action(CTA) link to take customer to the page where the changes can be made.","type":"string"},"ctaText":{"description":"Text describing the Call to Action(CTA).","type":"string"},"exampleLink":{"description":"Link to the example store with a sample to showcase a recommended action.","type":"string"},"exampleText":{"description":"The text to describe the example to showcase the recommended action.","type":"string"},"observedAverageDwellTimeIncrease":{"description":"The percentage by which store quality could improve by this recommendation.","type":"string"},"recommendedAction":{"description":"description of the recommendation.","type":"string"}},"type":"object"},"StoresAnalyticsAPIErrorResponse":{"description":"The error response object for analytics API.","properties":{"code":{"description":"The HTTP status code of the response.","type":"string"},"details":{"description":"A human-readable description of the response.","type":"string"}},"type":"object"},"TrafficSource":{"description":"Traffic Source Type:\n * `ADS` - Traffic from Sponsored Brands ads on Amazon.\n * `ORGANIC` - Traffic originating from your brand link on Amazon product detail pages.\n * `OTHER` - All other traffic sources not categorized.\n","enum":["ADS","ORGANIC","OTHER"],"type":"string"}},"securitySchemes":{}},"info":{"title":"Stores","version":"3.0"},"openapi":"3.0.1","paths":{"/stores/{brandEntityId}/asinMetrics":{"post":{"description":"Store asin metrics provides information about your store asin performance, including rendered impressions, viewed impressions, clicks and sales. You can access Stores insights through this API.\n\n**Requires one of these permissions**:\n[\"advertiser_campaign_edit\"]","operationId":"getAsinEngagementForStore","parameters":[{"description":"The identifier of the requested store. It can be fetched through calling existing API \"/v2/stores\" listed here https://advertising.amazon.com/API/docs/en-us/reference/2/stores","in":"path","name":"brandEntityId","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/vnd.GetAsinEngagementForStoreRequest.v1+json":{"schema":{"$ref":"#/components/schemas/GetAsinEngagementForStoreRequest"}}},"required":true},"responses":{"200":{"content":{"application/vnd.GetAsinEngagementForStoreResponse.v1+json":{"schema":{"$ref":"#/components/schemas/GetAsinEngagementForStoreResponse"}}},"description":"Successful"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoresAnalyticsAPIErrorResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoresAnalyticsAPIErrorResponse"}}},"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/StoresAnalyticsAPIErrorResponse"}}},"description":"Forbidden - Request failed because user does not have access to a specified resource."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoresAnalyticsAPIErrorResponse"}}},"description":"Not Found - Requested resource does not exist or is not visible for the authenticated user."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoresAnalyticsAPIErrorResponse"}}},"description":"Unprocessable entity - Failed due to invalid parameters."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoresAnalyticsAPIErrorResponse"}}},"description":"Too Many Requests - Request was rate-limited. Retry later."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoresAnalyticsAPIErrorResponse"}}},"description":"Internal Server Error - Something went wrong on the server. Retry later and report an error if unresolved."}},"tags":["Stores Analytics"]}},"/stores/{brandEntityId}/insights":{"post":{"description":"Stores insights provides information about your store's performance, including traffic and sales. You can access Stores insights through this API.\n\n**Requires one of these permissions**:\n[\"advertiser_campaign_edit\"]","operationId":"getInsightsForStoreAPI","parameters":[{"description":"The identifier of the requested store. It can be fetched through calling existing API \"/v2/stores\" listed here https://advertising.amazon.com/API/docs/en-us/reference/2/stores","in":"path","name":"brandEntityId","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/vnd.GetInsightsForStoreRequest.v1+json":{"schema":{"$ref":"#/components/schemas/GetInsightsForStoreRequest"}}},"required":true},"responses":{"200":{"content":{"application/vnd.GetInsightsForStoreResponse.v1+json":{"schema":{"$ref":"#/components/schemas/GetInsightsForStoreResponse"}}},"description":"Successful"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoresAnalyticsAPIErrorResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoresAnalyticsAPIErrorResponse"}}},"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/StoresAnalyticsAPIErrorResponse"}}},"description":"Forbidden - Request failed because user does not have access to a specified resource."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoresAnalyticsAPIErrorResponse"}}},"description":"Not Found - Requested resource does not exist or is not visible for the authenticated user."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoresAnalyticsAPIErrorResponse"}}},"description":"Unprocessable entity - Failed due to invalid parameters."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoresAnalyticsAPIErrorResponse"}}},"description":"Too Many Requests - Request was rate-limited. Retry later."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoresAnalyticsAPIErrorResponse"}}},"description":"Internal Server Error - Something went wrong on the server. Retry later and report an error if unresolved."}},"tags":["Stores Analytics"]}}}}