diff --git a/docs/schemas/attribution.json b/docs/schemas/attribution.json index b3377fc..3c61b6c 100644 --- a/docs/schemas/attribution.json +++ b/docs/schemas/attribution.json @@ -453,6 +453,18 @@ "description": "The identifier of a publisher that does not support macros.", "type": "string" }, + "PublishersResponse": { + "type": "object", + "properties": { + "publisher": { + "description": "A list of publishers.", + "type": "array", + "items": { + "$ref": "#/components/schemas/Publisher" + } + } + } + }, "MaaSError": { "description": "The error response object.", "type": "object", @@ -467,30 +479,12 @@ } } }, - "PublishersResponse": { - "type": "object", - "properties": { - "publisher": { - "description": "A list of publishers.", - "type": "array", - "items": { - "$ref": "#/components/schemas/Publisher" - } - } - } - }, "macroPublishers": { "type": "array", "items": { "$ref": "#/components/schemas/macroPublisher" } }, - "nonMacroPublishers": { - "type": "array", - "items": { - "$ref": "#/components/schemas/nonMacroPublisher" - } - }, "Publisher": { "type": "object", "properties": { @@ -520,6 +514,12 @@ } } }, + "nonMacroPublishers": { + "type": "array", + "items": { + "$ref": "#/components/schemas/nonMacroPublisher" + } + }, "attributionTagMap": { "description": "An object representing the association between a publisher identifier and an attribution tag.", "additionalProperties": { diff --git a/docs/schemas/authorization-manager-account.json b/docs/schemas/authorization-manager-account.json index f795842..42775b3 100644 --- a/docs/schemas/authorization-manager-account.json +++ b/docs/schemas/authorization-manager-account.json @@ -191,8 +191,8 @@ ] }, "get": { - "summary": "Returns all Manager accounts that a given Amazon Advertising user has access to.", - "description": "Returns all [Manager accounts](https://advertising.amazon.com/help?ref_=a20m_us_blog_whtsnewfb2020_040120#GU3YDB26FR7XT3C8) that a user has access to, along with metadata for all of the Amazon Advertising accounts that are linked to the Manager account.", + "summary": "Returns all manager accounts that a given Amazon Ads user has access to.", + "description": "Returns all [manager accounts](https://advertising.amazon.com/help?ref_=a20m_us_blog_whtsnewfb2020_040120#GU3YDB26FR7XT3C8) that a user has access to, along with metadata for the Amazon Ads accounts that are linked to each manager account. NOTE: A maximum of 50 linked accounts are returned for each manager account.", "operationId": "getManagerAccountsForUser", "responses": { "200": { @@ -407,6 +407,7 @@ "type": "string" }, "linkedAccounts": { + "maxItems": 50, "type": "array", "items": { "$ref": "#/components/schemas/Account" @@ -481,6 +482,19 @@ "MARKETING_CLOUD" ] }, + "GetManagerAccountsResponse": { + "description": "Response containing a list of Manager Accounts that a given user has access to.", + "type": "object", + "properties": { + "managerAccounts": { + "description": "List of Manager Accounts that the user has access to", + "type": "array", + "items": { + "$ref": "#/components/schemas/ManagerAccount" + } + } + } + }, "AccountToUpdate": { "description": "String identifier for an Amazon Advertising account or advertiser. `ACCOUNT_ID` is an identifier that is returned by the [Profiles resource](https://advertising.amazon.com/API/docs/en-us/reference/2/profiles#/Profiles/listProfiles), within the `AccountInfo.id` data member. `ACCOUNT_ID` may begin with the string `\"ENTITY\"`.\n`DSP_ADVERTISER_ID` is an identifier for a DSP advertiser, which is returned by the [DSP resource](https://advertising.amazon.com/API/docs/en-us/dsp-advertiser/#/Advertiser/get_dsp_advertisers).", "type": "object", @@ -506,19 +520,6 @@ } } }, - "GetManagerAccountsResponse": { - "description": "Response containing a list of Manager Accounts that a given user has access to.", - "type": "object", - "properties": { - "managerAccounts": { - "description": "List of Manager Accounts that the user has access to", - "type": "array", - "items": { - "$ref": "#/components/schemas/ManagerAccount" - } - } - } - }, "UpdateAdvertisingAccountsInManagerAccountResponse": { "description": "Link/Unlink Advertising account or advertiser Response", "type": "object", diff --git a/docs/schemas/common-audiences.json b/docs/schemas/common-audiences.json index 3f81ed9..fcb7f27 100644 --- a/docs/schemas/common-audiences.json +++ b/docs/schemas/common-audiences.json @@ -8,6 +8,10 @@ "/audiences/list": { "post": { "summary": "Gets audience segments based on filters", + "description": "Returns a list of audience segments for an advertiser. The result set can be filtered by providing an array of Filter objects. Each item in the resulting set will match all specified filters.\n\n**Requires one of these permissions**:\n[\"advertiser_campaign_edit\",\"advertiser_campaign_view\"]", + "tags": [ + "Discovery" + ], "requestBody": { "content": { "application/json": { @@ -18,7 +22,6 @@ }, "required": false }, - "description": "Returns a list of audience segments for an advertiser. The result set can be filtered by providing an array of Filter objects. Each item in the resulting set will match all specified filters.\n\n**Requires one of these permissions**:\n[\"advertiser_campaign_edit\",\"advertiser_campaign_view\"]", "operationId": "listAudiences", "responses": { "200": { @@ -127,15 +130,16 @@ "name": "maxResults", "description": "Sets the maximum number of audiences in the returned array. Use in conjunction with the `nextToken` parameter to control pagination. For example, supplying maxResults=20 with a previously returned token will fetch up to the next 20 items. In some cases, fewer items may be returned." } - ], - "tags": [ - "Discovery" ] } }, "/audiences/taxonomy/list": { "post": { "summary": "Browse the taxonomy of audience categories", + "description": "Returns a list of audience categories for a given category path\n\n**Requires one of these permissions**:\n[\"advertiser_campaign_edit\",\"advertiser_campaign_view\"]", + "tags": [ + "Discovery" + ], "requestBody": { "content": { "application/json": { @@ -146,7 +150,6 @@ }, "required": true }, - "description": "Returns a list of audience categories for a given category path\n\n**Requires one of these permissions**:\n[\"advertiser_campaign_edit\",\"advertiser_campaign_view\"]", "operationId": "fetchTaxonomy", "responses": { "200": { @@ -246,9 +249,6 @@ "name": "maxResults", "description": "Sets the maximum number of categories in the returned array. Use in conjunction with the `nextToken` parameter to control pagination. For example, supplying maxResults=20 with a previously returned token will fetch up to the next 20 items. In some cases, fewer items may be returned." } - ], - "tags": [ - "Discovery" ] } } @@ -291,18 +291,14 @@ } } }, - "FetchTaxonomyRequestBodyV1": { - "description": "The response data will have the categories that are under the given path, and main categories will be returned if no path is specified. The response data also depends on the adType specified here since ad programs may support targeting audiences in certain categories.", + "AudienceFilterV1": { "type": "object", "properties": { - "adType": { - "type": "string", - "enum": [ - "DSP", - "SD" - ] + "field": { + "description": "Field to filter by. Supported enums are 'audienceName', 'category', 'categoryPath', 'audienceId' and 'status'. The 'category' enum returns all audiences under a high-level category, whereas the 'categoryPath' enum expects a path of nodes in the taxonomy tree and returns audiences attached directly to the node at the specified path.", + "type": "string" }, - "categoryPath": { + "values": { "type": "array", "items": { "type": "string" @@ -310,14 +306,18 @@ } } }, - "AudienceFilterV1": { + "FetchTaxonomyRequestBodyV1": { + "description": "The response data will have the categories that are under the given path, and main categories will be returned if no path is specified. The response data also depends on the adType specified here since ad programs may support targeting audiences in certain categories.", "type": "object", "properties": { - "field": { - "description": "Field to filter by. Supported enums are 'audienceName', 'category', 'categoryPath' and 'audienceId'. The 'category' enum returns all audiences under a high-level category, whereas the 'categoryPath' enum expects a path of nodes in the taxonomy tree and returns audiences attached directly to the node at the specified path.", - "type": "string" + "adType": { + "type": "string", + "enum": [ + "DSP", + "SD" + ] }, - "values": { + "categoryPath": { "type": "array", "items": { "type": "string" @@ -495,25 +495,6 @@ } } }, - "AudienceSubErrorV1": { - "description": "The sub error object.", - "type": "object", - "required": [ - "errorType", - "message" - ], - "properties": { - "fieldName": { - "type": "string" - }, - "errorType": { - "type": "string" - }, - "message": { - "type": "string" - } - } - }, "FetchTaxonomyResponseV1": { "type": "object", "properties": { @@ -534,6 +515,25 @@ } } }, + "AudienceSubErrorV1": { + "description": "The sub error object.", + "type": "object", + "required": [ + "errorType", + "message" + ], + "properties": { + "fieldName": { + "type": "string" + }, + "errorType": { + "type": "string" + }, + "message": { + "type": "string" + } + } + }, "FetchTaxonomyNodeV1": { "type": "object", "properties": { diff --git a/docs/schemas/common-billing.json b/docs/schemas/common-billing.json index 1f2c053..ee2e5b9 100644 --- a/docs/schemas/common-billing.json +++ b/docs/schemas/common-billing.json @@ -437,12 +437,9 @@ "type": "object", "required": [ "amountDue", - "dueDate", "fromDate", "id", "invoiceDate", - "paymentMethod", - "purchaseOrderNumber", "remainingAmountDue", "status", "toDate" @@ -1249,27 +1246,6 @@ "INTERNAL_ERROR" ] }, - "governmentInvoiceInformation": { - "description": "Government invoice data is provided in marketplaces (such as Italy or India) that require a government-assigned invoice ID. This object contains this identifier, along with the type of transaction from a government standpoint (which will always be a debit in the case of an invoice).\n", - "title": "Government Invoice Information", - "type": "object", - "properties": { - "transactionType": { - "type": "string", - "enum": [ - "DEBIT", - "CREDIT" - ] - }, - "countryCode": { - "$ref": "#/components/schemas/countryCode" - }, - "governmentInvoiceId": { - "description": "Government generated ID", - "type": "string" - } - } - }, "address": { "title": "Address", "type": "object", @@ -1321,6 +1297,27 @@ } } }, + "governmentInvoiceInformation": { + "description": "Government invoice data is provided in marketplaces (such as Italy or India) that require a government-assigned invoice ID. This object contains this identifier, along with the type of transaction from a government standpoint (which will always be a debit in the case of an invoice).\n", + "title": "Government Invoice Information", + "type": "object", + "properties": { + "transactionType": { + "type": "string", + "enum": [ + "DEBIT", + "CREDIT" + ] + }, + "countryCode": { + "$ref": "#/components/schemas/countryCode" + }, + "governmentInvoiceId": { + "description": "Government generated ID", + "type": "string" + } + } + }, "advertiserMarketplace": { "type": "object", "title": "Advertiser Marketplace", diff --git a/docs/schemas/common-eligibility.json b/docs/schemas/common-eligibility.json index fe6b389..2148f18 100644 --- a/docs/schemas/common-eligibility.json +++ b/docs/schemas/common-eligibility.json @@ -455,7 +455,7 @@ ] }, "ProgramEligibilityRequestContent": { - "description": "A request to evaluate account level eligibility for Amazon ad programs (Sponsored Products, Sponsored Brands, Sponsored Display, Stores, etc).", + "description": "A request to evaluate account level eligibility for Amazon ad programs (Sponsored Products, Sponsored Brands, Sponsored Display, Stores, DirectToConsumer, Amazon Attribution, etc).", "type": "object", "properties": { "skipChecks": { @@ -640,7 +640,7 @@ } }, "EligibilityStatusMap": { - "description": "This is a map that will be key'd on the ad program (SB/SD); the value will be an eligibility object.", + "description": "This is a map that will be key'd on the ad program (SB/SD/DTC/MAAS); the value will be an eligibility object.", "additionalProperties": { "$ref": "#/components/schemas/EligibilityStatusDetail" }, diff --git a/docs/schemas/common-localization.json b/docs/schemas/common-localization.json index 30c52fd..1288302 100644 --- a/docs/schemas/common-localization.json +++ b/docs/schemas/common-localization.json @@ -486,6 +486,10 @@ "/targetingExpression/localize": { "post": { "summary": "Localizes targeting expressions used for advertising targeting.", + "description": "Localizes (maps) targeting expressions from a source marketplace to one or more target marketplaces. V3: Providing locales in your request's source details or target details, will now return in <sourceField> and <targetField> respectively the translations of your targeting expressions.", + "tags": [ + "Targeting Expression Localization" + ], "requestBody": { "description": "Contains a list of targeting expressions to localize.", "content": { @@ -502,7 +506,6 @@ }, "required": true }, - "description": "Localizes (maps) targeting expressions from a source marketplace to one or more target marketplaces. V3: Providing locales in your request's source details or target details, will now return in <sourceField> and <targetField> respectively the translations of your targeting expressions.", "operationId": "getLocalizedTargetingExpression", "responses": { "200": { @@ -743,9 +746,6 @@ "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.", "required": true } - ], - "tags": [ - "Targeting Expression Localization" ] } } diff --git a/docs/schemas/dsp-measurement.json b/docs/schemas/dsp-measurement.json index d7bfa0f..aada592 100644 --- a/docs/schemas/dsp-measurement.json +++ b/docs/schemas/dsp-measurement.json @@ -530,6 +530,47 @@ } } }, + "422": { + "description": "Unprocessable Entity - The syntax of the request is correct, but the server was unable to process the contained instructions.", + "content": { + "application/vnd.studymanagement.v1.1+json": { + "schema": { + "$ref": "#/components/schemas/ErrorV1" + }, + "example": { + "requestId": "07939123-b8aa-466a-a991-8ab45b3a2f8e", + "message": "Study Eligibility Failed" + } + }, + "application/vnd.studymanagement.v1.2+json": { + "schema": { + "$ref": "#/components/schemas/ErrorV1" + }, + "example": { + "requestId": "07939123-b8aa-466a-a991-8ab45b3a2f8e", + "message": "Study Eligibility Failed" + } + }, + "application/vnd.studymanagement.v1.3+json": { + "schema": { + "$ref": "#/components/schemas/ErrorV1" + }, + "example": { + "requestId": "07939123-b8aa-466a-a991-8ab45b3a2f8e", + "message": "Study Eligibility Failed" + } + }, + "application/vnd.studymanagement.v1+json": { + "schema": { + "$ref": "#/components/schemas/ErrorV1" + }, + "example": { + "requestId": "07939123-b8aa-466a-a991-8ab45b3a2f8e", + "message": "Study Eligibility Failed" + } + } + } + }, "429": { "description": "Too Many Requests - Request was rate-limited. Retry later.", "content": { @@ -1288,6 +1329,47 @@ } } }, + "422": { + "description": "Unprocessable Entity - The syntax of the request is correct, but the server was unable to process the contained instructions.", + "content": { + "application/vnd.studymanagement.v1.1+json": { + "schema": { + "$ref": "#/components/schemas/ErrorV1" + }, + "example": { + "requestId": "07939123-b8aa-466a-a991-8ab45b3a2f8e", + "message": "Study Eligibility Failed" + } + }, + "application/vnd.studymanagement.v1.2+json": { + "schema": { + "$ref": "#/components/schemas/ErrorV1" + }, + "example": { + "requestId": "07939123-b8aa-466a-a991-8ab45b3a2f8e", + "message": "Study Eligibility Failed" + } + }, + "application/vnd.studymanagement.v1.3+json": { + "schema": { + "$ref": "#/components/schemas/ErrorV1" + }, + "example": { + "requestId": "07939123-b8aa-466a-a991-8ab45b3a2f8e", + "message": "Study Eligibility Failed" + } + }, + "application/vnd.studymanagement.v1+json": { + "schema": { + "$ref": "#/components/schemas/ErrorV1" + }, + "example": { + "requestId": "07939123-b8aa-466a-a991-8ab45b3a2f8e", + "message": "Study Eligibility Failed" + } + } + } + }, "429": { "description": "Too Many Requests - Request was rate-limited. Retry later.", "content": { @@ -6894,6 +6976,165 @@ ] } }, + "/measurement/studies/{studyId}/curatedResult/download": { + "get": { + "summary": "Get the 3P vendor's curated result file.", + "description": "Get the download link and file type of the 3P vendor's study results in an easy to read and understand format which breaks down the effectiveness of an ad campaign. Returns a `200` response that includes an AWS S3 pre-signed URL where the curated study results file is located and the file type (format). The `OTHER` file type is returned when a new file type is added and is not supported in the current version of this API.For full support of the new file type, migrate to the latest version of this API when it is made available. The URL expires after 60 seconds. If the URL expires before the curated results file is downloaded, a new download request must be created.\n\n**Requires one of these permissions**:\n[]", + "operationId": "GetCuratedStudyResult", + "responses": { + "200": { + "description": "Successful operation for downloading curated results file.", + "content": { + "application/vnd.measurementresult.v1+json": { + "schema": { + "$ref": "#/components/schemas/CuratedStudyResultV1" + } + } + } + }, + "400": { + "description": "The `studyId` path parameter is missing, is of the wrong format or the study type associated with the `studyId` doesn't provide curated results.", + "content": { + "application/vnd.measurementresult.v1+json": { + "schema": { + "$ref": "#/components/schemas/ErrorV1" + }, + "example": { + "requestId": "ad165994-489a-4fcf-a175-7a846c899b41", + "message": "1 validation error(s) occurred. Please correct them and request again.", + "errors": [ + { + "fieldName": "studyId", + "errorType": "Unsupported study type", + "message": "Omnichannel Metrics is not supported, supported study types are: Brand Lift" + } + ] + } + } + } + }, + "401": { + "description": "Unauthenticated request.", + "content": { + "application/vnd.measurementresult.v1+json": { + "schema": { + "$ref": "#/components/schemas/ErrorV1" + }, + "example": { + "requestId": "ad165994-489a-4fcf-a175-7a846c899b41", + "message": "Unauthenticated Request" + } + } + } + }, + "403": { + "description": "Forbidden - Request failed because user is not authorized to access a resource.", + "content": { + "application/vnd.measurementresult.v1+json": { + "schema": { + "$ref": "#/components/schemas/ErrorV1" + }, + "example": { + "requestId": "ad165994-489a-4fcf-a175-7a846c899b41", + "message": "Unauthorized Access", + "errors": [ + { + "errorType": "ENTITY_NOT_ALLOWED", + "message": "Given entity is not allowed" + } + ] + } + } + } + }, + "404": { + "description": "Not Found - Requested resource does not exist or is not visible for the authenticated user.", + "content": { + "application/vnd.measurementresult.v1+json": { + "schema": { + "$ref": "#/components/schemas/ErrorV1" + }, + "example": { + "requestId": "ad165994-489a-4fcf-a175-7a846c899b41", + "message": "Resource Not Found" + } + } + } + }, + "415": { + "description": "Unsupported Media Type - Version not supported.", + "content": { + "application/vnd.measurementresult.v1+json": { + "schema": { + "$ref": "#/components/schemas/ErrorV1" + }, + "example": { + "requestId": "07939123-b8aa-466a-a991-8ab45b3a2f8e", + "message": "Invalid `accept` header provided. Please ensure you are specifying supported version for the requested resource." + } + } + } + }, + "429": { + "description": "Too Many Requests - Request was rate-limited. Retry later.", + "content": { + "application/vnd.measurementresult.v1+json": { + "schema": { + "$ref": "#/components/schemas/ErrorV1" + }, + "example": { + "requestId": "ad165994-489a-4fcf-a175-7a846c899b41", + "message": "Too Many Requests" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/vnd.measurementresult.v1+json": { + "schema": { + "$ref": "#/components/schemas/ErrorV1" + }, + "example": { + "requestId": "ad165994-489a-4fcf-a175-7a846c899b41", + "message": "Internal Server Error" + } + } + } + } + }, + "parameters": [ + { + "$ref": "#/components/parameters/clientHeader" + }, + { + "$ref": "#/components/parameters/profileHeader" + }, + { + "schema": { + "type": "string" + }, + "in": "header", + "name": "Accept", + "description": "The version(s) of the requested resource. Available version(s) - `application/vnd.measurementresult.v1+json`.", + "required": true + }, + { + "schema": { + "type": "string" + }, + "in": "path", + "name": "studyId", + "description": "The canonical identifier that represents a unique study.", + "required": true + } + ], + "tags": [ + "Measurement" + ] + } + }, "/measurement/vendorProducts/omnichannelMetrics/brands/list": { "post": { "summary": "Search for brands to be used in the OMNICHANNEL_METRICS vendor product.", @@ -9122,6 +9363,9 @@ "description": "Associated vendor product canonical identifier.", "type": "string" }, + "submissionType": { + "$ref": "#/components/schemas/StudySubmissionTypeV1" + }, "lastUpdatedDate": { "format": "date-time", "description": "The study last updated date in ISO format (YYYY-MM-DDThh:mm:ssTZD). Timezone is UTC.", diff --git a/docs/schemas/dsp.json b/docs/schemas/dsp.json index 35f93d9..0a0709f 100644 --- a/docs/schemas/dsp.json +++ b/docs/schemas/dsp.json @@ -78,6 +78,11 @@ "200": { "description": "Successful operation.", "content": { + "application/vnd.dsporders.v2.3+json": { + "schema": { + "$ref": "#/components/schemas/OrderV2_3" + } + }, "application/vnd.dsporders.v2.2+json": { "schema": { "$ref": "#/components/schemas/OrderV2_2" @@ -501,6 +506,11 @@ "200": { "description": "Successful operation.", "content": { + "application/vnd.dsporders.v2.3+json": { + "schema": { + "$ref": "#/components/schemas/OrdersV2_3" + } + }, "application/vnd.dsporders.v2.2+json": { "schema": { "$ref": "#/components/schemas/OrdersV2_2" @@ -876,6 +886,16 @@ "requestBody": { "description": "An array of order objects. For each object, specify required fields and their values. Maximum length of the array is 1.", "content": { + "application/vnd.dsporders.v2.3+json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/OrderV2_3" + }, + "minItems": 1, + "maxItems": 1 + } + }, "application/vnd.dsporders.v2.2+json": { "schema": { "type": "array", @@ -912,6 +932,14 @@ "207": { "description": "Multi-status. This holds array of items which represents success or failure corresponding to the index in the request body.", "content": { + "application/vnd.dsporders.v2.3+json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/OrderResponse" + } + } + }, "application/vnd.dsporders.v2.2+json": { "schema": { "type": "array", @@ -1296,6 +1324,16 @@ "requestBody": { "description": "An array of order objects. For each object, specify required fields and their values. Maximum length of the array is 1.", "content": { + "application/vnd.dsporders.v2.3+json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/OrderV2_3" + }, + "minItems": 1, + "maxItems": 1 + } + }, "application/vnd.dsporders.v2.2+json": { "schema": { "type": "array", @@ -1332,6 +1370,14 @@ "207": { "description": "Multi-status. This holds array of items which represents success or failure corresponding to the index in the request body.", "content": { + "application/vnd.dsporders.v2.3+json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/OrderResponse" + } + } + }, "application/vnd.dsporders.v2.2+json": { "schema": { "type": "array", @@ -9782,6 +9828,20 @@ "200": { "description": "Success", "content": { + "application/vnd.goalconfigurations.v1+json": { + "schema": { + "type": "object", + "properties": { + "goalConfigurations": { + "type": "array", + "description": "Array of GoalConfiguration sorted by goal name in ascending lexicographical order.", + "items": { + "$ref": "#/components/schemas/GoalConfigurationV1" + } + } + } + } + }, "application/json": { "schema": { "type": "object", @@ -9801,6 +9861,11 @@ "400": { "description": "Bad Request.", "content": { + "application/vnd.goalconfigurations.v1+json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" @@ -9811,6 +9876,11 @@ "401": { "description": "Unauthorized. The request failed because the user is not authenticated or is not allowed to invoke the operation.", "content": { + "application/vnd.goalconfigurations.v1+json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" @@ -9821,6 +9891,11 @@ "403": { "description": "Forbidden. The request failed because the user does not have access to the specified resource.", "content": { + "application/vnd.goalconfigurations.v1+json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" @@ -9831,6 +9906,11 @@ "429": { "description": "Too Many Requests. The request was rate-limited. Retry later.", "content": { + "application/vnd.goalconfigurations.v1+json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" @@ -9841,6 +9921,11 @@ "500": { "description": "Internal Server Error. Something went wrong on the server. Retry later and report an error if unresolved.", "content": { + "application/vnd.goalconfigurations.v1+json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" @@ -10338,6 +10423,23 @@ } } }, + "OrdersV2_3": { + "type": "object", + "properties": { + "totalResults": { + "type": "integer", + "description": "Total number of results which satisfy the filtering criteria. This will help to support pagination." + }, + "response": { + "type": "array", + "items": { + "$ref": "#/components/schemas/OrderBasicV2_3" + }, + "minItems": 1, + "maxItems": 100 + } + } + }, "OrderBasic": { "type": "object", "description": "This model is designed to support batch get operation for better performance.", @@ -10424,6 +10526,71 @@ } } }, + "OrderBasicV2_3": { + "type": "object", + "description": "This model is designed to support batch get operation for better performance.", + "properties": { + "orderId": { + "type": "string", + "description": "The order identifier." + }, + "advertiserId": { + "type": "string", + "description": "The advertiser identifier." + }, + "name": { + "type": "string", + "description": "The order name." + }, + "externalId": { + "type": "string", + "description": "The order external identifier, also known as purchase order number (PO number). This field is required if \"Mandatory PO numbers\" is set at the entity level. \"N/A\" (not applicable) is a valid value. This field will be deprecated and renamed to poNumber in a future release." + }, + "comments": { + "type": "string", + "description": "The order comments." + }, + "startDateTime": { + "type": "string", + "description": "The order start date in ISO format (YYYY-MM-DDThh:mm:ssTZD). Timezone is UTC. For example, 2020-12-16T19:20:30+01:00 UTC" + }, + "endDateTime": { + "type": "string", + "description": "The order end date in ISO format (YYYY-MM-DDThh:mm:ssTZD). Timezone is UTC. For example, 2020-12-16T19:20:30+01:00 UTC" + }, + "budget": { + "$ref": "#/components/schemas/OrderBudgetBasic" + }, + "agencyFee": { + "$ref": "#/components/schemas/AgencyFee" + }, + "currencyCode": { + "$ref": "#/components/schemas/CurrencyCodeV3" + }, + "deliveryActivationStatus": { + "$ref": "#/components/schemas/DeliveryActivationStatus" + }, + "deliveryStatus": { + "$ref": "#/components/schemas/OrderDeliveryStatus" + }, + "frequencyCap": { + "$ref": "#/components/schemas/FrequencyCap" + }, + "optimization": { + "$ref": "#/components/schemas/OrderOptimizationV2_3" + }, + "creationDate": { + "type": "string", + "description": "The order creation date in ISO format (YYYY-MM-DDThh:mm:ssTZD). Timezone is UTC. For example, 2020-12-16T19:20:30+01:00. This field is available since version `application/vnd.dsporders.v2.1+json`.", + "readOnly": true + }, + "lastUpdatedDate": { + "type": "string", + "description": "The order last update date in ISO format (YYYY-MM-DDThh:mm:ssTZD). Timezone is UTC. For example, 2020-12-16T19:20:30+01:00. This field is available since version `application/vnd.dsporders.v2.1+json`.", + "readOnly": true + } + } + }, "Order": { "type": "object", "description": "Complete order model which willl be used for create/update and get.", @@ -10511,6 +10678,81 @@ } } }, + "OrderV2_3": { + "type": "object", + "description": "Complete order model which willl be used for create/update and get.", + "properties": { + "orderId": { + "type": "string", + "description": "The order identifier. It will be used to perform update operation. Immutable field." + }, + "advertiserId": { + "type": "string", + "description": "The advertiser identifier. Immutable field." + }, + "name": { + "type": "string", + "description": "The order name." + }, + "externalId": { + "type": "string", + "description": "The order external identifier, also known as purchase order number (PO number). This field is required if \"Mandatory PO numbers\" is set at the entity level. `N/A` (not applicable) is a valid value. This field will be deprecated and renamed to `poNumber` in a future release." + }, + "comments": { + "type": "string", + "description": "The order comments." + }, + "startDateTime": { + "type": "string", + "description": "The order start date in ISO format (YYYY-MM-DDThh:mm:ssTZD). Timezone is UTC. For example, 2020-12-16T19:20:30+01:00 UTC. The start date has to be modeled as a part of flights object.\n", + "readOnly": true + }, + "endDateTime": { + "type": "string", + "description": "The order end date in ISO format (YYYY-MM-DDThh:mm:ssTZD). Timezone is UTC. For example, 2020-12-16T19:20:30+01:00 UTC. The end date has to be modeled as a part of flights object.\n", + "readOnly": true + }, + "budget": { + "$ref": "#/components/schemas/OrderBudget" + }, + "currencyCode": { + "$ref": "#/components/schemas/CurrencyCodeV3" + }, + "agencyFee": { + "description": "It is immutable if the order has one or more lineItems.", + "$ref": "#/components/schemas/AgencyFee" + }, + "frequencyCap": { + "$ref": "#/components/schemas/FrequencyCap" + }, + "optimization": { + "$ref": "#/components/schemas/OrderOptimizationV2_3" + }, + "deliveryActivationStatus": { + "$ref": "#/components/schemas/DeliveryActivationStatus" + }, + "deliveryStatus": { + "$ref": "#/components/schemas/OrderDeliveryStatus" + }, + "creationDate": { + "type": "string", + "description": "The order creation date in ISO format (YYYY-MM-DDThh:mm:ssTZD). Timezone is UTC. For example, 2020-12-16T19:20:30+01:00.", + "readOnly": true + }, + "lastUpdatedDate": { + "type": "string", + "description": "The order last update date in ISO format (YYYY-MM-DDThh:mm:ssTZD). Timezone is UTC. For example, 2020-12-16T19:20:30+01:00.", + "readOnly": true + } + }, + "required": [ + "advertiserId", + "name", + "budget", + "frequencyCap", + "optimization" + ] + }, "OrderResponse": { "description": "Response for the order create/update operations. If operation is successful, it contains only orderId. If it is a failure, it contains only errorDetails. success and failure will be corresponding to that requested index in that batch (array of items).\n", "type": "object", @@ -10980,62 +11222,126 @@ "type": "object", "properties": { "productLocation": { - "type": "string", - "description": "The product location indicates whether the product is endemic or non-endemic.", - "enum": [ - "SOLD_ON_AMAZON", - "NOT_SOLD_ON_AMAZON" - ] + "$ref": "#/components/schemas/ProductLocation" }, "goal": { - "type": "string", - "description": "The budget optimization goal type.", - "enum": [ - "AWARENESS", - "ENGAGEMENT_WITH_MY_AD", - "CONSIDERATIONS_ON_AMAZON", - "CONVERSIONS_OFF_AMAZON", - "PURCHASES_ON_AMAZON", - "MOBILE_APP_INSTALLS" - ] + "$ref": "#/components/schemas/OptimizationGoal" }, "goalKpi": { - "type": "string", - "description": "KPI for the selected goal.", - "enum": [ - "VIDEO_COMPLETION_RATE", - "CLICK_THROUGH_RATE", - "COST_PER_CLICK", - "COST_PER_ACQUISITION", - "COST_PER_DOWNLOAD", - "DETAIL_PAGE_VIEW_RATE", - "COST_PER_DETAIL_PAGE_VIEW", - "RETURN_ON_AD_SPEND", - "TOTAL_RETURN_ON_AD_SPEND", - "COST_PER_VIDEO_COMPLETION", - "NONE", - "OTHER", - "REACH" - ] + "$ref": "#/components/schemas/OptimizationGoalKpi" }, "autoOptimizations": { - "type": "array", - "description": "The list of optimizations supported.", - "items": { - "type": "string", - "enum": [ - "BUDGET", - "BID" - ] - } + "$ref": "#/components/schemas/AutoOptimizations" }, "biddingStrategy": { - "description": "It specifies how Amazon Ads determines bids on your behalf for each opportunity to serve an impression. It is immutable once the order has started delivering.\n", - "type": "string", - "enum": [ - "SPEND_BUDGET_IN_FULL", - "MAXIMIZE_PERFORMANCE" - ] + "$ref": "#/components/schemas/BiddingStrategy" + } + }, + "required": [ + "productLocation", + "goal", + "goalKpi" + ] + }, + "ProductLocation": { + "type": "string", + "description": "The product location indicates whether the product is endemic or non-endemic.", + "enum": [ + "SOLD_ON_AMAZON", + "NOT_SOLD_ON_AMAZON" + ] + }, + "OptimizationGoal": { + "type": "string", + "description": "The budget optimization goal type.", + "enum": [ + "AWARENESS", + "ENGAGEMENT_WITH_MY_AD", + "CONSIDERATIONS_ON_AMAZON", + "CONVERSIONS_OFF_AMAZON", + "PURCHASES_ON_AMAZON", + "MOBILE_APP_INSTALLS" + ] + }, + "OptimizationGoalKpi": { + "type": "string", + "description": "KPI for the selected goal.", + "enum": [ + "VIDEO_COMPLETION_RATE", + "CLICK_THROUGH_RATE", + "COST_PER_CLICK", + "COST_PER_ACQUISITION", + "COST_PER_DOWNLOAD", + "DETAIL_PAGE_VIEW_RATE", + "COST_PER_DETAIL_PAGE_VIEW", + "RETURN_ON_AD_SPEND", + "TOTAL_RETURN_ON_AD_SPEND", + "COST_PER_VIDEO_COMPLETION", + "NONE", + "OTHER", + "REACH" + ] + }, + "AutoOptimizations": { + "type": "array", + "description": "The list of optimizations supported.", + "items": { + "type": "string", + "enum": [ + "BUDGET", + "BID" + ] + } + }, + "BiddingStrategy": { + "description": "It specifies how Amazon Advertising determines bids on your behalf for each opportunity to serve an impression. It is immutable once the order has started delivering.\n", + "type": "string", + "enum": [ + "SPEND_BUDGET_IN_FULL", + "MAXIMIZE_PERFORMANCE" + ] + }, + "OptimizationGoalV2_3": { + "type": "string", + "description": "The budget optimization goal type. PURCHASES_ON_OFF_AMAZON is available since application/vnd.dsporders.v2.3+json.", + "allOf": [ + { + "$ref": "#/components/schemas/OptimizationGoal" + } + ], + "enum": [ + "PURCHASES_ON_OFF_AMAZON" + ] + }, + "OptimizationGoalKpiV2_3": { + "type": "string", + "description": "KPI for the selected goal. COMBINED_RETURN_ON_AD_SPEND is available since application/vnd.dsporders.v2.3+json.", + "allOf": [ + { + "$ref": "#/components/schemas/OptimizationGoalKpi" + } + ], + "enum": [ + "COMBINED_RETURN_ON_AD_SPEND" + ] + }, + "OrderOptimizationV2_3": { + "type": "object", + "properties": { + "productLocation": { + "$ref": "#/components/schemas/ProductLocation" + }, + "goal": { + "$ref": "#/components/schemas/OptimizationGoalV2_3" + }, + "goalKpi": { + "$ref": "#/components/schemas/OptimizationGoalKpiV2_3" + }, + "autoOptimizations": { + "$ref": "#/components/schemas/AutoOptimizations" + }, + "biddingStrategy": { + "$ref": "#/components/schemas/BiddingStrategy" } }, "required": [ @@ -15340,6 +15646,18 @@ "MOBILE_APP_INSTALLS" ] }, + "GoalV1": { + "type": "string", + "description": "The primary goal that a campaign using this configuration is trying to achieve. PURCHASES_ON_OFF_AMAZON is available since application/vnd.goalconfigurations.v1+json.", + "allOf": [ + { + "$ref": "#/components/schemas/Goal" + } + ], + "enum": [ + "PURCHASES_ON_OFF_AMAZON" + ] + }, "GoalKpi": { "type": "string", "description": "Performance metrics that may be chosen to measure how effectively an order is achieving the desired goal. Although some goals may have multiple possible KPIs, exactly one KPI must be chosen during order creation.", @@ -15359,6 +15677,18 @@ "VIDEO_COMPLETION_RATE" ] }, + "GoalKpiV1": { + "type": "string", + "description": "Performance metrics that may be chosen to measure how effectively an order is achieving the desired goal. Although some goals may have multiple possible KPIs, exactly one KPI must be chosen during order creation. COMBINED_RETURN_ON_AD_SPEND is available since application/vnd.goalconfigurations.v1+json.", + "allOf": [ + { + "$ref": "#/components/schemas/GoalKpi" + } + ], + "enum": [ + "COMBINED_RETURN_ON_AD_SPEND" + ] + }, "AutoOptimization": { "type": "string", "enum": [ @@ -15392,6 +15722,32 @@ } } }, + "GoalConfigurationV1": { + "type": "object", + "properties": { + "goalName": { + "$ref": "#/components/schemas/GoalV1" + }, + "availableKpis": { + "type": "array", + "items": { + "type": "object", + "properties": { + "kpiName": { + "$ref": "#/components/schemas/GoalKpiV1" + }, + "autoOptimizations": { + "type": "array", + "description": "Which optimizations can be applied for this KPI", + "items": { + "$ref": "#/components/schemas/AutoOptimization" + } + } + } + } + } + } + }, "Apps": { "type": "object", "properties": { diff --git a/docs/schemas/sponsored-brands-extra.json b/docs/schemas/sponsored-brands-extra.json index af9ac17..c109aa2 100644 --- a/docs/schemas/sponsored-brands-extra.json +++ b/docs/schemas/sponsored-brands-extra.json @@ -4462,6 +4462,95 @@ } } }, + "MultiAdGroupAd": { + "type": "object", + "properties": { + "adId": { + "description": "The ad identifier.", + "type": "string" + }, + "campaignId": { + "description": "The campaign identifier.", + "type": "string" + }, + "landingPage": { + "$ref": "#/components/schemas/LandingPage" + }, + "name": { + "minLength": 1, + "description": "The name of the ad.", + "type": "string", + "maxLength": 128 + }, + "state": { + "$ref": "#/components/schemas/EntityState" + }, + "adGroupId": { + "description": "The adGroup identifier.", + "type": "string" + }, + "creative": { + "$ref": "#/components/schemas/Creative" + }, + "extendedData": { + "$ref": "#/components/schemas/AdExtendedData" + } + }, + "required": [ + "adGroupId", + "adId", + "campaignId", + "name", + "state" + ] + }, + "ExtendedProductCollectionCreative": { + "type": "object", + "properties": { + "asins": { + "minItems": 0, + "maxItems": 3, + "uniqueItems": true, + "description": "An array of ASINs associated with the creative.", + "type": "array", + "items": { + "description": "ASIN", + "type": "string" + } + }, + "brandLogoCrop": { + "$ref": "#/components/schemas/AssetCrop" + }, + "brandName": { + "description": "The displayed brand name in the ad headline.\nMaximum length is 30 characters.\nSee [the policy](https://advertising.amazon.com/resources/ad-policy/sponsored-ads-policies#headlines) for headline requirements.", + "type": "string" + }, + "customImages": { + "minItems": 0, + "maxItems": 5, + "uniqueItems": true, + "description": "An array of customImages associated with the creative.", + "type": "array", + "items": { + "$ref": "#/components/schemas/CustomImage" + } + }, + "brandLogoAssetId": { + "description": "The identifier of the [brand logo](https://advertising.amazon.com/resources/ad-policy/sponsored-ads-policies#brandlogo) image from the brand store's asset library.\nNote that for campaigns created in the Amazon Advertising console prior to release of the brand store's assets library, responses will not include a value for this field.", + "type": "string" + }, + "headline": { + "description": "The headline text. Maximum length of the string is 50 characters for all marketplaces other than Japan, which has a maximum length of 35 characters.\nSee [the policy](https://advertising.amazon.com/resources/ad-policy/sponsored-ads-policies#headlines) for headline requirements.", + "type": "string" + } + }, + "required": [ + "asins", + "brandLogoAssetId", + "brandName", + "headline" + ] + }, "HeadlineSuggestionResponse": { "description": "Response structure of headline suggestion API.", "type": "object", @@ -4599,20 +4688,9 @@ "description": "Creative properties", "type": "object", "properties": { - "asins": { - "description": "A list of ASINs", - "type": "array", - "items": { - "description": "ASIN", - "type": "string" - } - }, "brandLogoCrop": { "$ref": "#/components/schemas/AssetCrop" }, - "brandLogoUrl": { - "type": "string" - }, "brandName": { "description": "The displayed brand name in the ad headline.\nMaximum length is 30 characters.\nSee [the policy](https://advertising.amazon.com/resources/ad-policy/sponsored-ads-policies#headlines) for headline requirements.", "type": "string" @@ -4621,22 +4699,43 @@ "description": "The identifier of image/video asset from the store's asset library", "type": "string" }, - "subpages": { - "description": "An array of subpages", + "landingPage": { + "$ref": "#/components/schemas/CreativeLandingPage" + }, + "customImages": { + "minItems": 0, + "maxItems": 5, + "uniqueItems": true, + "description": "An array of customImages associated with the creative.", "type": "array", "items": { - "$ref": "#/components/schemas/Subpage" + "$ref": "#/components/schemas/CustomImage" } }, - "landingPage": { - "$ref": "#/components/schemas/CreativeLandingPage" - }, "customImageCrop": { "$ref": "#/components/schemas/AssetCrop" }, "customImageUrl": { "type": "string" }, + "asins": { + "description": "A list of ASINs", + "type": "array", + "items": { + "description": "ASIN", + "type": "string" + } + }, + "brandLogoUrl": { + "type": "string" + }, + "subpages": { + "description": "An array of subpages", + "type": "array", + "items": { + "$ref": "#/components/schemas/Subpage" + } + }, "videoAssetIds": { "minItems": 1, "maxItems": 1, @@ -5083,7 +5182,7 @@ "type": "object", "properties": { "adId": { - "description": "The ad identifier.", + "description": "The ad identifier. Note: Ads created using version 3/non-multi ad group campaigns do not have an associated adId. [Learn more](https://advertising.amazon.com/API/docs/en-us/sponsored-brands/campaigns/managing-multi-ad-group-campaigns#ads).", "type": "string" }, "campaignId": { @@ -5095,7 +5194,7 @@ }, "name": { "minLength": 1, - "description": "The name of the ad.", + "description": "The name of the ad. Note: Ads created using version 3/non-multi ad group campaigns do not have an associated name. [Learn more](https://advertising.amazon.com/API/docs/en-us/sponsored-brands/campaigns/managing-multi-ad-group-campaigns#ads).", "type": "string", "maxLength": 128 }, @@ -5115,9 +5214,7 @@ }, "required": [ "adGroupId", - "adId", "campaignId", - "name", "state" ] }, @@ -5762,6 +5859,23 @@ "adGroups" ] }, + "CustomImage": { + "description": "Custom Image", + "type": "object", + "properties": { + "assetId": { + "description": "The identifier of the Custom image from the Store assets library.\nSee [the policy](https://advertising.amazon.com/resources/ad-policy/sponsored-ads-policies#customimage) for more information on what constitutes a valid Custom image.", + "type": "string" + }, + "crop": { + "$ref": "#/components/schemas/AssetCrop" + }, + "url": { + "description": "Read-only URL of image.", + "type": "string" + } + } + }, "SBListAssociatedBudgetRulesResponse": { "type": "object", "properties": { @@ -6287,6 +6401,22 @@ } } }, + "CreateExtendedProductCollectionCreativeRequestContent": { + "type": "object", + "properties": { + "adId": { + "description": "The unique ID of a Sponsored Brands ad.", + "type": "string" + }, + "creative": { + "$ref": "#/components/schemas/ExtendedProductCollectionCreative" + } + }, + "required": [ + "adId", + "creative" + ] + }, "AsinComponent": { "description": "Asin component which needs to be pre moderated.", "type": "object", @@ -7958,8 +8088,13 @@ "enum": [ "PRODUCT_LIST", "STORE", + "DETAIL_PAGE", "CUSTOM_URL", - "DETAIL_PAGE" + "AD_LANDING_PREVIEW", + "SEARCH", + "BROWSE", + "ADVERTISING_LANDING_PAGE", + "UNKNOWN" ] }, "PerformanceMeasureCondition": { @@ -9889,6 +10024,20 @@ } } }, + "CreateExtendedProductCollectionCreativeResponseContent": { + "description": "Create creative response", + "type": "object", + "properties": { + "adId": { + "description": "The unique ID of a Sponsored Brands ad.", + "type": "string" + }, + "creativeVersion": { + "description": "The version identifier that helps you keep track of multiple versions of a submitted (non-draft) Sponsored Brands creative.", + "type": "string" + } + } + }, "ViolatingImageContent": { "type": "object", "properties": { @@ -10534,6 +10683,10 @@ "type": "string" } }, + "isPrimeShipping": { + "description": "Indicates if products have prime shipping. Leave empty to include both prime shipping and non-prime shipping products.", + "type": "boolean" + }, "ratingRange": { "$ref": "#/components/schemas/SBTargetingRatingRange" }, @@ -10543,10 +10696,6 @@ }, "priceRange": { "$ref": "#/components/schemas/SBTargetingPriceRange" - }, - "isPrimeShopping": { - "description": "Indicates if products have prime shipping", - "type": "boolean" } }, "required": [ @@ -10711,7 +10860,7 @@ "type": "string" }, "ad": { - "$ref": "#/components/schemas/Ad" + "$ref": "#/components/schemas/MultiAdGroupAd" }, "index": { "description": "The index in the original list from the request.", diff --git a/docs/schemas/sponsored-brands.json b/docs/schemas/sponsored-brands.json index af528dd..e165a0d 100644 --- a/docs/schemas/sponsored-brands.json +++ b/docs/schemas/sponsored-brands.json @@ -122,7 +122,7 @@ ], "operationId": "listCampaigns", "summary": "Gets an array of all campaigns associated with the client identifier passed in the authorization header, filtered by specified criteria.", - "description": "**Note**: To ensure you are getting all campaign data, use the [version 4 list campaigns endpoint](https://advertising.amazon.com/API/docs/en-us/sponsored-brands/3-0/openapi/prod#/Campaigns/ListSponsoredBrandsCampaigns) instead.\n\nTo return Gets an array of all campaigns associated with the client identifier passed in the authorization header, filtered by specified criteria. Returns both productCollection and video campaigns. Use either `adFormatFilter` or `creativeType` to filter campaigns by ad formats such as `productCollection` or `video`.
**Note:** An advertiser that has lost brand eligibility will not be able to use any write operations such as `POST`, `PUT`, and `DELETE`. This includes the `GET` operation `/pageAsins`. However, the rest of the `GET` operations such as `/sb/campaigns` will be usable regardless of advertiser's eligibility status. ", + "description": "**Note**: GET /sb/campaigns returns only a single ad group and creative per campaign. Additionally, the v3.x endpoint does not return [brand video](https://advertising.amazon.com/API/docs/en-us/sponsored-brands/3-0/openapi/prod#/Ads/CreateSponsoredBrandsBrandVideoAds) ads. To view the full list of ad groups and ads associated to a campaign, use the [version 4 list endpoints](https://advertising.amazon.com/API/docs/en-us/sponsored-brands/3-0/openapi/prod) instead.\n\nTo return Gets an array of all campaigns associated with the client identifier passed in the authorization header, filtered by specified criteria. Returns both productCollection and video campaigns. Use either `adFormatFilter` or `creativeType` to filter campaigns by ad formats such as `productCollection` or `video`.
**Note:** An advertiser that has lost brand eligibility will not be able to use any write operations such as `POST`, `PUT`, and `DELETE`. This includes the `GET` operation `/pageAsins`. However, the rest of the `GET` operations such as `/sb/campaigns` will be usable regardless of advertiser's eligibility status. ", "parameters": [ { "$ref": "#/components/parameters/clientHeader" diff --git a/docs/schemas/sponsored-display.json b/docs/schemas/sponsored-display.json index 1738175..e8f91f9 100644 --- a/docs/schemas/sponsored-display.json +++ b/docs/schemas/sponsored-display.json @@ -6053,7 +6053,7 @@ ], "operationId": "getTargetBidRecommendations", "summary": "Returns a set of bid recommendations for targeting clauses", - "description": "Provides a list of bid recommendations based on the list of input advertised ASINs and targeting clauses in the same format as the targeting API. For each targeting clause in the request a corresponding bid recommendation will be returned in the response. Currently the API will accept up to 100 targeting clauses.\n\nThe recommended bids are derrived from the last 7 days of winning auction bids for the related targeting clause.\n\n\nReceive bid recommendations using the following:\nContextual targeting clause|Description|\n|-----------|----|\n|asinSameAs=B0123456789|Receive a bid recommendation for this target product\n|asinCategorySameAs=12345|Receive a bid recommendation for this target category\n|similarProduct|Receive a bid recommendation for targets that are similar to the advertised asins.\n\n\nAudience targeting clause|Description|\n|-----------|----|\n|views(asinCategorySameAs=12345 lookback=30)|Receive a bid recommendation for a target audience that has viewed products in the given category\n|views(similarProduct lookback=30)|Receive a bid recommendation for a target audience that has viewed similar products to the advertised asins\n|views(exactProduct lookback=30)|Receive a bid recommendation for a target audience that has viewed the advertised asins\n\n\n#### Notes:\n- Bid recommendations for purchases and audiences are **not currently supported**. This note will be removed when these operations are available.\n- Refinements are currently not supported and if included will not impact the bid recommendation for the target.\n\n\n#### Advertised ASIN Notes:\n- For asinSameAs targets the advertised asins will not impact the bid recommendation\n- For asinCategrySameAs targets the advertised asins are optional, but including them will provide a more refined bid recommendation\n- For similarProduct & exactProduct targets the advertised asins are required", + "description": "Provides a list of bid recommendations based on the list of input advertised ASINs and targeting clauses in the same format as the targeting API. For each targeting clause in the request a corresponding bid recommendation will be returned in the response. Currently the API will accept up to 100 targeting clauses.\n\nThe recommended bids are derrived from the last 7 days of winning auction bids for the related targeting clause.\n\n\nReceive bid recommendations using the following:\nContextual targeting clause|Description|\n|-----------|----|\n|asinSameAs=B0123456789|Receive a bid recommendation for this target product\n|asinCategorySameAs=12345|Receive a bid recommendation for this target category\n|similarProduct|Receive a bid recommendation for targets that are similar to the advertised asins.\n\n\nAudience targeting clause|Description|\n|-----------|----|\n|views(asinCategorySameAs=12345 lookback=30)|Receive a bid recommendation for a target audience that has viewed products in the given category\n|views(similarProduct lookback=30)|Receive a bid recommendation for a target audience that has viewed similar products to the advertised asins\n|views(exactProduct lookback=30)|Receive a bid recommendation for a target audience that has viewed the advertised asins\n|purchases(asinCategorySameAs=12345 lookback=30)|Receive a bid recommendation for a target audience that has purchased products in the given category\n|purchases(exactProduct lookback=30)|Receive a bid recommendation for a target audience that has purchased the advertised asins\n|purchases(relatedProduct lookback=30)|Receive a bid recommendation for a target audience that has purchased products related to the advertised asins\n|audience(audienceSameAs=12345)|Receive a bid recommendation for the given target audience\n\n\n#### Notes:\n- Refinements are currently not supported and if included will not impact the bid recommendation for the target.\n\n\n#### Advertised ASIN Notes:\n- For asinSameAs targets the advertised asins will not impact the bid recommendation\n- For asinCategrySameAs targets the advertised asins are optional, but including them will provide a more refined bid recommendation\n- For similarProduct, exactProduct, and relatedProduct targets the advertised asins are required", "parameters": [ { "$ref": "#/components/parameters/clientHeader" @@ -7028,7 +7028,7 @@ "schemas": { "TacticReport": { "type": "string", - "description": "The advertising tactic associated with the campaign. The following table lists available tactic names:\n|Tactic Name|Type|Description|\n|-----------|-----|-----------|\n|T00020 |Contextual targeting | Choose individual products to show your ads in placements related to those products.
Choose individual categories to show your ads in placements related to those categories on and off Amazon. This tactic supports adGroup creativeType IMAGE only.|\n|T00030 |Audiences targeting | Select individual audiences to show your ads. This tactic supports adGroup creativeType IMAGE and VIDEO. |", + "description": "The advertising tactic associated with the campaign. The following table lists available tactic names:\n|Tactic Name|Type|Description|\n|-----------|-----|-----------|\n|T00020 |Contextual targeting | Choose individual products to show your ads in placements related to those products.
Choose individual categories to show your ads in placements related to those categories on and off Amazon. This tactic supports adGroup creativeType IMAGE and VIDEO.|\n|T00030 |Audiences targeting | Select individual audiences to show your ads. This tactic supports adGroup creativeType IMAGE and VIDEO. |", "example": "T00020", "enum": [ "T00020", @@ -7045,7 +7045,7 @@ }, "Tactic": { "type": "string", - "description": "The advertising tactic associated with the campaign. The following table lists available tactic names:\n|Tactic Name|Type|Description|\n|-----------|-----|-----------|\n|T00020 |Contextual targeting | Choose individual products to show your ads in placements related to those products.
Choose individual categories to show your ads in placements related to those categories on and off Amazon. This tactic supports adGroup creativeType IMAGE only.|\n|T00030 |Audiences targeting | Select individual audiences to show your ads. This tactic supports adGroup creativeType IMAGE and VIDEO.|", + "description": "The advertising tactic associated with the campaign. The following table lists available tactic names:\n|Tactic Name|Type|Description|\n|-----------|-----|-----------|\n|T00020 |Contextual targeting | Choose individual products to show your ads in placements related to those products.
Choose individual categories to show your ads in placements related to those categories on and off Amazon. This tactic supports adGroup creativeType IMAGE and VIDEO.|\n|T00030 |Audiences targeting | Select individual audiences to show your ads. This tactic supports adGroup creativeType IMAGE and VIDEO.|", "example": "T00020", "enum": [ "T00020", @@ -7055,7 +7055,7 @@ "CreativeType": { "type": "string", "nullable": true, - "description": "The type of the associated creative. If the field is empty or null, a default value of IMAGE will be used. One ad group only supports one type (VIDEO or IMAGE) of creativeType at a time.\n|Name|Tactic|Description|\n|----|------|-----------|\n|IMAGE |T00020, T00030 |The creative will display static assets (e.g. headline, brandLogo or custom image).|\n|VIDEO |T00030 |The creative will display video assets. This type of creative must have video assets provided. Audiences (T00030) is currently only available today, contextual (T00020) will be coming soon.|", + "description": "The type of the associated creative. If the field is empty or null, a default value of IMAGE will be used. One ad group only supports one type (VIDEO or IMAGE) of creativeType at a time.\n|Name|Tactic|Description|\n|----|------|-----------|\n|IMAGE |T00020, T00030 |The creative will display static assets (e.g. headline, brandLogo or custom image).|\n|VIDEO |T00020, T00030 |The creative will display video assets. This type of creative must have a video asset provided.|", "example": null, "enum": [ "IMAGE", @@ -8248,7 +8248,7 @@ } }, "TargetingRecommendationsResponse": { - "description": "Response to a request for targeting recommendations", + "description": "Response to a request for targeting recommendations.", "properties": { "recommendations": { "$ref": "#/components/schemas/TargetingRecommendations" @@ -10007,7 +10007,7 @@ }, "SDTargetingPredicateV31": { "type": "object", - "description": "A predicate to match against in the Targeting Expression (only applicable to contextual targeting - T00020).\n\n* All IDs passed for category and brand-targeting predicates must be valid IDs in the Amazon Ads browse system.\n* Brand, price, and review predicates are optional and may only be specified if category is also specified.\n* Review predicates accept numbers between 0 and 5 and are inclusive.\n* When using either of the ‘between’ strings to construct a targeting expression the format of the string is ‘double-double’ where the first double must be smaller than the second double. Prices are not inclusive.", + "description": "A predicate to match against in the Targeting Expression (only applicable to contextual targeting - T00020).\n\n* All IDs passed for category and brand-targeting predicates must be valid IDs in the Amazon Ads browse system.\n* Brand, price, and review predicates are optional and may only be specified if category is also specified.\n* Review predicates accept numbers between 0 and 5 and are inclusive.\n* When using either of the 'between' strings to construct a targeting expression the format of the string is 'double-double' where the first double must be smaller than the second double. Prices are not inclusive.", "required": [ "type" ], @@ -10062,7 +10062,7 @@ }, "SDTargetingPredicateBaseV31": { "type": "object", - "description": "A predicate to match against inside the TargetingPredicateNested component (only applicable to audience targeting - T00030).\n\n* All IDs passed for category and brand-targeting predicates must be valid IDs in the Amazon Ads browse system.\n* Brand, price, and review predicates are optional and may only be specified if category is also specified.\n* Review predicates accept numbers between 0 and 5 and are inclusive.\n* When using either of the ‘between’ strings to construct a targeting expression the format of the string is ‘double-double’ where the first double must be smaller than the second double. Prices are not inclusive.\n* The exactProduct, similarProduct, and negative types do not utilize the value field.\n* The only type currently applicable to Amazon Audiences targeting is 'audienceSameAs'.\n* **Future** A 'negative' TargetingPredicateBase will exclude that TargetingPredicateNested from the overall audience.", + "description": "A predicate to match against inside the TargetingPredicateNested component (only applicable to audience targeting - T00030).\n\n* All IDs passed for category and brand-targeting predicates must be valid IDs in the Amazon Ads browse system.\n* Brand, price, and review predicates are optional and may only be specified if category is also specified.\n* Review predicates accept numbers between 0 and 5 and are inclusive.\n* When using either of the 'between' strings to construct a targeting expression the format of the string is 'double-double' where the first double must be smaller than the second double. Prices are not inclusive.\n* The exactProduct, similarProduct, relatedProduct, and negative types do not utilize the value field.\n* The only type currently applicable to Amazon Audiences targeting is 'audienceSameAs'.\n* **Future** A 'negative' TargetingPredicateBase will exclude that TargetingPredicateNested from the overall audience.", "required": [ "type" ], @@ -10079,6 +10079,7 @@ "asinReviewRatingGreaterThan", "asinReviewRatingBetween", "similarProduct", + "relatedProduct", "exactProduct", "asinIsPrimeShippingEligible", "asinAgeRangeSameAs", diff --git a/docs/schemas/sponsored-products-extra.json b/docs/schemas/sponsored-products-extra.json index 9773c26..0e2e66f 100644 --- a/docs/schemas/sponsored-products-extra.json +++ b/docs/schemas/sponsored-products-extra.json @@ -123,10 +123,6 @@ "/sp/targets/keywords/recommendations": { "post": { "summary": "Get keyword recommendations", - "description": "The POST /sp/targets/keywords/recommendations endpoint returns recommended keyword targets given either A) a list of ad ASINs or B) a campaign ID and ad group ID. Please use the recommendationType field to specify if you want to use option A or option B. This endpoint will also return recommended bids along with each recommendation keyword target.

Ranking
The keyword recommendations will be ranked in descending order of clicks or impressions, depending on the sortDimension field provided by the user. You may also input your own keyword targets to be ranked alongside the keyword recommendations by using the targets array.

Localization
Use the locale field to get keywords in your specified locale. Supported marketplace to locale mappings can be found at the POST /keywords/localize endpoint.

Version 5.0

New Features

Version 5.0 utilizes the new theme-based bid recommendations, which can be retrieved at the endpoint /sp/targets/bid/recommendations, to return improved bid recommendations for each keyword. Theme-based bid recommendations provide \\\\\\\"themes\\\\\\\" and \\\\\\\"impact metrics\\\\\\\" along with each bid suggestion to help you choose the right bid for your keyword target.

Themes
We now may return multiple bid suggestions for each keyword target. Each suggestion will have a theme to express the business objective of the bid. Available themes are: Impact Metrics
We have added impact metrics which provide insight on the number of clicks and conversions you will receive for targeting a keyword at a certain bid.

Bidding Strategy
You may now specify your bidding strategy in the KEYWORDS_BY_ASINS request to get bid suggestions tailored to your bidding strategy. For KEYWORDS_BY_ADGROUP requests, you will not specify a bidding strategy, because the bidding strategy of the ad group is used. The three bidding strategies are:

Availability

Version 5.0 is only available in the following marketplaces: US, CA, UK, DE, FR, ES, IN, JP.

Version 4.0

New features

Version 4.0 allows users to retrieve recommended keyword targets which are sorted in descending order of clicks or conversions. The default sort dimension, if not specified, ranks recommendations by our interal ranking mechanism. We have also have added search term metrics. Search term impression share indicates the percentage share of all ad-attributed impressions you received on that keyword in the last 30 days. This metric helps advertisers identify potential opportunities based on their share on relevant keywords. Search term impression rank indicates your ranking among all advertisers for the keyword by ad impressions in a marketplace. It tells an advertiser how many advertisers had higher share of ad impressions. Search term information is only available for keywords the advertiser targeted with ad impressions.

Availability

Version 4.0 is available in all marketplaces.\n\n**Requires one of these permissions**:\n[\"advertiser_campaign_edit\",\"advertiser_campaign_view\"]", - "tags": [ - "Keyword Recommendations" - ], "requestBody": { "content": { "application/vnd.spkeywordsrecommendation.v3+json": { @@ -141,8 +137,8 @@ ], "discriminator": { "mapping": { - "KEYWORDS_FOR_ADGROUP": "#/components/schemas/AdGroupKeywordTargetRankRecommendationRequest", - "KEYWORDS_FOR_ASINS": "#/components/schemas/AsinsKeywordTargetRankRecommendationRequest" + "KEYWORD_FOR_ADGROUP": "#/components/schemas/AdGroupKeywordTargetRankRecommendationRequest", + "KEYWORD_FOR_ASINS": "#/components/schemas/AsinsKeywordTargetRankRecommendationRequest" }, "propertyName": "recommendationType" } @@ -152,16 +148,18 @@ "schema": { "oneOf": [ { - "$ref": "#/components/schemas/RankedKeywordTargetsForAdGroupRequest" + "$ref": "#/components/schemas/RankedKeywordTargetsForAsinsRequest" }, { - "$ref": "#/components/schemas/RankedKeywordTargetsForAsinsRequest" + "$ref": "#/components/schemas/RankedKeywordTargetsForAdGroupRequest" } ], "discriminator": { - "KEYWORDS_FOR_ADGROUP": "#/components/schemas/RankedKeywordTargetsForAdGroupRequest", - "propertyName": "recommendationType", - "KEYWORDS_FOR_ASINS": "#/components/schemas/RankedKeywordTargetsForAsinsRequest" + "mapping": { + "KEYWORD_FOR_ADGROUP": "#/components/schemas/RankedKeywordTargetsForAdGroupRequest", + "KEYWORD_FOR_ASINS": "#/components/schemas/RankedKeywordTargetsForAsinsRequest" + }, + "propertyName": "recommendationType" } } }, @@ -177,8 +175,8 @@ ], "discriminator": { "mapping": { - "KEYWORDS_FOR_ADGROUP": "#/components/schemas/AdGroupKeywordTargetRankRecommendationRequest", - "KEYWORDS_FOR_ASINS": "#/components/schemas/AsinsKeywordTargetRankRecommendationRequest" + "KEYWORD_FOR_ADGROUP": "#/components/schemas/AdGroupKeywordTargetRankRecommendationRequest", + "KEYWORD_FOR_ASINS": "#/components/schemas/AsinsKeywordTargetRankRecommendationRequest" }, "propertyName": "recommendationType" } @@ -187,17 +185,14 @@ } }, "operationId": "getRankedKeywordRecommendation", + "description": "The POST /sp/targets/keywords/recommendations endpoint returns recommended keyword targets given either A) a list of ad ASINs or B) a campaign ID and ad group ID. Please use the recommendationType field to specify if you want to use option A or option B. This endpoint will also return recommended bids along with each recommendation keyword target.

Ranking
The keyword recommendations will be ranked in descending order of clicks or impressions, depending on the sortDimension field provided by the user. You may also input your own keyword targets to be ranked alongside the keyword recommendations by using the targets array.

Localization
Use the locale field to get keywords in your specified locale. Supported marketplace to locale mappings can be found at the POST /keywords/localize endpoint.

Version 5.0

New Features

Version 5.0 utilizes the new theme-based bid recommendations, which can be retrieved at the endpoint /sp/targets/bid/recommendations, to return improved bid recommendations for each keyword. Theme-based bid recommendations provide \\\\\\\"themes\\\\\\\" and \\\\\\\"impact metrics\\\\\\\" along with each bid suggestion to help you choose the right bid for your keyword target.

Themes
We now may return multiple bid suggestions for each keyword target. Each suggestion will have a theme to express the business objective of the bid. Available themes are: Impact Metrics
We have added impact metrics which provide insight on the number of clicks and conversions you will receive for targeting a keyword at a certain bid.

Bidding Strategy
You may now specify your bidding strategy in the KEYWORDS_BY_ASINS request to get bid suggestions tailored to your bidding strategy. For KEYWORDS_BY_ADGROUP requests, you will not specify a bidding strategy, because the bidding strategy of the ad group is used. The three bidding strategies are:

Availability

Version 5.0 is only available in the following marketplaces: US, CA, UK, DE, FR, ES, IN, JP.

Version 4.0

New features

Version 4.0 allows users to retrieve recommended keyword targets which are sorted in descending order of clicks or conversions. The default sort dimension, if not specified, ranks recommendations by our interal ranking mechanism. We have also added search term metrics. Search term impression share indicates the percentage share of all ad-attributed impressions you received on that keyword in the last 30 days. This metric helps advertisers identify potential opportunities based on their share on relevant keywords. Search term impression rank indicates your ranking among all advertisers for the keyword by ad impressions in a marketplace. It tells an advertiser how many advertisers had higher share of ad impressions. Search term information is only available for keywords the advertiser targeted with ad impressions.

Availability

Version 4.0 is available in all marketplaces.\n\n**Requires one of these permissions**:\n[\"advertiser_campaign_edit\",\"advertiser_campaign_view\"]", "responses": { "200": { "description": "success", "content": { "application/vnd.spkeywordsrecommendation.v3+json": { "schema": { - "description": "A list of ranked keyword targets", - "type": "array", - "items": { - "$ref": "#/components/schemas/KeywordTargetResponse" - } + "$ref": "#/components/schemas/KeywordTargetResponse" } }, "application/vnd.spkeywordsrecommendation.v5+json": { @@ -220,6 +215,11 @@ "$ref": "#/components/schemas/SPTargetingError" } }, + "application/vnd.spkeywordsrecommendation.v5+json": { + "schema": { + "$ref": "#/components/schemas/SPTargetingError" + } + }, "application/vnd.spkeywordsrecommendation.v4+json": { "schema": { "$ref": "#/components/schemas/SPTargetingError" @@ -228,13 +228,18 @@ } }, "401": { - "description": "Unauthorized - Request failed because user is not authenticated or is not allowed to invoke the operation.", + "description": "Unauthorized - Request failed because user is not authenticated or\nis not allowed to invoke the operation.", "content": { "application/vnd.spkeywordsrecommendation.v3+json": { "schema": { "$ref": "#/components/schemas/SPTargetingError" } }, + "application/vnd.spkeywordsrecommendation.v5+json": { + "schema": { + "$ref": "#/components/schemas/SPTargetingError" + } + }, "application/vnd.spkeywordsrecommendation.v4+json": { "schema": { "$ref": "#/components/schemas/SPTargetingError" @@ -250,6 +255,11 @@ "$ref": "#/components/schemas/SPTargetingError" } }, + "application/vnd.spkeywordsrecommendation.v5+json": { + "schema": { + "$ref": "#/components/schemas/SPTargetingError" + } + }, "application/vnd.spkeywordsrecommendation.v4+json": { "schema": { "$ref": "#/components/schemas/SPTargetingError" @@ -265,6 +275,11 @@ "$ref": "#/components/schemas/SPTargetingError" } }, + "application/vnd.spkeywordsrecommendation.v5+json": { + "schema": { + "$ref": "#/components/schemas/SPTargetingError" + } + }, "application/vnd.spkeywordsrecommendation.v4+json": { "schema": { "$ref": "#/components/schemas/SPTargetingError" @@ -273,7 +288,7 @@ } }, "500": { - "description": "Internal Server Error - Something went wrong on the server. Retry later and report an error if unresolved.", + "description": "Internal Server Error - Something went wrong on the server. Retry\nlater and report an error if unresolved.", "content": { "application/vnd.spkeywordsrecommendation.v3+json": { "schema": { @@ -295,7 +310,7 @@ }, "in": "header", "name": "Amazon-Advertising-API-MarketplaceId", - "description": "The advertiser's Marketplace ID associated with the advertiser account." + "description": "The advertiser's Marketplace ID associated with the advertiser.\naccount." }, { "schema": { @@ -323,6 +338,9 @@ "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. This is a required header for advertisers and integrators using the Advertising API.", "required": true } + ], + "tags": [ + "Keyword Targets" ] } }, @@ -448,36 +466,36 @@ ] } }, - "/sp/negativeKeywords/delete": { + "/sp/campaignNegativeKeywords/delete": { "post": { "requestBody": { "content": { - "application/vnd.spNegativeKeyword.v3+json": { + "application/vnd.spCampaignNegativeKeyword.v3+json": { "schema": { - "$ref": "#/components/schemas/SponsoredProductsDeleteSponsoredProductsNegativeKeywordsRequestContent" + "$ref": "#/components/schemas/SponsoredProductsDeleteSponsoredProductsCampaignNegativeKeywordsRequestContent" } } }, "required": true }, - "operationId": "DeleteSponsoredProductsNegativeKeywords", + "operationId": "DeleteSponsoredProductsCampaignNegativeKeywords", "responses": { "207": { - "description": "DeleteSponsoredProductsNegativeKeywords 207 response", + "description": "DeleteSponsoredProductsCampaignNegativeKeywords 207 response", "content": { - "application/vnd.spNegativeKeyword.v3+json": { + "application/vnd.spCampaignNegativeKeyword.v3+json": { "schema": { - "$ref": "#/components/schemas/SponsoredProductsDeleteSponsoredProductsNegativeKeywordsResponseContent" + "$ref": "#/components/schemas/SponsoredProductsDeleteSponsoredProductsCampaignNegativeKeywordsResponseContent" } } } }, "400": { - "description": "NegativeKeywordMutationException 400 response", + "description": "CampaignNegativeKeywordMutationException 400 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SponsoredProductsNegativeKeywordMutationExceptionResponseContent" + "$ref": "#/components/schemas/SponsoredProductsCampaignNegativeKeywordMutationExceptionResponseContent" } } } @@ -567,297 +585,345 @@ } ], "tags": [ - "NegativeKeywords" + "CampaignNegativeKeywords" ] } }, - "/sp/targets/products/count": { + "/sp/negativeKeywords/delete": { "post": { - "summary": "Get number of targetable asins based on refinements provided by the user.", "requestBody": { "content": { - "application/vnd.spproducttargeting.v3+json": { + "application/vnd.spNegativeKeyword.v3+json": { "schema": { - "$ref": "#/components/schemas/GetTargetableAsinCountsRequest" + "$ref": "#/components/schemas/SponsoredProductsDeleteSponsoredProductsNegativeKeywordsRequestContent" } } - } + }, + "required": true }, - "operationId": "getTargetableASINCounts", - "description": "Get number of targetable asins based on refinements provided by the user. Please use the GetTargetableCategories API or the GetCategoryRecommendationsForASINs API to retrieve the category ID. Please use the GetRefinementsByCategory API to retrieve refinements data for a category.\n\n**Requires one of these permissions**:\n[\"advertiser_campaign_edit\",\"advertiser_campaign_view\"]", + "operationId": "DeleteSponsoredProductsNegativeKeywords", "responses": { - "200": { - "description": "success", + "207": { + "description": "DeleteSponsoredProductsNegativeKeywords 207 response", "content": { - "application/vnd.spproducttargetingresponse.v3+json": { + "application/vnd.spNegativeKeyword.v3+json": { "schema": { - "$ref": "#/components/schemas/TargetableAsinCounts" + "$ref": "#/components/schemas/SponsoredProductsDeleteSponsoredProductsNegativeKeywordsResponseContent" } } } }, "400": { - "description": "Bad Request - The input fails to satisfy the constraints of the API.", + "description": "NegativeKeywordMutationException 400 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/BadRequestException" + "$ref": "#/components/schemas/SponsoredProductsNegativeKeywordMutationExceptionResponseContent" } } } }, "401": { - "description": "Unauthorized - Request failed because user is not authenticated.", + "description": "UnauthorizedException 401 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/UnauthorizedException" + "$ref": "#/components/schemas/SponsoredProductsUnauthorizedExceptionResponseContent" } } } }, - "422": { - "description": "Unprocessable entity - Failed due to invalid parameters.", + "403": { + "description": "AccessDeniedException 403 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/UnprocessableEntityException" + "$ref": "#/components/schemas/SponsoredProductsAccessDeniedExceptionResponseContent" + } + } + } + }, + "415": { + "description": "UnsupportedMediaTypeException 415 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SponsoredProductsUnsupportedMediaTypeExceptionResponseContent" } } } }, "429": { - "description": "Too Many Requests - Request was rate-limited. Retry later.", + "headers": { + "Retry-After": { + "schema": { + "format": "int32", + "description": "Delay in seconds, before the next re-try attempt to the operation is recommended", + "type": "integer" + }, + "description": "Delay in seconds, before the next re-try attempt to the operation is recommended" + } + }, + "description": "ThrottlingException 429 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ThrottlingException" + "$ref": "#/components/schemas/SponsoredProductsThrottlingExceptionResponseContent" } } } }, "500": { - "description": "Internal Server Error - Something went wrong on the server. Retry\nlater and report an error if unresolved.", + "description": "InternalServerException 500 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/InternalServerException" + "$ref": "#/components/schemas/SponsoredProductsInternalServerExceptionResponseContent" } } } } }, + "description": "\n\n**Requires one of these permissions**:\n[\"advertiser_campaign_edit\"]", "parameters": [ { "schema": { + "description": "The identifier of a client associated with a \"Login with Amazon\" account.", "type": "string" }, "in": "header", "name": "Amazon-Advertising-API-ClientId", - "description": "The identifier of a client associated with a \"Login with Amazon\" account. This is a required header for advertisers and integrators using the Advertising API.", + "description": "The identifier of a client associated with a \"Login with Amazon\" account.", "required": true }, { "schema": { + "description": "The identifier of a profile associated with the advertiser account. Use GET method on Profiles resource to list\nprofiles associated with the access token passed in the HTTP Authorization header.", "type": "string" }, "in": "header", "name": "Amazon-Advertising-API-Scope", - "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. This is a required header for advertisers and integrators using the Advertising API.", + "description": "The identifier of a profile associated with the advertiser account. Use GET method on Profiles resource to list\nprofiles associated with the access token passed in the HTTP Authorization header.", "required": true - }, - { - "schema": { - "type": "string" - }, - "in": "header", - "name": "Prefer", - "description": "Used to indicate the behavior preferred by the client but is not required for successful completion of the request. Supported values will be updated in the future.", - "required": false } ], "tags": [ - "Product Targeting" + "NegativeKeywords" ] } }, - "/sp/targets/categories": { - "get": { - "summary": "Returns all targetable categories.", - "operationId": "getTargetableCategories", - "description": "Returns all targetable categories. This API returns a large JSON string containing a tree of category nodes. Each category node has the fields - category id, category name, and child categories.\n\n**Requires one of these permissions**:\n[\"advertiser_campaign_edit\",\"advertiser_campaign_view\"]", + "/sp/campaignNegativeKeywords/list": { + "post": { + "requestBody": { + "content": { + "application/vnd.spCampaignNegativeKeyword.v3+json": { + "schema": { + "$ref": "#/components/schemas/SponsoredProductsListSponsoredProductsCampaignNegativeKeywordsRequestContent" + } + } + } + }, + "operationId": "ListSponsoredProductsCampaignNegativeKeywords", "responses": { "200": { - "description": "success", + "description": "ListSponsoredProductsCampaignNegativeKeywords 200 response", "content": { - "application/vnd.spproducttargetingresponse.v3+json": { - "schema": { - "$ref": "#/components/schemas/TargetableCategories" - } - }, - "application/vnd.spproducttargetingresponse.v4+json": { + "application/vnd.spCampaignNegativeKeyword.v3+json": { "schema": { - "$ref": "#/components/schemas/TargetableCategories" + "$ref": "#/components/schemas/SponsoredProductsListSponsoredProductsCampaignNegativeKeywordsResponseContent" } } } }, "400": { - "description": "Bad Request", + "description": "CampaignNegativeKeywordAccessException 400 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/BadRequestException" + "$ref": "#/components/schemas/SponsoredProductsCampaignNegativeKeywordAccessExceptionResponseContent" } } } }, "401": { - "description": "Unauthorized - Request failed because user is not authenticated.", + "description": "UnauthorizedException 401 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/UnauthorizedException" + "$ref": "#/components/schemas/SponsoredProductsUnauthorizedExceptionResponseContent" + } + } + } + }, + "403": { + "description": "AccessDeniedException 403 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SponsoredProductsAccessDeniedExceptionResponseContent" + } + } + } + }, + "415": { + "description": "UnsupportedMediaTypeException 415 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SponsoredProductsUnsupportedMediaTypeExceptionResponseContent" } } } }, "429": { - "description": "Too Many Requests - Request was rate-limited. Retry later.", + "headers": { + "Retry-After": { + "schema": { + "format": "int32", + "description": "Delay in seconds, before the next re-try attempt to the operation is recommended", + "type": "integer" + }, + "description": "Delay in seconds, before the next re-try attempt to the operation is recommended" + } + }, + "description": "ThrottlingException 429 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ThrottlingException" + "$ref": "#/components/schemas/SponsoredProductsThrottlingExceptionResponseContent" } } } }, "500": { - "description": "Internal Server Error - Something went wrong on the server. Retry\nlater and report an error if unresolved.", + "description": "InternalServerException 500 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/InternalServerException" + "$ref": "#/components/schemas/SponsoredProductsInternalServerExceptionResponseContent" } } } } }, + "description": "\n\n**Requires one of these permissions**:\n[\"advertiser_campaign_edit\",\"advertiser_campaign_view\"]", "parameters": [ { "schema": { + "description": "The identifier of a client associated with a \"Login with Amazon\" account.", "type": "string" }, "in": "header", "name": "Amazon-Advertising-API-ClientId", - "description": "The identifier of a client associated with a \"Login with Amazon\" account. This is a required header for advertisers and integrators using the Advertising API.", + "description": "The identifier of a client associated with a \"Login with Amazon\" account.", "required": true }, { "schema": { + "description": "The identifier of a profile associated with the advertiser account. Use GET method on Profiles resource to list\nprofiles associated with the access token passed in the HTTP Authorization header.", "type": "string" }, "in": "header", "name": "Amazon-Advertising-API-Scope", - "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. This is a required header for advertisers and integrators using the Advertising API.", + "description": "The identifier of a profile associated with the advertiser account. Use GET method on Profiles resource to list\nprofiles associated with the access token passed in the HTTP Authorization header.", "required": true - }, - { - "schema": { - "type": "string" - }, - "in": "header", - "name": "Prefer", - "description": "Used to indicate the behavior preferred by the client but is not required for successful completion of the request. Supported values will be updated in the future.", - "required": false } ], "tags": [ - "Product Targeting" + "CampaignNegativeKeywords" ] } }, - "/sp/rules/campaignOptimization": { + "/sp/campaigns/delete": { "post": { - "summary": "Creates a campaign optimization rule.", "requestBody": { "content": { - "application/vnd.optimizationrules.v1+json": { + "application/vnd.spCampaign.v3+json": { "schema": { - "$ref": "#/components/schemas/CreateSPCampaignOptimizationRulesRequest" + "$ref": "#/components/schemas/SponsoredProductsDeleteSponsoredProductsCampaignsRequestContent" } } }, "required": true }, - "operationId": "CreateOptimizationRule", + "operationId": "DeleteSponsoredProductsCampaigns", "responses": { - "200": { - "description": "Successful Operation.", + "207": { + "description": "DeleteSponsoredProductsCampaigns 207 response", "content": { - "application/vnd.optimizationrules.v1+json": { + "application/vnd.spCampaign.v3+json": { "schema": { - "$ref": "#/components/schemas/CreateSPCampaignOptimizationRulesResponse" + "$ref": "#/components/schemas/SponsoredProductsDeleteSponsoredProductsCampaignsResponseContent" } } } }, "400": { - "description": "Bad Request.", + "description": "CampaignMutationException 400 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CampaignOptimizationRuleError" + "$ref": "#/components/schemas/SponsoredProductsCampaignMutationExceptionResponseContent" } } } }, "401": { - "description": "Unauthorized. The request failed because the user is not authenticated or is not allowed to invoke the operation.", + "description": "UnauthorizedException 401 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CampaignOptimizationRuleError" + "$ref": "#/components/schemas/SponsoredProductsUnauthorizedExceptionResponseContent" } } } }, "403": { - "description": "Forbidden. The request failed because user does not have access to a specified resource.", + "description": "AccessDeniedException 403 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CampaignOptimizationRuleError" + "$ref": "#/components/schemas/SponsoredProductsAccessDeniedExceptionResponseContent" } } } }, - "422": { - "description": "Unprocessable entity. The server understood the request, but was unable to process the instruction.", + "415": { + "description": "UnsupportedMediaTypeException 415 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CampaignOptimizationRuleError" + "$ref": "#/components/schemas/SponsoredProductsUnsupportedMediaTypeExceptionResponseContent" } } } }, "429": { - "description": "Too Many Requests. The request was rate-limited. Retry later.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CampaignOptimizationRuleError" + "headers": { + "Retry-After": { + "schema": { + "format": "int32", + "description": "Delay in seconds, before the next re-try attempt to the operation is recommended", + "type": "integer" + }, + "description": "Delay in seconds, before the next re-try attempt to the operation is recommended" + } + }, + "description": "ThrottlingException 429 response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SponsoredProductsThrottlingExceptionResponseContent" } } } }, "500": { - "description": "Internal Server Error. Something went wrong on the server. Retry later and report an error if unresolved.", + "description": "InternalServerException 500 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CampaignOptimizationRuleError" + "$ref": "#/components/schemas/SponsoredProductsInternalServerExceptionResponseContent" } } } @@ -867,113 +933,106 @@ "parameters": [ { "schema": { + "description": "The identifier of a client associated with a \"Login with Amazon\" account.", "type": "string" }, "in": "header", "name": "Amazon-Advertising-API-ClientId", - "description": "The identifier of a client associated with a \"Login with Amazon\" account. This is a required header for advertisers and integrators using the Advertising API.", + "description": "The identifier of a client associated with a \"Login with Amazon\" account.", "required": true }, { "schema": { + "description": "The identifier of a profile associated with the advertiser account. Use GET method on Profiles resource to list\nprofiles associated with the access token passed in the HTTP Authorization header.", "type": "string" }, "in": "header", "name": "Amazon-Advertising-API-Scope", - "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. This is a required header for advertisers and integrators using the Advertising API.", + "description": "The identifier of a profile associated with the advertiser account. Use GET method on Profiles resource to list\nprofiles associated with the access token passed in the HTTP Authorization header.", "required": true } ], "tags": [ - "Campaign Optimization Rules" + "Campaigns" ] - }, - "put": { - "summary": "Updates a campaign optimization rule.", + } + }, + "/sp/targets/products/count": { + "post": { + "summary": "Get number of targetable asins based on refinements provided by the user.", "requestBody": { "content": { - "application/vnd.optimizationrules.v1+json": { + "application/vnd.spproducttargeting.v3+json": { "schema": { - "$ref": "#/components/schemas/UpdateSPCampaignOptimizationRulesRequest" + "$ref": "#/components/schemas/GetTargetableAsinCountsRequest" } } - }, - "required": true + } }, - "operationId": "UpdateOptimizationRule", + "operationId": "getTargetableASINCounts", + "description": "Get number of targetable asins based on refinements provided by the user. Please use the GetTargetableCategories API or the GetCategoryRecommendationsForASINs API to retrieve the category ID. Please use the GetRefinementsByCategory API to retrieve refinements data for a category.\n\n**Requires one of these permissions**:\n[\"advertiser_campaign_edit\",\"advertiser_campaign_view\"]", "responses": { "200": { - "description": "Successfully updated", + "description": "success", "content": { - "application/vnd.optimizationrules.v1+json": { + "application/vnd.spproducttargetingresponse.v3+json": { "schema": { - "$ref": "#/components/schemas/UpdateSPCampaignOptimizationRuleResponse" + "$ref": "#/components/schemas/TargetableAsinCounts" } } } }, "400": { - "description": "Bad Request.", + "description": "Bad Request - The input fails to satisfy the constraints of the API.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CampaignOptimizationRuleError" + "$ref": "#/components/schemas/BadRequestException" } } } }, "401": { - "description": "Unauthorized. The request failed because the user is not authenticated or is not allowed to invoke the operation.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CampaignOptimizationRuleError" - } - } - } - }, - "403": { - "description": "Forbidden. The request failed because user does not have access to a specified resource.", + "description": "Unauthorized - Request failed because user is not authenticated.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CampaignOptimizationRuleError" + "$ref": "#/components/schemas/UnauthorizedException" } } } }, "422": { - "description": "Unprocessable entity. The server understood the request, but was unable to process the instruction.", + "description": "Unprocessable entity - Failed due to invalid parameters.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CampaignOptimizationRuleError" + "$ref": "#/components/schemas/UnprocessableEntityException" } } } }, "429": { - "description": "Too Many Requests. The request was rate-limited. Retry later.", + "description": "Too Many Requests - Request was rate-limited. Retry later.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CampaignOptimizationRuleError" + "$ref": "#/components/schemas/ThrottlingException" } } } }, "500": { - "description": "Internal Server Error. ", + "description": "Internal Server Error - Something went wrong on the server. Retry\nlater and report an error if unresolved.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CampaignOptimizationRuleError" + "$ref": "#/components/schemas/InternalServerException" } } } } }, - "description": "\n\n**Requires one of these permissions**:\n[\"advertiser_campaign_edit\"]", "parameters": [ { "schema": { @@ -992,150 +1051,257 @@ "name": "Amazon-Advertising-API-Scope", "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. This is a required header for advertisers and integrators using the Advertising API.", "required": true + }, + { + "schema": { + "type": "string" + }, + "in": "header", + "name": "Prefer", + "description": "Used to indicate the behavior preferred by the client but is not required for successful completion of the request. Supported values will be updated in the future.", + "required": false } ], "tags": [ - "Campaign Optimization Rules" + "Product Targeting" ] } }, - "/sp/campaigns/{campaignId}/budgetRules": { + "/sp/campaigns/list": { "post": { - "summary": "Associates one or more budget rules to a campaign specified by identifer.", "requestBody": { "content": { - "application/json": { + "application/vnd.spCampaign.v3+json": { "schema": { - "$ref": "#/components/schemas/CreateAssociatedBudgetRulesRequest" + "$ref": "#/components/schemas/SponsoredProductsListSponsoredProductsCampaignsRequestContent" } } - }, - "required": true + } }, - "description": "A maximum of 250 rules can be associated to a campaign. Note that the name of each rule associated to a campaign is required to be unique.\n\n**Requires one of these permissions**:\n[\"advertiser_campaign_edit\"]", - "operationId": "CreateAssociatedBudgetRulesForSPCampaigns", + "operationId": "ListSponsoredProductsCampaigns", "responses": { - "207": { - "description": "Multi-status. An object containing a list of associated budget rule response objects reflecting the same order as the input.", + "200": { + "description": "ListSponsoredProductsCampaigns 200 response", "content": { - "application/json": { + "application/vnd.spCampaign.v3+json": { "schema": { - "$ref": "#/components/schemas/CreateAssociatedBudgetRulesResponse" + "$ref": "#/components/schemas/SponsoredProductsListSponsoredProductsCampaignsResponseContent" } } } }, "400": { - "description": "Bad Request.", + "description": "CampaignAccessException 400 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/BudgetRuleError" + "$ref": "#/components/schemas/SponsoredProductsCampaignAccessExceptionResponseContent" } } } }, "401": { - "description": "Unauthorized. The request failed because the user is not authenticated or is not allowed to invoke the operation.", + "description": "UnauthorizedException 401 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/BudgetRuleError" + "$ref": "#/components/schemas/SponsoredProductsUnauthorizedExceptionResponseContent" } } } }, "403": { - "description": "Forbidden. The request failed because user does not have access to a specified resource.", + "description": "AccessDeniedException 403 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/BudgetRuleError" + "$ref": "#/components/schemas/SponsoredProductsAccessDeniedExceptionResponseContent" } } } }, - "422": { - "description": "Unprocessable entity. The server understood the request, but was unable to process the instruction.", + "415": { + "description": "UnsupportedMediaTypeException 415 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/BudgetRuleError" + "$ref": "#/components/schemas/SponsoredProductsUnsupportedMediaTypeExceptionResponseContent" } } } }, "429": { - "description": "Too Many Requests. The request was rate-limited. Retry later.", + "headers": { + "Retry-After": { + "schema": { + "format": "int32", + "description": "Delay in seconds, before the next re-try attempt to the operation is recommended", + "type": "integer" + }, + "description": "Delay in seconds, before the next re-try attempt to the operation is recommended" + } + }, + "description": "ThrottlingException 429 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/BudgetRuleError" + "$ref": "#/components/schemas/SponsoredProductsThrottlingExceptionResponseContent" } } } }, "500": { - "description": "Internal Server Error. Something went wrong on the server. Retry later and report an error if unresolved.", + "description": "InternalServerException 500 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/BudgetRuleError" + "$ref": "#/components/schemas/SponsoredProductsInternalServerExceptionResponseContent" } } } } }, + "description": "\n\n**Requires one of these permissions**:\n[\"advertiser_campaign_edit\",\"advertiser_campaign_view\"]", "parameters": [ { "schema": { + "description": "The identifier of a client associated with a \"Login with Amazon\" account.", "type": "string" }, "in": "header", "name": "Amazon-Advertising-API-ClientId", - "description": "The identifier of a client associated with a Login with Amazon account. This is a required header for advertisers and integrators using the Advertising API.", + "description": "The identifier of a client associated with a \"Login with Amazon\" account.", "required": true }, { "schema": { + "description": "The identifier of a profile associated with the advertiser account. Use GET method on Profiles resource to list\nprofiles associated with the access token passed in the HTTP Authorization header.", "type": "string" }, "in": "header", "name": "Amazon-Advertising-API-Scope", - "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. This is a required header for advertisers and integrators using the Advertising API.", + "description": "The identifier of a profile associated with the advertiser account. Use GET method on Profiles resource to list\nprofiles associated with the access token passed in the HTTP Authorization header.", + "required": true + } + ], + "tags": [ + "Campaigns" + ] + } + }, + "/sp/targets/categories": { + "get": { + "summary": "Returns all targetable categories.", + "operationId": "getTargetableCategories", + "description": "Returns all targetable categories. This API returns a large JSON string containing a tree of category nodes. Each category node has the fields - category id, category name, and child categories.\n\n**Requires one of these permissions**:\n[\"advertiser_campaign_edit\",\"advertiser_campaign_view\"]", + "responses": { + "200": { + "description": "success", + "content": { + "application/vnd.spproducttargetingresponse.v3+json": { + "schema": { + "$ref": "#/components/schemas/TargetableCategories" + } + }, + "application/vnd.spproducttargetingresponse.v4+json": { + "schema": { + "$ref": "#/components/schemas/TargetableCategories" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BadRequestException" + } + } + } + }, + "401": { + "description": "Unauthorized - Request failed because user is not authenticated.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnauthorizedException" + } + } + } + }, + "429": { + "description": "Too Many Requests - Request was rate-limited. Retry later.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ThrottlingException" + } + } + } + }, + "500": { + "description": "Internal Server Error - Something went wrong on the server. Retry\nlater and report an error if unresolved.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InternalServerException" + } + } + } + } + }, + "parameters": [ + { + "schema": { + "type": "string" + }, + "in": "header", + "name": "Amazon-Advertising-API-ClientId", + "description": "The identifier of a client associated with a \"Login with Amazon\" account. This is a required header for advertisers and integrators using the Advertising API.", "required": true }, { "schema": { - "format": "int64", - "type": "number" + "type": "string" }, - "in": "path", - "name": "campaignId", - "description": "The campaign identifier.", + "in": "header", + "name": "Amazon-Advertising-API-Scope", + "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. This is a required header for advertisers and integrators using the Advertising API.", "required": true + }, + { + "schema": { + "type": "string" + }, + "in": "header", + "name": "Prefer", + "description": "Used to indicate the behavior preferred by the client but is not required for successful completion of the request. Supported values will be updated in the future.", + "required": false } ], "tags": [ - "BudgetRules" + "Product Targeting" ] - }, + } + }, + "/sp/budgetRules/{budgetRuleId}/campaigns": { "get": { - "summary": "Gets a list of budget rules associated to a campaign specified by identifier.", - "operationId": "ListAssociatedBudgetRulesForSPCampaigns", + "summary": "Gets all the campaigns associated with a budget rule", + "operationId": "GetCampaignsAssociatedWithSPBudgetRule", "responses": { "200": { "description": "Successful operation.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SPListAssociatedBudgetRulesResponse" + "$ref": "#/components/schemas/SPGetAssociatedCampaignsResponse" } } } }, "400": { - "description": "Bad Request", + "description": "Bad Request.", "content": { "application/json": { "schema": { @@ -1195,7 +1361,6 @@ } } }, - "description": "\n\n**Requires one of these permissions**:\n[\"advertiser_campaign_edit\",\"advertiser_campaign_view\"]", "parameters": [ { "schema": { @@ -1217,12 +1382,28 @@ }, { "schema": { - "format": "int64", - "type": "number" + "type": "string" }, "in": "path", - "name": "campaignId", - "description": "The campaign identifier.", + "name": "budgetRuleId", + "description": "The budget rule identifier.", + "required": true + }, + { + "schema": { + "type": "string" + }, + "in": "query", + "name": "nextToken", + "description": "To retrieve the next page of results, call the same operation and specify this token in the request. If the `nextToken` field is empty, there are no further results." + }, + { + "schema": { + "type": "number" + }, + "in": "query", + "name": "pageSize", + "description": "Sets a limit on the number of results returned. Maximum limit of `pageSize` is 30.", "required": true } ], @@ -1231,67 +1412,88 @@ ] } }, - "/sp/negativeTargets/brands/search": { + "/sp/campaigns/{campaignId}/budgetRules": { "post": { - "summary": "Returns brands related to keyword input for negative targeting.", + "summary": "Associates one or more budget rules to a campaign specified by identifer.", "requestBody": { "content": { - "application/vnd.spproducttargeting.v3+json": { + "application/json": { "schema": { - "$ref": "#/components/schemas/SearchBrandsRequest" + "$ref": "#/components/schemas/CreateAssociatedBudgetRulesRequest" } } - } + }, + "required": true }, - "operationId": "searchBrands", - "description": "Returns up to 100 brands related to keyword input for negative targeting.\n\n**Requires one of these permissions**:\n[\"advertiser_campaign_edit\",\"advertiser_campaign_view\"]", + "description": "A maximum of 250 rules can be associated to a campaign. Note that the name of each rule associated to a campaign is required to be unique.\n\n**Requires one of these permissions**:\n[\"advertiser_campaign_edit\"]", + "operationId": "CreateAssociatedBudgetRulesForSPCampaigns", "responses": { - "200": { - "description": "success", + "207": { + "description": "Multi-status. An object containing a list of associated budget rule response objects reflecting the same order as the input.", "content": { - "application/vnd.spproducttargetingresponse.v3+json": { + "application/json": { "schema": { - "$ref": "#/components/schemas/Brands" + "$ref": "#/components/schemas/CreateAssociatedBudgetRulesResponse" } } } }, "400": { - "description": "Bad Request - The input fails to satisfy the constraints of the API.", + "description": "Bad Request.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/BadRequestException" + "$ref": "#/components/schemas/BudgetRuleError" } } } }, "401": { - "description": "Unauthorized - Request failed because user is not authenticated.", + "description": "Unauthorized. The request failed because the user is not authenticated or is not allowed to invoke the operation.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/UnauthorizedException" + "$ref": "#/components/schemas/BudgetRuleError" + } + } + } + }, + "403": { + "description": "Forbidden. The request failed because user does not have access to a specified resource.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BudgetRuleError" + } + } + } + }, + "422": { + "description": "Unprocessable entity. The server understood the request, but was unable to process the instruction.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BudgetRuleError" } } } }, "429": { - "description": "Too Many Requests - Request was rate-limited. Retry later.", + "description": "Too Many Requests. The request was rate-limited. Retry later.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ThrottlingException" + "$ref": "#/components/schemas/BudgetRuleError" } } } }, "500": { - "description": "Internal Server Error - Something went wrong on the server. Retry\nlater and report an error if unresolved.", + "description": "Internal Server Error. Something went wrong on the server. Retry later and report an error if unresolved.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/InternalServerException" + "$ref": "#/components/schemas/BudgetRuleError" } } } @@ -1304,7 +1506,7 @@ }, "in": "header", "name": "Amazon-Advertising-API-ClientId", - "description": "The identifier of a client associated with a \"Login with Amazon\" account. This is a required header for advertisers and integrators using the Advertising API.", + "description": "The identifier of a client associated with a Login with Amazon account. This is a required header for advertisers and integrators using the Advertising API.", "required": true }, { @@ -1318,31 +1520,29 @@ }, { "schema": { - "type": "string" + "format": "int64", + "type": "number" }, - "in": "header", - "name": "Prefer", - "description": "Used to indicate the behavior preferred by the client but is not required for successful completion of the request. Supported values will be updated in the future.", - "required": false + "in": "path", + "name": "campaignId", + "description": "The campaign identifier.", + "required": true } ], "tags": [ - "Product Targeting" + "BudgetRules" ] - } - }, - "/sp/targets/category/{categoryId}/refinements": { + }, "get": { - "summary": "Returns refinements according to category input.", - "operationId": "getRefinementsForCategory", - "description": "Returns refinements according to category input.\n\n**Requires one of these permissions**:\n[\"advertiser_campaign_edit\",\"advertiser_campaign_view\"]", + "summary": "Gets a list of budget rules associated to a campaign specified by identifier.", + "operationId": "ListAssociatedBudgetRulesForSPCampaigns", "responses": { "200": { - "description": "success", + "description": "Successful operation.", "content": { - "application/vnd.spproducttargetingresponse.v3+json": { + "application/json": { "schema": { - "$ref": "#/components/schemas/Refinements" + "$ref": "#/components/schemas/SPListAssociatedBudgetRulesResponse" } } } @@ -1352,52 +1552,63 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/BadRequestException" + "$ref": "#/components/schemas/BudgetRuleError" } } } }, "401": { - "description": "Unauthorized - Request failed because user is not authenticated.", + "description": "Unauthorized. The request failed because the user is not authenticated or is not allowed to invoke the operation.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/UnauthorizedException" + "$ref": "#/components/schemas/BudgetRuleError" + } + } + } + }, + "403": { + "description": "Forbidden. The request failed because user does not have access to a specified resource.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BudgetRuleError" } } } }, "422": { - "description": "Unprocessable entity - Failed due to invalid parameters.", + "description": "Unprocessable entity. The server understood the request, but was unable to process the instruction.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/UnprocessableEntityException" + "$ref": "#/components/schemas/BudgetRuleError" } } } }, "429": { - "description": "Too Many Requests - Request was rate-limited. Retry later.", + "description": "Too Many Requests. The request was rate-limited. Retry later.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ThrottlingException" + "$ref": "#/components/schemas/BudgetRuleError" } } } }, "500": { - "description": "Internal Server Error - Something went wrong on the server. Retry\nlater and report an error if unresolved.", + "description": "Internal Server Error. Something went wrong on the server. Retry later and report an error if unresolved.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/InternalServerException" + "$ref": "#/components/schemas/BudgetRuleError" } } } } }, + "description": "\n\n**Requires one of these permissions**:\n[\"advertiser_campaign_edit\",\"advertiser_campaign_view\"]", "parameters": [ { "schema": { @@ -1419,73 +1630,51 @@ }, { "schema": { - "type": "string" + "format": "int64", + "type": "number" }, "in": "path", - "name": "categoryId", - "description": "The category ID. Please use the GetTargetableCategories API or the GetCategoriesForASINs API to retrieve categories IDs. This API does not check if the category is a valid category.", + "name": "campaignId", + "description": "The campaign identifier.", "required": true - }, - { - "schema": { - "type": "string" - }, - "in": "header", - "name": "Prefer", - "description": "Used to indicate the behavior preferred by the client but is not required for successful completion of the request. Supported values will be updated in the future.", - "required": false } ], "tags": [ - "Product Targeting" + "BudgetRules" ] } }, - "/sp/rules/campaignOptimization/state": { - "post": { - "summary": "Gets campaign optimization rule state. Recommended refresh frequency is once a day.", - "description": "\n\n**Requires one of these permissions**:\n[\"advertiser_campaign_edit\",\"advertiser_campaign_view\"]", - "tags": [ - "Campaign Optimization Rules" - ], - "requestBody": { - "content": { - "application/vnd.optimizationrules.v1+json": { - "schema": { - "$ref": "#/components/schemas/SPCampaignOptimizationNotificationAPIRequest" - } - } - }, - "required": true - }, - "operationId": "GetRuleNotification", + "/sp/campaigns/{campaignId}/budgetRules/{budgetRuleId}": { + "delete": { + "summary": "Disassociates a budget rule specified by identifier from a campaign specified by identifier.", + "operationId": "DisassociateAssociatedBudgetRuleForSPCampaigns", "responses": { "200": { - "description": "Successful Operation.", + "description": "Successful operation.", "content": { - "application/vnd.optimizationrules.v1+json": { + "application/json": { "schema": { - "$ref": "#/components/schemas/SPCampaignOptimizationNotificationAPIResponse" + "$ref": "#/components/schemas/DisassociateAssociatedBudgetRuleResponse" } } } }, "400": { - "description": "Bad Request.", + "description": "Bad Request", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CampaignOptimizationRuleError" + "$ref": "#/components/schemas/BudgetRuleError" } } } }, "401": { - "description": "Unauthorized. The request failed because the user is not authenticated or is not allowed to invoke the operation.", + "description": "Unauthorized. The request failed because user is not authenticated or is not allowed to invoke the operation.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CampaignOptimizationRuleError" + "$ref": "#/components/schemas/BudgetRuleError" } } } @@ -1495,7 +1684,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CampaignOptimizationRuleError" + "$ref": "#/components/schemas/BudgetRuleError" } } } @@ -1505,7 +1694,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CampaignOptimizationRuleError" + "$ref": "#/components/schemas/BudgetRuleError" } } } @@ -1515,22 +1704,23 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CampaignOptimizationRuleError" + "$ref": "#/components/schemas/BudgetRuleError" } } } }, "500": { - "description": "Internal Server Error.", + "description": "Internal Server Error. Something went wrong on the server. Retry later and report an error if unresolved.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CampaignOptimizationRuleError" + "$ref": "#/components/schemas/BudgetRuleError" } } } } }, + "description": "\n\n**Requires one of these permissions**:\n[\"advertiser_campaign_edit\"]", "parameters": [ { "schema": { @@ -1549,39 +1739,71 @@ "name": "Amazon-Advertising-API-Scope", "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. This is a required header for advertisers and integrators using the Advertising API.", "required": true + }, + { + "schema": { + "format": "int64", + "type": "number" + }, + "in": "path", + "name": "campaignId", + "description": "The campaign identifier.", + "required": true + }, + { + "schema": { + "type": "string" + }, + "in": "path", + "name": "budgetRuleId", + "description": "The budget rule identifier.", + "required": true } + ], + "tags": [ + "BudgetRules" ] } }, - "/sp/productAds/list": { + "/sp/adGroups": { "post": { "requestBody": { "content": { - "application/vnd.spProductAd.v3+json": { + "application/vnd.spAdGroup.v3+json": { "schema": { - "$ref": "#/components/schemas/SponsoredProductsListSponsoredProductsProductAdsRequestContent" + "$ref": "#/components/schemas/SponsoredProductsCreateSponsoredProductsAdGroupsRequestContent" } } - } + }, + "required": true }, - "operationId": "ListSponsoredProductsProductAds", + "operationId": "CreateSponsoredProductsAdGroups", "responses": { - "200": { - "description": "ListSponsoredProductsProductAds 200 response", + "207": { + "headers": { + "Preference-Applied": { + "schema": { + "description": "Header containing preferences applied while processing API call", + "type": "string" + }, + "description": "Header containing preferences applied while processing API call" + } + }, + "description": "CreateSponsoredProductsAdGroups 207 response", "content": { - "application/vnd.spProductAd.v3+json": { + "application/vnd.spAdGroup.v3+json": { "schema": { - "$ref": "#/components/schemas/SponsoredProductsListSponsoredProductsProductAdsResponseContent" + "$ref": "#/components/schemas/SponsoredProductsCreateSponsoredProductsAdGroupsResponseContent" } } } }, "400": { - "description": "ProductAdAccessException 400 response", + "description": "AdGroupMutationException 400 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SponsoredProductsProductAdAccessExceptionResponseContent" + "$ref": "#/components/schemas/SponsoredProductsAdGroupMutationExceptionResponseContent" } } } @@ -1647,7 +1869,7 @@ } } }, - "description": "\n\n**Requires one of these permissions**:\n[\"advertiser_campaign_edit\",\"advertiser_campaign_view\"]", + "description": "\n\n**Requires one of these permissions**:\n[\"advertiser_campaign_edit\"]", "parameters": [ { "schema": { @@ -1668,42 +1890,59 @@ "name": "Amazon-Advertising-API-Scope", "description": "The identifier of a profile associated with the advertiser account. Use GET method on Profiles resource to list\nprofiles associated with the access token passed in the HTTP Authorization header.", "required": true + }, + { + "schema": { + "description": "The \"Prefer\" header, as defined in [RFC7240], allows clients to request certain behavior from the service.\nThe service ignores preference values that are either not supported or not known by the service.\nEither multiple Prefer headers are passed or single one with comma separated values, both forms are equivalent\nSupported preferences:\nreturn=representation - return the full object when doing create/update/delete operations instead of ids", + "type": "string" + }, + "in": "header", + "name": "Prefer", + "description": "The \"Prefer\" header, as defined in [RFC7240], allows clients to request certain behavior from the service.\nThe service ignores preference values that are either not supported or not known by the service.\nEither multiple Prefer headers are passed or single one with comma separated values, both forms are equivalent\nSupported preferences:\nreturn=representation - return the full object when doing create/update/delete operations instead of ids" } ], "tags": [ - "ProductAds" + "AdGroups" ] - } - }, - "/sp/negativeTargets/list": { - "post": { + }, + "put": { "requestBody": { "content": { - "application/vnd.spNegativeTargetingClause.v3+json": { + "application/vnd.spAdGroup.v3+json": { "schema": { - "$ref": "#/components/schemas/SponsoredProductsListSponsoredProductsNegativeTargetingClausesRequestContent" + "$ref": "#/components/schemas/SponsoredProductsUpdateSponsoredProductsAdGroupsRequestContent" } } - } + }, + "required": true }, - "operationId": "ListSponsoredProductsNegativeTargetingClauses", + "operationId": "UpdateSponsoredProductsAdGroups", "responses": { - "200": { - "description": "ListSponsoredProductsNegativeTargetingClauses 200 response", + "207": { + "headers": { + "Preference-Applied": { + "schema": { + "description": "Header containing preferences applied while processing API call", + "type": "string" + }, + "description": "Header containing preferences applied while processing API call" + } + }, + "description": "UpdateSponsoredProductsAdGroups 207 response", "content": { - "application/vnd.spNegativeTargetingClause.v3+json": { + "application/vnd.spAdGroup.v3+json": { "schema": { - "$ref": "#/components/schemas/SponsoredProductsListSponsoredProductsNegativeTargetingClausesResponseContent" + "$ref": "#/components/schemas/SponsoredProductsUpdateSponsoredProductsAdGroupsResponseContent" } } } }, "400": { - "description": "NegativeTargetAccessException 400 response", + "description": "AdGroupMutationException 400 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SponsoredProductsNegativeTargetAccessExceptionResponseContent" + "$ref": "#/components/schemas/SponsoredProductsAdGroupMutationExceptionResponseContent" } } } @@ -1769,7 +2008,7 @@ } } }, - "description": "\n\n**Requires one of these permissions**:\n[\"advertiser_campaign_edit\",\"advertiser_campaign_view\"]", + "description": "\n\n**Requires one of these permissions**:\n[\"advertiser_campaign_edit\"]", "parameters": [ { "schema": { @@ -1790,380 +2029,293 @@ "name": "Amazon-Advertising-API-Scope", "description": "The identifier of a profile associated with the advertiser account. Use GET method on Profiles resource to list\nprofiles associated with the access token passed in the HTTP Authorization header.", "required": true + }, + { + "schema": { + "description": "The \"Prefer\" header, as defined in [RFC7240], allows clients to request certain behavior from the service.\nThe service ignores preference values that are either not supported or not known by the service.\nEither multiple Prefer headers are passed or single one with comma separated values, both forms are equivalent\nSupported preferences:\nreturn=representation - return the full object when doing create/update/delete operations instead of ids", + "type": "string" + }, + "in": "header", + "name": "Prefer", + "description": "The \"Prefer\" header, as defined in [RFC7240], allows clients to request certain behavior from the service.\nThe service ignores preference values that are either not supported or not known by the service.\nEither multiple Prefer headers are passed or single one with comma separated values, both forms are equivalent\nSupported preferences:\nreturn=representation - return the full object when doing create/update/delete operations instead of ids" } ], "tags": [ - "NegativeTargetingClauses" + "AdGroups" ] } }, - "/sp/productAds": { + "/sp/targets/products/recommendations": { "post": { + "summary": "Suggested target ASINs for your advertised product", "requestBody": { "content": { - "application/vnd.spProductAd.v3+json": { + "application/vnd.spproductrecommendation.v3+json": { "schema": { - "$ref": "#/components/schemas/SponsoredProductsCreateSponsoredProductsProductAdsRequestContent" + "$ref": "#/components/schemas/GetProductRecommendationsRequest" } } - }, - "required": true + } }, - "operationId": "CreateSponsoredProductsProductAds", + "operationId": "getProductRecommendations", + "description": "Given an advertised ASIN as input, this API returns suggested ASINs to target in a product targeting campaign. We use various methods to generate these suggestions. These include using historical performance of your ad, items that shoppers they frequently view and purchase together, etc. The suggested targets can be retrieved either as a single list, or grouped by ‘theme' – i.e. an accompanying context for why we recommend the items. You can pick the desired format using the Accepts header, please see the response mediaTypes for more information.
\n

Pagination Behavior

The API supports cursor based pagination using encoded cursor values to return next set of records or previously served records. The count parameter in the request body will be used to determine the size of results when requesting the previous page or next page. If no value for count is passed in the request, a default value is assumed. Please refer the range and defaults for these values in the request schema under GetProductRecommendationsRequest.
Note: The clients should never cache pagination cursor values locally as these values will expire after a certain time period. However a cursor value can be reused to perform retries in case of failures as long as the value has not expired.\n

Themes

Themes provide additional context for why we are recommending a product as a target. See below for an overall list of themes currently available –
- Top converting targets – These ASINs generated conversions for the input ASIN in the past 30 days (e.g. your product appeared as an ad on the detail page of these items, and a shopper clicked and purchased your item). The suggested ASINs under this theme are sorted in decreasing order of sales generated for your promoted item.
- Similar items (frequently viewed together) – Items that shoppers frequently view and click along with your advertised item during a shopping session.\n
- Complements – Items that are frequently purchased together as complements. For example, if you are promoting a tennis racquet, you may see tennis balls recommended under this theme.\n
- Similar items with low ratings and reviews – Subset of the ‘similar items’ theme containing items that are rated lower than 3 stars and/or with fewer than 5 reviews.\n
- Other books read by your readers – Items that shoppers frequently view and click along with your advertised item during a shopping session.

Note: Availability of themes differs by input ASIN - some ASINs may not have all above themes available\n", "responses": { - "207": { - "headers": { - "Preference-Applied": { - "schema": { - "description": "Header containing preferences applied while processing API call", - "type": "string" - }, - "description": "Header containing preferences applied while processing API call" - } - }, - "description": "CreateSponsoredProductsProductAds 207 response", - "content": { - "application/vnd.spProductAd.v3+json": { - "schema": { - "$ref": "#/components/schemas/SponsoredProductsCreateSponsoredProductsProductAdsResponseContent" - } - } - } - }, - "400": { - "description": "ProductAdMutationException 400 response", + "200": { + "description": "success", "content": { - "application/json": { + "application/vnd.spproductrecommendationresponse.themes.v3+json": { "schema": { - "$ref": "#/components/schemas/SponsoredProductsProductAdMutationExceptionResponseContent" + "$ref": "#/components/schemas/ProductRecommendationsByTheme" } - } - } - }, - "401": { - "description": "UnauthorizedException 401 response", - "content": { - "application/json": { + }, + "application/vnd.spproductrecommendationresponse.asins.v3+json": { "schema": { - "$ref": "#/components/schemas/SponsoredProductsUnauthorizedExceptionResponseContent" + "$ref": "#/components/schemas/ProductRecommendationsByASIN" } } } }, - "403": { - "description": "AccessDeniedException 403 response", + "400": { + "description": "Bad Request", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SponsoredProductsAccessDeniedExceptionResponseContent" + "$ref": "#/components/schemas/BadRequestException" } } } }, - "415": { - "description": "UnsupportedMediaTypeException 415 response", + "422": { + "description": "Unprocessable entity - Failed due to invalid parameters.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SponsoredProductsUnsupportedMediaTypeExceptionResponseContent" + "$ref": "#/components/schemas/UnprocessableEntityException" } } } }, "429": { - "headers": { - "Retry-After": { - "schema": { - "format": "int32", - "description": "Delay in seconds, before the next re-try attempt to the operation is recommended", - "type": "integer" - }, - "description": "Delay in seconds, before the next re-try attempt to the operation is recommended" - } - }, - "description": "ThrottlingException 429 response", + "description": "Too Many Requests - Request was rate-limited. Retry later.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SponsoredProductsThrottlingExceptionResponseContent" + "$ref": "#/components/schemas/ThrottlingException" } } } }, "500": { - "description": "InternalServerException 500 response", + "description": "Internal Server Error - Something went wrong on the server. Retry later and report an error if unresolved.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SponsoredProductsInternalServerExceptionResponseContent" + "$ref": "#/components/schemas/InternalServerException" } } } } }, - "description": "\n\n**Requires one of these permissions**:\n[\"advertiser_campaign_edit\"]", "parameters": [ { "schema": { - "description": "The identifier of a client associated with a \"Login with Amazon\" account.", "type": "string" }, "in": "header", - "name": "Amazon-Advertising-API-ClientId", - "description": "The identifier of a client associated with a \"Login with Amazon\" account.", - "required": true + "name": "Amazon-Advertising-API-AdvertiserId", + "description": "The Advertiser ID associated with the advertiser account." }, { "schema": { - "description": "The identifier of a profile associated with the advertiser account. Use GET method on Profiles resource to list\nprofiles associated with the access token passed in the HTTP Authorization header.", "type": "string" }, "in": "header", - "name": "Amazon-Advertising-API-Scope", - "description": "The identifier of a profile associated with the advertiser account. Use GET method on Profiles resource to list\nprofiles associated with the access token passed in the HTTP Authorization header.", + "name": "Amazon-Advertising-API-ClientId", + "description": "The identifier of a client associated with a \"Login with Amazon\" account. This is a required header for advertisers and integrators using the Advertising API.", "required": true }, { "schema": { - "description": "The \"Prefer\" header, as defined in [RFC7240], allows clients to request certain behavior from the service.\nThe service ignores preference values that are either not supported or not known by the service.\nEither multiple Prefer headers are passed or single one with comma separated values, both forms are equivalent\nSupported preferences:\nreturn=representation - return the full object when doing create/update/delete operations instead of ids", "type": "string" }, "in": "header", - "name": "Prefer", - "description": "The \"Prefer\" header, as defined in [RFC7240], allows clients to request certain behavior from the service.\nThe service ignores preference values that are either not supported or not known by the service.\nEither multiple Prefer headers are passed or single one with comma separated values, both forms are equivalent\nSupported preferences:\nreturn=representation - return the full object when doing create/update/delete operations instead of ids" + "name": "Amazon-Advertising-API-Scope", + "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. This is a required header for advertisers and integrators using the Advertising API.", + "required": true } ], "tags": [ - "ProductAds" + "Product Recommendation Service" ] - }, - "put": { + } + }, + "/sp/negativeTargets/brands/search": { + "post": { + "summary": "Returns brands related to keyword input for negative targeting.", "requestBody": { "content": { - "application/vnd.spProductAd.v3+json": { + "application/vnd.spproducttargeting.v3+json": { "schema": { - "$ref": "#/components/schemas/SponsoredProductsUpdateSponsoredProductsProductAdsRequestContent" + "$ref": "#/components/schemas/SearchBrandsRequest" } } - }, - "required": true + } }, - "operationId": "UpdateSponsoredProductsProductAds", + "operationId": "searchBrands", + "description": "Returns up to 100 brands related to keyword input for negative targeting.\n\n**Requires one of these permissions**:\n[\"advertiser_campaign_edit\",\"advertiser_campaign_view\"]", "responses": { - "207": { - "headers": { - "Preference-Applied": { - "schema": { - "description": "Header containing preferences applied while processing API call", - "type": "string" - }, - "description": "Header containing preferences applied while processing API call" - } - }, - "description": "UpdateSponsoredProductsProductAds 207 response", + "200": { + "description": "success", "content": { - "application/vnd.spProductAd.v3+json": { + "application/vnd.spproducttargetingresponse.v3+json": { "schema": { - "$ref": "#/components/schemas/SponsoredProductsUpdateSponsoredProductsProductAdsResponseContent" + "$ref": "#/components/schemas/Brands" } } } }, "400": { - "description": "ProductAdMutationException 400 response", + "description": "Bad Request - The input fails to satisfy the constraints of the API.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SponsoredProductsProductAdMutationExceptionResponseContent" + "$ref": "#/components/schemas/BadRequestException" } } } }, "401": { - "description": "UnauthorizedException 401 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SponsoredProductsUnauthorizedExceptionResponseContent" - } - } - } - }, - "403": { - "description": "AccessDeniedException 403 response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SponsoredProductsAccessDeniedExceptionResponseContent" - } - } - } - }, - "415": { - "description": "UnsupportedMediaTypeException 415 response", + "description": "Unauthorized - Request failed because user is not authenticated.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SponsoredProductsUnsupportedMediaTypeExceptionResponseContent" + "$ref": "#/components/schemas/UnauthorizedException" } } } }, "429": { - "headers": { - "Retry-After": { - "schema": { - "format": "int32", - "description": "Delay in seconds, before the next re-try attempt to the operation is recommended", - "type": "integer" - }, - "description": "Delay in seconds, before the next re-try attempt to the operation is recommended" - } - }, - "description": "ThrottlingException 429 response", + "description": "Too Many Requests - Request was rate-limited. Retry later.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SponsoredProductsThrottlingExceptionResponseContent" + "$ref": "#/components/schemas/ThrottlingException" } } } }, "500": { - "description": "InternalServerException 500 response", + "description": "Internal Server Error - Something went wrong on the server. Retry\nlater and report an error if unresolved.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SponsoredProductsInternalServerExceptionResponseContent" + "$ref": "#/components/schemas/InternalServerException" } } } } }, - "description": "\n\n**Requires one of these permissions**:\n[\"advertiser_campaign_edit\"]", "parameters": [ { "schema": { - "description": "The identifier of a client associated with a \"Login with Amazon\" account.", "type": "string" }, "in": "header", "name": "Amazon-Advertising-API-ClientId", - "description": "The identifier of a client associated with a \"Login with Amazon\" account.", + "description": "The identifier of a client associated with a \"Login with Amazon\" account. This is a required header for advertisers and integrators using the Advertising API.", "required": true }, { "schema": { - "description": "The identifier of a profile associated with the advertiser account. Use GET method on Profiles resource to list\nprofiles associated with the access token passed in the HTTP Authorization header.", "type": "string" }, "in": "header", "name": "Amazon-Advertising-API-Scope", - "description": "The identifier of a profile associated with the advertiser account. Use GET method on Profiles resource to list\nprofiles associated with the access token passed in the HTTP Authorization header.", + "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. This is a required header for advertisers and integrators using the Advertising API.", "required": true }, { "schema": { - "description": "The \"Prefer\" header, as defined in [RFC7240], allows clients to request certain behavior from the service.\nThe service ignores preference values that are either not supported or not known by the service.\nEither multiple Prefer headers are passed or single one with comma separated values, both forms are equivalent\nSupported preferences:\nreturn=representation - return the full object when doing create/update/delete operations instead of ids", "type": "string" }, "in": "header", "name": "Prefer", - "description": "The \"Prefer\" header, as defined in [RFC7240], allows clients to request certain behavior from the service.\nThe service ignores preference values that are either not supported or not known by the service.\nEither multiple Prefer headers are passed or single one with comma separated values, both forms are equivalent\nSupported preferences:\nreturn=representation - return the full object when doing create/update/delete operations instead of ids" + "description": "Used to indicate the behavior preferred by the client but is not required for successful completion of the request. Supported values will be updated in the future.", + "required": false } ], "tags": [ - "ProductAds" + "Product Targeting" ] } }, - "/sp/budgetRules": { - "post": { - "summary": "Creates one or more budget rules.", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CreateSPBudgetRulesRequest" - } - } - }, - "required": true - }, - "operationId": "CreateBudgetRulesForSPCampaigns", - "responses": { - "207": { - "description": "Multi-status. An object containing a list of budget rule response objects reflecting the same order as the input.", + "/sp/targets/category/{categoryId}/refinements": { + "get": { + "summary": "Returns refinements according to category input.", + "operationId": "getRefinementsForCategory", + "description": "Returns refinements according to category input.\n\n**Requires one of these permissions**:\n[\"advertiser_campaign_edit\",\"advertiser_campaign_view\"]", + "responses": { + "200": { + "description": "success", "content": { - "application/json": { + "application/vnd.spproducttargetingresponse.v3+json": { "schema": { - "$ref": "#/components/schemas/CreateBudgetRulesResponse" + "$ref": "#/components/schemas/Refinements" } } } }, "400": { - "description": "Bad Request.", + "description": "Bad Request", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/BudgetRuleError" + "$ref": "#/components/schemas/BadRequestException" } } } }, "401": { - "description": "Unauthorized. The request failed because the user is not authenticated or is not allowed to invoke the operation.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/BudgetRuleError" - } - } - } - }, - "403": { - "description": "Forbidden. The request failed because user does not have access to a specified resource.", + "description": "Unauthorized - Request failed because user is not authenticated.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/BudgetRuleError" + "$ref": "#/components/schemas/UnauthorizedException" } } } }, "422": { - "description": "Unprocessable entity. The server understood the request, but was unable to process the instruction.", + "description": "Unprocessable entity - Failed due to invalid parameters.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/BudgetRuleError" + "$ref": "#/components/schemas/UnprocessableEntityException" } } } }, "429": { - "description": "Too Many Requests. The request was rate-limited. Retry later.", + "description": "Too Many Requests - Request was rate-limited. Retry later.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/BudgetRuleError" + "$ref": "#/components/schemas/ThrottlingException" } } } }, "500": { - "description": "Internal Server Error. Something went wrong on the server. Retry later and report an error if unresolved.", + "description": "Internal Server Error - Something went wrong on the server. Retry\nlater and report an error if unresolved.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/BudgetRuleError" + "$ref": "#/components/schemas/InternalServerException" } } } } }, - "description": "\n\n**Requires one of these permissions**:\n[\"advertiser_campaign_edit\"]", "parameters": [ { "schema": { @@ -2182,208 +2334,243 @@ "name": "Amazon-Advertising-API-Scope", "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. This is a required header for advertisers and integrators using the Advertising API.", "required": true + }, + { + "schema": { + "type": "string" + }, + "in": "path", + "name": "categoryId", + "description": "The category ID. Please use the GetTargetableCategories API or the GetCategoriesForASINs API to retrieve categories IDs. This API does not check if the category is a valid category.", + "required": true + }, + { + "schema": { + "type": "string" + }, + "in": "header", + "name": "Prefer", + "description": "Used to indicate the behavior preferred by the client but is not required for successful completion of the request. Supported values will be updated in the future.", + "required": false } ], "tags": [ - "BudgetRules" + "Product Targeting" ] - }, - "get": { - "summary": "Get all budget rules created by an advertiser", - "operationId": "GetSPBudgetRulesForAdvertiser", + } + }, + "/sp/productAds/list": { + "post": { + "requestBody": { + "content": { + "application/vnd.spProductAd.v3+json": { + "schema": { + "$ref": "#/components/schemas/SponsoredProductsListSponsoredProductsProductAdsRequestContent" + } + } + } + }, + "operationId": "ListSponsoredProductsProductAds", "responses": { "200": { - "description": "Successful operation.", + "description": "ListSponsoredProductsProductAds 200 response", "content": { - "application/json": { + "application/vnd.spProductAd.v3+json": { "schema": { - "$ref": "#/components/schemas/GetSPBudgetRulesForAdvertiserResponse" + "$ref": "#/components/schemas/SponsoredProductsListSponsoredProductsProductAdsResponseContent" } } } }, "400": { - "description": "Bad Request.", + "description": "ProductAdAccessException 400 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/BudgetRuleError" + "$ref": "#/components/schemas/SponsoredProductsProductAdAccessExceptionResponseContent" } } } }, "401": { - "description": "Unauthorized. The request failed because the user is not authenticated or is not allowed to invoke the operation.", + "description": "UnauthorizedException 401 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/BudgetRuleError" + "$ref": "#/components/schemas/SponsoredProductsUnauthorizedExceptionResponseContent" } } } }, "403": { - "description": "Forbidden. The request failed because user does not have access to a specified resource.", + "description": "AccessDeniedException 403 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/BudgetRuleError" + "$ref": "#/components/schemas/SponsoredProductsAccessDeniedExceptionResponseContent" } } } }, - "422": { - "description": "Unprocessable entity. The server understood the request, but was unable to process the instruction.", + "415": { + "description": "UnsupportedMediaTypeException 415 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/BudgetRuleError" + "$ref": "#/components/schemas/SponsoredProductsUnsupportedMediaTypeExceptionResponseContent" } } } }, "429": { - "description": "Too Many Requests. The request was rate-limited. Retry later.", + "headers": { + "Retry-After": { + "schema": { + "format": "int32", + "description": "Delay in seconds, before the next re-try attempt to the operation is recommended", + "type": "integer" + }, + "description": "Delay in seconds, before the next re-try attempt to the operation is recommended" + } + }, + "description": "ThrottlingException 429 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/BudgetRuleError" + "$ref": "#/components/schemas/SponsoredProductsThrottlingExceptionResponseContent" } } } }, "500": { - "description": "Internal Server Error. Something went wrong on the server. Retry later and report an error if unresolved.", + "description": "InternalServerException 500 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/BudgetRuleError" + "$ref": "#/components/schemas/SponsoredProductsInternalServerExceptionResponseContent" } } } } }, + "description": "\n\n**Requires one of these permissions**:\n[\"advertiser_campaign_edit\",\"advertiser_campaign_view\"]", "parameters": [ { "schema": { + "description": "The identifier of a client associated with a \"Login with Amazon\" account.", "type": "string" }, "in": "header", "name": "Amazon-Advertising-API-ClientId", - "description": "The identifier of a client associated with a \"Login with Amazon\" account. This is a required header for advertisers and integrators using the Advertising API.", + "description": "The identifier of a client associated with a \"Login with Amazon\" account.", "required": true }, { "schema": { + "description": "The identifier of a profile associated with the advertiser account. Use GET method on Profiles resource to list\nprofiles associated with the access token passed in the HTTP Authorization header.", "type": "string" }, "in": "header", "name": "Amazon-Advertising-API-Scope", - "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. This is a required header for advertisers and integrators using the Advertising API.", - "required": true - }, - { - "schema": { - "type": "string" - }, - "in": "query", - "name": "nextToken", - "description": "To retrieve the next page of results, call the same operation and specify this token in the request. If the `nextToken` field is empty, there are no further results." - }, - { - "schema": { - "type": "number" - }, - "in": "query", - "name": "pageSize", - "description": "Sets a limit on the number of results returned. Maximum limit of `pageSize` is 30.", + "description": "The identifier of a profile associated with the advertiser account. Use GET method on Profiles resource to list\nprofiles associated with the access token passed in the HTTP Authorization header.", "required": true } ], "tags": [ - "BudgetRules" + "ProductAds" ] - }, - "put": { - "summary": "Updates one or more budget rules.", + } + }, + "/sp/negativeTargets/delete": { + "post": { "requestBody": { "content": { - "application/json": { + "application/vnd.spNegativeTargetingClause.v3+json": { "schema": { - "$ref": "#/components/schemas/UpdateSPBudgetRulesRequest" + "$ref": "#/components/schemas/SponsoredProductsDeleteSponsoredProductsNegativeTargetingClausesRequestContent" } } }, "required": true }, - "operationId": "UpdateBudgetRulesForSPCampaigns", + "operationId": "DeleteSponsoredProductsNegativeTargetingClauses", "responses": { "207": { - "description": "Multi-status. An object containing a list of budget rule response objects reflecting the same order as the input.", + "description": "DeleteSponsoredProductsNegativeTargetingClauses 207 response", "content": { - "application/json": { + "application/vnd.spNegativeTargetingClause.v3+json": { "schema": { - "$ref": "#/components/schemas/UpdateBudgetRulesResponse" + "$ref": "#/components/schemas/SponsoredProductsDeleteSponsoredProductsNegativeTargetingClausesResponseContent" } } } }, "400": { - "description": "Bad Request.", + "description": "NegativeTargetMutationException 400 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/BudgetRuleError" + "$ref": "#/components/schemas/SponsoredProductsNegativeTargetMutationExceptionResponseContent" } } } }, "401": { - "description": "Unauthorized. The request failed because the user is not authenticated or is not allowed to invoke the operation.", + "description": "UnauthorizedException 401 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/BudgetRuleError" + "$ref": "#/components/schemas/SponsoredProductsUnauthorizedExceptionResponseContent" } } } }, "403": { - "description": "Forbidden. The request failed because user does not have access to a specified resource.", + "description": "AccessDeniedException 403 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/BudgetRuleError" + "$ref": "#/components/schemas/SponsoredProductsAccessDeniedExceptionResponseContent" } } } }, - "422": { - "description": "Unprocessable entity. The server understood the request, but was unable to process the instruction.", + "415": { + "description": "UnsupportedMediaTypeException 415 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/BudgetRuleError" + "$ref": "#/components/schemas/SponsoredProductsUnsupportedMediaTypeExceptionResponseContent" } } } }, "429": { - "description": "Too Many Requests. The request was rate-limited. Retry later.", + "headers": { + "Retry-After": { + "schema": { + "format": "int32", + "description": "Delay in seconds, before the next re-try attempt to the operation is recommended", + "type": "integer" + }, + "description": "Delay in seconds, before the next re-try attempt to the operation is recommended" + } + }, + "description": "ThrottlingException 429 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/BudgetRuleError" + "$ref": "#/components/schemas/SponsoredProductsThrottlingExceptionResponseContent" } } } }, "500": { - "description": "Internal Server Error. Something went wrong on the server. Retry later and report an error if unresolved.", + "description": "InternalServerException 500 response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/BudgetRuleError" + "$ref": "#/components/schemas/SponsoredProductsInternalServerExceptionResponseContent" } } } @@ -2393,400 +2580,451 @@ "parameters": [ { "schema": { + "description": "The identifier of a client associated with a \"Login with Amazon\" account.", "type": "string" }, "in": "header", "name": "Amazon-Advertising-API-ClientId", - "description": "The identifier of a client associated with a \"Login with Amazon\" account. This is a required header for advertisers and integrators using the Advertising API.", + "description": "The identifier of a client associated with a \"Login with Amazon\" account.", "required": true }, { "schema": { + "description": "The identifier of a profile associated with the advertiser account. Use GET method on Profiles resource to list\nprofiles associated with the access token passed in the HTTP Authorization header.", "type": "string" }, "in": "header", "name": "Amazon-Advertising-API-Scope", - "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. This is a required header for advertisers and integrators using the Advertising API.", + "description": "The identifier of a profile associated with the advertiser account. Use GET method on Profiles resource to list\nprofiles associated with the access token passed in the HTTP Authorization header.", "required": true } ], "tags": [ - "BudgetRules" + "NegativeTargetingClauses" ] } }, - "/sp/targets/categories/recommendations": { + "/sp/negativeTargets/list": { "post": { - "summary": "Returns a list of category recommendations for the input list of ASINs.", "requestBody": { "content": { - "application/vnd.spproducttargeting.v3+json": { + "application/vnd.spNegativeTargetingClause.v3+json": { "schema": { - "$ref": "#/components/schemas/GetCategoryRecommendationsForAsinsRequest" + "$ref": "#/components/schemas/SponsoredProductsListSponsoredProductsNegativeTargetingClausesRequestContent" } } } }, - "operationId": "getCategoryRecommendationsForASINs", - "description": "Returns a list of category recommendations for the input list of ASINs. Use this API to discover relevant categories to target. To find ASINs, either use the Product Metadata API or browse the Amazon Retail Website.