curl --request POST \
--url https://api.paygentic.io/v0/subscriptions/{id}/adjustments \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"type": "percentageDiscount",
"percentageDiscount": "0.35",
"effectiveFrom": "2026-01-01T00:00:00Z",
"effectiveTo": null,
"description": "FY26 Growth",
"idempotencyKey": "adj_fy26_growth_001"
}
'{
"object": "subscriptionAdjustment",
"id": "<string>",
"subscriptionId": "<string>",
"type": "percentageDiscount",
"percentageDiscount": "<string>",
"usageDiscount": "<string>",
"minimumQuantity": "<string>",
"maximumQuantity": "<string>",
"targetPriceIds": [
"<string>"
],
"effectiveFrom": "2023-11-07T05:31:56Z",
"effectiveTo": "2023-11-07T05:31:56Z",
"description": "<string>",
"createdAt": "2023-11-07T05:31:56Z"
}{
"object": "subscriptionAdjustment",
"id": "subadj_a1b2c3d4e5f6g7h8",
"subscriptionId": "sub_z1a2b3c4d5e6f7g8",
"type": "percentageDiscount",
"percentageDiscount": "0.35",
"effectiveFrom": "2026-01-01T00:00:00Z",
"effectiveTo": null,
"description": "FY26 Growth",
"createdAt": "2025-12-20T09:30:00Z",
"usageDiscount": null,
"targetPriceIds": []
}{
"message": "The requested resource was not found",
"error": "not_found"
}{
"message": "The requested resource was not found",
"error": "not_found"
}{
"message": "The requested resource was not found",
"error": "not_found"
}{
"message": "The requested resource was not found",
"error": "not_found"
}{
"message": "The requested resource was not found",
"error": "not_found"
}Create Adjustment
Attaches an adjustment to the subscription for a dated window. A percentageDiscount reduces every discountable charge by a rate and carries one discount line per charge on the invoice. A usageDiscount takes a number of usage units off one metered price’s billable quantity before that line is priced, so the line re-slots on a volume ladder and shows the corrected quantity; it emits no line of its own. Tax is assessed on the reduced amount either way. An invoice that already exists is not changed, including one still in draft — the adjustment reaches the periods that close after it is created. There is no update operation, and a window cannot be changed after it is created. To change an adjustment before any invoice has issued under it, delete it and create a replacement. Once an invoice has issued the adjustment is permanent, so set effectiveTo at creation time whenever the deal has a known end date.
curl --request POST \
--url https://api.paygentic.io/v0/subscriptions/{id}/adjustments \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"type": "percentageDiscount",
"percentageDiscount": "0.35",
"effectiveFrom": "2026-01-01T00:00:00Z",
"effectiveTo": null,
"description": "FY26 Growth",
"idempotencyKey": "adj_fy26_growth_001"
}
'{
"object": "subscriptionAdjustment",
"id": "<string>",
"subscriptionId": "<string>",
"type": "percentageDiscount",
"percentageDiscount": "<string>",
"usageDiscount": "<string>",
"minimumQuantity": "<string>",
"maximumQuantity": "<string>",
"targetPriceIds": [
"<string>"
],
"effectiveFrom": "2023-11-07T05:31:56Z",
"effectiveTo": "2023-11-07T05:31:56Z",
"description": "<string>",
"createdAt": "2023-11-07T05:31:56Z"
}{
"object": "subscriptionAdjustment",
"id": "subadj_a1b2c3d4e5f6g7h8",
"subscriptionId": "sub_z1a2b3c4d5e6f7g8",
"type": "percentageDiscount",
"percentageDiscount": "0.35",
"effectiveFrom": "2026-01-01T00:00:00Z",
"effectiveTo": null,
"description": "FY26 Growth",
"createdAt": "2025-12-20T09:30:00Z",
"usageDiscount": null,
"targetPriceIds": []
}{
"message": "The requested resource was not found",
"error": "not_found"
}{
"message": "The requested resource was not found",
"error": "not_found"
}{
"message": "The requested resource was not found",
"error": "not_found"
}{
"message": "The requested resource was not found",
"error": "not_found"
}{
"message": "The requested resource was not found",
"error": "not_found"
}Authorizations
API key authentication
Path Parameters
The subscription ID
Body
- Option 1
- Option 2
- Option 3
- Option 4
One adjustment to attach to the subscription. The type decides which number the body carries: a rate for percentageDiscount, a unit count and one target price for usageDiscount, and a contracted quantity and one target price for minimumQuantity and maximumQuantity.
Reduces every discountable charge on the invoice by a rate.
percentageDiscount The discount rate as a decimal fraction between 0 and 1, sent as a string. "0.35" means 35 percent. "1" means 100 percent, not 1 percent. At most 6 decimal places. A value of 0 or above 1 is rejected.
The first instant the discount applies. Inclusive.
The instant the discount stops applying. Exclusive, so a window ending on the same date another begins neither overlaps nor leaves a gap. Null means the discount never stops, and it cannot be ended later — set an instant whenever the deal has a known end date. Must be after effectiveFrom.
The deal's own name, shown on each discount line of the invoice.
255A key of your choosing that makes a retry safe. Sending the same key against the same subscription returns the adjustment already created and creates no second one. Without a key a retried request creates a second adjustment, and two percentage discounts compound — two of 0.35 bill 57.75 percent off, not 35 percent.
1 - 255"adj_fy26_growth_001"
Response
An adjustment already exists for this idempotency key, and is returned unchanged. Nothing was created.
subscriptionAdjustment The adjustment ID
Unique identifier for a subscription
^sub_[a-zA-Z0-9]+$percentageDiscount, usageDiscount, minimumQuantity, maximumQuantity The discount rate as a decimal fraction between 0 and 1. "0.35" means 35 percent. Null on every other type.
The number of usage units taken off the targeted line's billable quantity. Null on every other type.
The contracted minimum quantity billed for one period of the targeted price. Null on every other type.
The contracted maximum quantity billed for one period of the targeted price. Null on every other type.
The prices this adjustment applies to. Exactly one price on a usageDiscount; empty on a percentageDiscount, which reduces every discountable charge. A minimumQuantity or maximumQuantity is created against exactly one price, and later lists more than one only where that charge moved to a new price — a floating subscription moving to a new plan version, or a price edit freezing the subscription's version. Every id listed is the same charge, and the bound applies to whichever one a period bills under.
Opens the window. Read per type: INCLUSIVE on a percentageDiscount, whose window is prorated by day overlap; EXCLUSIVE on a usageDiscount and on both quantity bounds, which apply to a line whose period END falls strictly after this instant.
Closes the window, or null for never. Read per type: EXCLUSIVE on a percentageDiscount; INCLUSIVE on a usageDiscount and on both quantity bounds, which apply to a line whose period END falls on or before this instant. A delete shortens this to the end of the last period the adjustment has already been billed on.
The deal's own name. Shown on each discount line a percentageDiscount emits; every other type emits no line, so its description is carried here only.
Was this page helpful?