Create an adjustment

posthttps://api.paddle.com/adjustments

Creates an adjustment for one or more transaction items.

You may create adjustments for billed or completed transactions:

Where an adjustment is for a manually-collected transaction with the status of billed (an issued invoice), credit adjustments reduce the balance to pay on the invoice.
Where an adjustment is a refund, the total is returned to a customer's original payment method.

You can't create credits for automatically-collected transactions. Paddle creates and manages credits for automatically-collected transactions when you make changes to the related subscription and choose to prorate.

Refunds must be approved by Paddle. They're created with the status pending_approval, before moving to approved or rejected.

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.

Request Body

actionstringrequired

How this adjustment impacts the related transaction. refund adjustments must be approved by Paddle, and are created with the status pending_approval.

itemsarray[object]required

List of items on this adjustment.

item_idstringrequired

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

typestringrequired

Type of adjustment for this transaction item. tax and proration 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.

reasonstringrequired

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

transaction_idstringrequired

Paddle ID for the transaction related to this adjustment, prefixed with txn_. Transactions must be billed or completed. You can't create an adjustment for a transaction that has an adjustment that's pending_approval.

Response

dataobject

Represents an adjustment entity.

idstring

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

actionstring

How this adjustment impacts the related transaction. refund adjustments must be approved by Paddle, and are created with the status pending_approval.

transaction_idstring

Paddle ID for the transaction related to this adjustment, 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 when the related transaction collection_mode is manual and its status is billed. The adjustment is used to reduce the balance due on the transaction.

true for automatically-collected transactions and completed manually-collected 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.

refund adjustments must be approved by Paddle, and are created with the status pending_approval until they move to approved or rejected on review. Other kinds of adjustment do not need approval, so are created with the status approved.

itemsarray[object]

List of items on this adjustment.

totalsobject

Breakdown of the total for an adjustment.

payout_totalsobject or null

Breakdown of how this adjustment affects your payout balance.

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.

metaobject

Information about this response.

request_idstring

Unique ID for the request relating to this response. Provide this when contacting Paddle support about a specific request.

Request

1
2
3
4
5
6
7
8
9
10
11
12
1{
2  "action": "refund",
3  "items": [
4    {
5      "item_id": "txnitm_01hvcc94b7qgz60qmrqmbm19zw",
6      "type": "partial",
7      "amount": "100"
8    }
9  ],
10  "reason": "error",
11  "transaction_id": "txn_01hvcc93znj3mpqt1tenkjb04y"
12}

Response