> ## Documentation Index > Fetch the complete documentation index at: https://docs.paygentic.io/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /openapi.json post /v0/subscriptions/{id}/adjustments openapi: 3.1.0 info: title: Paygentic API version: 0.1.0 description: > The Paygentic API provides a comprehensive platform for building and scaling monetization infrastructure. ## Authentication All API requests require authentication using an API key passed in the `Authorization` header: ``` Authorization: Bearer YOUR_API_KEY ``` ## Base URL All API requests should be made to: ``` https://api.paygentic.io/v0 ``` contact: name: Paygentic Support email: support@paygentic.io license: name: Proprietary servers: - url: https://api.paygentic.io description: Production API - url: https://api.sandbox.paygentic.io description: Sandbox API security: - BearerAuth: [] tags: - name: Customers description: >- A `Customer` is an entity connected to a `Merchant` via a `Subscription`. This represents the merchant-facing perspective of `Consumers` who purchase their `Products`. - name: Billable Metrics description: >- A `Billable Metric` defines a measurable quantity tied to a `Product`'s consumption. Each metric stores details including its label, an explanatory description, and measurement units. - name: Grants description: >- Grants credit a customer's metered entitlement balance. Merchants can create grants directly or void existing ones. Use `GET /v1/entitlements?customerId={id}` or `GET /v1/entitlements?subscriptionId={id}` to find the metered entitlement `id` needed for these endpoints. - name: Features description: >- A `Feature` represents a specific capability or functionality provided by a `Product`. Features can be metered (usage-based), static (fixed allocation), or boolean (enabled/disabled). - name: Fees description: >- A `Fee` defines a recurring or one-time charge tied to a `Product`. Fees are linked to prices, and cadence is defined on the Price. - name: Plans description: >- A `Plan` links a collection of `Prices` to a `Product`. It functions as a pricing structure document for a particular feature set or service offering. - name: Prices description: >- A `Price` determines the monetary value for a single unit of a `Billable Metric`. Prices are exclusively grouped within a `Plan`. - name: Products description: >- A `Product` is an offering sold by a `Merchant`. It includes product metadata like title, summary, and pricing details. `Plans`, `Prices`, and `Subscriptions` are all associated with products. - name: Sources description: >- A `Source` is an external data provider capable of automatically creating usage events. Configuration occurs at the plan level, enabling data retrieval from third-party platforms such as Stripe to produce billable events. - name: Subscriptions description: >- A `Subscription` is a customer's commitment to purchase a `Product` following the terms of a `Plan` and its linked `Prices`. - name: Users description: >- A `User` is an entity granted access to an Organization's resources. All operations are performed by users. - name: Invoices V2 description: >- Invoice V2 operations supporting billing cycles organized by time periods. Warning: v0 invoice endpoints are no longer supported. - name: Revenue description: Revenue data from invoices and payments - name: Profitability description: Per-customer profitability summaries - name: Test Clocks description: >- Test clocks provide programmable time control to simulate subscription and billing scenarios during testing. - name: Events description: Ingest raw metering events that are processed by the meters service. - name: Payments description: >- Create and manage one-off payments. A payment represents a single charge that a merchant wants to collect from a customer. - name: Payment Sessions description: >- Handle payment session lifecycle and processing across various entity types including invoices and subscriptions - name: Costs description: >- A Cost represents the operational or infrastructure expense of serving customers for a given product. Costs are metered (driven by event-based usage) and are tracked in parallel with billable metrics to give merchants visibility into both revenue and cost per customer. - name: ExternalReferences description: >- An `ExternalReference` links a Paygentic entity (e.g. an `Item`) to a record in an external system such as Salesforce or NetSuite. Multiple external records may map to the same Paygentic entity, but each external id is the *primary* reference of at most one entity per merchant. - name: Items description: >- An `Item` is the canonical "thing you sell" that external-system mappings point at. It is fully decoupled from the billing `Product` and holds no pricing/plan/metering, and it is CRM/ERP agnostic — which providers map to it lives entirely in its `ExternalReference` rows. - name: MerchantIntegrations description: >- A `MerchantIntegration` records a merchant's connection to an external provider. One connection per `(merchant, provider)` — re-connecting upserts in place. - name: Approvals description: Submit, decide, cancel, and read maker-checker approvals. - name: Orders description: Manage Orders, their line items, and billing schedules. - name: Billing Schedules description: >- Owner-polymorphic billing schedules with intervals and staged invoice projections. A BillingSchedule belongs to exactly one Order or one Subscription (XOR). Cadence lives on ScheduleIntervals (cadence-on-the-line). paths: /v0/subscriptions/{id}/adjustments: post: tags: - Subscriptions summary: Create Adjustment description: >- 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. operationId: createSubscriptionAdjustment parameters: - in: path name: id required: true schema: type: string description: The subscription ID requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateSubscriptionAdjustmentRequest' examples: percentageDiscount: summary: A 35% deal discount, open-ended value: type: percentageDiscount percentageDiscount: '0.35' effectiveFrom: '2026-01-01T00:00:00Z' effectiveTo: null description: FY26 Growth idempotencyKey: adj_fy26_growth_001 usageDiscount: summary: >- 300 erroneous units taken off one metered price for a single period value: type: usageDiscount usageDiscount: '300' targetPriceIds: - price_a1b2c3d4e5f6g7h8 effectiveFrom: '2026-03-01T00:00:00Z' effectiveTo: '2026-04-01T00:00:00Z' description: March outage — bad events idempotencyKey: adj_march_outage_001 responses: '200': description: >- An adjustment already exists for this idempotency key, and is returned unchanged. Nothing was created. content: application/json: schema: $ref: '#/components/schemas/SubscriptionAdjustment' '201': description: The adjustment was created and applies from its effectiveFrom date. content: application/json: schema: $ref: '#/components/schemas/SubscriptionAdjustment' example: 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: [] '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' components: schemas: CreateSubscriptionAdjustmentRequest: description: >- 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. oneOf: - $ref: '#/components/schemas/CreatePercentageDiscountAdjustment' - $ref: '#/components/schemas/CreateUsageDiscountAdjustment' discriminator: propertyName: type mapping: percentageDiscount: $ref: '#/components/schemas/CreatePercentageDiscountAdjustment' usageDiscount: $ref: '#/components/schemas/CreateUsageDiscountAdjustment' SubscriptionAdjustment: type: object required: - object - id - subscriptionId - type - percentageDiscount - usageDiscount - targetPriceIds - effectiveFrom - effectiveTo - description - createdAt properties: object: type: string enum: - subscriptionAdjustment id: type: string description: The adjustment ID subscriptionId: $ref: '#/components/schemas/SubscriptionId' type: type: string enum: - percentageDiscount - usageDiscount percentageDiscount: type: - string - 'null' description: >- 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. usageDiscount: type: - string - 'null' description: >- The number of usage units taken off the targeted line's billable quantity. Null on a percentageDiscount, which carries a rate instead. targetPriceIds: type: array items: type: string description: >- The prices this adjustment reduces. Exactly one metered price on a usageDiscount; empty on a percentageDiscount, which reduces every discountable charge. effectiveFrom: type: string format: date-time description: >- 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. effectiveTo: type: - string - 'null' format: date-time description: >- 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. description: type: - string - 'null' description: >- 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. createdAt: type: string format: date-time CreatePercentageDiscountAdjustment: type: object additionalProperties: false required: - type - percentageDiscount - effectiveFrom properties: type: type: string enum: - percentageDiscount description: Reduces every discountable charge on the invoice by a rate. percentageDiscount: type: string description: >- 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. effectiveFrom: type: string format: date-time description: The first instant the discount applies. Inclusive. effectiveTo: type: - string - 'null' format: date-time description: >- 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. description: type: - string - 'null' maxLength: 255 description: The deal's own name, shown on each discount line of the invoice. idempotencyKey: type: string minLength: 1 maxLength: 255 description: >- A 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. example: adj_fy26_growth_001 CreateUsageDiscountAdjustment: type: object additionalProperties: false required: - type - usageDiscount - targetPriceIds - effectiveFrom properties: type: type: string enum: - usageDiscount description: >- Reduces one metered price's billable quantity by a number of usage units, before the line is priced. usageDiscount: type: string pattern: ^[0-9]+(\.[0-9]+)?$ description: >- The number of usage units to take off the billable quantity, sent as a plain decimal string. "300" waives 300 units. Greater than 0, at most 6 decimal places, fewer than 35 digits before the point. Plain notation only — no sign, exponent, hex or digit separators, so "1_000" and "1e3" are rejected rather than read as 1000. Applied in full or not at all — a unit count is never prorated across a partial window — and once per matching line, so an invoice bundling several periods is corrected on each of them. The line is floored at 0, so a discount larger than the billable quantity zeroes it rather than crediting. On a volume ladder the corrected quantity also re-selects the band, so a waiver that crosses a boundary can bill more than the uncorrected line did: waiving 300 of 1000 units on a ladder of 2.00 up to 999 and 1.00 beyond bills 700 at 2.00 for 1400.00, where the 1000 units billed 1000.00. That is the ladder's price for the corrected usage — what a customer who genuinely used 700 units pays — so check the ladder before waiving units near a band boundary. targetPriceIds: type: array items: type: string minItems: 1 maxItems: 1 description: >- Exactly one metered price of this subscription, priced as standard or volume. Usage units are not comparable across metrics, so a usage discount names the one price it reduces. A dynamic or percentage price is refused: its quantity is a monetary amount rather than a unit count. A price billing at a negative rate (a usage-scaled rebate) is refused too, because removing its units would raise the invoice. effectiveFrom: type: string format: date-time description: >- Opens the window. Exclusive for this type: a metered line is corrected when its period END falls after this instant, so a window opening exactly when a period ends belongs to the next period, not that one. Set it to the start of the period you are correcting. effectiveTo: type: - string - 'null' format: date-time description: >- Closes the window. INCLUSIVE for this type, unlike percentageDiscount: a metered line bills in arrears, so set this to the exact period end you are correcting and that period is covered. Null means the discount never stops — it then takes its full unit count off this price on EVERY later invoice, so set both bounds whenever you are correcting one period. Must be after effectiveFrom. description: type: - string - 'null' maxLength: 255 description: >- Your own name for this correction. A usageDiscount emits no invoice line, so this is printed nowhere on the invoice — it is returned on the adjustment for your own records. idempotencyKey: type: string minLength: 1 maxLength: 255 description: >- A 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 usage discounts against one price SUM — two of "300" waive 600 units, not 300. Nothing else detects a duplicate. example: adj_mar_outage_001 SubscriptionId: type: string pattern: ^sub_[a-zA-Z0-9]+$ description: Unique identifier for a subscription Error: type: object required: - message properties: error: type: string description: >- Coarse HTTP error category (e.g. 'bad_request', 'forbidden'). Maps to the HTTP status code. message: type: string description: >- Human-readable error message. Clients must not parse this field programmatically. code: type: string examples: - TAX_NOT_ENABLED - PAYMENT_SESSION_EXPIRED description: >- Optional semantic business error code for machine-readable discrimination (e.g. 'TAX_NOT_ENABLED'). UPPER_SNAKE_CASE. Clients should check this field, not message. details: type: object description: Additional error details additionalProperties: true example: message: The requested resource was not found error: not_found ValidationError: type: object required: - message - errors properties: error: type: string enum: - validation_error default: validation_error description: Error type indicating validation failure message: type: string description: Human-readable error message errors: type: array items: type: object properties: field: type: string description: The field that failed validation message: type: string description: Validation error message for this field code: type: string description: Validation error code required: - field - message description: Array of field-specific validation errors example: message: Validation failed error: validation_error errors: - field: email message: Invalid email format code: invalid_format responses: BadRequest: description: >- Bad Request - The request could not be understood or was missing required parameters content: application/json: schema: oneOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/ValidationError' Unauthorized: description: Unauthorized - Authentication failed or user does not have permissions content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: Forbidden - Request is understood but refused content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: Not Found - The requested resource could not be found content: application/json: schema: $ref: '#/components/schemas/Error' InternalServerError: description: Internal Server Error - Something went wrong on the server side content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: BearerAuth: type: http scheme: bearer description: API key authentication ````