Create an adjustment

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    action: 'refund',
    items: [{item_id: 'txnitm_01hvcc94b7qgz60qmrqmbm19zw', type: 'partial', amount: '100'}],
    reason: 'error',
    transaction_id: 'txn_01hvcc93znj3mpqt1tenkjb04y'
  })
};

fetch('https://api.paddle.com/adjustments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "data": {
    "id": "adj_01hvgf2s84dr6reszzg29zbvcm",
    "action": "refund",
    "type": "partial",
    "transaction_id": "txn_01hvcc93znj3mpqt1tenkjb04y",
    "subscription_id": "sub_01hvccbx32q2gb40sqx7n42430",
    "customer_id": "ctm_01hrffh7gvp29kc7xahm8wddwa",
    "reason": "error",
    "currency_code": "USD",
    "status": "pending_approval",
    "items": [
      {
        "id": "adjitm_01hvgf2s84dr6reszzg2gx70gj",
        "item_id": "txnitm_01hvcc94b7qgz60qmrqmbm19zw",
        "type": "partial",
        "amount": "100",
        "proration": null,
        "totals": {
          "subtotal": "92",
          "tax": "8",
          "total": "100"
        }
      }
    ],
    "totals": {
      "subtotal": "92",
      "tax": "8",
      "total": "100",
      "fee": "5",
      "earnings": "87",
      "currency_code": "USD"
    },
    "payout_totals": {
      "subtotal": "92",
      "tax": "8",
      "total": "100",
      "fee": "5",
      "earnings": "87",
      "currency_code": "USD"
    },
    "created_at": "2024-04-15T08:48:20.239695Z",
    "updated_at": "2024-04-15T08:48:20.239695Z"
  },
  "meta": {
    "request_id": "c1906ac5-c210-4443-ba9b-122ecaeb506d"
  }
}

Adjustments

Create an adjustment

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

Create an adjustment

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    action: 'refund',
    items: [{item_id: 'txnitm_01hvcc94b7qgz60qmrqmbm19zw', type: 'partial', amount: '100'}],
    reason: 'error',
    transaction_id: 'txn_01hvcc93znj3mpqt1tenkjb04y'
  })
};

fetch('https://api.paddle.com/adjustments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "data": {
    "id": "adj_01hvgf2s84dr6reszzg29zbvcm",
    "action": "refund",
    "type": "partial",
    "transaction_id": "txn_01hvcc93znj3mpqt1tenkjb04y",
    "subscription_id": "sub_01hvccbx32q2gb40sqx7n42430",
    "customer_id": "ctm_01hrffh7gvp29kc7xahm8wddwa",
    "reason": "error",
    "currency_code": "USD",
    "status": "pending_approval",
    "items": [
      {
        "id": "adjitm_01hvgf2s84dr6reszzg2gx70gj",
        "item_id": "txnitm_01hvcc94b7qgz60qmrqmbm19zw",
        "type": "partial",
        "amount": "100",
        "proration": null,
        "totals": {
          "subtotal": "92",
          "tax": "8",
          "total": "100"
        }
      }
    ],
    "totals": {
      "subtotal": "92",
      "tax": "8",
      "total": "100",
      "fee": "5",
      "earnings": "87",
      "currency_code": "USD"
    },
    "payout_totals": {
      "subtotal": "92",
      "tax": "8",
      "total": "100",
      "fee": "5",
      "earnings": "87",
      "currency_code": "USD"
    },
    "created_at": "2024-04-15T08:48:20.239695Z",
    "updated_at": "2024-04-15T08:48:20.239695Z"
  },
  "meta": {
    "request_id": "c1906ac5-c210-4443-ba9b-122ecaeb506d"
  }
}

Authorizations

Authorization

string

header

required

Requests are authenticated with API keys. Provide your API key as a Bearer token in the Authorization header.

API keys are assigned permissions, granting them access to entities and operations. Each endpoint may require one or more permissions, defined with the x-permissions extension. Values for include parameters may require specific permissions as defined in the x-enum-permissions extension. See all available permissions in the permission schema or documentation.

Get an API key and select the permissions you need from the Paddle dashboard under Paddle > Developer Tools > Authentication.

Body

application/json

Represents an adjustment entity when creating adjustments.

action

enum<string>

required

How this adjustment impacts the related transaction.

Available options:

credit,

refund,

chargeback,

chargeback_reverse,

chargeback_warning,

chargeback_warning_reverse,

credit_reverse

transaction_id

string

required

Paddle ID of the transaction that this adjustment is for, prefixed with txn_.

Automatically-collected transactions must be completed; manually-collected transactions must have a status of billed or past_due

You can't create an adjustment for a transaction that has a refund that's pending approval.

Example:

"txn_01h04vsbhqc62t8hmd4z3b578c"

reason

string

required

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

type

enum<string>

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

Available options:

full,

partial

Example:

"partial"

tax_mode

enum<string>

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

Available options:

external,

internal

items

Adjustment item · object[] | null

List of transaction items to adjust. Required if type is not populated or set to partial.

Required array length: 1 - 100 elements

Show child attributes

Response

Created

data

Adjustment · object

required

Represents an adjustment entity.

Show child attributes

Updates

2026

2025

2024

Products

Prices

Transactions

Pricing preview

Adjustments

Customers

Addresses

Businesses

Payment methods

Customer portal sessions

Notification settings

Event types

Events

Notifications

Notification logs

Simulation types

Simulations

Simulation runs

Simulation run events

IP addresses

Discounts

Subscriptions

Reports

API Keys

Payouts

Create an adjustment

Authorizations

Body

Response