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

Creates a percentage-based discount promotion that automatically applies to specific product items based on customer tags.

\n

Unlike product-wide promotions, this targets individual product items or SKUs with percentage discounts.\nCustomers are automatically qualified based on tags, and discounts apply only to usage of the specified items.

\n

Use this for targeted item promotions like premium feature discounts for enterprise customers,\nnew product launches, or cross-selling campaigns with item-specific percentage incentives.

", "contentType": "application/json", "request": { "pathParameters": [], "headerParameters": [], "queryParameters": [], "bodyDataParameters": [ { "kind": "required", "name": "body", "type": "object", "description": "Promotion configuration with item targeting and percentage discount rates", "customType": "payment.pricing.promotions.pre_created.RelativeProductItemAutomaticPromotion.in", "schema": [ { "name": "id", "kind": "required", "type": "string", "description": "Unique identifier for the relative product item automatic promotion configuration.", "example": "" }, { "name": "type", "kind": "optional", "type": "string", "description": "Fixed promotion type identifier for item-level automatic percentage discounts.", "example": "", "default": "relative_product_item_automatic_promotion" }, { "name": "promotionName", "kind": "required", "type": "string", "description": "Display name for the item-level automatic percentage promotion in billing interfaces.", "example": "" }, { "name": "description", "kind": "optional", "type": "string", "description": "Optional detailed description explaining the promotion's purpose and customer targeting criteria.", "example": "" }, { "name": "lockingStatus", "kind": "optional", "type": "string", "description": "Configuration lock status controlling whether promotion settings can be modified after creation.", "modelRef": "#/components/schemas/common.LockingStatus.in", "customType": "common.LockingStatus.in", "schema": [] }, { "name": "dimensionConstraintMap", "kind": "optional", "type": "map", "description": "Key-value constraints for targeting specific dimension values, supporting regex matching when isRegEx enabled.", "example": "", "customType": "map", "schema": [] }, { "name": "customerTags", "kind": "optional", "type": "map", "description": "Required customer tag key-value pairs that automatically trigger this percentage discount promotion activation.", "example": "", "customType": "map", "schema": [] }, { "name": "isHidden", "kind": "optional", "type": "boolean", "description": "Controls whether this automatic promotion appears in customer-facing billing statements and detailed invoices.", "example": "" }, { "name": "discountRatio", "kind": "optional", "type": "number", "description": "Percentage discount as decimal value applied to qualifying usage charges (0.1 equals 10% discount).", "example": "" }, { "name": "totalMaxDiscount", "kind": "optional", "type": "number", "description": "Optional absolute limit on total discount amount across all billing cycles for cost control.", "example": "" }, { "name": "cycleMaxDiscount", "kind": "optional", "type": "number", "description": "Optional absolute limit on discount amount per individual billing cycle for consistent budget management.", "example": "" }, { "name": "targetProductItemId", "kind": "optional", "type": "string", "description": "Specific product item identifier that this percentage discount promotion will target for usage charges.", "example": "" }, { "name": "isRegEx", "kind": "optional", "type": "boolean", "description": "Enables regular expression pattern matching for dimension constraint values providing flexible targeting rules.", "example": "" } ], "modelRef": "#/components/schemas/payment.pricing.promotions.pre_created.RelativeProductItemAutomaticPromotion.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 automatic percentage-based promotion that applies discounts to specific product item usage charges when customers have matching tags.", "customType": "payment.pricing.promotions.pre_created.RelativeProductItemAutomaticPromotion.out", "schema": [ { "name": "id", "kind": "required", "type": "string", "description": "Unique identifier for the created relative product item automatic promotion configuration.", "example": "" }, { "name": "type", "kind": "optional", "type": "string", "description": "Fixed promotion type identifier for item-level automatic percentage discounts.", "example": "", "default": "relative_product_item_automatic_promotion" }, { "name": "promotionName", "kind": "required", "type": "string", "description": "Display name for the item-level automatic percentage promotion in billing interfaces.", "example": "" }, { "name": "description", "kind": "optional", "type": "string", "description": "Optional detailed description explaining the promotion's purpose and customer targeting criteria.", "example": "" }, { "name": "lockingStatus", "kind": "optional", "type": "string", "description": "Current configuration lock status controlling whether promotion settings 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 promotion configuration was last modified.", "example": 0 }, { "name": "dimensionConstraintMap", "kind": "optional", "type": "map", "description": "Applied key-value constraints for targeting specific dimension values with optional regex matching.", "example": "", "customType": "map", "schema": [] }, { "name": "customerTags", "kind": "optional", "type": "map", "description": "Configured customer tag key-value pairs that automatically trigger this percentage discount promotion.", "example": "", "customType": "map", "schema": [] }, { "name": "isHidden", "kind": "optional", "type": "boolean", "description": "Current visibility setting controlling whether promotion appears in customer billing statements.", "example": "" }, { "name": "discountRatio", "kind": "optional", "type": "number", "description": "Applied percentage discount as decimal value for qualifying usage charges (0.1 equals 10% discount).", "example": "" }, { "name": "totalMaxDiscount", "kind": "optional", "type": "number", "description": "Configured absolute limit on total discount amount across all billing cycles for cost control.", "example": "" }, { "name": "cycleMaxDiscount", "kind": "optional", "type": "number", "description": "Configured absolute limit on discount amount per individual billing cycle for budget management.", "example": "" }, { "name": "targetProductItemId", "kind": "optional", "type": "string", "description": "Specific product item identifier that this percentage discount promotion targets for usage charges.", "example": "" }, { "name": "isRegEx", "kind": "optional", "type": "boolean", "description": "Current setting enabling regular expression pattern matching for dimension constraint values.", "example": "" } ], "modelRef": "#/components/schemas/payment.pricing.promotions.pre_created.RelativeProductItemAutomaticPromotion.out", "isExpanded": true } ] }, { "statusCode": "400", "description": "Bad request - invalid promotion configuration", "jsonExample": "", "isExpanded": true }, { "statusCode": "404", "description": "Product item not found", "jsonExample": "", "isExpanded": true }, { "statusCode": "409", "description": "Conflict with existing promotion", "jsonExample": "", "isExpanded": true } ], "hasXCodeSamples": false, "examples": { "languages": [ { "id": "eznJPKXNX4qnMFN1gOICl", "language": "curl", "label": "cURL", "code": "curl --request POST \\\n --url https://app.amberflo.io/payments/pricing/amberflo/account-pricing/promotions/relative_product_item_automatic_promotion \\\n --header 'accept: application/json' \\\n --header 'content-type: application/json' \\\n --data '{\n \"id\": \"\",\n \"type\": \"relative_product_item_automatic_promotion\",\n \"promotionName\": \"\"\n }'" }, { "id": "WsbMz2gKEyWEQOEA--DmB", "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_item_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_item_automatic_promotion\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));" }, { "id": "ffrfpffZcUsYfmb7BfS_4", "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_item_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_item_automatic_promotion\",\n \"promotionName\": \"\"\n})\n\nresponse = https.request(request)\nputs response.read_body\n" }, { "id": "XpvQzlGN1fwnUrh81EnkW", "language": "python", "label": "Python", "code": "import requests\nimport json\n\nurl = \"https://app.amberflo.io/payments/pricing/amberflo/account-pricing/promotions/relative_product_item_automatic_promotion\"\n\npayload = json.dumps({\n \"id\": \"\",\n \"type\": \"relative_product_item_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": "eznJPKXNX4qnMFN1gOICl" }, "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 \"targetProductItemId\": \"\",\n \"isRegEx\": false\n}" }, { "id": "response-1-400", "language": "400", "code": "// Bad request - invalid promotion configuration\n" }, { "id": "response-2-404", "language": "404", "code": "// Product item not found\n" }, { "id": "response-3-409", "language": "409", "code": "// Conflict with existing promotion\n" } ], "selectedLanguageId": "response-0-200" } }, "children": [ { "text": "" } ] }