--- title: Create relative product automatic promotion slug: reference/create-relative-product-automatic-promotion docTags: createdAt: 2025-03-18T18:28:02.919Z --- { "id": "SxcteaD8VmtBX4iVlp-lz", "type": "api-oas-v2", "data": { "method": "POST", "url": "https://app.amberflo.io/payments/pricing/amberflo/account-pricing/promotions/relative_product_automatic_promotion", "servers": [ { "url": "https://app.amberflo.io/payments/pricing/amberflo/account-pricing/promotions/relative_product_automatic_promotion" } ], "name": "Create relative product automatic promotion", "description": "

Creates a percentage-based discount promotion that automatically applies to entire products based on customer tags.

\n

The promotion uses customer tags (like tier, region, industry) to automatically qualify customers and apply\npercentage discounts to all charges within the targeted product. Discount savings scale with usage - higher\nusage results in greater dollar savings.

\n

Use this for automatic customer segmentation promotions where you want percentage discounts applied\nproduct-wide based on customer attributes like premium tier, geographic region, or industry vertical.

", "contentType": "application/json", "request": { "pathParameters": [], "headerParameters": [], "queryParameters": [], "bodyDataParameters": [ { "kind": "required", "name": "body", "type": "object", "description": "Promotion configuration with customer tag criteria and percentage discount rates", "customType": "payment.pricing.promotions.pre_created.RelativeProductAutomaticPromotion.in", "schema": [ { "name": "id", "kind": "required", "type": "string", "description": "Unique identifier for the relative product automatic promotion instance within your account pricing configuration.", "example": "" }, { "name": "type", "kind": "optional", "type": "string", "description": "Fixed promotion type identifier for automatic percentage-based product-level promotions triggered by customer tag conditions.", "example": "", "default": "relative_product_automatic_promotion" }, { "name": "promotionName", "kind": "required", "type": "string", "description": "Human-readable display name for the automatic percentage product promotion shown in billing interfaces and reports.", "example": "" }, { "name": "description", "kind": "optional", "type": "string", "description": "Optional detailed explanation of the automatic promotion's purpose and customer targeting strategy for internal reference.", "example": "" }, { "name": "lockingStatus", "kind": "optional", "type": "string", "description": "Administrative lock state controlling whether the automatic percentage product promotion can be modified or deleted.", "modelRef": "#/components/schemas/common.LockingStatus.in", "customType": "common.LockingStatus.in", "schema": [] }, { "name": "dimensionConstraintMap", "kind": "optional", "type": "map", "description": "Optional dimension filters restricting when the automatic promotion applies based on usage characteristics, geographic regions, or metadata attributes.", "example": "", "customType": "map", "schema": [] }, { "name": "customerTags", "kind": "optional", "type": "map", "description": "Required key-value pairs that customers must possess for the automatic promotion to activate and apply percentage discounts.", "example": "", "customType": "map", "schema": [] }, { "name": "isHidden", "kind": "optional", "type": "boolean", "description": "Visibility flag controlling whether the automatic percentage promotion appears in customer-facing billing statements and invoice summaries.", "example": "" }, { "name": "discountRatio", "kind": "optional", "type": "number", "description": "Percentage discount ratio automatically applied to product billing totals, expressed as decimal value between 0 and 1.", "example": "" }, { "name": "totalMaxDiscount", "kind": "optional", "type": "number", "description": "Optional maximum cumulative discount amount applicable across all billing cycles for this automatic promotion and customer combination.", "example": "" }, { "name": "cycleMaxDiscount", "kind": "optional", "type": "number", "description": "Optional maximum discount amount that can be applied within a single billing cycle for this automatic promotion.", "example": "" }, { "name": "targetProductId", "kind": "optional", "type": "string", "description": "Specific product identifier that this automatic percentage promotion applies to within your account's pricing structure.", "example": "" } ], "modelRef": "#/components/schemas/payment.pricing.promotions.pre_created.RelativeProductAutomaticPromotion.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": "Response format for successfully created or updated automatic percentage-based product promotions. Returns complete promotion configuration including system timestamps and activation settings for customer tag-triggered discounts that scale proportionally with product usage, supporting volume-based incentives and loyalty programs.", "customType": "payment.pricing.promotions.pre_created.RelativeProductAutomaticPromotion.out", "schema": [ { "name": "id", "kind": "required", "type": "string", "description": "Unique identifier for the relative product automatic promotion instance within your account pricing configuration.", "example": "" }, { "name": "type", "kind": "optional", "type": "string", "description": "Fixed promotion type identifier confirming this is an automatic percentage-based product-level promotion triggered by customer tag conditions.", "example": "", "default": "relative_product_automatic_promotion" }, { "name": "promotionName", "kind": "required", "type": "string", "description": "Human-readable display name for the automatic percentage product promotion shown in billing interfaces and reports.", "example": "" }, { "name": "description", "kind": "optional", "type": "string", "description": "Optional detailed explanation of the automatic promotion's purpose and customer targeting strategy for internal reference.", "example": "" }, { "name": "lockingStatus", "kind": "optional", "type": "string", "description": "Current administrative lock state indicating whether the automatic percentage product promotion can be modified or deleted.", "modelRef": "#/components/schemas/common.LockingStatus.in", "customType": "common.LockingStatus.in", "schema": [] }, { "name": "lastUpdateTimeInMillis", "kind": "optional", "type": "integer", "description": "Unix timestamp in milliseconds when the automatic percentage product promotion was last modified or created.", "example": 0 }, { "name": "dimensionConstraintMap", "kind": "optional", "type": "map", "description": "Active dimension filters restricting when the automatic promotion applies based on usage characteristics, geographic regions, or metadata attributes.", "example": "", "customType": "map", "schema": [] }, { "name": "customerTags", "kind": "optional", "type": "map", "description": "Key-value pairs that customers must possess for the automatic promotion to activate and apply percentage discounts.", "example": "", "customType": "map", "schema": [] }, { "name": "isHidden", "kind": "optional", "type": "boolean", "description": "Visibility setting controlling whether the automatic percentage promotion appears in customer-facing billing statements and invoice summaries.", "example": "" }, { "name": "discountRatio", "kind": "optional", "type": "number", "description": "Percentage discount ratio that will be automatically applied to product billing totals, expressed as decimal value between 0 and 1.", "example": "" }, { "name": "totalMaxDiscount", "kind": "optional", "type": "number", "description": "Maximum cumulative discount amount applicable across all billing cycles for this automatic promotion and customer combination.", "example": "" }, { "name": "cycleMaxDiscount", "kind": "optional", "type": "number", "description": "Maximum discount amount that can be applied within a single billing cycle for this automatic promotion instance.", "example": "" }, { "name": "targetProductId", "kind": "optional", "type": "string", "description": "Specific product identifier that this automatic percentage promotion applies to within your account's pricing structure.", "example": "" } ], "modelRef": "#/components/schemas/payment.pricing.promotions.pre_created.RelativeProductAutomaticPromotion.out", "isExpanded": true } ] }, { "statusCode": "400", "description": "Bad request - invalid promotion configuration", "jsonExample": "", "isExpanded": true }, { "statusCode": "409", "description": "Conflict with existing promotion", "jsonExample": "", "isExpanded": true } ], "hasXCodeSamples": false, "examples": { "languages": [ { "id": "Y-L6AlHjwbMMV3Jn3KUQt", "language": "curl", "label": "cURL", "code": "curl --request POST \\\n --url https://app.amberflo.io/payments/pricing/amberflo/account-pricing/promotions/relative_product_automatic_promotion \\\n --header 'accept: application/json' \\\n --header 'content-type: application/json' \\\n --data '{\n \"id\": \"\",\n \"type\": \"relative_product_automatic_promotion\",\n \"promotionName\": \"\"\n }'" }, { "id": "eRJ2p7VnfFVlJuISFY3Fn", "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_automatic_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_automatic_promotion\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));" }, { "id": "cfYcnuY0BTmRSPk6Rzz7H", "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_automatic_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_automatic_promotion\",\n \"promotionName\": \"\"\n})\n\nresponse = https.request(request)\nputs response.read_body\n" }, { "id": "K7-BOqcdime37eXJd6xZ1", "language": "python", "label": "Python", "code": "import requests\nimport json\n\nurl = \"https://app.amberflo.io/payments/pricing/amberflo/account-pricing/promotions/relative_product_automatic_promotion\"\n\npayload = json.dumps({\n \"id\": \"\",\n \"type\": \"relative_product_automatic_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": "Y-L6AlHjwbMMV3Jn3KUQt" }, "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 \"isHidden\": false,\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-409", "language": "409", "code": "// Conflict with existing promotion\n" } ], "selectedLanguageId": "response-0-200" } }, "children": [ { "text": "" } ] }