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>",
"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>",
"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
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.
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 The discount rate as a decimal fraction between 0 and 1. "0.35" means 35 percent. Null on a usageDiscount, which carries a unit count instead.
The number of usage units taken off the targeted line's billable quantity. Null on a percentageDiscount, which carries a rate instead.
The prices this adjustment reduces. Exactly one metered price on a usageDiscount; empty on a percentageDiscount, which reduces every discountable charge.
Opens the window. Read per type: INCLUSIVE on a percentageDiscount, whose window is prorated by day overlap; EXCLUSIVE on a usageDiscount, which corrects 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, which corrects a line whose period END falls on or before this instant.
The deal's own name. Shown on each discount line a percentageDiscount emits; a usageDiscount emits no line, so its description is carried here only.
Was this page helpful?