Docs

List adjustments

Returns a paginated list of adjustments.

GET /adjustments
Returns a paginated list of adjustments. Use the query parameters to page through results.

Requires adjustment.read permission.

Query parameters

idarray
Return only the IDs specified. Use a comma-separated list to get multiple entities.
afterstring
Return entities after the specified Paddle ID when working with paginated endpoints. Used in the meta.pagination.next URL in responses for list operations.
actionarray
Return entities for the specified action. Use a comma-separated list to specify multiple action values.
Values
  • credit
    Return adjustments where the action is credit. Returned adjustments are credits for some or all the related transaction.
  • refund
    Return adjustments where the action is refund. Returned adjustments are refunds for some or all the related transaction.
  • chargeback
    Return adjustments where the action is chargeback. Returned adjustments are chargebacks for their related transactions.
  • chargeback_reverse
    Return adjustments where the action is chargeback_reverse.
  • chargeback_warning
    Return adjustments where the action is chargeback_warning. Returned adjustments are warnings of upcoming chargebacks for their related transactions.
+ Show all values
  • chargeback_warning_reverse
    Return adjustments where the action is chargeback_warning_reverse. Returned adjustments are reversals of chargeback warnings for their related transactions.
  • credit_reverse
    Return adjustments where the action is credit_reverse.
customer_idarray
Return entities related to the specified customer. Use a comma-separated list to specify multiple customer IDs.
order_bystring
Default: id[DESC]

Order returned entities by the specified field and direction ([ASC] or [DESC]). For example, ?order_by=id[ASC].

Valid fields for ordering: id.

per_pageinteger
Default: 10

Set how many entities are returned per page. Paddle returns the maximum number of results if a number greater than the maximum is requested. Check meta.pagination.per_page in the response to see how many were returned.

Default: 10; Maximum: 50.

Max: 50
statusarray
Return entities that match the specified status. Use a comma-separated list to specify multiple status values.
Values
  • pending_approval
    Return adjustments where the status is pending_approval. Returned adjustments are refunds that are pending approval by Paddle.
  • approved
    Return adjustments where the status is approved. Returned adjustments are credits or refunds that have been approved by Paddle.
  • rejected
    Return adjustments where the status is rejected. Returned adjustments are rejected refunds.
  • reversed
    Return adjustments where the status is reversed.
subscription_idarray
Return entities related to the specified subscription. Use a comma-separated list to specify multiple subscription IDs.
transaction_idarray
Return entities related to the specified transaction. Use a comma-separated list to specify multiple transaction IDs.

Response (200)

dataarrayrequired
idstringrequired
Example: adj_01gya6twkp8y0tv1e19rsgst9m
Unique Paddle ID for this adjustment entity, prefixed with adj_.
Pattern: ^adj_[a-z\d]{26}$
actionstringrequired
How this adjustment impacts the related transaction.
Values
  • credit
    Credits some or all the related transaction.
  • refund
    Refunds some or all the related transaction. Must be approved by Paddle in most cases.
  • chargeback
    Chargeback for the related transaction. Automatically created by Paddle when a customer successfully disputes a charge.
  • chargeback_reverse
    Reversal of a chargeback for the related transaction. Automatically created by Paddle when Paddle contests a chargeback successfully.
  • chargeback_warning
    Warning of an upcoming chargeback for the related transaction. Automatically created by Paddle.
+ Show all values
  • chargeback_warning_reverse
    Reversal of a chargeback warning for the related transaction. Automatically created by Paddle.
  • credit_reverse
    Reversal of a credit for the related transaction. Automatically created by Paddle.
typestringrequired
Default: partial
Example: 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.
Values
  • full
    The grand total for the related transaction is adjusted.
  • partial
    Some line items for the related transaction are adjusted. Requires items.
transaction_idstringrequired
Example: txn_01h04vsbhqc62t8hmd4z3b578c
Paddle ID of the transaction that this adjustment is for, prefixed with txn_.
Pattern: ^txn_[a-z\d]{26}$
subscription_idstring | nullrequired
Example: sub_01h04vsc0qhwtsbsxh3422wjs4
Unique Paddle ID for this subscription entity, prefixed with sub_.
Pattern: ^sub_[a-z\d]{26}$
customer_idstringrequired
Example: ctm_01grnn4zta5a1mf02jjze7y2ys
Paddle ID for the customer related to this adjustment, prefixed with ctm_. Set automatically by Paddle based on the customer_id of the related transaction.
Pattern: ^ctm_[a-z\d]{26}$
reasonstringrequired
Why this adjustment was created. Appears in the Paddle dashboard. Retained for record-keeping purposes.
credit_applied_to_balanceboolean | null
Whether this adjustment was applied to the related customer's credit balance. Only returned for credit adjustments.
currency_codestringrequired
Three-letter ISO 4217 currency code for this adjustment. Set automatically by Paddle based on the currency_code of the related transaction.
Values
  • USD
    United States Dollar
  • EUR
    Euro
  • GBP
    Pound Sterling
  • JPY
    Japanese Yen
  • AUD
    Australian Dollar
+ Show all values
  • CAD
    Canadian Dollar
  • CHF
    Swiss Franc
  • HKD
    Hong Kong Dollar
  • SGD
    Singapore Dollar
  • SEK
    Swedish Krona
  • ARS
    Argentine Peso
  • BRL
    Brazilian Real
  • CLP
    Chilean Peso
  • CNY
    Chinese Yuan
  • COP
    Colombian Peso
  • CZK
    Czech Koruna
  • DKK
    Danish Krone
  • HUF
    Hungarian Forint
  • ILS
    Israeli Shekel
  • INR
    Indian Rupee
  • KRW
    South Korean Won
  • MXN
    Mexican Peso
  • NOK
    Norwegian Krone
  • NZD
    New Zealand Dollar
  • PEN
    Peruvian Sol
  • PLN
    Polish Zloty
  • RUB
    Russian Ruble
  • THB
    Thai Baht
  • TRY
    Turkish Lira
  • TWD
    New Taiwan Dollar
  • UAH
    Ukrainian Hryvnia
  • VND
    Vietnamese Dong
  • ZAR
    South African Rand
statusstringrequired

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.

Values
  • pending_approval
    Adjustment is pending approval by Paddle. Most refunds for live accounts must be approved by Paddle.
  • approved
    Adjustment is approved. Default for credits. Set when Paddle approves a refund that was pending_approval.
  • rejected
    Adjustment has been rejected. Set when Paddle rejects a refund that was pending_approval.
  • reversed
    Adjustment has been reversed. Set by Paddle when a chargeback_reversal or credit_reversal adjustment is created for this adjustment.
itemsarrayrequired
List of items on this adjustment. Required if type is not populated or set to partial.
Items: 1–100
idstringrequired
Example: adjitm_01gw4rs4kex0prncwfne87ft8x
Unique Paddle ID for this adjustment item, prefixed with adjitm_.
Pattern: ^adjitm_[a-z\d]{26}$
item_idstringrequired
Example: txnitm_01gm302t81w94gyjpjpqypkzkf
Paddle ID for the transaction item that this adjustment item relates to, prefixed with txnitm_.
Pattern: ^txnitm_[a-z\d]{26}$
typestringrequired
Example: full
Type of adjustment for this transaction item. tax adjustments are automatically created by Paddle. Include amount when creating a partial adjustment.
Values
  • full
    Full total for this transaction item is adjusted.
  • partial
    Part of this transaction item is adjusted. Include amount to specify the partial amount adjusted.
  • tax
    Tax for this transaction item is adjusted. Created automatically by Paddle.
  • proration
    A prorated amount for this transaction item is adjusted. Created automatically by Paddle in some cases when making changes to a subscription.
amountstring | nullrequired
Amount adjusted for this transaction item. Required when item type is partial.
prorationobject | nullrequired
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.
ratestringrequired
Rate used to calculate proration.
billing_periodobjectrequired
Billing period that proration is based on.
starts_atstring (date-time)required
Example: 2024-10-12T07:20:50.52Z
RFC 3339 datetime string of when this period starts.
ends_atstring (date-time)required
Example: 2024-10-12T07:20:50.52Z
RFC 3339 datetime string of when this period ends.
totalsobjectrequired
Breakdown of the total for an adjustment item.
subtotalstringrequired
Example: 15000
Amount multiplied by quantity.
taxstringrequired
Example: 1500
Total tax on the subtotal.
totalstringrequired
Example: 16500
Total after tax.
totalsobjectrequired
Breakdown of the total for an adjustment.
subtotalstringrequired
Example: 15000
Total before tax. For tax adjustments, the value is 0.
taxstringrequired
Example: 1500
Total tax on the subtotal.
totalstringrequired
Example: 16500
Total after tax.
feestringrequired
Example: 300
Total fee taken by Paddle for this adjustment.
retained_feestring
Example: 300
Paddle fees retained for this adjustment.
earningsstringrequired
Example: 14700
Total earnings. This is the subtotal minus the Paddle 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_codestringrequired
Example: USD
Three-letter ISO 4217 currency code used for this adjustment.
Values
  • USD
    United States Dollar
  • EUR
    Euro
  • GBP
    Pound Sterling
  • JPY
    Japanese Yen
  • AUD
    Australian Dollar
+ Show all values
  • CAD
    Canadian Dollar
  • CHF
    Swiss Franc
  • HKD
    Hong Kong Dollar
  • SGD
    Singapore Dollar
  • SEK
    Swedish Krona
  • ARS
    Argentine Peso
  • BRL
    Brazilian Real
  • CLP
    Chilean Peso
  • CNY
    Chinese Yuan
  • COP
    Colombian Peso
  • CZK
    Czech Koruna
  • DKK
    Danish Krone
  • HUF
    Hungarian Forint
  • ILS
    Israeli Shekel
  • INR
    Indian Rupee
  • KRW
    South Korean Won
  • MXN
    Mexican Peso
  • NOK
    Norwegian Krone
  • NZD
    New Zealand Dollar
  • PEN
    Peruvian Sol
  • PLN
    Polish Zloty
  • RUB
    Russian Ruble
  • THB
    Thai Baht
  • TRY
    Turkish Lira
  • TWD
    New Taiwan Dollar
  • UAH
    Ukrainian Hryvnia
  • VND
    Vietnamese Dong
  • ZAR
    South African Rand
payout_totalsobject | nullrequired
Breakdown of how this adjustment affects your payout balance.
subtotalstringrequired
Example: 15000
Adjustment total before tax and fees.
taxstringrequired
Example: 1500
Total tax on the adjustment subtotal.
totalstringrequired
Example: 16500
Adjustment total after tax.
feestringrequired
Example: 300
Adjusted Paddle fee.
retained_feestringrequired
Example: 300
Paddle fees retained for this adjustment.
chargeback_feeobject
Chargeback fees incurred for this adjustment. Only returned when the adjustment action is chargeback or chargeback_warning.
amountstringrequired
Example: 1680
Chargeback fee converted into the payout currency.
originalobject | nullrequired
Chargeback fee before conversion to the payout currency. null when the chargeback fee is the same as the payout currency.
amountstringrequired
Example: 1500
Fee amount for this chargeback in the original currency.
currency_codestringrequired
Example: USD
Three-letter ISO 4217 currency code for the original chargeback fee.
Values
  • AUD
    Australian Dollar
  • CAD
    Canadian Dollar
  • EUR
    Euro
  • GBP
    Pound Sterling
  • USD
    United States Dollar
earningsstringrequired
Example: 15120
Adjusted payout earnings. This is the adjustment total plus adjusted Paddle fees, excluding chargeback fees.
currency_codestringrequired
Three-letter ISO 4217 currency code used for the payout for this transaction. If your primary currency has changed, this reflects the primary currency at the time the transaction was billed.
Values
  • AUD
    Australian Dollar
  • CAD
    Canadian Dollar
  • CHF
    Swiss Franc
  • CNY
    Chinese Yuan
  • CZK
    Czech Koruna
+ Show all values
  • DKK
    Danish Krone
  • EUR
    Euro
  • GBP
    Pound Sterling
  • HUF
    Hungarian Forint
  • PLN
    Polish Zloty
  • SEK
    Swedish Krona
  • USD
    United States Dollar
  • ZAR
    South African Rand
tax_rates_usedarrayrequired
tax_ratestringrequired
Example: 0.2
Rate used to calculate tax for this adjustment.
totalsobjectrequired
Calculated totals for the tax applied to this adjustment.
subtotalstringrequired
Example: 15000
Total before tax. For tax adjustments, the value is 0.
taxstringrequired
Example: 1500
Total tax on the subtotal.
totalstringrequired
Example: 16500
Total after tax.
created_atstring (date-time)required
Example: 2024-10-12T07:20:50.52Z
RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
updated_atstring (date-time)required
Example: 2024-10-13T07:20:50.52Z
RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
metaobjectrequired
Information about this response.
request_idstringrequired
Example: b15ec92e-8688-40d4-a04d-f44cbec93355
Unique ID for the request relating to this response. Provide this when contacting Paddle support about a specific request.
paginationobjectrequired
Keys used for working with paginated results.
per_pageintegerrequired
Number of entities per page for this response. May differ from the number requested if the requested number is greater than the maximum.
nextstring (uri)required
URL containing the query parameters of the original request, along with the after parameter that marks the starting point of the next page. Always returned, even if has_more is false.
has_morebooleanrequired
Whether this response has another page.
estimated_totalinteger
Example: 999
Estimated number of entities for this response.
Response
{
  "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",
        "retained_fee": "5"
      },
      "payout_totals": {
        "subtotal": "92",
        "tax": "8",
        "total": "100",
        "fee": "5",
        "earnings": "87",
        "currency_code": "USD",
        "retained_fee": "5",
        "chargeback_fee": {
          "amount": "10",
          "original": null
        }
      },
      "created_at": "2024-04-15T08:48:20.239695Z",
      "updated_at": "2024-04-15T08:48:20.239695Z",
      "credit_applied_to_balance": null,
      "tax_rates_used": []
    },
    {
      "id": "adj_01hp46vn5px3nntyy2hr8gnv73",
      "action": "credit",
      "type": "partial",
      "credit_applied_to_balance": true,
      "transaction_id": "txn_01hp46m5hyz2g3e9ar31pzy2kc",
      "subscription_id": "sub_01hp463gxfvndqjjyqn2n7tkth",
      "customer_id": "ctm_01hp462x4578nc20acj9g956yy",
      "reason": "subscription_recurring",
      "currency_code": "USD",
      "status": "pending_approval",
      "items": [
        {
          "id": "adjitm_01hp46vn5qkvqg09m1r8qkdwrx",
          "item_id": "txnitm_01hp46m5xkw9zthfvxre4dgtp0",
          "type": "proration",
          "amount": "163261",
          "proration": {
            "rate": "0.9999",
            "billing_period": {
              "starts_at": "2024-02-08T11:15:15.582Z",
              "ends_at": "2024-03-08T11:02:03.946454Z"
            }
          },
          "totals": {
            "subtotal": "149953",
            "tax": "13308",
            "total": "163261"
          }
        },
        {
          "id": "adjitm_01hp46vn5qkvqg09m1ra13rqsj",
          "item_id": "txnitm_01hp46m5xkw9zthfvxrpf9r0pd",
          "type": "proration",
          "amount": "31020",
          "proration": {
            "rate": "0.9999",
            "billing_period": {
              "starts_at": "2024-02-08T11:15:15.596Z",
              "ends_at": "2024-03-08T11:02:03.946454Z"
            }
          },
          "totals": {
            "subtotal": "28491",
            "tax": "2529",
            "total": "31020"
          }
        }
      ],
      "totals": {
        "subtotal": "178444",
        "tax": "15837",
        "total": "194281",
        "fee": "9764",
        "retained_fee": "9764",
        "earnings": "168680",
        "currency_code": "USD"
      },
      "payout_totals": {
        "subtotal": "178444",
        "tax": "15837",
        "total": "194281",
        "fee": "9764",
        "earnings": "168680",
        "currency_code": "USD",
        "retained_fee": "9764",
        "chargeback_fee": {
          "amount": "0",
          "original": null
        }
      },
      "created_at": "2024-02-08T11:15:15.779373Z",
      "updated_at": "2024-02-08T11:15:15.779374Z",
      "tax_rates_used": []
    },
    {
      "id": "adj_01hkrape8pq0s8yxbpd76htz33",
      "action": "credit",
      "type": "partial",
      "credit_applied_to_balance": true,
      "transaction_id": "txn_01hj327s2cpxh4mprx55p5qwdz",
      "subscription_id": "sub_01hj32a99syawqhdkkbpxacwgb",
      "customer_id": "ctm_01hj3289s46amtzv8vr57xtnxp",
      "reason": "subscription_recurring",
      "currency_code": "USD",
      "status": "approved",
      "items": [
        {
          "id": "adjitm_01hkrape8pq0s8yxbpdcrkakf4",
          "item_id": "txnitm_01hj328ac2ak7h82bjg443x4px",
          "type": "proration",
          "amount": "6783",
          "proration": {
            "rate": "0.62305",
            "billing_period": {
              "starts_at": "2024-01-01T00:00:00Z",
              "ends_at": "2024-01-20T07:33:49.542313Z"
            }
          },
          "totals": {
            "subtotal": "6230",
            "tax": "553",
            "total": "6783"
          }
        },
        {
          "id": "adjitm_01hkrape8pq0s8yxbpd9x3bp1f",
          "item_id": "txnitm_01hj328ac2ak7h82bjfzdk992c",
          "type": "proration",
          "amount": "20350",
          "proration": {
            "rate": "0.62305",
            "billing_period": {
              "starts_at": "2024-01-01T00:00:00Z",
              "ends_at": "2024-01-20T07:33:49.542313Z"
            }
          },
          "totals": {
            "subtotal": "18691",
            "tax": "1659",
            "total": "20350"
          }
        }
      ],
      "totals": {
        "subtotal": "24921",
        "tax": "2212",
        "total": "27133",
        "fee": "1378",
        "retained_fee": "1378",
        "earnings": "23543",
        "currency_code": "USD"
      },
      "payout_totals": {
        "subtotal": "24921",
        "tax": "2212",
        "total": "27133",
        "fee": "1378",
        "earnings": "23543",
        "currency_code": "USD",
        "retained_fee": "1378",
        "chargeback_fee": {
          "amount": "0",
          "original": null
        }
      },
      "created_at": "2024-01-10T00:00:02.343628Z",
      "updated_at": "2024-01-10T00:00:05.88352Z",
      "tax_rates_used": []
    },
    {
      "id": "adj_01hkmv8zzdphm0szm330xw4ryh",
      "action": "credit_reverse",
      "type": "partial",
      "credit_applied_to_balance": true,
      "transaction_id": "txn_01hkmv58gk496gyak35j4gt1nh",
      "subscription_id": "sub_01hkmv7trnae9vbksdqpmctnmg",
      "customer_id": "ctm_01hkmv5x0djj0xae30nmqxmdc0",
      "reason": "subscription_update_failed",
      "currency_code": "USD",
      "status": "approved",
      "items": [
        {
          "id": "adjitm_01hkmv8zzdphm0szm3314waab3",
          "item_id": "txnitm_01hkmv5xkdf83cvkevfy9z2s4m",
          "type": "proration",
          "amount": "-32662",
          "proration": {
            "rate": "1",
            "billing_period": {
              "starts_at": "2024-01-08T15:32:46.434Z",
              "ends_at": "2024-02-08T15:32:10.959052Z"
            }
          },
          "totals": {
            "subtotal": "-30000",
            "tax": "-2662",
            "total": "-32662"
          }
        }
      ],
      "totals": {
        "subtotal": "-30000",
        "tax": "-2662",
        "total": "-32662",
        "fee": "-1658",
        "retained_fee": "-1658",
        "earnings": "-28342",
        "currency_code": "USD"
      },
      "payout_totals": {
        "subtotal": "-30000",
        "tax": "-2662",
        "total": "-32662",
        "fee": "-1658",
        "earnings": "-28342",
        "currency_code": "USD",
        "retained_fee": "-1658",
        "chargeback_fee": {
          "amount": "0",
          "original": null
        }
      },
      "created_at": "2024-01-08T15:32:49.774707Z",
      "updated_at": "2024-01-08T15:32:49.774707Z",
      "tax_rates_used": []
    },
    {
      "id": "adj_01hkmv8wv1e8yt0k1q0h5h2cq2",
      "action": "credit",
      "type": "partial",
      "credit_applied_to_balance": true,
      "transaction_id": "txn_01hkmv58gk496gyak35j4gt1nh",
      "subscription_id": "sub_01hkmv7trnae9vbksdqpmctnmg",
      "customer_id": "ctm_01hkmv5x0djj0xae30nmqxmdc0",
      "reason": "subscription_recurring",
      "currency_code": "USD",
      "status": "reversed",
      "items": [
        {
          "id": "adjitm_01hkmv8wv1e8yt0k1q0kskhgks",
          "item_id": "txnitm_01hkmv5xkdf83cvkevfy9z2s4m",
          "type": "proration",
          "amount": "32662",
          "proration": {
            "rate": "1",
            "billing_period": {
              "starts_at": "2024-01-08T15:32:46.434Z",
              "ends_at": "2024-02-08T15:32:10.959052Z"
            }
          },
          "totals": {
            "subtotal": "30000",
            "tax": "2662",
            "total": "32662"
          }
        }
      ],
      "totals": {
        "subtotal": "30000",
        "tax": "2662",
        "total": "32662",
        "fee": "1658",
        "retained_fee": "1658",
        "earnings": "28342",
        "currency_code": "USD"
      },
      "payout_totals": {
        "subtotal": "30000",
        "tax": "2662",
        "total": "32662",
        "fee": "1658",
        "earnings": "28342",
        "currency_code": "USD",
        "retained_fee": "1658",
        "chargeback_fee": {
          "amount": "0",
          "original": null
        }
      },
      "created_at": "2024-01-08T15:32:46.571866Z",
      "updated_at": "2024-01-08T15:32:49.774707Z",
      "tax_rates_used": []
    }
  ],
  "meta": {
    "request_id": "8295b301-8306-436d-813a-55f6ed03ccf8",
    "pagination": {
      "per_page": 10,
      "next": "https://api.paddle.com/adjustments?after=adj_01hkmv8wv1e8yt0k1q0h5h2cq2",
      "has_more": false,
      "estimated_total": 5
    }
  }
}

Was this page helpful?