---
title: Create relative product sales event promotion
slug: reference/create-relative-product-sales-event-promotion
docTags:
createdAt: 2025-03-18T18:28:02.919Z
---
{
"id": "VzjxKHDA7cPGjiMVepQ5w",
"type": "api-oas-v2",
"data": {
"method": "POST",
"url": "https://app.amberflo.io/payments/pricing/amberflo/account-pricing/promotions/relative_product_sales_event_promotion",
"servers": [
{
"url": "https://app.amberflo.io/payments/pricing/amberflo/account-pricing/promotions/relative_product_sales_event_promotion"
}
],
"name": "Create relative product sales event promotion",
"description": "Creates a percentage-based discount promotion for entire products during sales events or promotional campaigns.
\nThis applies percentage discounts to all charges within the targeted product during specific promotional periods.\nDiscount savings scale with usage - customers with higher product usage receive greater absolute savings during the campaign.
\nUse this for product-wide promotional campaigns like seasonal sales, new customer acquisition campaigns,\nor competitive response promotions where you want comprehensive percentage discounts across the entire product.
",
"contentType": "application/json",
"request": {
"pathParameters": [],
"headerParameters": [],
"queryParameters": [],
"bodyDataParameters": [
{
"kind": "required",
"name": "body",
"type": "object",
"description": "Promotion configuration with campaign details and percentage discount rates",
"customType": "payment.pricing.promotions.pre_created.RelativeProductSalesEventPromotion.in",
"schema": [
{
"name": "id",
"kind": "required",
"type": "string",
"description": "Unique identifier for the relative product sales event promotion configuration.",
"example": ""
},
{
"name": "type",
"kind": "optional",
"type": "string",
"description": "Fixed promotion type identifier for product-level time-limited percentage-based sales event promotions.",
"example": "",
"default": "relative_product_sales_event_promotion"
},
{
"name": "promotionName",
"kind": "required",
"type": "string",
"description": "Display name for the time-limited product sales event promotion in campaign interfaces.",
"example": ""
},
{
"name": "description",
"kind": "optional",
"type": "string",
"description": "Optional explanation of the sales event promotion's purpose and campaign objectives.",
"example": ""
},
{
"name": "lockingStatus",
"kind": "optional",
"type": "string",
"description": "Administrative lock state controlling whether the sales event promotion can be modified.",
"modelRef": "#/components/schemas/common.LockingStatus.in",
"customType": "common.LockingStatus.in",
"schema": []
},
{
"name": "dimensionConstraintMap",
"kind": "optional",
"type": "map",
"description": "Optional dimension filters restricting when product promotion applies during sales events.",
"example": "",
"customType": "map",
"schema": []
},
{
"name": "customerTags",
"kind": "optional",
"type": "map",
"description": "Optional customer tag criteria for targeted promotion activation during sales campaigns.",
"example": "",
"customType": "map",
"schema": []
},
{
"name": "acceptablePromotionTimeRange",
"kind": "optional",
"type": "object",
"description": "Required time boundaries defining when the sales event promotion is active.",
"modelRef": "#/components/schemas/payment.common.TimeRange.in",
"customType": "payment.common.TimeRange.in",
"schema": [
{
"name": "startTimeInSeconds",
"kind": "optional",
"type": "integer",
"description": "Unix timestamp marking the beginning of the time range in seconds",
"example": 0
},
{
"name": "endTimeInSeconds",
"kind": "optional",
"type": "integer",
"description": "Unix timestamp marking the end of time range or null for open-ended ranges",
"example": 0
}
]
},
{
"name": "recurrenceInterval",
"kind": "optional",
"type": "object",
"description": "Optional recurring pattern configuration for repeated sales events and promotional campaigns.",
"modelRef": "#/components/schemas/payment.pricing.promotions.PromotionRecurrenceInterval.in",
"customType": "payment.pricing.promotions.PromotionRecurrenceInterval.in",
"schema": [
{
"name": "intervalLength",
"kind": "optional",
"type": "string",
"description": "Time unit specification for the recurring interval duration such as days, weeks, months, or years.",
"modelRef": "#/components/schemas/payment.pricing.promotions.PromotionRecurringIntervalLength.in",
"customType": "payment.pricing.promotions.PromotionRecurringIntervalLength.in",
"schema": []
},
{
"name": "intervalLengthCount",
"kind": "optional",
"type": "integer",
"description": "Multiplier for the interval length to create expressions like every three months or fifteen days.",
"example": 0
},
{
"name": "maxRecurrence",
"kind": "optional",
"type": "integer",
"description": "Maximum number of recurrence cycles allowed for this promotion before it expires automatically.",
"example": 0
}
]
},
{
"name": "discountRatio",
"kind": "optional",
"type": "number",
"description": "Percentage discount ratio applied to entire product charges, expressed as decimal between 0 and 1.",
"example": ""
},
{
"name": "totalMaxDiscount",
"kind": "optional",
"type": "number",
"description": "Optional maximum cumulative discount amount across all billing cycles during sales events.",
"example": ""
},
{
"name": "cycleMaxDiscount",
"kind": "optional",
"type": "number",
"description": "Optional maximum discount amount per billing cycle during the sales event period.",
"example": ""
},
{
"name": "targetProductId",
"kind": "optional",
"type": "string",
"description": "Required identifier of specific product receiving percentage discounts during sales events.",
"example": ""
}
],
"modelRef": "#/components/schemas/payment.pricing.promotions.pre_created.RelativeProductSalesEventPromotion.in",
"isExpanded": true
}
],
"formDataParameters": [],
"oAuthParameters": [
{
"id": "apiKey",
"name": "X-API-KEY",
"kind": "optional",
"type": "apiKey",
"in": "header"
}
]
},
"responses": [
{
"statusCode": "200",
"description": "Promotion successfully created",
"jsonExample": "",
"isExpanded": true,
"schema": [
{
"kind": "optional",
"type": "object",
"description": "Created time-limited percentage-based promotion for entire products during sales events with optional recurring schedules and customer targeting.",
"customType": "payment.pricing.promotions.pre_created.RelativeProductSalesEventPromotion.out",
"schema": [
{
"name": "id",
"kind": "required",
"type": "string",
"description": "Unique identifier for the created relative product sales event promotion configuration.",
"example": ""
},
{
"name": "type",
"kind": "optional",
"type": "string",
"description": "Fixed promotion type identifier confirming product-level time-limited percentage-based sales event promotion.",
"example": "",
"default": "relative_product_sales_event_promotion"
},
{
"name": "promotionName",
"kind": "required",
"type": "string",
"description": "Display name for the created product sales event promotion in campaign interfaces.",
"example": ""
},
{
"name": "description",
"kind": "optional",
"type": "string",
"description": "Optional explanation of the sales event promotion's purpose and campaign objectives.",
"example": ""
},
{
"name": "lockingStatus",
"kind": "optional",
"type": "string",
"description": "Current administrative lock state controlling whether the sales event promotion can be modified.",
"modelRef": "#/components/schemas/common.LockingStatus.in",
"customType": "common.LockingStatus.in",
"schema": []
},
{
"name": "lastUpdateTimeInMillis",
"kind": "optional",
"type": "integer",
"description": "Unix timestamp in milliseconds when the sales event promotion was last modified.",
"example": 0
},
{
"name": "dimensionConstraintMap",
"kind": "optional",
"type": "map",
"description": "Applied dimension filters restricting when product promotion applies during sales events.",
"example": "",
"customType": "map",
"schema": []
},
{
"name": "customerTags",
"kind": "optional",
"type": "map",
"description": "Configured customer tag criteria for targeted promotion activation during sales campaigns.",
"example": "",
"customType": "map",
"schema": []
},
{
"name": "acceptablePromotionTimeRange",
"kind": "optional",
"type": "object",
"description": "Configured time boundaries defining when the sales event promotion is active.",
"modelRef": "#/components/schemas/payment.common.TimeRange.in",
"customType": "payment.common.TimeRange.in",
"schema": [
{
"name": "startTimeInSeconds",
"kind": "optional",
"type": "integer",
"description": "Unix timestamp marking the beginning of the time range in seconds",
"example": 0
},
{
"name": "endTimeInSeconds",
"kind": "optional",
"type": "integer",
"description": "Unix timestamp marking the end of time range or null for open-ended ranges",
"example": 0
}
]
},
{
"name": "recurrenceInterval",
"kind": "optional",
"type": "object",
"description": "Configured recurring pattern for repeated sales events and promotional campaigns.",
"modelRef": "#/components/schemas/payment.pricing.promotions.PromotionRecurrenceInterval.out",
"customType": "payment.pricing.promotions.PromotionRecurrenceInterval.out",
"schema": [
{
"name": "intervalLength",
"kind": "optional",
"type": "string",
"description": "Time unit specification for the recurring interval duration such as days, weeks, months, or years.",
"modelRef": "#/components/schemas/payment.pricing.promotions.PromotionRecurringIntervalLength.in",
"customType": "payment.pricing.promotions.PromotionRecurringIntervalLength.in",
"schema": []
},
{
"name": "intervalLengthCount",
"kind": "optional",
"type": "integer",
"description": "Multiplier for the interval length to create expressions like every three months or fifteen days.",
"example": 0
},
{
"name": "maxRecurrence",
"kind": "optional",
"type": "integer",
"description": "Maximum number of recurrence cycles allowed for this promotion before it expires automatically.",
"example": 0
}
]
},
{
"name": "discountRatio",
"kind": "optional",
"type": "number",
"description": "Applied percentage discount ratio for entire product charges, expressed as decimal between 0 and 1.",
"example": ""
},
{
"name": "totalMaxDiscount",
"kind": "optional",
"type": "number",
"description": "Configured maximum cumulative discount amount across all billing cycles during sales events.",
"example": ""
},
{
"name": "cycleMaxDiscount",
"kind": "optional",
"type": "number",
"description": "Configured maximum discount amount per billing cycle during the sales event period.",
"example": ""
},
{
"name": "targetProductId",
"kind": "optional",
"type": "string",
"description": "Specific product identifier receiving percentage discounts during the sales events.",
"example": ""
}
],
"modelRef": "#/components/schemas/payment.pricing.promotions.pre_created.RelativeProductSalesEventPromotion.out",
"isExpanded": true
}
]
},
{
"statusCode": "400",
"description": "Bad request - invalid promotion configuration",
"jsonExample": "",
"isExpanded": true
},
{
"statusCode": "404",
"description": "Product not found",
"jsonExample": "",
"isExpanded": true
},
{
"statusCode": "409",
"description": "Conflict with existing promotion",
"jsonExample": "",
"isExpanded": true
}
],
"hasXCodeSamples": false,
"examples": {
"languages": [
{
"id": "vC2a1Op1QBVdoCyP9X3P9",
"language": "curl",
"label": "cURL",
"code": "curl --request POST \\\n --url https://app.amberflo.io/payments/pricing/amberflo/account-pricing/promotions/relative_product_sales_event_promotion \\\n --header 'accept: application/json' \\\n --header 'content-type: application/json' \\\n --data '{\n \"id\": \"\",\n \"type\": \"relative_product_sales_event_promotion\",\n \"promotionName\": \"\"\n }'"
},
{
"id": "rCm3o9W6zJSGrujM9NsNs",
"language": "javascript",
"label": "javascript",
"code": "var myHeaders = new Headers();\nmyHeaders.append(\"accept\", \"application/json\");\nmyHeaders.append(\"content-type\", \"application/json\");\n\nvar raw = JSON.stringify({\n \"id\": \"\",\n \"type\": \"relative_product_sales_event_promotion\",\n \"promotionName\": \"\"\n});\n\nvar requestOptions = {\n method: 'POST',\n headers: myHeaders,\n body: raw,\n redirect: 'follow'\n};\n\nfetch(\"https://app.amberflo.io/payments/pricing/amberflo/account-pricing/promotions/relative_product_sales_event_promotion\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));"
},
{
"id": "D6daQXxE83cxE0j58NNES",
"language": "ruby",
"label": "Ruby",
"code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://app.amberflo.io/payments/pricing/amberflo/account-pricing/promotions/relative_product_sales_event_promotion\")\n\nhttps = Net::HTTP.new(url.host, url.port)\nhttps.use_ssl = true\n\nrequest = Net::HTTP::Post.new(url)\nrequest[\"accept\"] = \"application/json\"\nrequest[\"content-type\"] = \"application/json\"\nrequest.body = JSON.dump({\n \"id\": \"\",\n \"type\": \"relative_product_sales_event_promotion\",\n \"promotionName\": \"\"\n})\n\nresponse = https.request(request)\nputs response.read_body\n"
},
{
"id": "NSB3e2dJ9aeVlig7JPSMd",
"language": "python",
"label": "Python",
"code": "import requests\nimport json\n\nurl = \"https://app.amberflo.io/payments/pricing/amberflo/account-pricing/promotions/relative_product_sales_event_promotion\"\n\npayload = json.dumps({\n \"id\": \"\",\n \"type\": \"relative_product_sales_event_promotion\",\n \"promotionName\": \"\"\n})\nheaders = {\n 'accept': 'application/json',\n 'content-type': 'application/json'\n}\n\nresponse = requests.request(\"POST\", url, headers=headers, data=payload)\n\nprint(response.text)\n"
}
],
"selectedLanguageId": "vC2a1Op1QBVdoCyP9X3P9"
},
"results": {
"languages": [
{
"id": "response-0-200",
"language": "200",
"code": "// Promotion successfully created\n{\n \"id\": \"\",\n \"type\": \"\",\n \"promotionName\": \"\",\n \"description\": \"\",\n \"lockingStatus\": \"\",\n \"lastUpdateTimeInMillis\": \"\",\n \"dimensionConstraintMap\": \"\",\n \"customerTags\": \"\",\n \"acceptablePromotionTimeRange\": {\n \"startTimeInSeconds\": \"\",\n \"endTimeInSeconds\": \"\"\n },\n \"recurrenceInterval\": {\n \"intervalLength\": \"\",\n \"intervalLengthCount\": \"\",\n \"maxRecurrence\": \"\"\n },\n \"discountRatio\": 0,\n \"totalMaxDiscount\": 0,\n \"cycleMaxDiscount\": 0,\n \"targetProductId\": \"\"\n}"
},
{
"id": "response-1-400",
"language": "400",
"code": "// Bad request - invalid promotion configuration\n"
},
{
"id": "response-2-404",
"language": "404",
"code": "// Product not found\n"
},
{
"id": "response-3-409",
"language": "409",
"code": "// Conflict with existing promotion\n"
}
],
"selectedLanguageId": "response-0-200"
}
},
"children": [
{
"text": ""
}
]
}