{ "openapi": "3.0.0", "info": { "title": "promotions", "description": "MCP tools related to promotions", "version": "v1" }, "paths": { "/mcp/redeem_promotion_code": { "post": { "operationId": "redeem_promotion_code", "description": "Redeem a promotion code for an advertiser account. Creates a promotion code redemption that activates a promotional offer for the specified marketplace. Returns the redemption result including the associated promotion offer. On failure, returns error code: INVALID_PROMOTION_CODE (code does not exist), EXPIRED_PROMOTION_CODE (code has expired), MAXIMUM_REDEMPTIONS_REACHED (max redemptions for account reached), ACCOUNT_NOT_ELIGIBLE (account does not meet eligibility criteria), UNSUPPORTED_MARKETPLACE (marketplace not supported).", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/redeem_promotion_codeInputSchema" } } } }, "tags": [ "promotions" ] } }, "/mcp/query_promotion_offers": { "post": { "operationId": "query_promotion_offers", "description": "Query and list promotion offers available for an advertiser account. Returns promotion details including status, marketplace, promotion campaign info, fulfilment criteria, and reward information. Supports filtering by marketplace and offer status. A promotion offer represents an opportunity to earn a reward by meeting specific criteria. The fulfilment criteria defines what the advertiser must do to earn the reward, such as launching a campaign or spending a certain amount within a time period. The promotion campaign is the marketing initiative associated with the offer.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/query_promotion_offersInputSchema" } } } }, "tags": [ "promotions" ] } }, "/mcp/query_promotion_rewards": { "post": { "operationId": "query_promotion_rewards", "description": "Query and list promotion rewards for an advertiser account. A promotion reward represents financial credit that has been granted to an advertiser and is tracked from issuance to full consumption. Returns reward details including total reward amount, remaining amount, reward type, marketplace, and validity dates. Supports filtering by reward ID, type, marketplace, and start or end date ranges. Optionally returns a per-invoice consumption breakdown showing how the reward has been applied across invoices.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/query_promotion_rewardsInputSchema" } } } }, "tags": [ "promotions" ] } } }, "components": { "schemas": { "redeem_promotion_codeInputSchema": { "type": "object", "properties": { "body": { "type": "object", "properties": { "accessRequestedAccount": { "oneOf": [ { "type": "object", "properties": { "advertiserAccountId": { "type": "string" } }, "required": [ "advertiserAccountId" ] } ] }, "promotionCodeRedemptions": { "type": "array", "maxItems": 5, "minItems": 1, "items": { "type": "object", "properties": { "promotionCodeId": { "type": "string", "description": "The promotion code to redeem" }, "marketplace": { "type": "string", "description": "The marketplace where the promotion code should be redeemed", "enum": [ "AE", "AU", "BE", "BR", "CA", "CL", "CO", "DE", "EG", "ES", "FR", "GB", "IE", "IN", "IT", "JP", "MX", "NG", "NL", "PL", "SA", "SE", "SG", "TR", "US", "ZA" ] } }, "required": [ "promotionCodeId", "marketplace" ] } } }, "required": [ "accessRequestedAccount", "promotionCodeRedemptions" ] } }, "required": [ "body" ] }, "query_promotion_offersInputSchema": { "type": "object", "properties": { "body": { "type": "object", "properties": { "accessRequestedAccount": { "oneOf": [ { "type": "object", "properties": { "advertiserAccountId": { "type": "string" } }, "required": [ "advertiserAccountId" ] } ] }, "marketplaceFilter": { "type": "object", "description": "Filter results by marketplace country codes", "properties": { "include": { "type": "array", "maxItems": 30, "minItems": 1, "items": { "type": "string", "enum": [ "AE", "AU", "BE", "BR", "CA", "CL", "CO", "DE", "EG", "ES", "FR", "GB", "IE", "IN", "IT", "JP", "MX", "NG", "NL", "PL", "SA", "SE", "SG", "TR", "US", "ZA" ] } } }, "required": [ "include" ] }, "statusFilter": { "type": "object", "description": "Filter results by promotion offer status. AVAILABLE: offer is active and the advertiser has not yet started fulfilling the criteria. IN_PROGRESS: the advertiser has begun working toward the fulfilment criteria but has not yet completed them. REWARDED: fulfilment criteria met and the reward has been applied to the account. MISSED: the offer expired before the advertiser met the fulfilment criteria.", "properties": { "include": { "type": "array", "maxItems": 4, "minItems": 1, "items": { "type": "string", "enum": [ "AVAILABLE", "IN_PROGRESS", "REWARDED", "MISSED" ] } } }, "required": [ "include" ] }, "maxResults": { "type": "integer", "default": 100, "maximum": 100, "minimum": 1, "description": "Maximum number of promotion offers to return (1-100, default 100)" }, "nextToken": { "type": "string", "description": "Pagination token from a previous response to retrieve the next page of results" } }, "required": [ "accessRequestedAccount" ] } }, "required": [ "body" ] }, "query_promotion_rewardsInputSchema": { "type": "object", "properties": { "body": { "type": "object", "properties": { "accessRequestedAccount": { "oneOf": [ { "type": "object", "properties": { "advertiserAccountId": { "type": "string" } }, "required": [ "advertiserAccountId" ] } ] }, "promotionRewardIdFilter": { "type": "object", "description": "Filter by specific promotion reward IDs. Accepts up to 10 IDs", "properties": { "include": { "type": "array", "maxItems": 10, "minItems": 1, "items": { "type": "string" } } }, "required": [ "include" ] }, "promotionRewardTypeFilter": { "type": "object", "description": "Filter by reward type. ADHOC: one-off reward granted for specific business reasons. SIGNUP: reward granted when an advertiser signs up for an advertising program. PROMO_CODE: reward granted when an advertiser redeems a promotion code", "properties": { "include": { "type": "array", "maxItems": 3, "minItems": 1, "items": { "type": "string", "enum": [ "ADHOC", "SIGNUP", "PROMO_CODE" ] } } }, "required": [ "include" ] }, "marketplaceFilter": { "type": "object", "description": "Filter by marketplace country codes. Accepts up to 28 marketplaces", "properties": { "include": { "type": "array", "maxItems": 28, "minItems": 1, "items": { "type": "string", "enum": [ "AE", "AU", "BE", "BR", "CA", "CL", "CO", "DE", "EG", "ES", "FR", "GB", "IE", "IN", "IT", "JP", "MX", "NG", "NL", "PL", "SA", "SE", "SG", "TR", "US", "ZA" ] } } }, "required": [ "include" ] }, "startDateTimeFilter": { "type": "object", "description": "Filter by reward start date. Accepts one value for an exact date match, or two values (from, to) for an inclusive range. ISO 8601 date-time", "properties": { "include": { "type": "array", "maxItems": 2, "minItems": 1, "items": { "type": "string", "format": "date-time" } } }, "required": [ "include" ] }, "endDateTimeFilter": { "type": "object", "description": "Filter by reward end date. Accepts one value for an exact date match, or two values (from, to) for an inclusive range. ISO 8601 date-time", "properties": { "include": { "type": "array", "maxItems": 2, "minItems": 1, "items": { "type": "string", "format": "date-time" } } }, "required": [ "include" ] }, "includePromotionRewardConsumptionFilter": { "type": "object", "description": "When include is [true], the response includes a per-invoice consumption breakdown for each reward. Default excludes consumption details for better performance. Set to true only when the caller needs invoice-level detail", "properties": { "include": { "type": "array", "maxItems": 1, "minItems": 1, "items": { "type": "boolean" } } }, "required": [ "include" ] }, "maxResults": { "type": "integer", "default": 25, "maximum": 25, "minimum": 1, "description": "Maximum number of promotion rewards to return (1-25, default 25)" }, "nextToken": { "type": "string", "description": "Pagination token from a previous response to retrieve the next page of results" } }, "required": [ "accessRequestedAccount" ] } }, "required": [ "body" ] } } } }