Adjustments

Adjustment entities describe a post-billing adjustment to a billed or completed transaction.

Billed transactions are considered financial records for tax and legal purposes, so they can't be changed. Adjustments let you record actions that impact revenue for a transaction after it's been billed.

You can create adjustments for billed or completed transactions to refund or credit all or part of a transaction.

Most refunds for live accounts must be approved by Paddle, but some are automatically approved. For sandbox accounts, Paddle automatically approves all refunds every ten minutes.

Where customers raise a chargeback with their payment method issuer, Paddle automatically creates an adjustment to refund the disputed amount.

Adjustment entities hold information like:

What kind of adjustment it is.
Why the adjustment was created.
Which transaction and items an adjustment is for.
Calculated totals for an adjustment.

Adjustments work with transactions, subscriptions, and customers.

Adjustments are financial records. They can't be deleted or changed once they've been created. Contact Paddle if you need help with an adjustment.

Work with adjustments

Refund or credit a transaction

Cancel an invoice

Attributes

idstring

Unique Paddle ID for this adjustment entity, prefixed with adj_.

actionstring

How this adjustment impacts the related transaction.

transaction_idstring

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

subscription_idstring or null

Paddle ID for the subscription related to this adjustment, prefixed with sub_. Set automatically by Paddle based on the subscription_id of the related transaction.

customer_idstring

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.

reasonstring

Why this adjustment was created. Appears in the Paddle dashboard. Retained for record-keeping purposes.

credit_applied_to_balanceboolean or null

Whether this adjustment was applied to the related customer's credit balance. Only returned for credit adjustments.

false where the related transaction is billed. The adjustment reduces the amount due on the transaction.

true where the related transaction is completed. The amount is added the customer's credit balance and used to pay future transactions.

currency_codestring

Three-letter ISO 4217 currency code for this adjustment. Set automatically by Paddle based on the currency_code of the related transaction.

statusstring

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.

itemsarray[object]

List of items on this adjustment.

idstring

Unique Paddle ID for this adjustment item, prefixed with adjitm_.

item_idstring

Paddle ID for the transaction item that this adjustment item relates to, prefixed with txnitm_.

typestring

Type of adjustment for this transaction item. tax adjustments are automatically created by Paddle. Include amount when creating a partial adjustment.

amountstring or null

Amount adjusted for this transaction item. Required when adjustment type is partial.

prorationobject or null

How proration was calculated for this adjustment item.

totalsobject

Breakdown of the total for an adjustment item.

totalsobject

Breakdown of the total for an adjustment.

subtotalstring

Total before tax. For tax adjustments, the value is 0.

taxstring

Total tax on the subtotal.

totalstring

Total after tax.

feestring

Total fee taken by Paddle for this adjustment.

earningsstring

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_codestring

Three-letter ISO 4217 currency code used for this adjustment.

payout_totalsobject or null

Breakdown of how this adjustment affects your payout balance.

subtotalstring

Adjustment total before tax and fees.

taxstring

Total tax on the adjustment subtotal.

totalstring

Adjustment total after tax.

feestring

Adjusted Paddle fee.

chargeback_feeobject

Chargeback fees incurred for this adjustment. Only returned when the adjustment action is chargeback or chargeback_warning.

amountstring

Chargeback fee converted into the payout currency.

originalobject or null

Chargeback fee before conversion to the payout currency. null when the chargeback fee is the same as the payout currency.

earningsstring

Adjusted payout earnings. This is the adjustment total plus adjusted Paddle fees, excluding chargeback fees.

currency_codestring

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.

tax_rates_usedarray[object]

List of tax rates applied for this adjustment.

tax_ratestring

Rate used to calculate tax for this adjustment.

totalsobject

Calculated totals for the tax applied to this adjustment.

created_atstring<date-time>

RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.

updated_atstring<date-time>

RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.

List adjustments

gethttps://api.paddle.com/adjustments

Create an adjustment

posthttps://api.paddle.com/adjustments