---
title: Create time-limited tiered absolute item discount
slug: reference/create-time-limited-tiered-absolute-item-discount
docTags:
createdAt: 2025-03-18T18:28:02.919Z
---
{
"id": "LliygRG-YaEafaeg2pAYl",
"type": "api-oas-v2",
"data": {
"method": "POST",
"url": "https://app.amberflo.io/payments/pricing/amberflo/account-pricing/promotions/time_limited_tiered_absolute_item_discount",
"servers": [
{
"url": "https://app.amberflo.io/payments/pricing/amberflo/account-pricing/promotions/time_limited_tiered_absolute_item_discount"
}
],
"name": "Create time-limited tiered absolute item discount",
"description": "Creates a tiered promotion with escalating fixed-amount discounts for specific product items that automatically expires after a defined time period.
\nThis provides progressively higher fixed dollar amount discounts based on usage tiers, with automatic start and end times.\nCustomers automatically qualify for higher discount tiers as their usage increases during the promotional period.
\nUse this for limited-time volume incentive campaigns, flash sales with usage-based rewards,\nor seasonal promotions where you want escalating fixed-amount discounts that automatically expire.
",
"contentType": "application/json",
"request": {
"pathParameters": [],
"headerParameters": [],
"queryParameters": [],
"bodyDataParameters": [
{
"kind": "required",
"name": "body",
"type": "object",
"description": "Time-limited tiered promotion configuration with item targeting, tier thresholds, escalating discount amounts, and time limits",
"customType": "payment.pricing.promotions.pre_created.TimeLimitedTieredAbsoluteProductItemDiscount.in",
"schema": [
{
"name": "id",
"kind": "required",
"type": "string",
"description": "Unique identifier for the time-limited tiered absolute product item discount promotion configuration.",
"example": ""
},
{
"name": "type",
"kind": "optional",
"type": "string",
"description": "Fixed promotion type identifier for time-limited tiered absolute product item discount promotions.",
"example": "",
"default": "time_limited_tiered_absolute_item_discount"
},
{
"name": "promotionName",
"kind": "required",
"type": "string",
"description": "Display name for the time-limited tiered absolute product item discount promotion in billing interfaces.",
"example": ""
},
{
"name": "description",
"kind": "optional",
"type": "string",
"description": "Optional detailed description explaining the time-limited tiered item discount promotion's purpose and activation schedule.",
"example": ""
},
{
"name": "lockingStatus",
"kind": "optional",
"type": "string",
"description": "Administrative lock status controlling whether the time-limited tiered item promotion settings can be modified.",
"modelRef": "#/components/schemas/common.LockingStatus.in",
"customType": "common.LockingStatus.in",
"schema": []
},
{
"name": "targetProductItemId",
"kind": "optional",
"type": "string",
"description": "Specific product item identifier that this time-limited tiered discount promotion targets for discounting.",
"example": ""
},
{
"name": "promotionTimeLimit",
"kind": "optional",
"type": "object",
"description": "Time constraints defining promotion duration and automatic activation schedule based on history requirements.",
"modelRef": "#/components/schemas/payment.pricing.promotions.attributes.HistoryRequirements.in",
"customType": "payment.pricing.promotions.attributes.HistoryRequirements.in",
"schema": [
{
"name": "cycles",
"kind": "optional",
"type": "integer",
"description": "Minimum number of billing cycles of customer invoice history required for promotion calculations.",
"example": 0
},
{
"name": "months",
"kind": "optional",
"type": "integer",
"description": "Minimum number of months of customer invoice history required for promotion calculations.",
"example": 0
}
]
},
{
"name": "discountMap",
"kind": "optional",
"type": "map",
"description": "Usage threshold map defining fixed discount amounts for each item tier level.",
"example": "",
"customType": "map",
"schema": []
},
{
"name": "totalMaxDiscount",
"kind": "optional",
"type": "number",
"description": "Maximum total discount amount across the entire promotion lifetime for cost control.",
"example": ""
},
{
"name": "measure",
"kind": "optional",
"type": "object",
"description": "Measure for calculating discount thresholds, defaults to TotalPrice when not specified.",
"modelRef": "#/components/schemas/payment.pricing.promotions.attributes.measure.Measure.in",
"customType": "payment.pricing.promotions.attributes.measure.Measure.in",
"schema": [],
"complexType": "oneOf",
"complexItems": [
{
"name": "payment.pricing.promotions.attributes.measure.PerUnitBatch.in",
"description": "",
"modelRef": "#/components/schemas/payment.pricing.promotions.attributes.measure.PerUnitBatch.in",
"schema": [
{
"name": "type",
"kind": "optional",
"type": "string",
"description": "Measure type identifier always set to 'per_batch' for batch-based discount calculations.",
"example": "",
"default": "per_batch"
},
{
"name": "batchSize",
"kind": "optional",
"type": "integer",
"description": "Number of usage units grouped together to form a single discountable batch for promotion calculations.",
"example": 0
}
]
},
{
"name": "payment.pricing.promotions.attributes.measure.PerUnit.in",
"description": "",
"modelRef": "#/components/schemas/payment.pricing.promotions.attributes.measure.PerUnit.in",
"schema": [
{
"name": "type",
"kind": "optional",
"type": "string",
"description": "Measure type identifier always set to 'per_unit' for per-unit discount calculations.",
"example": "",
"default": "per_unit"
}
]
},
{
"name": "payment.pricing.promotions.attributes.measure.TotalPrice.in",
"description": "",
"modelRef": "#/components/schemas/payment.pricing.promotions.attributes.measure.TotalPrice.in",
"schema": [
{
"name": "type",
"kind": "optional",
"type": "string",
"description": "Measure type identifier always set to 'total_price' for total price discount calculations.",
"example": "",
"default": "total_price"
}
]
}
]
},
{
"name": "dimensionConstraintMap",
"kind": "optional",
"type": "map",
"description": "Optional dimension filters restricting when the promotion applies to specific usage characteristics.",
"example": "",
"customType": "map",
"schema": []
},
{
"name": "acrossBillingPeriods",
"kind": "optional",
"type": "boolean",
"description": "Controls whether discount tiers accumulate across billing periods or reset per cycle.",
"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.TimeLimitedTieredAbsoluteProductItemDiscount.in",
"isExpanded": true
}
],
"formDataParameters": [],
"oAuthParameters": [
{
"id": "apiKey",
"name": "X-API-KEY",
"kind": "optional",
"type": "apiKey",
"in": "header"
}
]
},
"responses": [
{
"statusCode": "200",
"description": "Time-limited tiered promotion successfully created",
"jsonExample": "",
"isExpanded": true,
"schema": [
{
"kind": "optional",
"type": "object",
"description": "Created time-limited promotion applying tiered fixed-amount discounts to specific product item charges based on usage thresholds with automatic activation and dimension filtering.",
"customType": "payment.pricing.promotions.pre_created.TimeLimitedTieredAbsoluteProductItemDiscount.out",
"schema": [
{
"name": "id",
"kind": "required",
"type": "string",
"description": "Unique identifier for the created time-limited tiered absolute product item discount promotion configuration.",
"example": ""
},
{
"name": "type",
"kind": "optional",
"type": "string",
"description": "Fixed promotion type identifier confirming time-limited tiered absolute product item discount promotion.",
"example": "",
"default": "time_limited_tiered_absolute_item_discount"
},
{
"name": "promotionName",
"kind": "required",
"type": "string",
"description": "Display name for the created time-limited tiered absolute product item discount promotion in billing interfaces.",
"example": ""
},
{
"name": "description",
"kind": "optional",
"type": "string",
"description": "Optional detailed description explaining the time-limited tiered item discount promotion's purpose and activation schedule.",
"example": ""
},
{
"name": "lockingStatus",
"kind": "optional",
"type": "string",
"description": "Current administrative lock status controlling whether the time-limited tiered item 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 time-limited tiered item promotion was last modified.",
"example": 0
},
{
"name": "targetProductItemId",
"kind": "optional",
"type": "string",
"description": "Specific product item identifier that this time-limited tiered discount promotion targets for discounting.",
"example": ""
},
{
"name": "promotionTimeLimit",
"kind": "optional",
"type": "object",
"description": "Configured time constraints defining promotion duration and automatic activation schedule based on history requirements.",
"modelRef": "#/components/schemas/payment.pricing.promotions.attributes.HistoryRequirements.in",
"customType": "payment.pricing.promotions.attributes.HistoryRequirements.in",
"schema": [
{
"name": "cycles",
"kind": "optional",
"type": "integer",
"description": "Minimum number of billing cycles of customer invoice history required for promotion calculations.",
"example": 0
},
{
"name": "months",
"kind": "optional",
"type": "integer",
"description": "Minimum number of months of customer invoice history required for promotion calculations.",
"example": 0
}
]
},
{
"name": "discountMap",
"kind": "optional",
"type": "map",
"description": "Configured usage threshold map defining fixed discount amounts for each item tier level.",
"example": "",
"customType": "map",
"schema": []
},
{
"name": "totalMaxDiscount",
"kind": "optional",
"type": "number",
"description": "Configured maximum total discount amount across the entire promotion lifetime for cost control.",
"example": ""
},
{
"name": "measure",
"kind": "optional",
"type": "object",
"description": "Applied measure for calculating discount thresholds, defaults to TotalPrice when not specified.",
"modelRef": "#/components/schemas/payment.pricing.promotions.attributes.measure.Measure.out",
"customType": "payment.pricing.promotions.attributes.measure.Measure.out",
"schema": [],
"complexType": "oneOf",
"complexItems": [
{
"name": "payment.pricing.promotions.attributes.measure.PerUnitBatch.in",
"description": "",
"modelRef": "#/components/schemas/payment.pricing.promotions.attributes.measure.PerUnitBatch.in",
"schema": [
{
"name": "type",
"kind": "optional",
"type": "string",
"description": "Measure type identifier always set to 'per_batch' for batch-based discount calculations.",
"example": "",
"default": "per_batch"
},
{
"name": "batchSize",
"kind": "optional",
"type": "integer",
"description": "Number of usage units grouped together to form a single discountable batch for promotion calculations.",
"example": 0
}
]
},
{
"name": "payment.pricing.promotions.attributes.measure.PerUnit.in",
"description": "",
"modelRef": "#/components/schemas/payment.pricing.promotions.attributes.measure.PerUnit.in",
"schema": [
{
"name": "type",
"kind": "optional",
"type": "string",
"description": "Measure type identifier always set to 'per_unit' for per-unit discount calculations.",
"example": "",
"default": "per_unit"
}
]
},
{
"name": "payment.pricing.promotions.attributes.measure.TotalPrice.in",
"description": "",
"modelRef": "#/components/schemas/payment.pricing.promotions.attributes.measure.TotalPrice.in",
"schema": [
{
"name": "type",
"kind": "optional",
"type": "string",
"description": "Measure type identifier always set to 'total_price' for total price discount calculations.",
"example": "",
"default": "total_price"
}
]
}
]
},
{
"name": "dimensionConstraintMap",
"kind": "optional",
"type": "map",
"description": "Applied dimension filters restricting when the promotion applies to specific usage characteristics.",
"example": "",
"customType": "map",
"schema": []
},
{
"name": "acrossBillingPeriods",
"kind": "optional",
"type": "boolean",
"description": "Current setting controlling whether discount tiers accumulate across billing periods or reset per cycle.",
"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.TimeLimitedTieredAbsoluteProductItemDiscount.out",
"isExpanded": true
}
]
},
{
"statusCode": "400",
"description": "Bad request - invalid tier 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": "DzhNdBVtVbhTy4Ubxhb6j",
"language": "curl",
"label": "cURL",
"code": "curl --request POST \\\n --url https://app.amberflo.io/payments/pricing/amberflo/account-pricing/promotions/time_limited_tiered_absolute_item_discount \\\n --header 'accept: application/json' \\\n --header 'content-type: application/json' \\\n --data '{\n \"id\": \"\",\n \"type\": \"time_limited_tiered_absolute_item_discount\",\n \"promotionName\": \"\",\n \"measure\": {\n \"type\": \"per_batch\"\n }\n }'"
},
{
"id": "ztVGT2cvZr3qXGDlE5OS2",
"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\": \"time_limited_tiered_absolute_item_discount\",\n \"promotionName\": \"\",\n \"measure\": {\n \"type\": \"per_batch\"\n }\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/time_limited_tiered_absolute_item_discount\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));"
},
{
"id": "AmjjllCHktzhCr_1vRNGN",
"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/time_limited_tiered_absolute_item_discount\")\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\": \"time_limited_tiered_absolute_item_discount\",\n \"promotionName\": \"\",\n \"measure\": {\n \"type\": \"per_batch\"\n }\n})\n\nresponse = https.request(request)\nputs response.read_body\n"
},
{
"id": "3QHOYhyPErx6rKErYf1K4",
"language": "python",
"label": "Python",
"code": "import requests\nimport json\n\nurl = \"https://app.amberflo.io/payments/pricing/amberflo/account-pricing/promotions/time_limited_tiered_absolute_item_discount\"\n\npayload = json.dumps({\n \"id\": \"\",\n \"type\": \"time_limited_tiered_absolute_item_discount\",\n \"promotionName\": \"\",\n \"measure\": {\n \"type\": \"per_batch\"\n }\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": "DzhNdBVtVbhTy4Ubxhb6j"
},
"results": {
"languages": [
{
"id": "response-0-200",
"language": "200",
"code": "// Time-limited tiered promotion successfully created\n{\n \"id\": \"\",\n \"type\": \"\",\n \"promotionName\": \"\",\n \"description\": \"\",\n \"lockingStatus\": \"\",\n \"lastUpdateTimeInMillis\": \"\",\n \"targetProductItemId\": \"\",\n \"promotionTimeLimit\": {\n \"cycles\": \"\",\n \"months\": \"\"\n },\n \"discountMap\": \"\",\n \"totalMaxDiscount\": 0,\n \"measure\": {},\n \"dimensionConstraintMap\": \"\",\n \"acrossBillingPeriods\": false,\n \"isRegEx\": false\n}"
},
{
"id": "response-1-400",
"language": "400",
"code": "// Bad request - invalid tier 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": ""
}
]
}