Docs

Create an adjustment

Creates an adjustment for one or more transaction items.

POST /adjustments

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.

Requires adjustment.write permission.

Request body

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

Values
  • external
    Amounts are exclusive of tax.
  • internal
    Amounts are inclusive of tax.
transaction_idstringrequired
Example: txn_01h04vsbhqc62t8hmd4z3b578c

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.

Pattern: ^txn_[a-z\d]{26}$
reasonstringrequired
Why this adjustment was created. Appears in the Paddle dashboard. Retained for recordkeeping purposes.
Pattern: .*\S.*
itemsarray | null
List of transaction items to adjust. Required if type is not populated or set to partial.
Items: 1–100
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 | null
Amount adjusted for this transaction item. Required when item type is partial.

Response (201)

dataobjectrequired
Represents an adjustment entity.
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.
Request
{
  "action": "refund",
  "items": [
    {
      "item_id": "txnitm_01hvcc94b7qgz60qmrqmbm19zw",
      "type": "partial",
      "amount": "100"
    }
  ],
  "reason": "error",
  "transaction_id": "txn_01hvcc93znj3mpqt1tenkjb04y"
}
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": []
  },
  "meta": {
    "request_id": "c1906ac5-c210-4443-ba9b-122ecaeb506d"
  }
}

Was this page helpful?