{ "swagger": "2.0", "info": { "description": "The Selling Partner API for Promotions enables selling partners to create and manage promotions.", "version": "2025-12-01", "title": "The Selling Partner API for Promotions", "contact": { "name": "Selling Partner API Developer Support", "url": "https://sellercentral.amazon.com/gp/mws/contactus.html" }, "license": { "name": "Apache License 2.0", "url": "http://www.apache.org/licenses/LICENSE-2.0" } }, "host": "sellingpartnerapi-na.amazon.com", "schemes": [ "https" ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "paths": { "/promotions/2025-12-01/promotions": { "get": { "x-amzn-api-internal": "INTERNAL_AND_EXTERNAL", "tags": [ "promotions" ], "description": "Search and filter promotions based on various criteria. Returns a paginated list of promotion summaries.\n\n**Usage Plan:**\n\n| Rate (requests per second) | Burst |\n| ---- | ---- |\n| 0.1 | 4 |\n\nThe `x-amzn-RateLimit-Limit` response header returns the usage plan rate limits that were applied to the requested operation, when available. The preceding table indicates the default rate and burst values for this operation. Selling partners whose business demands require higher throughput may have higher rate and burst values than those shown here. For more information, refer to [Usage Plans and Rate Limits](https://developer-docs.amazon/sp-api/docs/usage-plans-and-rate-limits).", "operationId": "searchPromotions", "parameters": [ { "name": "marketplaceIds", "in": "query", "description": "The Amazon stores from which to retrieve promotions. Refer to [Store Identifiers](https://developer-docs.amazon/sp-api/docs/store-identifiers) for a list of Amazon store values.", "required": true, "type": "array", "items": { "type": "string" }, "maxItems": 1, "collectionFormat": "csv", "x-example": "ATVPDKIKX0DER" }, { "name": "locale", "in": "query", "description": "The locale from which to retrieve promotions. Formatted as an ISO 639 language code, followed by an underscore, followed by an ISO 3166-1 alpha-2 country code.", "pattern": "^[a-z]{2}_[A-Z]{2}$", "type": "string", "required": false, "default": "en_US" }, { "name": "statuses", "in": "query", "description": "The statuses of promotions to retrieve, formatted as a comma-delimited list.", "required": false, "type": "array", "items": { "type": "string", "enum": [ "PROCESSING", "UPCOMING", "RUNNING", "EXPIRED", "FAILED", "CANCELLING", "CANCELLED" ] }, "collectionFormat": "csv", "x-example": "RUNNING,UPCOMING,PROCESSING", "x-docgen-enum-table-extension": [ { "value": "PROCESSING", "description": "Promotion is being processed and validated by the system." }, { "value": "UPCOMING", "description": "Promotion is scheduled and becomes active at the specified start date." }, { "value": "RUNNING", "description": "Promotion is currently active and available to customers." }, { "value": "EXPIRED", "description": "Promotion has passed its end date and is no longer active." }, { "value": "FAILED", "description": "Promotion processing or validation has failed and requires attention." }, { "value": "CANCELLING", "description": "Promotion cancellation is in progress." }, { "value": "CANCELLED", "description": "Promotion has been successfully canceled and is no longer active." } ] }, { "name": "asins", "in": "query", "description": "The ASINs to which promotions apply, formatted as a comma-delimited list.", "required": false, "type": "array", "maxItems": 10, "items": { "type": "string" }, "collectionFormat": "csv", "x-example": "B08N5WRWNW,B07XJ8C8F5,B09MKTS6R4" }, { "name": "skus", "in": "query", "description": "The SKUs to which promotions apply, formatted as a comma-delimited list.", "required": false, "type": "array", "maxItems": 10, "items": { "type": "string" }, "collectionFormat": "csv", "x-example": "SKU-001,SKU-002,SKU-003" }, { "name": "promotionTypes", "in": "query", "description": "The promotion types to which promotions apply, formatted as a comma-delimited list.", "required": false, "type": "array", "items": { "type": "string", "enum": [ "BASKET_BUILDING", "DEAL", "PRICE_DISCOUNT", "COUPON" ] }, "collectionFormat": "csv", "x-example": "DEAL" }, { "name": "startDateBefore", "in": "query", "description": "Promotions that start before this date are returned. Formatted in ISO 8601 format, including the timezone. For example: `1970-01-01T00:00:00-07:00`.", "required": false, "type": "string", "format": "date-time", "x-example": "2025-08-31T23:59:59-07:00" }, { "name": "startDateAfter", "in": "query", "description": "Promotions that start after this date are returned. Formatted in ISO 8601 format, including the timezone. For example: `1970-01-01T00:00:00-07:00`.", "required": false, "type": "string", "format": "date-time", "x-example": "2025-07-01T00:00:00-07:00" }, { "name": "endDateBefore", "in": "query", "description": "Promotions that end before this date are returned. Formatted in ISO 8601 format, including the timezone. For example: `1970-01-01T00:00:00-07:00`.", "required": false, "type": "string", "format": "date-time", "x-example": "2025-12-31T23:59:59-08:00" }, { "name": "endDateAfter", "in": "query", "description": "Promotions that end after this date are returned. Formatted in ISO 8601 format, including the timezone. For example: `1970-01-01T00:00:00-07:00`.", "required": false, "type": "string", "format": "date-time", "x-example": "2025-09-01T00:00:00-07:00" }, { "name": "updateDateAfter", "in": "query", "description": "Filter promotions that were last modified after this timestamp. Zoned Datetime in ISO 8601 format (e.g., 1970-01-01T00:00:00-07:00).", "required": false, "type": "string", "format": "date-time", "x-example": "2025-07-01T00:00:00-07:00" }, { "name": "updateDateBefore", "in": "query", "description": "Filter promotions that were last modified before this timestamp. Zoned Datetime in ISO 8601 format (e.g., 1970-01-01T00:00:00-07:00).", "required": false, "type": "string", "format": "date-time", "x-example": "2025-12-31T23:59:59-07:00" }, { "in": "query", "name": "paginationToken", "type": "string", "description": "A token that you use to retrieve the next page of results. The response includes `paginationToken` when the number of results exceeds the specified `limit` value. To get the next page of results, call the operation with this token and include the same arguments as the call that produced the token. To get a complete list, call this operation until `paginationToken` is null. Note that this operation can return empty pages.", "required": false, "x-example": "sdlkj234lkj234lksjdflkjwdflkjsfdlkj234234234234" }, { "name": "revision", "in": "query", "description": "Specifies which promotion revision or revisions to match against when filtering. This controls which promotions are included in search results, not the shape of the response. The response always returns the published revision in the main body, with `latestRevision` included when the latest revision diverges.", "required": false, "type": "string", "enum": [ "LATEST", "PUBLISHED", "ANY" ], "default": "PUBLISHED", "x-example": "PUBLISHED", "x-docgen-enum-table-extension": [ { "value": "LATEST", "description": "Query against latest revision of promotions. Returns promotions based on their latest revision state. This will skip promotions where the query matched only its published revision." }, { "value": "PUBLISHED", "description": "Query against published revisions of promotions. Returns only promotions that have been published. This will skip promotions where the query matched only its latest revision." }, { "value": "ANY", "description": "Query against published and latest revisions. This provides the complete state including both published and latest revision promotions." } ] }, { "name": "limit", "in": "query", "description": "The maximum number of response results per page.", "required": false, "type": "integer", "format": "int64", "minimum": 1, "maximum": 100, "default": 20 }, { "name": "includedData", "in": "query", "description": "A comma-delimited list of datasets to include in the response.", "required": false, "type": "array", "items": { "type": "string", "enum": [ "ISSUES", "CUSTOMER_SEGMENTS" ] }, "collectionFormat": "csv", "x-example": "ISSUES", "x-docgen-enum-table-extension": [ { "value": "ISSUES", "description": "Include promotion level issues and warnings in the response. If not specified, the 'issues' field will be omitted from the response even if issues exist for the promotion." }, { "value": "CUSTOMER_SEGMENTS", "description": "Include customer segment targeting information in the response. If not specified, the 'customerSegments' field will be omitted from the response." } ] } ], "responses": { "200": { "description": "Successfully retrieved promotions.", "headers": { "x-amzn-RequestId": { "description": "Unique request reference identifier.", "type": "string" }, "x-amzn-RateLimit-Limit": { "description": "Your rate limit (requests per second) for this operation.", "type": "string" } }, "schema": { "$ref": "#/definitions/SearchPromotionsResponse" }, "x-amzn-api-sandbox": { "static": [ { "request": { "parameters": { "marketplaceIds": { "value": [ "ATVPDKIKX0DER" ] }, "locale": { "value": "en_US" }, "statuses": { "value": [ "RUNNING", "UPCOMING" ] }, "limit": { "value": 10 } } }, "response": { "totalResults": 2, "pagination": { "nextToken": "sdlkj234lkj234lksjdflkjwdflkjsfdlkj234234234234" }, "promotions": [ { "promotionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "trackingId": "v2024-a1b2c3d4-e5f6-7890-abcd-ef1234567890", "marketplaceId": "ATVPDKIKX0DER", "status": "RUNNING", "createdDate": "2025-07-01T02:01:08-07:00", "lastUpdatedDate": "2025-07-15T14:30:00-07:00", "promotionTitle": "Summer Sale 2025", "selection": { "selectionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "revisionId": 1, "type": "ITEMS" }, "promotionType": "DEAL", "schedule": { "startDate": "2025-07-01T00:00:00-07:00", "endDate": "2025-08-31T23:59:59-07:00", "eventId": "PRIME_DAY_2025" } }, { "promotionId": "b2c3d4e5-f6g7-8901-bcde-fg2345678901", "trackingId": "v2024-b2c3d4e5-f6g7-8901-bcde-fg2345678901", "marketplaceId": "ATVPDKIKX0DER", "status": "UPCOMING", "createdDate": "2025-08-01T10:00:00-07:00", "lastUpdatedDate": "2025-08-05T16:45:00-07:00", "promotionTitle": "Back to School Special", "selection": { "selectionId": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "revisionId": 1, "type": "ITEMS" }, "promotionType": "BASKET_BUILDING", "schedule": { "startDate": "2025-09-01T00:00:00-07:00", "endDate": "2025-09-30T23:59:59-07:00" }, "budget": { "type": "UNITS", "value": 500 }, "purchaseRequirements": { "selection": { "selectionId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "revisionId": 1, "type": "ITEMS" }, "condition": { "quantityThreshold": { "type": "AT_LEAST", "quantity": 2 } } }, "benefit": { "discount": { "type": "AMOUNT_OFF", "amountOff": 10, "currencyCode": "USD" }, "benefitQuantity": 1, "perCustomerUses": 3, "stacking": "NOT_ALLOWED" }, "merchandising": { "displayOnWebsite": "ALLOWED" } } ] } } ] } }, "400": { "description": "Request has missing or invalid parameters and cannot be parsed.", "schema": { "$ref": "#/definitions/ErrorList" }, "headers": { "x-amzn-RateLimit-Limit": { "type": "string", "description": "Your rate limit (requests per second) for this operation." }, "x-amzn-RequestId": { "type": "string", "description": "Unique request reference identifier." } }, "x-amzn-api-sandbox": { "static": [ { "request": { "parameters": { "marketplaceIds": { "value": [ "INVALID_MARKETPLACE" ] }, "locale": { "value": "en_US" } } }, "response": { "errors": [ { "code": "INVALID_VALUE", "message": "The request contains invalid parameters.", "details": "Invalid marketplace identifier provided." } ] } } ] } }, "403": { "description": "Indicates that access to the resource is forbidden. Possible reasons include Access Denied, Unauthorized, Expired Token, or Invalid Signature.", "schema": { "$ref": "#/definitions/ErrorList" }, "headers": { "x-amzn-RequestId": { "type": "string", "description": "Unique request reference identifier." } } }, "404": { "description": "The resource specified does not exist.", "schema": { "$ref": "#/definitions/ErrorList" }, "headers": { "x-amzn-RateLimit-Limit": { "type": "string", "description": "Your rate limit (requests per second) for this operation." }, "x-amzn-RequestId": { "type": "string", "description": "Unique request reference identifier." } } }, "413": { "description": "The request size exceeded the maximum accepted size.", "headers": { "x-amzn-RequestId": { "description": "Unique request reference identifier.", "type": "string" } }, "schema": { "$ref": "#/definitions/ErrorList" } }, "415": { "description": "The request payload is in an unsupported format.", "headers": { "x-amzn-RequestId": { "description": "Unique request reference identifier.", "type": "string" } }, "schema": { "$ref": "#/definitions/ErrorList" } }, "429": { "description": "The frequency of requests was greater than allowed.", "schema": { "$ref": "#/definitions/ErrorList" }, "headers": { "x-amzn-RequestId": { "type": "string", "description": "Unique request reference identifier." } } }, "500": { "description": "An unexpected condition occurred that prevented the server from fulfilling the request.", "schema": { "$ref": "#/definitions/ErrorList" }, "headers": { "x-amzn-RequestId": { "type": "string", "description": "Unique request reference identifier." } } }, "503": { "description": "Temporary overloading or maintenance of the server.", "schema": { "$ref": "#/definitions/ErrorList" }, "headers": { "x-amzn-RequestId": { "type": "string", "description": "Unique request reference identifier." } } } } } }, "/promotions/2025-12-01/promotions/{promotionId}": { "get": { "x-amzn-api-internal": "INTERNAL_AND_EXTERNAL", "tags": [ "promotions" ], "description": "Retrieve details of a specified promotion.\n\n**Usage Plan:**\n\n| Rate (requests per second) | Burst |\n| ---- | ---- |\n| 0.1 | 2 |\n\nThe `x-amzn-RateLimit-Limit` response header returns the usage plan rate limits that were applied to the requested operation, when available. The preceding table indicates the default rate and burst values for this operation. Selling partners whose business demands require higher throughput may have higher rate and burst values than those shown here. For more information, refer to [Usage Plans and Rate Limits](https://developer-docs.amazon/sp-api/docs/usage-plans-and-rate-limits).", "operationId": "getPromotion", "parameters": [ { "name": "promotionId", "in": "path", "description": "The ID of the promotion.", "required": true, "type": "string" }, { "name": "includedData", "in": "query", "description": "A comma-delimited list of datasets to include in the response.", "required": false, "type": "array", "items": { "type": "string", "enum": [ "ISSUES", "SELECTION", "CUSTOMER_SEGMENTS" ] }, "collectionFormat": "csv", "x-example": "ISSUES", "x-docgen-enum-table-extension": [ { "value": "ISSUES", "description": "Include promotion level issues and warnings in the response. If not specified, the `issues` field will be omitted from the response even if issues exist for the promotion. If this field is specified without `SELECTION`, then item level issues will not be returned in the response. To get item level issues as well, specify both `SELECTION` and `ISSUES` in the query parameters, or use the paginated `getSelection` operation." }, { "value": "SELECTION", "description": "Include `selectionDetails` field within the `selection` object, containing item-level information such as benefits, budgets, and other details. If not specified, the `selection` field will contain only minimal metadata (`selectionId`, `type`, and optionally `revisionId`). Item issues are only populated if both `SELECTION` and `ISSUES` are specified in the query parameters, or use the `getSelection` operation." }, { "value": "CUSTOMER_SEGMENTS", "description": "Include customer segment targeting information in the response. If not specified, the 'customerSegments' field will be omitted from the response." } ] }, { "name": "locale", "in": "query", "description": "The locale of the promotion. Formatted as an ISO 639 language code, followed by an underscore, followed by an ISO 3166-1 alpha-2 country code.", "pattern": "^[a-z]{2}_[A-Z]{2}$", "type": "string", "required": false, "default": "en_US" } ], "responses": { "200": { "description": "Successfully retrieved the promotion details.", "headers": { "x-amzn-RequestId": { "description": "Unique request reference identifier.", "type": "string" }, "x-amzn-RateLimit-Limit": { "description": "Your rate limit (requests per second) for this operation.", "type": "string" } }, "schema": { "$ref": "#/definitions/GetPromotionResponse" }, "x-amzn-api-sandbox": { "static": [ { "request": { "parameters": { "promotionId": { "value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "includedData": { "value": [ "ISSUES", "SELECTION", "CUSTOMER_SEGMENTS" ] }, "locale": { "value": "en_US" } } }, "response": { "promotionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "trackingId": "df066132-dd1d-4cf0-bfb0-31578b28845d", "marketplaceId": "ATVPDKIKX0DER", "status": "RUNNING", "createdDate": "2025-07-01T02:01:08-07:00", "lastUpdatedDate": "2025-07-15T14:30:00-07:00", "promotionTitle": "Summer Sale 2025", "promotionType": "COUPON", "couponType": "STANDARD", "schedule": { "startDate": "2025-07-01T00:00:00-07:00", "endDate": "2025-08-31T23:59:59-07:00" }, "budget": { "type": "AMOUNT", "value": 1000, "currencyCode": "USD" }, "selection": { "selectionId": "198ac961-28cf-4b9a-bec8-2260a28102d7", "revisionId": 1, "type": "ITEMS", "selectionDetails": { "items": [ { "asin": "B08N5WRWNW" }, { "asin": "B07XJ8C8F5" } ], "issues": [ { "code": "PRODUCT_NOT_AVAILABLE", "message": "PRODUCT_NOT_AVAILABLE", "severity": "ERROR", "identifier": { "asin": "B08N5WRWNW" } } ] } }, "benefit": { "discount": { "type": "PERCENTAGE_OFF", "percentOff": 15 }, "perCustomerUses": 5, "stacking": "ALLOWED" }, "issues": [ { "code": "HAS_OVERLAPPING_PROMOTIONS", "message": "HAS_OVERLAPPING_PROMOTIONS", "severity": "WARNING" } ], "customerSegments": [ { "segmentType": "BRAND", "segmentId": "c157be82-b0c1-49e1-bf9b-4180da99b66d", "segmentDetails": { "brandSegmentDetails": { "brandId": "G13V1IB3VIYZZH" } } }, { "segmentType": "PROGRAM", "segmentId": "PRIME_EXCLUSIVE" } ] } }, { "request": { "parameters": { "promotionId": { "value": "b2c3d4e5-f6a7-8901-bcde-fg2345678901" }, "includedData": { "value": [ "SELECTION" ] }, "locale": { "value": "en_US" } } }, "response": { "promotionId": "b2c3d4e5-f6a7-8901-bcde-fg2345678901", "trackingId": "8f2d4a1c-3b5e-4f7a-9c8d-1e2f3a4b5c6d", "marketplaceId": "ATVPDKIKX0DER", "status": "RUNNING", "createdDate": "2026-07-01T00:00:00-07:00", "lastUpdatedDate": "2026-07-01T00:00:00-07:00", "promotionTitle": "Subscribe & Save - 10% off", "promotionType": "COUPON", "couponType": "SUBSCRIBE_AND_SAVE", "schedule": { "startDate": "2026-07-01T00:00:00-07:00", "endDate": "2026-08-31T23:59:59-07:00" }, "budget": { "type": "AMOUNT", "value": 15000, "currencyCode": "USD" }, "selection": { "selectionId": "7c1f9b22-5a3d-4e8f-b6c1-9d2e0f3a4b5c", "revisionId": 1, "type": "ITEMS", "selectionDetails": { "items": [ { "asin": "B0GYV2ZXJ9" } ], "issues": [] } }, "benefit": { "discount": { "type": "PERCENTAGE_OFF", "percentOff": 10 }, "perCustomerUses": 1, "stacking": "ALLOWED" }, "merchandising": { "displayOnWebsite": "ALLOWED" } } }, { "request": { "parameters": { "promotionId": { "value": "d4e5f6a7-b8c9-0123-defg-hi4567890123" }, "includedData": { "value": [ "ISSUES", "SELECTION" ] }, "locale": { "value": "en_US" } } }, "response": { "promotionId": "d4e5f6a7-b8c9-0123-defg-hi4567890123", "trackingId": "v2024-d4e5f6a7-b8c9-0123-defg-hi4567890123", "marketplaceId": "ATVPDKIKX0DER", "status": "RUNNING", "createdDate": "2025-07-01T02:01:08-07:00", "lastUpdatedDate": "2025-07-15T14:30:00-07:00", "promotionTitle": "Summer Sale 2025", "promotionType": "DEAL", "schedule": { "startDate": "2025-07-01T00:00:00-07:00", "endDate": "2025-08-31T23:59:59-07:00", "eventId": "PRIME_DAY_2025" }, "selection": { "selectionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "revisionId": 1, "type": "ITEMS", "selectionDetails": { "items": [ { "asin": "B08N5WRWNW", "sku": "B08N5WRWNW-SKU", "benefit": { "type": "FIXED_PRICE", "price": { "amount": 15, "currencyCode": "USD" }, "discount": { "type": "PERCENTAGE_OFF", "percentOff": 15 } }, "budget": { "type": "UNITS", "value": 50 } }, { "asin": "B07XJ8C8F5", "sku": "B07XJ8C8F5-SKU", "benefit": { "type": "DISCOUNTED_PRICE", "discount": { "type": "AMOUNT_OFF", "amountOff": 10, "currencyCode": "USD" } }, "budget": { "type": "AMOUNT", "value": 10000, "currencyCode": "USD" } } ], "issues": [ { "code": "PRODUCT_NOT_AVAILABLE", "message": "PRODUCT_NOT_AVAILABLE", "severity": "ERROR", "identifier": { "asin": "B08N5WRWNW" } } ] } }, "issues": [] } }, { "request": { "parameters": { "promotionId": { "value": "e5f6a7b8-c9d0-1234-efgh-ij5678901234" }, "includedData": { "value": [ "ISSUES", "SELECTION", "CUSTOMER_SEGMENTS" ] }, "locale": { "value": "en_US" } } }, "response": { "promotionId": "e5f6a7b8-c9d0-1234-efgh-ij5678901234", "trackingId": "df066132-dd1d-4cf0-bfb0-31578b28845d", "marketplaceId": "ATVPDKIKX0DER", "status": "PROCESSING", "createdDate": "2025-07-01T02:01:08-07:00", "lastUpdatedDate": "2025-07-01T02:01:08-07:00", "promotionTitle": "Summer Sale for Brand Customers", "promotionType": "BASKET_BUILDING", "schedule": { "startDate": "2025-07-01T02:01:08-07:00", "endDate": "2025-08-31T23:59:59-07:00" }, "budget": { "type": "AMOUNT", "value": 1000, "currencyCode": "USD" }, "selection": { "selectionId": "198ac961-28cf-4b9a-bec8-2260a28102d7", "revisionId": 1, "type": "ITEMS", "selectionDetails": { "items": [ { "asin": "B08N5WRWNW", "sku": "B08N5WRWNW-SKU-001" }, { "asin": "B07XJ8C8F5", "sku": "B07XJ8C8F5-SKU-001" } ], "issues": [ { "code": "PRODUCT_NOT_AVAILABLE", "message": "PRODUCT_NOT_AVAILABLE", "severity": "ERROR", "identifier": { "asin": "B08N5WRWNW" } } ] } }, "purchaseRequirements": { "selection": { "selectionId": "7f3a91d2-4e8b-4c6f-a5d0-9b2e7f1c8d3a", "revisionId": 1, "type": "ITEMS" }, "condition": { "quantityThreshold": { "type": "FOR_EACH", "quantity": 3 } }, "claimCode": { "type": "INDIVIDUAL" } }, "benefit": { "benefitQuantity": 1, "discount": { "type": "PERCENTAGE_OFF", "percentOff": 10 }, "perCustomerUses": 1, "stacking": "NOT_ALLOWED" }, "merchandising": { "displayOnWebsite": "ALLOWED" }, "issues": [ { "code": "HAS_OVERLAPPING_PROMOTIONS", "message": "HAS_OVERLAPPING_PROMOTIONS", "severity": "WARNING" } ], "customerSegments": [ { "segmentType": "BRAND", "segmentId": "c157be82-b0c1-49e1-bf9b-4180da99b66d", "segmentDetails": { "brandSegmentDetails": { "brandId": "XYZV1IB3VIYABC" } } } ] } }, { "request": { "parameters": { "promotionId": { "value": "86396572-e0e3-4dc6-a072-410f461dee60" }, "includedData": { "value": [ "ISSUES", "SELECTION" ] }, "locale": { "value": "en_US" } } }, "response": { "promotionId": "86396572-e0e3-4dc6-a072-410f461dee60", "trackingId": "v2024-86396572-e0e3-4dc6-a072-410f461dee60", "marketplaceId": "ATVPDKIKX0DER", "status": "RUNNING", "createdDate": "2025-07-01T02:01:08-07:00", "lastUpdatedDate": "2025-07-20T10:30:00-07:00", "promotionTitle": "Summer Sale 2025 - Updated", "promotionType": "COUPON", "couponType": "STANDARD", "schedule": { "startDate": "2025-07-01T00:00:00-07:00", "endDate": "2025-08-31T23:59:59-07:00" }, "budget": { "type": "AMOUNT", "value": 1000, "currencyCode": "USD" }, "selection": { "selectionId": "198ac961-28cf-4b9a-bec8-2260a28102d7", "revisionId": 1, "type": "ITEMS", "selectionDetails": { "items": [ { "asin": "B08N5WRWNW" } ], "issues": [] } }, "benefit": { "discount": { "type": "PERCENTAGE_OFF", "percentOff": 15 }, "perCustomerUses": 5, "stacking": "ALLOWED" }, "issues": [], "latestRevision": { "revisionStatus": "FAILED", "promotionId": "86396572-e0e3-4dc6-a072-410f461dee60", "trackingId": "v2024-86396572-e0e3-4dc6-a072-410f461dee60", "marketplaceId": "ATVPDKIKX0DER", "promotionTitle": "Summer Sale 2025 - Updated", "promotionType": "COUPON", "couponType": "STANDARD", "schedule": { "startDate": "2025-07-01T00:00:00-07:00", "endDate": "2025-06-01T00:00:00-07:00" }, "budget": { "type": "AMOUNT", "value": 1000, "currencyCode": "USD" }, "benefit": { "discount": { "type": "PERCENTAGE_OFF", "percentOff": 15 }, "perCustomerUses": 5, "stacking": "ALLOWED" }, "selection": { "selectionId": "198ac961-28cf-4b9a-bec8-2260a28102d7", "revisionId": 2, "type": "ITEMS" }, "issues": [ { "code": "INVALID_SCHEDULE", "message": "End date cannot be in the past", "severity": "ERROR" } ], "feeSnapshot": { "previewedFeeRates": { "upfrontFee": { "rate": { "amount": 100, "currencyCode": "USD" }, "frequency": "ONE_TIME" } } }, "createdDate": "2025-07-20T10:00:00-07:00", "lastUpdatedDate": "2025-07-20T10:30:00-07:00" } } } ] } }, "400": { "description": "Request has missing or invalid parameters and cannot be parsed.", "schema": { "$ref": "#/definitions/ErrorList" }, "headers": { "x-amzn-RateLimit-Limit": { "type": "string", "description": "Your rate limit (requests per second) for this operation." }, "x-amzn-RequestId": { "type": "string", "description": "Unique request reference identifier." } }, "x-amzn-api-sandbox": { "static": [ { "request": { "parameters": { "promotionId": { "value": "a1b2c3d4-e5f6-7890-abcd-ef12345678911" } } }, "response": { "errors": [ { "code": "INVALID_VALUE", "message": "The request contains invalid parameters.", "details": "Invalid parameter value provided." } ] } } ] } }, "403": { "description": "Indicates that access to the resource is forbidden. Possible reasons include Access Denied, Unauthorized, Expired Token, or Invalid Signature.", "schema": { "$ref": "#/definitions/ErrorList" }, "headers": { "x-amzn-RequestId": { "type": "string", "description": "Unique request reference identifier." } } }, "404": { "description": "The resource specified does not exist.", "schema": { "$ref": "#/definitions/ErrorList" }, "headers": { "x-amzn-RateLimit-Limit": { "type": "string", "description": "Your rate limit (requests per second) for this operation." }, "x-amzn-RequestId": { "type": "string", "description": "Unique request reference identifier." } } }, "413": { "description": "The request size exceeded the maximum accepted size.", "headers": { "x-amzn-RequestId": { "description": "Unique request reference identifier.", "type": "string" } }, "schema": { "$ref": "#/definitions/ErrorList" } }, "415": { "description": "The request payload is in an unsupported format.", "headers": { "x-amzn-RequestId": { "description": "Unique request reference identifier.", "type": "string" } }, "schema": { "$ref": "#/definitions/ErrorList" } }, "429": { "description": "The frequency of requests was greater than allowed.", "schema": { "$ref": "#/definitions/ErrorList" }, "headers": { "x-amzn-RequestId": { "type": "string", "description": "Unique request reference identifier." } } }, "500": { "description": "An unexpected condition occurred that prevented the server from fulfilling the request.", "schema": { "$ref": "#/definitions/ErrorList" }, "headers": { "x-amzn-RequestId": { "type": "string", "description": "Unique request reference identifier." } } }, "503": { "description": "Temporary overloading or maintenance of the server.", "schema": { "$ref": "#/definitions/ErrorList" }, "headers": { "x-amzn-RequestId": { "type": "string", "description": "Unique request reference identifier." } } } } } }, "/promotions/2025-12-01/promotions/{promotionId}/selections/{selectionId}": { "get": { "x-amzn-api-internal": "INTERNAL_AND_EXTERNAL", "tags": [ "promotions" ], "description": "Retrieve up to 100 product items that are associated with a specified promotion. This operation only supports items found in `SelectionType.ITEMS`. Items found in `SelectionType.CATALOG` are not supported. Selection objects always include `selectionDetails` with item information.\n\n**Usage Plan:**\n\n| Rate (requests per second) | Burst |\n| ---- | ---- |\n| 0.1 | 2 |\n\nThe `x-amzn-RateLimit-Limit` response header returns the usage plan rate limits that were applied to the requested operation, when available. The preceding table indicates the default rate and burst values for this operation. Selling partners whose business demands require higher throughput may have higher rate and burst values than those shown here. For more information, refer to [Usage Plans and Rate Limits](https://developer-docs.amazon/sp-api/docs/usage-plans-and-rate-limits).", "operationId": "getSelection", "parameters": [ { "name": "promotionId", "in": "path", "description": "The ID of the promotion.", "required": true, "type": "string" }, { "name": "selectionId", "in": "path", "description": "The ID of the selection.", "required": true, "type": "string" }, { "name": "revisionId", "in": "query", "description": "The revision identifier for the selection. Use the `revisionId` from the `getPromotion` response. A promotion may have multiple selection revisions when an update is in progress. Passing the correct `revisionId` ensures you retrieve the expected data.", "required": true, "type": "integer", "minimum": 1, "x-example": 1 }, { "name": "locale", "in": "query", "description": "The locale of the promotion. Formatted as an ISO 639 language code, followed by an underscore, followed by an ISO 3166-1 alpha-2 country code.", "pattern": "^[a-z]{2}_[A-Z]{2}$", "type": "string", "required": false, "default": "en_US", "x-example": "en_US" }, { "in": "query", "name": "paginationToken", "type": "string", "description": "A token that you use to retrieve the next page of results. The response includes `paginationToken` when the number of results exceeds the specified `limit` value. To get the next page of results, call the operation with this token and include the same arguments as the call that produced the token. To get a complete list, call this operation until `paginationToken` is null. Note that this operation can return empty pages.", "required": false, "x-example": "sdlkj234lkj234lksjdflkjwdflkjsfdlkj234234234234" }, { "name": "limit", "in": "query", "description": "The maximum number of response results per page.", "required": false, "type": "integer", "format": "int64", "minimum": 1, "maximum": 100, "default": 20 }, { "name": "includedData", "in": "query", "description": "A comma-delimited list of datasets to include in the response.", "required": false, "type": "array", "items": { "type": "string", "enum": [ "ISSUES" ] }, "collectionFormat": "csv", "x-example": "ISSUES", "x-docgen-enum-table-extension": [ { "value": "ISSUES", "description": "Include item level issues and warnings in the response. If not specified, the 'issues' field will be omitted from the response even if issues exist for the item." } ] } ], "responses": { "200": { "description": "Successfully retrieved the item selection for the promotion.", "headers": { "x-amzn-RequestId": { "description": "Unique request reference identifier.", "type": "string" }, "x-amzn-RateLimit-Limit": { "description": "Your rate limit (requests per second) for this operation.", "type": "string" } }, "schema": { "$ref": "#/definitions/GetSelectionResponse" }, "x-amzn-api-sandbox": { "static": [ { "request": { "parameters": { "promotionId": { "value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "selectionId": { "value": "b1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "revisionId": { "value": 1 }, "locale": { "value": "en_US" }, "limit": { "value": 1 }, "includedData": { "value": [ "ISSUES" ] } } }, "response": { "selection": { "selectionId": "b1b2c3d4-e5f6-7890-abcd-ef1234567890", "revisionId": 1, "type": "ITEMS", "selectionDetails": { "items": [ { "asin": "B08N5WRWNW", "benefit": { "type": "DISCOUNTED_PRICE", "discount": { "type": "PERCENTAGE_OFF", "percentOff": 15 } } } ], "issues": [ { "code": "PRODUCT_NOT_AVAILABLE", "message": "PRODUCT_NOT_AVAILABLE", "severity": "ERROR", "identifier": { "asin": "B08N5WRWNW" } } ], "pagination": { "nextToken": "eyJwYWdlIjoyLCJsaW1pdCI6MjB9" } } } } }, { "request": { "parameters": { "promotionId": { "value": "a1b2c3d4-e5f6-7890-abcd-ef1234567891" }, "selectionId": { "value": "b1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "revisionId": { "value": 1 }, "paginationToken": { "value": "eyJwYWdlIjoyLCJsaW1pdCI6MjB9" }, "limit": { "value": 20 }, "includedData": { "value": [ "ISSUES" ] } } }, "response": { "selection": { "selectionId": "b1b2c3d4-e5f6-7890-abcd-ef1234567890", "revisionId": 1, "type": "ITEMS", "selectionDetails": { "items": [ { "asin": "B07XJ8C8F5", "benefit": { "type": "FIXED_PRICE", "price": { "amount": 24.99, "currencyCode": "USD" }, "discount": { "type": "AMOUNT_OFF", "amountOff": 5, "currencyCode": "USD" } } } ], "issues": [] } } } }, { "request": { "parameters": { "promotionId": { "value": "a1b2c3d4-e5f6-7890-abcd-ef1234567892" }, "selectionId": { "value": "b1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "revisionId": { "value": 1 }, "locale": { "value": "en_US" }, "limit": { "value": 2 }, "includedData": { "value": [ "ISSUES" ] } } }, "response": { "selection": { "selectionId": "b1b2c3d4-e5f6-7890-abcd-ef1234567890", "revisionId": 1, "type": "CATALOG", "selectionDetails": { "rules": { "excludedItems": [ { "asin": "B08N5WRWNW" }, { "asin": "B07XJ8C8F5" } ] }, "issues": [], "pagination": { "nextToken": "eyJwYWdlIjoyLCJsaW1pdCI6NTB9" } } } } } ] } }, "400": { "description": "Request has missing or invalid parameters and cannot be parsed.", "headers": { "x-amzn-RateLimit-Limit": { "type": "string", "description": "Your rate limit (requests per second) for this operation." }, "x-amzn-RequestId": { "type": "string", "description": "Unique request reference identifier." } }, "schema": { "$ref": "#/definitions/ErrorList" }, "x-amzn-api-sandbox": { "static": [ { "request": { "parameters": { "promotionId": { "value": "invalid-id" }, "selectionId": { "value": "sel-12345" } } }, "response": { "errors": [ { "code": "INVALID_VALUE", "message": "The request contains invalid parameters.", "details": "Invalid promotion ID format." } ] } }, { "request": { "parameters": { "promotionId": { "value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "selectionId": { "value": "invalid-selection-id" } } }, "response": { "errors": [ { "code": "INVALID_VALUE", "message": "The request contains invalid parameters.", "details": "Invalid selection ID format." } ] } }, { "request": { "parameters": { "promotionId": { "value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "selectionId": { "value": "a1b2c3d4-e5f6-7890-abcd-abc234567980" }, "paginationToken": { "value": "invalid-token" } } }, "response": { "errors": [ { "code": "INVALID_VALUE", "message": "The request contains invalid parameters.", "details": "Invalid pagination token provided." } ] } } ] } }, "403": { "description": "Indicates that access to the resource is forbidden. Possible reasons include Access Denied, Unauthorized, Expired Token, or Invalid Signature.", "schema": { "$ref": "#/definitions/ErrorList" }, "headers": { "x-amzn-RequestId": { "type": "string", "description": "Unique request reference identifier." } } }, "404": { "description": "The resource specified does not exist.", "headers": { "x-amzn-RateLimit-Limit": { "type": "string", "description": "Your rate limit (requests per second) for this operation." }, "x-amzn-RequestId": { "type": "string", "description": "Unique request reference identifier." } }, "schema": { "$ref": "#/definitions/ErrorList" }, "x-amzn-api-sandbox": { "static": [ { "request": { "parameters": { "promotionId": { "value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "selectionId": { "value": "nonexistent-selection" } } }, "response": { "errors": [ { "code": "NotFound", "message": "The specified selection does not exist.", "details": "Selection ID not found for this promotion." } ] } } ] } }, "413": { "description": "The request size exceeded the maximum accepted size.", "headers": { "x-amzn-RequestId": { "description": "Unique request reference identifier.", "type": "string" } }, "schema": { "$ref": "#/definitions/ErrorList" } }, "415": { "description": "The request payload is in an unsupported format.", "headers": { "x-amzn-RequestId": { "description": "Unique request reference identifier.", "type": "string" } }, "schema": { "$ref": "#/definitions/ErrorList" } }, "429": { "description": "The frequency of requests was greater than allowed.", "schema": { "$ref": "#/definitions/ErrorList" }, "headers": { "x-amzn-RequestId": { "type": "string", "description": "Unique request reference identifier." } } }, "500": { "description": "An unexpected condition occurred that prevented the server from fulfilling the request.", "schema": { "$ref": "#/definitions/ErrorList" }, "headers": { "x-amzn-RequestId": { "type": "string", "description": "Unique request reference identifier." } } }, "503": { "description": "Temporary overloading or maintenance of the server.", "schema": { "$ref": "#/definitions/ErrorList" }, "headers": { "x-amzn-RequestId": { "type": "string", "description": "Unique request reference identifier." } } } } } } }, "definitions": { "Error": { "type": "object", "description": "Error response returned when the request is unsuccessful.", "properties": { "code": { "type": "string", "description": "An error code that identifies the type of error that occurred." }, "message": { "type": "string", "description": "A message that describes the error condition.", "maxLength": 1024 }, "details": { "type": "string", "description": "Additional details that can help the caller understand or fix the issue." }, "itemIdentifier": { "$ref": "#/definitions/ItemIdentifier", "description": "Identifier of the item that this error is associated with. Present only if the error is an item-level error." } }, "required": [ "code", "message" ] }, "ErrorList": { "type": "object", "description": "A list of error responses returned when a request is unsuccessful.", "properties": { "errors": { "type": "array", "description": "List of errors.", "items": { "$ref": "#/definitions/Error" } } }, "required": [ "errors" ] }, "Currency": { "type": "object", "description": "Currency amount with ISO 4217 currency code.", "properties": { "amount": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "description": "Amount value.", "example": 5 }, "currencyCode": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code.", "example": "USD" } }, "required": [ "amount", "currencyCode" ], "example": { "amount": 10, "currencyCode": "USD" } }, "Issue": { "type": "object", "description": "Issue information with code, message, and severity.", "properties": { "code": { "type": "string", "description": "Issue code identifier.", "example": "INVALID_INPUT" }, "message": { "type": "string", "description": "Issue description.", "example": "The provided input is invalid.", "maxLength": 1024 }, "severity": { "description": "Issue severity level.", "type": "string", "enum": [ "ERROR", "WARNING" ], "example": "ERROR", "x-docgen-enum-table-extension": [ { "value": "ERROR", "description": "Indicates a critical issue that must be resolved." }, { "value": "WARNING", "description": "Indicates a non-critical issue that should be reviewed." } ] } }, "required": [ "code", "message", "severity" ], "example": { "code": "INVALID_INPUT", "message": "The provided input is invalid.", "severity": "ERROR" } }, "ItemIdentifier": { "type": "object", "description": "The key identifiers of an item.", "properties": { "asin": { "type": "string", "description": "Amazon Standard Identification Number (ASIN).", "example": "B08N5WRWNW" }, "sku": { "type": "string", "description": "Stock Keeping Unit (SKU).", "example": "MY-SKU-12345" } }, "example": { "asin": "B08N5WRWNW" } }, "PromotionIssue": { "description": "A promotion-level validation issue.", "allOf": [ { "$ref": "#/definitions/Issue" } ] }, "ItemIssue": { "description": "An item-level validation issue.", "allOf": [ { "$ref": "#/definitions/Issue" }, { "type": "object", "properties": { "identifier": { "$ref": "#/definitions/ItemIdentifier", "description": "Identifier of the item associated with this issue." } }, "required": [ "identifier" ] } ] }, "Item": { "type": "object", "description": "An item in the Amazon catalog for promotion selection.", "properties": { "asin": { "type": "string", "description": "The Amazon Standard Identification Number (ASIN) is the unique identifier for an item in the Amazon catalog.", "example": "B08N5WRWNW" }, "sku": { "type": "string", "description": "The Stock Keeping Unit (SKU).", "example": "MY-SKU-12345" }, "benefit": { "$ref": "#/definitions/ItemBenefit", "description": "Item-level benefit configuration. This only applies to `DEAL` and `PRICE_DISCOUNT` promotion types." }, "budget": { "$ref": "#/definitions/Budget", "description": "Item-level budget configuration. This only applies to `DEAL` and `PRICE_DISCOUNT` promotion types." } } }, "Selection": { "type": "object", "description": "Defines which products qualify for a benefit, allowing either specific items to be selected by ASIN or the entire catalog with optional exclusions.", "properties": { "selectionId": { "type": "string", "description": "The unique identifier for this selection configuration. **Note:** This field is absent when `type` is `CATALOG`.", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "revisionId": { "type": "integer", "minimum": 1, "description": "The revision identifier for the selection. Pass this value to the `getSelection` operation's `revisionId` query parameter to retrieve the correct version of the selection. A promotion may have multiple selection revisions when an update is in progress. **Note:** This field is absent when `type` is `CATALOG`." }, "type": { "type": "string", "enum": [ "CATALOG", "ITEMS" ], "description": "Selection type.", "example": "ITEMS", "x-docgen-enum-table-extension": [ { "value": "CATALOG", "description": "Select all items in the catalog with optional exclusions." }, { "value": "ITEMS", "description": "Select specific items by ASIN or SKU." } ] }, "selectionDetails": { "$ref": "#/definitions/SelectionDetails", "description": "Detailed selection information." } }, "required": [ "type" ], "example": { "selectionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "revisionId": 1, "type": "ITEMS", "selectionDetails": { "items": [ { "asin": "B08N5WRWNW", "benefit": { "type": "DISCOUNTED_PRICE", "discount": { "type": "PERCENTAGE_OFF", "percentOff": 15 } } }, { "asin": "B07XJ8C8F5" } ] } } }, "SelectionDetails": { "type": "object", "description": "Detailed selection information including items, rules, issues, and pagination.", "properties": { "rules": { "$ref": "#/definitions/SelectionRules", "description": "Rule configuration for catalog-based selections. Only valid when `type` is `CATALOG`." }, "issues": { "type": "array", "items": { "$ref": "#/definitions/ItemIssue" }, "description": "Item-level validation issues for items in this selection. Only present when `ISSUES` is included in the `includedData` query parameter.", "example": [ { "code": "INVALID_SKU", "message": "The SKU provided is not valid", "severity": "ERROR", "identifier": { "sku": "MY-SKU-12345" } } ] }, "items": { "type": "array", "items": { "$ref": "#/definitions/Item" }, "maxItems": 100, "description": "List of specific items to include. Only valid when `type` is `ITEMS` (maximum 100 items).", "example": [ { "asin": "B08N5WRWNW", "benefit": { "type": "DISCOUNTED_PRICE", "discount": { "type": "PERCENTAGE_OFF", "percentOff": 15 }, "perCustomerUses": 3 }, "budget": { "type": "AMOUNT", "value": 500, "currencyCode": "USD" } }, { "asin": "B07XJ8C8F5", "benefit": { "type": "FIXED_PRICE", "price": { "amount": 24.99, "currencyCode": "USD" }, "discount": { "type": "AMOUNT_OFF", "amountOff": 10, "currencyCode": "USD" }, "perCustomerUses": 5 }, "budget": { "type": "UNITS", "value": 100 } } ] }, "pagination": { "$ref": "#/definitions/Pagination", "description": "Pagination metadata for navigating through pages of selection items." } } }, "SelectionRules": { "type": "object", "description": "Rules for catalog-based selections.", "properties": { "excludedItems": { "type": "array", "items": { "$ref": "#/definitions/Item" }, "maxItems": 100, "description": "Items to exclude from the catalog selection (maximum 100 items).", "example": [ { "asin": "B08N5WRWNW" }, { "asin": "B07XJ8C8F5" } ] } }, "example": { "excludedItems": [ { "asin": "B08N5WRWNW" } ] } }, "Schedule": { "type": "object", "description": "A promotion's start and end dates with optional event association.", "properties": { "startDate": { "type": "string", "format": "date-time", "description": "The promotion's start date and time. Formatted in ISO 8601 format, including the timezone. For example: `1970-01-01T00:00:00-07:00`." }, "endDate": { "type": "string", "format": "date-time", "description": "The promotion's end date and time. Formatted in ISO 8601 format, including the timezone. For example: `1970-01-01T00:00:00-07:00`." }, "eventId": { "type": "string", "description": "An event identifier that associates the promotion with a specific event. For event promotions, this field contains the event name when available (for example, `Prime Day`). For historic event promotions, this field may contain `EVENT` as a placeholder.", "example": "Prime Day" } } }, "Budget": { "type": "object", "description": "Budget configuration for spending limits. For `COUPON` and `BASKET_BUILDING` promotion types, the budget is set at the promotion level and applies to the entire promotion. For `DEAL` and `PRICE_DISCOUNT` promotion types, the budget is set at the item level within each item in the selection.", "properties": { "type": { "description": "The budget type, either monetary or unit-based.", "type": "string", "enum": [ "AMOUNT", "UNITS" ], "x-docgen-enum-table-extension": [ { "value": "AMOUNT", "description": "Budget specified as a monetary amount." }, { "value": "UNITS", "description": "Budget specified as a number of units." } ] }, "value": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "description": "Budget value (amount or unit count)." }, "currencyCode": { "type": "string", "description": "The currency code in ISO 4217 format. Required when `type` is `AMOUNT`.", "minLength": 3, "maxLength": 3 } }, "required": [ "type", "value" ] }, "CustomerSegment": { "type": "object", "description": "The customer segment. When `segmentType` is `BRAND`, `segmentId` contains the segment / audience ID and `segmentDetails.brandSegmentDetails` must be provided. When `segmentType` is `PROGRAM`, `segmentId` contains the program name (for example, `PRIME_EXCLUSIVE`, `MOM`, `STUDENT`).", "properties": { "segmentType": { "description": "Top-level segment type.", "$ref": "#/definitions/CustomerSegmentType" }, "segmentId": { "type": "string", "description": "The segment identifier. For `BRAND`: the segment / audience ID. For `PROGRAM`: the program name (for example, `PRIME_EXCLUSIVE`, `MOM`, `STUDENT` etc)." }, "segmentDetails": { "description": "Additional segment-specific details. Required for `BRAND` segments type.", "$ref": "#/definitions/CustomerSegmentDetails" } }, "required": [ "segmentType", "segmentId" ] }, "CustomerSegmentType": { "type": "string", "description": "The segment type for targeting specific customer cohorts.", "enum": [ "BRAND", "PROGRAM" ], "x-docgen-enum-table-extension": [ { "value": "BRAND", "description": "Brand-tailored audience that targets customers interested in specific brands." }, { "value": "PROGRAM", "description": "Program-based audience that targets specific customer programs such as Prime, Reorder, and Save." } ] }, "CustomerSegmentDetails": { "type": "object", "description": "Additional segment type-specific details. Use the appropriate property based on `segmentType`.", "properties": { "brandSegmentDetails": { "description": "Brand segment details. This field is required when `segmentType` is `BRAND`.", "$ref": "#/definitions/BrandSegmentDetails" } } }, "BrandSegmentDetails": { "type": "object", "description": "Additional details specific to the `BRAND` segments type.", "properties": { "brandId": { "type": "string", "description": "Brand identifier." } }, "required": [ "brandId" ] }, "Discount": { "type": "object", "description": "The discount configuration shared across benefit types.", "properties": { "type": { "description": "The method used to calculate the discount amount.", "type": "string", "enum": [ "PERCENTAGE_OFF", "AMOUNT_OFF", "FREE_ITEM" ], "x-docgen-enum-table-extension": [ { "value": "PERCENTAGE_OFF", "description": "The discount is applied as a percentage off the original price." }, { "value": "AMOUNT_OFF", "description": "The discount is applied as a fixed amount off the original price." }, { "value": "FREE_ITEM", "description": "The item is provided free of charge. Only applicable to the `BASKET_BUILDING` promotion type." } ] }, "percentOff": { "type": "number", "minimum": 1, "maximum": 100, "description": "The percentage discount value (1-100). Only valid when `type` is `PERCENTAGE_OFF`." }, "amountOff": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "description": "The amount off value. Only valid when `type` is `AMOUNT_OFF`.", "example": 5 }, "currencyCode": { "type": "string", "minLength": 3, "maxLength": 3, "description": "The currency code in ISO 4217 format. Required when `type` is `AMOUNT_OFF`.", "example": "USD" } }, "required": [ "type" ] }, "QuantityThreshold": { "type": "object", "description": "Quantity-based purchase conditions for basket building promotions.", "properties": { "type": { "type": "string", "enum": [ "AT_LEAST", "FOR_EACH" ], "description": "How the quantity requirement is evaluated.", "x-docgen-enum-table-extension": [ { "value": "AT_LEAST", "description": "The customer must purchase at least the specified quantity of items." }, { "value": "FOR_EACH", "description": "The benefit applies for every group of specified quantity purchased. For example, for every two items." } ] }, "quantity": { "type": "integer", "minimum": 1, "description": "The number of items required to meet this purchase condition.", "example": 2 } }, "required": [ "type", "quantity" ], "example": { "type": "AT_LEAST", "quantity": 2 } }, "AmountThreshold": { "type": "object", "description": "Amount-based purchase conditions for basket building promotions. Customers must spend a minimum dollar amount.", "properties": { "type": { "type": "string", "enum": [ "AT_LEAST" ], "description": "The type of amount requirement. Only `AT_LEAST` is supported for spend-based conditions.", "x-docgen-enum-table-extension": [ { "value": "AT_LEAST", "description": "The customer must spend at least the specified dollar amount." } ] }, "currency": { "$ref": "#/definitions/Currency", "description": "The minimum spend amount customers must meet." } }, "required": [ "type", "currency" ], "example": { "type": "AT_LEAST", "currency": { "amount": 50, "currencyCode": "USD" } } }, "PurchaseCondition": { "type": "object", "description": "Minimum purchase requirements using quantity-based or amount-based conditions for basket building promotions. You can specify conditions within purchase requirements and multi-tier benefit configurations. You must specify exactly one of `quantityThreshold` or `amountThreshold`.", "properties": { "quantityThreshold": { "$ref": "#/definitions/QuantityThreshold", "description": "Quantity-based purchase requirement. Specify this for item count conditions." }, "amountThreshold": { "$ref": "#/definitions/AmountThreshold", "description": "Amount-based purchase requirement. Specify this for minimum spend conditions." } }, "example": { "amountThreshold": { "type": "AT_LEAST", "currency": { "amount": 50, "currencyCode": "USD" } } } }, "PurchaseRequirements": { "type": "object", "description": "Purchase requirements that customers must meet to qualify for a basket building promotion. Contains eligibility selection (what to buy), purchase condition (how much to buy), and an optional claim code. This is the 'Buy X' portion of 'Buy X Get Y' promotions.", "properties": { "selection": { "$ref": "#/definitions/Selection", "description": "Which items customers must purchase to qualify for the promotion. References the eligibility product set. This selection only contains `selectionId`, `revisionId`, and `type`; the `selectionDetails` field is not included. For some `BASKET_BUILDING` promotions, this selection may be the same as the benefit selection when purchase requirements and benefits apply to the same set of items." }, "condition": { "$ref": "#/definitions/PurchaseCondition", "description": "Minimum purchase requirement that specify either the quantity of items or the total spend amount that customers must meet to qualify. For multi-tier `BASKET_BUILDING` promotions, this is the first-tier purchase condition. Additional tier conditions are defined in `benefit.additionalTiers`." }, "claimCode": { "$ref": "#/definitions/ClaimCode", "description": "An optional claim code customers must enter to access the promotion. When present, the promotion is code-gated and only available to customers who provide this code." } }, "required": [ "selection", "condition" ], "example": { "selection": { "selectionId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "revisionId": 1, "type": "ITEMS" }, "condition": { "quantityThreshold": { "type": "AT_LEAST", "quantity": 2 } }, "claimCode": { "type": "GROUP", "value": "SAVE20" } } }, "ClaimCode": { "type": "object", "description": "Claim code configuration for accessing the promotion.", "properties": { "type": { "type": "string", "enum": [ "GROUP", "INDIVIDUAL" ], "description": "The type of claim code.", "example": "GROUP", "x-docgen-enum-table-extension": [ { "value": "GROUP", "description": "A 6-12 digit claim-code that can be used by multiple customers to redeem the promotion." }, { "value": "INDIVIDUAL", "description": "Individual claim codes that are unique per customer. This is a placeholder value indicating the promotion contains individual claim codes. **Note:** The actual code value is not available through this API." } ] }, "value": { "type": "string", "minLength": 6, "maxLength": 12, "pattern": "^[0-9A-Z]+$", "description": "The claim code (6-12 alphanumeric uppercase). Required when `type` is `GROUP`.", "example": "SAVE20" } }, "required": [ "type" ], "example": { "type": "GROUP", "value": "SAVE20" } }, "BenefitTier": { "type": "object", "description": "Defines a progressive (multi-tier) benefit tier that applies when customers exceed a higher purchase quantity for basket building promotions. Each tier specifies a purchase condition and corresponding enhanced discount.", "properties": { "purchaseCondition": { "$ref": "#/definitions/PurchaseCondition", "description": "The purchase condition that must be met to receive this tier's enhanced discount." }, "discount": { "$ref": "#/definitions/Discount", "description": "The discount configuration for this tier." } }, "required": [ "purchaseCondition", "discount" ], "example": { "purchaseCondition": { "quantityThreshold": { "type": "AT_LEAST", "quantity": 3 } }, "discount": { "type": "PERCENTAGE_OFF", "percentOff": 20 } } }, "Merchandising": { "type": "object", "description": "The merchandising configuration for displaying promotions on the retail website.", "properties": { "displayOnWebsite": { "type": "string", "enum": [ "ALLOWED", "NOT_ALLOWED" ], "description": "Whether the promotion badge and details are displayed on the product detail pages and search results on the retail website.", "x-docgen-enum-table-extension": [ { "value": "ALLOWED", "description": "The promotion is displayed on the retail website." }, { "value": "NOT_ALLOWED", "description": "The promotion is not displayed on the retail website." } ] } }, "example": { "displayOnWebsite": "ALLOWED" } }, "ItemBenefit": { "type": "object", "description": "Item-level benefit configuration with pricing options. Applicable to `DEAL` and `PRICE_DISCOUNT` promotion types, where each item can have its own distinct benefit. For `COUPON` and `BASKET_BUILDING` promotion types, benefits are configured at the promotion level.", "properties": { "type": { "type": "string", "enum": [ "FIXED_PRICE", "DISCOUNTED_PRICE" ], "description": "The benefit type for item-level pricing.", "example": "DISCOUNTED_PRICE", "x-docgen-enum-table-extension": [ { "value": "FIXED_PRICE", "description": "The item is offered at a fixed price." }, { "value": "DISCOUNTED_PRICE", "description": "The item is offered at a discounted price based on discount configuration." } ] }, "price": { "$ref": "#/definitions/Currency", "description": "Fixed price." }, "discount": { "$ref": "#/definitions/Discount", "description": "The discount configuration when using `DISCOUNTED_PRICE` type." }, "perCustomerUses": { "type": "integer", "minimum": 1, "description": "The maximum number of uses per customer for this item benefit.", "example": 5 } }, "required": [ "type" ], "example": { "type": "DISCOUNTED_PRICE", "discount": { "type": "PERCENTAGE_OFF", "percentOff": 15 }, "perCustomerUses": 5 } }, "PromotionBenefit": { "type": "object", "description": "Promotion-level benefit configuration. Applicable to `COUPON` and `BASKET_BUILDING` promotion types, where the benefit applies uniformly across all items in the promotion. For `DEAL` and `PRICE_DISCOUNT` promotion types, benefits are configured at the item level within each item in the selection.", "properties": { "discount": { "$ref": "#/definitions/Discount", "description": "The discount configuration for the promotion. For multi-tier `BASKET_BUILDING` promotions, this represents the first tier discount. Additional tier discounts are defined in `additionalTiers`." }, "benefitQuantity": { "type": "integer", "description": "The quantity of items from the benefit selection that receive the discount after the customer satisfies purchase conditions. This property is specific to `BASKET_BUILDING` promotions.", "example": 1 }, "perCustomerUses": { "type": "integer", "minimum": 1, "description": "The maximum number of uses per customer for this promotion.", "example": 5 }, "stacking": { "type": "string", "enum": [ "ALLOWED", "NOT_ALLOWED" ], "description": "Whether this benefit can be stacked with other promotions.", "example": "ALLOWED" }, "additionalTiers": { "type": "array", "items": { "$ref": "#/definitions/BenefitTier" }, "maxItems": 9, "description": "Progressive discount tiers offering increased benefits as customers purchase more. For example: buy 2 get 10% off, buy 3 get 15% off. For multi-tier `BASKET_BUILDING` promotions, each tier specifies additional purchase conditions and corresponding discounts beyond the first tier (defined in `benefit.discount` and `purchaseRequirements.condition`).", "example": [ { "purchaseCondition": { "quantityThreshold": { "type": "AT_LEAST", "quantity": 3 } }, "discount": { "type": "PERCENTAGE_OFF", "percentOff": 20 } }, { "purchaseCondition": { "quantityThreshold": { "type": "AT_LEAST", "quantity": 5 } }, "discount": { "type": "PERCENTAGE_OFF", "percentOff": 25 } } ] } } }, "PromotionType": { "type": "string", "description": "The type of promotion, categorized by the discount rules and eligibility criteria.", "enum": [ "BASKET_BUILDING", "DEAL", "PRICE_DISCOUNT", "COUPON" ], "x-docgen-enum-table-extension": [ { "value": "BASKET_BUILDING", "description": "Basket building promotions allow customers to receive a discount on a product by performing another action, usually purchasing a product." }, { "value": "DEAL", "description": "A general discount promotion applied to eligible items." }, { "value": "PRICE_DISCOUNT", "description": "A price discount promotion that offers reduced prices on eligible items." }, { "value": "COUPON", "description": "A coupon-based promotion that requires a shopper action for redemption." } ] }, "CouponType": { "type": "string", "default": "STANDARD", "enum": [ "STANDARD", "SUBSCRIBE_AND_SAVE", "REORDER_REWARDS" ], "example": "SUBSCRIBE_AND_SAVE", "description": "The subtype of a `COUPON` promotion. Only applicable when `promotionType` is `COUPON`; not set for other promotion types. When omitted, the coupon is treated as `STANDARD`.", "x-docgen-enum-table-extension": [ { "value": "STANDARD", "description": "A standard coupon that offers a discount on any eligible product." }, { "value": "SUBSCRIBE_AND_SAVE", "description": "A coupon that offers a discount on products enrolled in Subscribe & Save. The discount applies to the first delivery only." }, { "value": "REORDER_REWARDS", "description": "A coupon that offers a discount to customers who previously purchased the product but have not reordered within the expected time." } ] }, "Pagination": { "type": "object", "description": "When a request produces a list that is larger than the page size, pagination occurs. This divides the response into individual pages. To retrieve the next page, pass the `nextToken` as the `paginationToken` query parameter in the subsequent request. When there are no more pages to retrieve, the `Pagination` key will be absent from the response. When a `Pagination` object is present, it contains `nextToken` as non-null value", "properties": { "nextToken": { "description": "A token that can be used to retrieve the next page from the current page of results.", "type": "string" } } }, "PromotionSummary": { "description": "Summary information for a promotion in search results.", "allOf": [ { "$ref": "#/definitions/PromotionRevisionAttributes" }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "PROCESSING", "UPCOMING", "RUNNING", "EXPIRED", "FAILED", "CANCELLING", "CANCELLED" ], "description": "Current promotion status indicating the lifecycle state of the promotion.", "x-docgen-enum-table-extension": [ { "value": "PROCESSING", "description": "The promotion is being processed and validated by the system." }, { "value": "UPCOMING", "description": "The promotion is scheduled and becomes active at the specified start date." }, { "value": "RUNNING", "description": "The promotion is currently active and available to customers." }, { "value": "EXPIRED", "description": "The promotion passed its end date and is no longer active." }, { "value": "FAILED", "description": "The promotion processing or validation has failed and requires attention." }, { "value": "CANCELLING", "description": "The promotion cancellation is in progress." }, { "value": "CANCELLED", "description": "The promotion has been successfully canceled and is no longer active." } ] }, "latestRevision": { "$ref": "#/definitions/LatestRevision", "description": "The latest revision data, when it diverges from the published revision. Present only when an edit is still processing (`revisionStatus: PROCESSING`) or was rejected (`revisionStatus: FAILED`). Absent when the latest revision matches the published revision (stable state)." } }, "required": [ "status" ] } ] }, "SearchPromotionsResponse": { "type": "object", "description": "The response schema for the `searchPromotions` operation. **Note:** The `selectionDetails` field is not present in the selection object within promotion summaries.", "properties": { "totalResults": { "type": "integer", "description": "The total number of promotions matching the search criteria, across all pages. This count remains consistent across paginated requests. **Note:** In rare cases, individual records cannot be returned and are omitted from the response. When this happens, a page may contain fewer items than expected, and the combined number of items across all pages may be less than `totalResults`. The request itself still completes successfully.", "minimum": 0 }, "pagination": { "$ref": "#/definitions/Pagination", "description": "Pagination information for navigating results." }, "promotions": { "type": "array", "items": { "$ref": "#/definitions/PromotionSummary" }, "description": "A list of promotion summaries that matches the search criteria." } }, "required": [ "totalResults", "promotions" ], "example": { "totalResults": 2, "pagination": { "nextToken": "sdlkj234lkj234lksjdflkjwdflkjsfdlkj234234234234" }, "promotions": [ { "promotionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "trackingId": "v2024-a1b2c3d4-e5f6-7890-abcd-ef1234567890", "marketplaceId": "ATVPDKIKX0DER", "status": "RUNNING", "createdDate": "2025-07-01T02:01:08.180Z", "lastUpdatedDate": "2025-07-15T14:30:00.180Z", "promotionTitle": "Summer Sale 2025", "selection": { "selectionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "revisionId": 1, "type": "ITEMS" }, "promotionType": "DEAL", "schedule": { "startDate": "2025-07-01T00:00:00.000Z", "endDate": "2025-08-31T23:59:59.999Z" } } ] } }, "GetPromotionResponse": { "description": "The response schema for `getPromotion`. **Note:** `selectionDetails` are included when `SELECTION` is in the `includedData` request parameter.", "allOf": [ { "$ref": "#/definitions/PromotionRevisionAttributes" }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "PROCESSING", "UPCOMING", "RUNNING", "EXPIRED", "FAILED", "CANCELLING", "CANCELLED" ], "description": "Current promotion status indicating the lifecycle state of the promotion.", "x-docgen-enum-table-extension": [ { "value": "PROCESSING", "description": "The promotion is being processed and validated by the system." }, { "value": "UPCOMING", "description": "The promotion is scheduled and becomes active at the specified start date." }, { "value": "RUNNING", "description": "The promotion is currently active and available to customers." }, { "value": "EXPIRED", "description": "The promotion passed its end date and is no longer active." }, { "value": "FAILED", "description": "The promotion processing or validation has failed and requires attention." }, { "value": "CANCELLING", "description": "The promotion cancellation is in progress." }, { "value": "CANCELLED", "description": "The promotion has been successfully canceled and is no longer active." } ] }, "latestRevision": { "$ref": "#/definitions/LatestRevision", "description": "Contains the latest revision data when it diverges from the published revision. Present only when an edit is still processing (`revisionStatus: PROCESSING`) or was rejected (`revisionStatus: FAILED`). Absent when the latest revision matches the published revision (stable state)." } }, "required": [ "status" ] } ] }, "GetSelectionResponse": { "type": "object", "description": "The response schema for `getSelection`. The `selectionDetails` field is always present when `type` is `ITEMS`.", "properties": { "selection": { "$ref": "#/definitions/Selection" } }, "required": [ "selection" ] }, "PromotionFeeSnapshot": { "type": "object", "description": "The promotion's fee information (rates and incentive programs) that was locked at the time of promotion creation. You can estimate promotion fees (fee preview) at time t1, while promotion creation can happen at time t2. This object includes the fee information captured at time t2. If empty, it means that no fee information was recorded, which indicates that either a promotion type or a marketplace does not currently support promotion fees.", "properties": { "previewedFeeRates": { "$ref": "#/definitions/PreviewedFeeRates" } }, "example": { "previewedFeeRates": { "upfrontFee": { "rate": { "amount": 100, "currencyCode": "USD" }, "frequency": "ONE_TIME" }, "variableFee": { "salesPercentage": 0.05, "feeCapAmount": { "amount": 1000, "currencyCode": "USD" } } } } }, "PreviewedFeeRates": { "type": "object", "description": "Fee rates that were previewed to the selling partner. Example fee rates are `$100` or `5% of sales`.", "properties": { "upfrontFee": { "$ref": "#/definitions/UpfrontFee" }, "variableFee": { "$ref": "#/definitions/VariableFee" } }, "example": { "upfrontFee": { "rate": { "amount": 100, "currencyCode": "USD" }, "frequency": "ONE_TIME" }, "variableFee": { "salesPercentage": 0.05, "feeCapAmount": { "amount": 1000, "currencyCode": "USD" } } } }, "UpfrontFee": { "type": "object", "description": "Upfront fee (or a flat fee) for each promotion submitted.", "properties": { "rate": { "$ref": "#/definitions/Currency" }, "frequency": { "$ref": "#/definitions/FeeFrequency" } }, "required": [ "rate", "frequency" ], "example": { "rate": { "amount": 100, "currencyCode": "USD" }, "frequency": "ONE_TIME" } }, "VariableFee": { "type": "object", "description": "Performance based fee, usually represented as a percentage of promotion sales with a cap amount.", "properties": { "salesPercentage": { "type": "number", "minimum": 0, "maximum": 1, "description": "Sales Percentage", "example": 0.05 }, "feeCapAmount": { "$ref": "#/definitions/Currency" } }, "required": [ "salesPercentage" ], "example": { "salesPercentage": 0.05, "feeCapAmount": { "amount": 1000, "currencyCode": "USD" } } }, "FeeFrequency": { "type": "string", "description": "For participation fees, the frequency at which fees are charged.", "enum": [ "ONE_TIME", "DAILY" ], "x-docgen-enum-table-extension": [ { "value": "ONE_TIME", "description": "One time charge of a participation fee." }, { "value": "DAILY", "description": "Daily charge of a participation fee, example `$50 per day`." } ] }, "LatestRevision": { "description": "The latest revision data, when it diverges from the published revision. Present only when an edit is still processing or was rejected. Mirrors the top-level promotion object structure.", "allOf": [ { "$ref": "#/definitions/PromotionRevisionAttributes" }, { "type": "object", "properties": { "revisionStatus": { "type": "string", "description": "The processing status of the latest revision.", "enum": [ "PROCESSING", "FAILED" ], "x-docgen-enum-table-extension": [ { "value": "PROCESSING", "description": "The latest revision is still being validated and has not yet been published." }, { "value": "FAILED", "description": "The latest revision failed validation and was rejected. The published revision remains live." } ] } }, "required": [ "revisionStatus" ] } ] }, "PromotionRevisionAttributes": { "type": "object", "description": "Common promotion fields shared between the published promotion and the latest revision. Contains all promotion attributes except lifecycle status.", "properties": { "issues": { "type": "array", "items": { "$ref": "#/definitions/PromotionIssue" }, "description": "Promotion-level validation issues found during processing." }, "promotionTitle": { "type": "string", "description": "The name of the promotion for the selling partner. This value is not displayed to buyers." }, "selection": { "$ref": "#/definitions/Selection", "description": "A selection that defines which items in the customer's order qualify for the promotion benefit. The discount or offer is applied to items in this selection. For `BASKET_BUILDING` promotions, this denotes the items that receive the discount after purchase requirements are met. For `DEAL`, `PRICE_DISCOUNT`, and `COUPON` promotions, this denotes the eligible items that receive the benefit." }, "purchaseRequirements": { "$ref": "#/definitions/PurchaseRequirements", "description": "Purchase requirements for `BASKET_BUILDING` promotions." }, "schedule": { "$ref": "#/definitions/Schedule", "description": "The promotion schedule configuration." }, "budget": { "$ref": "#/definitions/Budget", "description": "Promotion-level budget configuration. Applicable to `COUPON` and `BASKET_BUILDING` promotion types. For `DEAL` and `PRICE_DISCOUNT` promotion types, the budget is configured at the item level within the selection." }, "customerSegments": { "type": "array", "items": { "$ref": "#/definitions/CustomerSegment" }, "description": "The target customer segments for the promotion." }, "benefit": { "$ref": "#/definitions/PromotionBenefit", "description": "Promotion-level benefit configuration. Applicable to `COUPON` and `BASKET_BUILDING` promotion types. For `DEAL` and `PRICE_DISCOUNT` promotion types, the benefit is configured at the item level within the selection." }, "merchandising": { "$ref": "#/definitions/Merchandising", "description": "The merchandising configuration that determines promotion display on the retail website." }, "createdDate": { "type": "string", "format": "date-time", "description": "When the promotion was created. Formatted in ISO 8601 format, including the timezone. For example: `1970-01-01T00:00:00-07:00`." }, "lastUpdatedDate": { "type": "string", "format": "date-time", "description": "When the promotion was last updated. Formatted in ISO 8601 format, including the timezone. For example: `1970-01-01T00:00:00-07:00`." }, "feeSnapshot": { "$ref": "#/definitions/PromotionFeeSnapshot" }, "marketplaceId": { "type": "string", "description": "The Amazon store identifier. For a complete list of `marketplaceId` values, refer to [Store Identifiers](https://developer-docs.amazon/sp-api/docs/store-identifiers)." }, "promotionId": { "type": "string", "description": "The unique promotion identifier." }, "promotionType": { "$ref": "#/definitions/PromotionType", "description": "The promotion type." }, "couponType": { "$ref": "#/definitions/CouponType", "description": "The subtype of a COUPON promotion. Only present when `promotionType` is `COUPON`; when omitted, the coupon is treated as `STANDARD`." }, "trackingId": { "type": "string", "description": "The tracking ID you can use to uniquely identify a promotion and track its performance." } }, "required": [ "createdDate", "lastUpdatedDate", "promotionTitle", "schedule", "selection", "marketplaceId", "promotionId", "promotionType", "trackingId" ], "example": { "promotionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "trackingId": "v2024-a1b2c3d4-e5f6-7890-abcd-ef1234567890", "marketplaceId": "ATVPDKIKX0DER", "promotionTitle": "Summer Sale 2025", "promotionType": "BASKET_BUILDING", "schedule": { "startDate": "2025-07-01T00:00:00-07:00", "endDate": "2025-08-31T23:59:59-07:00" }, "budget": { "type": "AMOUNT", "value": 1000, "currencyCode": "USD" }, "benefit": { "discount": { "type": "PERCENTAGE_OFF", "percentOff": 15 }, "benefitQuantity": 1, "perCustomerUses": 5, "stacking": "ALLOWED" }, "selection": { "selectionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "revisionId": 1, "type": "ITEMS" }, "purchaseRequirements": { "selection": { "selectionId": "6ba7b814-9dad-11d1-80b4-00c04fd430c8", "revisionId": 1, "type": "ITEMS" }, "condition": { "quantityThreshold": { "type": "AT_LEAST", "quantity": 2 } } }, "merchandising": { "displayOnWebsite": "ALLOWED" }, "customerSegments": [ { "segmentType": "BRAND", "segmentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "segmentDetails": { "brandSegmentDetails": { "brandId": "XYZV1IB3VIYABC" } } } ], "issues": [ { "code": "HAS_OVERLAPPING_PROMOTIONS", "message": "HAS_OVERLAPPING_PROMOTIONS", "severity": "WARNING" } ], "feeSnapshot": { "previewedFeeRates": { "upfrontFee": { "rate": { "amount": 100, "currencyCode": "USD" }, "frequency": "ONE_TIME" }, "variableFee": { "salesPercentage": 0.05, "feeCapAmount": { "amount": 1000, "currencyCode": "USD" } } } }, "createdDate": "2025-07-01T02:01:08-07:00", "lastUpdatedDate": "2025-07-15T14:30:00-07:00" } } } }