---
title: "Create an adjustment"
method: POST
path: "/adjustments"
tags: ["Adjustments"]
---

# Create an adjustment

`POST /adjustments`

## Request

- Base URL: `https://sandbox-api.paddle.com`
- URL: `https://sandbox-api.paddle.com/adjustments`
- Auth: HTTP bearer

Creates an adjustment for one or more transaction items.

You can create adjustments to refund or credit all or part of a transaction and its items:

* Refunds return an amount to a customer's original payment method. You can create refund adjustments for transactions that are `completed`.
* Credits reduce the amount that a customer has to pay for a transaction. You can create credit adjustments for manually-collected transactions that are `billed` or `past_due`.

You can create adjustments to refund transactions that are `completed`, or to reduce the amount to due on manually-collected transactions that are `billed` or `past_due`.
Most refunds for live accounts are created with the status of `pending_approval` until reviewed by Paddle, but [some are automatically approved](https://developer.paddle.com/build/transactions/create-transaction-adjustments#background-refunds). For sandbox accounts, Paddle automatically approves refunds every ten minutes.

Adjustments can apply to some or all items on a transaction. You'll need the Paddle ID of the transaction to create a refund or credit for, along with the Paddle ID of any transaction items (`details.line_items[].id`).

If successful, your response includes a copy of the new adjustment entity.

## Request body

- AdjustmentCreate: Represents an adjustment entity when creating adjustments.
  - `action` 'credit' | 'refund' | 'chargeback' | 'chargeback_reverse' | 'chargeback_warning' | 'chargeback_warning_reverse' | 'credit_reverse', required: How this adjustment impacts the related transaction.
  - `type` 'full' | 'partial': Type of adjustment. Use `full` to adjust the grand total for the related transaction. Include an `items` array when creating a `partial` adjustment. If omitted, defaults to `partial`.
  - `tax_mode` 'external' | 'internal': Whether the amounts to be adjusted are inclusive or exclusive of tax. If `internal`, adjusted amounts are considered to be inclusive of tax. If `external`, Paddle calculates the tax and adds it to the amounts provided. Only valid for adjustments where the `type` is `partial`. If omitted, defaults to `internal`.
  - `transaction_id` string, required: Unique Paddle ID for this transaction entity, prefixed with `txn_`.
  - `reason` string, required: Why this adjustment was created. Appears in the Paddle dashboard. Retained for recordkeeping purposes.
  - `items` AdjustmentItemCreate[], nullable: List of transaction items to adjust. Required if `type` is not populated or set to `partial`.
    - `item_id` string, required: Unique Paddle ID for this transaction item, prefixed with `txnitm_`. Used when working with [adjustments](https://developer.paddle.com/build/transactions/create-transaction-adjustments).
    - `type` 'full' | 'partial' | 'tax' | 'proration', required: Type of adjustment for this transaction item. `tax` adjustments are automatically created by Paddle. Include `amount` when creating a `partial` adjustment.
    - `amount` string, nullable: Amount adjusted for this transaction item. Required when item `type` is `partial`.

## Response `201`

The request has succeeded and a new resource has been created as a result.

- object
  - `data` Adjustment, required: Represents an adjustment entity.
    - `id` string, required: Unique Paddle ID for this adjustment entity, prefixed with `adj_`.
    - `action` 'credit' | 'refund' | 'chargeback' | 'chargeback_reverse' | 'chargeback_warning' | 'chargeback_warning_reverse' | 'credit_reverse', required: How this adjustment impacts the related transaction.
    - `type` 'full' | 'partial', required: Type of adjustment. Use `full` to adjust the grand total for the related transaction. Include an `items` array when creating a `partial` adjustment. If omitted, defaults to `partial`.
    - `transaction_id` string, required: Unique Paddle ID for this transaction entity, prefixed with `txn_`.
    - `subscription_id` string, required: Unique Paddle ID for this subscription entity, prefixed with `sub_`.
    - `customer_id` string, required: Unique Paddle ID for this customer entity, prefixed with `ctm_`.
    - `reason` string, required: Why this adjustment was created. Appears in the Paddle dashboard. Retained for record-keeping purposes.
    - `credit_applied_to_balance` boolean, nullable: Whether this adjustment was applied to the related customer's credit balance. Only returned for `credit` adjustments.
    - `currency_code` 'USD' | 'EUR' | 'GBP' | 'JPY' | 'AUD' | 'CAD' | 'CHF' | 'HKD' | 'SGD' | 'SEK' | 'ARS' | 'BRL' | 'CLP' | 'CNY' | 'COP' | 'CZK' | 'DKK' | 'HUF' | 'ILS' | 'INR' | 'KRW' | 'MXN' | 'NOK' | 'NZD' | 'PEN' | 'PLN' | 'RUB' | 'THB' | 'TRY' | 'TWD' | 'UAH' | 'VND' | 'ZAR', required: Supported three-letter ISO 4217 currency code.
    - `status` 'pending_approval' | 'approved' | 'rejected' | 'reversed', required: Status of this adjustment. Set automatically by Paddle. Most refunds for live accounts are created with the status of `pending_approval` until reviewed by Paddle, but some are automatically approved. For sandbox accounts, Paddle automatically approves refunds every ten minutes. Credit adjustments don't require approval from Paddle, so they're created as `approved`.
    - `items` object[], required: List of items on this adjustment. Required if `type` is not populated or set to `partial`.
      - `id` string, required: Unique Paddle ID for this adjustment item, prefixed with `adjitm_`.
      - `item_id` string, required: Unique Paddle ID for this transaction item, prefixed with `txnitm_`. Used when working with [adjustments](https://developer.paddle.com/build/transactions/create-transaction-adjustments).
      - `type` 'full' | 'partial' | 'tax' | 'proration', required: Type of adjustment for this transaction item. `tax` adjustments are automatically created by Paddle. Include `amount` when creating a `partial` adjustment.
      - `amount` string, nullable, required: Amount adjusted for this transaction item. Required when item `type` is `partial`.
      - `proration` TransactionItemProration, required: How proration was calculated for this item. Populated when a transaction is created from a subscription change, where `proration_billing_mode` was `prorated_immediately` or `prorated_next_billing_period`. Set automatically by Paddle.
        - `rate` string, required: Rate used to calculate proration.
        - `billing_period` TimePeriod, required
          - `starts_at` string, date-time, required: RFC 3339 datetime string.
          - `ends_at` string, date-time, required: RFC 3339 datetime string.
      - `totals` AdjustmentItemTotals, required: Breakdown of the total for an adjustment item.
        - `subtotal` string, required: Amount multiplied by quantity.
        - `tax` string, required: Total tax on the subtotal.
        - `total` string, required: Total after tax.
    - `totals` AdjustmentTotals, required: Breakdown of the total for an adjustment.
      - `subtotal` string, required: Total before tax. For tax adjustments, the value is 0.
      - `tax` string, required: Total tax on the subtotal.
      - `total` string, required: Total after tax.
      - `fee` string, required: Total fee taken by Paddle for this adjustment.
      - `retained_fee` string: Paddle fees retained for this adjustment.
      - `earnings` string, required: Total earnings. This is the subtotal minus the fee. For tax adjustments, this value is negative, which means a positive effect in the transaction earnings. This is because the fee is originally calculated from the transaction total, so if a tax adjustment is made, then the fee portion of it is returned.
      - `currency_code` 'USD' | 'EUR' | 'GBP' | 'JPY' | 'AUD' | 'CAD' | 'CHF' | 'HKD' | 'SGD' | 'SEK' | 'ARS' | 'BRL' | 'CLP' | 'CNY' | 'COP' | 'CZK' | 'DKK' | 'HUF' | 'ILS' | 'INR' | 'KRW' | 'MXN' | 'NOK' | 'NZD' | 'PEN' | 'PLN' | 'RUB' | 'THB' | 'TRY' | 'TWD' | 'UAH' | 'VND' | 'ZAR', required: Supported three-letter ISO 4217 currency code.
    - `payout_totals` AdjustmentPayoutTotals, required: Breakdown of how this adjustment affects your payout balance.
      - `subtotal` string, required: Adjustment total before tax and fees.
      - `tax` string, required: Total tax on the adjustment subtotal.
      - `total` string, required: Adjustment total after tax.
      - `fee` string, required: Adjusted Paddle fee.
      - `retained_fee` string, required: Paddle fees retained for this adjustment.
      - `chargeback_fee` AdjustmentPayoutTotalsChargebackFee
        - `amount` string, required: Chargeback fee converted into the payout currency.
        - `original` AdjustmentPayoutTotalsChargebackFeeOriginal, required
          - `amount` string, required: Fee amount for this chargeback in the original currency.
          - `currency_code` 'AUD' | 'CAD' | 'EUR' | 'GBP' | 'USD', required: Three-letter ISO 4217 currency code for chargeback fees.
      - `earnings` string, required: Adjusted payout earnings. This is the adjustment total plus adjusted fees.
      - `currency_code` 'AUD' | 'CAD' | 'CHF' | 'CNY' | 'CZK' | 'DKK' | 'EUR' | 'GBP' | 'HUF' | 'PLN' | 'SEK' | 'USD' | 'ZAR', required: Supported three-letter ISO 4217 currency code for payouts from Paddle.
    - `tax_rates_used` AdjustmentTaxRatesUsed[], required
      - `tax_rate` string, required: Rate used to calculate tax for this adjustment.
      - `totals` AdjustmentTaxRatesUsedItemTotals, required: Calculated totals for the tax applied to this adjustment.
        - `subtotal` string, required: Total before tax. For tax adjustments, the value is 0.
        - `tax` string, required: Total tax on the subtotal.
        - `total` string, required: Total after tax.
    - `created_at` string, date-time, required: RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
    - `updated_at` string, date-time, required: RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
  - `meta` Meta, required: Information about this response.
    - `request_id` string, required: Unique ID for the request relating to this response. Provide this when contacting Paddle support about a specific request.

## Other responses

- `default`: An unexpected error response.

## Changes

- **2026-07-09** (v1) `e1ac347eb3c5`: 4 warning
  - added the new `CLP` enum value to the `data/currency_code/allOf[subschema #1: Currency code]/` response property for the response status `201`
  - added the new `CLP` enum value to the `data/totals/allOf[subschema #1: AdjustmentTotals]/currency_code/allOf[subschema #1: Currency code]/` response property for the response status `201`
  - added the new `PEN` enum value to the `data/currency_code/allOf[subschema #1: Currency code]/` response property for the response status `201`
  - added the new `PEN` enum value to the `data/totals/allOf[subschema #1: AdjustmentTotals]/currency_code/allOf[subschema #1: Currency code]/` response property for the response status `201`
- **2026-02-02** (v1) `9ba8be0f2006`: 31 breaking, 10 warning, 85 info
  - request body became required
  - added `#/components/schemas/AdjustmentTaxMode` to the `tax_mode` request property `allOf` list
  - added `#/components/schemas/AdjustmentType` to the `type` request property `allOf` list
  - added `#/components/schemas/TransactionId` to the `transaction_id` request property `allOf` list
  - …122 more
- **2025-05-27** (v1) `e57c515077cc`: 1 warning, 1 info
  - added the new `chargeback_warning_reverse` enum value to the `data/action` response property for the response status `201`
  - added the new `chargeback_warning_reverse` enum value to the request property `action`
- …earlier changes not shown

[Operation history](https://skmtc.dev/paddlehq/apis/paddle-api/changes/adjustments/post.md)

---

[API](https://skmtc.dev/paddlehq/apis/paddle-api.md) - [All operations](https://skmtc.dev/paddlehq/apis/paddle-api/llms.txt) - [OpenAPI document](https://skmtc.dev/paddlehq/apis/paddle-api/revisions/bbc0c72039c8?raw)