# POST /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](https://developer.paddle.com/build/transactions/create-transaction-adjustments#background-refunds). 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.

**Required permissions:** `adjustment.write`

## Request body

- `action`: string (required) — How this adjustment impacts the related transaction.
- `type`: string — 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`.
- `tax_mode`: string — 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`.
- `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. (pattern: `^txn_[a-z\d]{26}$`)
- `reason`: string (required) — Why this adjustment was created. Appears in the Paddle dashboard. Retained for recordkeeping purposes. (pattern: `.*\S.*`)
- `items` — List of transaction items to adjust. Required if `type` is not populated or set to `partial`. (Items: 1–100)

### Request example

```json
{
  "action": "refund",
  "items": [
    {
      "item_id": "txnitm_01hvcc94b7qgz60qmrqmbm19zw",
      "type": "partial",
      "amount": "100"
    }
  ],
  "reason": "error",
  "transaction_id": "txn_01hvcc93znj3mpqt1tenkjb04y"
}
```

## Response (201)

- `data`: object (required) — Represents an adjustment entity.
  - `id`: string (required) — Unique Paddle ID for this adjustment entity, prefixed with `adj_`. (pattern: `^adj_[a-z\d]{26}$`)
  - `action`: string (required) — How this adjustment impacts the related transaction.
  - `type`: string (required) — 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`.
  - `transaction_id`: string (required) — Paddle ID of the transaction that this adjustment is for, prefixed with `txn_`. (pattern: `^txn_[a-z\d]{26}$`)
  - `subscription_id` (required) — 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_id`: string (required) — 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}$`)
  - `reason`: string (required) — Why this adjustment was created. Appears in the Paddle dashboard. Retained for record-keeping purposes.
  - `credit_applied_to_balance` — Whether this adjustment was applied to the related customer's credit balance. Only returned for `credit` adjustments.
  - `currency_code`: string (required) — Three-letter ISO 4217 currency code for this adjustment. Set automatically by Paddle based on the `currency_code` of the related transaction.
  - `status`: string (required) — 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`.
  - `items`: array (required) — List of items on this adjustment. Required if `type` is not populated or set to `partial`. (Items: 1–100)
  - `totals`: object (required) — Breakdown of the total for an adjustment.
    - `subtotal`: string (required) — Total before tax. For tax adjustments, the value is 0.
    - `tax`: string (required) — Total tax on the subtotal.
    - `total`: string (required) — Total after tax.
    - `fee`: string (required) — Total fee taken by Paddle for this adjustment.
    - `retained_fee`: string — Paddle fees retained for this adjustment.
    - `earnings`: string (required) — 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_code`: string (required) — Three-letter ISO 4217 currency code used for this adjustment.
  - `payout_totals` (required) — Breakdown of how this adjustment affects your payout balance.
  - `tax_rates_used`: array (required)
  - `created_at`: string (date-time) (required) — RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
  - `updated_at`: string (date-time) (required) — RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
- `meta`: object (required) — Information about this response.
  - `request_id`: string (required) — Unique ID for the request relating to this response. Provide this when contacting Paddle support about a specific request.

### Response example

```json
{
  "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"
  }
}
```