Account2

Addresses4

Adjustments3

API root1

Businesses4

Checkout domains4

Client tokens4

Countries1

Currencies1

Customer portals1

Customers6

Discount groups4

Discounts4

Event types1

Events1

IP addresses1

Metrics9

Notification logs1

Notification settings5

Notifications3

Payment methods3

Prices4

Pricing preview1

Products4

Reports4

Settings18

Simulation run events3

Simulation runs3

Simulation types1

Simulations4

Subscription history1

Subscriptions11

Transactions7

Verifications2

Webhooks

Addresses3

Adjustments2

API keys6

Businesses3

Client tokens3

Customers3

Discount groups2

Discounts3

Payment methods2

Payouts2

Prices3

Products3

Reports2

Subscriptions9

Transactions10

Adjustments

Create an adjustment

Changed on Jul 9, 2026

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. 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.

post/adjustments

Request

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

Request body

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_idstring required

Unique Paddle ID for this transaction entity, prefixed with txn_.

reasonstring required

Why this adjustment was created. Appears in the Paddle dashboard. Retained for recordkeeping purposes.

Example request

{
  "type": "partial",
  "transaction_id": "txn_01h04vsbhqc62t8hmd4z3b578c",
  "items": [
    {
      "item_id": "txnitm_01gm302t81w94gyjpjpqypkzkf",
      "type": "full"
    }
  ]
}

Response

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

Example response

{
  "data": {
    "id": "adj_01gya6twkp8y0tv1e19rsgst9m",
    "type": "partial",
    "transaction_id": "txn_01h04vsbhqc62t8hmd4z3b578c",
    "subscription_id": "sub_01h04vsc0qhwtsbsxh3422wjs4",
    "customer_id": "ctm_01grnn4zta5a1mf02jjze7y2ys",
    "items": [
      {
        "id": "adjitm_01gw4rs4kex0prncwfne87ft8x",
        "item_id": "txnitm_01gm302t81w94gyjpjpqypkzkf",
        "type": "full",
        "proration": {
          "billing_period": {
            "starts_at": "2024-10-12T07:20:50.52Z",
            "ends_at": "2024-10-12T07:20:50.52Z"
          }
        },
        "totals": {
          "subtotal": "15000",
          "tax": "1500",
          "total": "16500"
        }
      }
    ],
    "totals": {
      "subtotal": "15000",
      "tax": "1500",
      "total": "16500",
      "fee": "300",
      "retained_fee": "300",
      "earnings": "14700"
    },
    "payout_totals": {
      "subtotal": "15000",
      "tax": "1500",
      "total": "16500",
      "fee": "300",
      "retained_fee": "300",
      "chargeback_fee": {
        "amount": "1680",
        "original": {
          "amount": "1500"
        }
      },
      "earnings": "15120"
    },
    "tax_rates_used": [
      {
        "tax_rate": "0.2",
        "totals": {
          "subtotal": "15000",
          "tax": "1500",
          "total": "16500"
        }
      }
    ],
    "created_at": "2024-10-12T07:20:50.52Z",
    "updated_at": "2024-10-13T07:20:50.52Z"
  },
  "meta": {
    "request_id": "b15ec92e-8688-40d4-a04d-f44cbec93355"
  }
}

Changes

Jul 9, 2026v1e1ac347eb3c5 Revision changes
- warning
  added the new CLP enum value to the // response property for the response status
- warning
  added the new CLP enum value to the //// response property for the response status
- warning
  added the new PEN enum value to the // response property for the response status
- warning
  added the new PEN enum value to the //// response property for the response status
Feb 2, 2026v19ba8be0f2006 Revision changes
- breaking
  request body became required
- breaking
  added to the request property allOf list
- breaking
  added to the request property allOf list
- breaking
  added to the request property allOf list
- breaking
  the request property became not nullable
- breaking
  removed the enum value external of the request property
- breaking
  removed the enum value full of the request property
- breaking
  removed the enum value internal of the request property
- breaking
  removed the enum value partial of the request property
- breaking
  added the pattern .*\S.* to the request property
- breaking
  the request property type changed from string to no type
- breaking
  the request property type changed from string to no type
- breaking
  the request property type changed from string to no type
- breaking
  the / response property's maxLength was unset from 3 for the response status
- breaking
  the / response property's minLength was decreased from 3 to 0 for the response status
- breaking
  the / response's property type changed from string to no type, and format from date-time to no format for status
- breaking
  the / response's property type changed from string to no type for status
- breaking
  the / response's property type changed from string to no type for status
- breaking
  the / response's property type changed from string to no type for status
- breaking
  the // response's property type changed from no type to object for status
- breaking
  the / response's property type changed from string to no type for status
- breaking
  the /// response's property type changed from object to no type for status
- breaking
  the / response's property type changed from object to no type for status
- breaking
  the / response's property type changed from string to no type for status
- breaking
  the / response's property type changed from string to no type for status
- breaking
  the / response's property type changed from string to no type, and format from date-time to no format for status
- breaking
  the response's property type changed from object to no type for status
- breaking
  removed the required property / from the response with the status
- breaking
  removed the required property / from the response with the status
- breaking
  removed the required property / from the response with the status
- breaking
  removed the required property / from the response with the status
- warning
  removed the optional property //// from the response with the status
- warning
  removed the optional property //// from the response with the status
- warning
  removed the optional property //// from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property // from the response with the status
- warning
  removed the optional property / from the response with the status
- info
  request property list-of-types was widened by adding types null to media type application/json
- info
  removed the pattern ^txn_[a-z\d]{26}$ from the request property
- info
  added to the / response property allOf list for the response status
- info
  added to the / response property allOf list for the response status
- info
  added to the /// response property allOf list for the response status
- info
  added to the / response property allOf list for the response status
- info
  added to the / response property allOf list for the response status
- info
  added to the response property allOf list for the response status
- info
  added to the / response property allOf list for the response status
- info
  added to the / response property allOf list for the response status
- info
  added to the / response property allOf list for the response status
- info
  added to the / response property allOf list for the response status
- info
  added to the / response property allOf list for the response status
- info
  removed subschema #1 from the // response property allOf list for the response status
- info
  added subschema #2 to the / response property anyOf list for the response status
- info
  added subschema #2 to the / response property anyOf list for the response status
- info
  added subschema #1 subschema #2 to the / response property anyOf list for the response status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the response property /// became required for the status
- info
  the response property /// became required for the status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the response property became required for the status
- info
  the response property became required for the status
- info
  removed the ARS enum value from the / response property for the response status
- info
  removed the AUD enum value from the / response property for the response status
- info
  removed the BRL enum value from the / response property for the response status
- info
  removed the CAD enum value from the / response property for the response status
- info
  removed the CHF enum value from the / response property for the response status
- info
  removed the CNY enum value from the / response property for the response status
- info
  removed the COP enum value from the / response property for the response status
- info
  removed the CZK enum value from the / response property for the response status
- info
  removed the DKK enum value from the / response property for the response status
- info
  removed the EUR enum value from the / response property for the response status
- info
  removed the GBP enum value from the / response property for the response status
- info
  removed the HKD enum value from the / response property for the response status
- info
  removed the HUF enum value from the / response property for the response status
- info
  removed the ILS enum value from the / response property for the response status
- info
  removed the INR enum value from the / response property for the response status
- info
  removed the JPY enum value from the / response property for the response status
- info
  removed the KRW enum value from the / response property for the response status
- info
  removed the MXN enum value from the / response property for the response status
- info
  removed the NOK enum value from the / response property for the response status
- info
  removed the NZD enum value from the / response property for the response status
- info
  removed the PLN enum value from the / response property for the response status
- info
  removed the RUB enum value from the / response property for the response status
- info
  removed the SEK enum value from the / response property for the response status
- info
  removed the SGD enum value from the / response property for the response status
- info
  removed the THB enum value from the / response property for the response status
- info
  removed the TRY enum value from the / response property for the response status
- info
  removed the TWD enum value from the / response property for the response status
- info
  removed the UAH enum value from the / response property for the response status
- info
  removed the USD enum value from the / response property for the response status
- info
  removed the VND enum value from the / response property for the response status
- info
  removed the ZAR enum value from the / response property for the response status
- info
  removed the approved enum value from the / response property for the response status
- info
  removed the full enum value from the / response property for the response status
- info
  removed the partial enum value from the / response property for the response status
- info
  removed the pending_approval enum value from the / response property for the response status
- info
  removed the rejected enum value from the / response property for the response status
- info
  removed the reversed enum value from the / response property for the response status
- info
  removed subschema #2 from the / response property oneOf list for the response status
- info
  removed subschema #2 from the / response property oneOf list for the response status
- info
  removed subschema #1 subschema #2 from the / response property oneOf list for the response status
- info
  the / response's property pattern ^ctm_[a-z\d]{26}$ was removed for the status
- info
  the / response's property pattern ^adj_[a-z\d]{26}$ was removed for the status
- info
  the / response's property pattern ^txn_[a-z\d]{26}$ was removed for the status
- info
  added the required property /// to the response with the status
- info
  added the required property /// to the response with the status
- info
  added the required property /// to the response with the status
- info
  added the required property /// to the response with the status
- info
  added the required property /// to the response with the status
- info
  added the required property /// to the response with the status

Operation history (8 revisions)