create_adjustment
Create refunds or credits for billed transactions by specifying transaction details, adjustment type, and tax calculation method to record revenue-impacting actions after billing.
Instructions
This tool will create an adjustment to refund or credit all or part of a transaction and its items.
Billed transactions are considered financial records for tax and legal purposes, so they can't be changed. Adjustments record actions that impact revenue for a transaction after it's been billed.
Don't use this tool without checking with the user first. Avoid using before gaining explicit approval.
The transaction ID and the IDs of any transaction items (details.lineItems[].id) are required to create a refund or credit.
An adjustment can have an action of credit or refund:
Refunds return an amount to a customer's original payment method. Create refund adjustments for transactions that are completed.
Credits reduce the amount that a customer has to pay for a transaction. Create credit adjustments for 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.
Other action types (chargeback, chargeback_reverse, chargeback_warning, chargeback_warning_reverse, credit_reverse) are automatically created by Paddle and can't be set manually.
Adjustments can apply to some or all items on a transaction by defining the type:
full: The grand total for the related transaction is adjusted.
partial: Some line items for the related transaction are adjusted. Requires items.
When selecting taxMode, choose the one that best describes how the tax should be calculated for the adjustment:
external: Amounts are exclusive of tax. Common in European countries.
internal: Amounts are inclusive of tax. Common in countries like the United States and Canada.
Creating an adjustment for a transaction that has a refund that's pending approval isn't possible.
Ensure you have all the information needed before making the call. Don't fabricate, imagine, or infer details and parameter values unless explicitly asked to. If anything is ambiguous, unknown, or unclear, ask the user for clarification or details before you proceed.
If successful, the response includes a copy of the new adjustment entity.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | How this adjustment impacts the related transaction. | |
| type | No | 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`. | |
| taxMode | No | 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`. | |
| transactionId | Yes | Paddle ID of the transaction that this adjustment is for, prefixed with `txn_`. Automatically-collected transactions must be `completed`, and manually-collected transactions must be `billed` or `past_due`. | |
| reason | Yes | Why this adjustment was created. Appears in the Paddle dashboard. Retained for record-keeping purposes. | |
| items | Yes | List of transaction items to adjust. Required if `type` is not populated or set to `partial`. |
Implementation Reference
- src/functions.ts:218-228 (handler)The handler function that implements the core logic of the 'create_adjustment' tool by calling Paddle's adjustments.create API.
export const createAdjustment = async ( paddle: Paddle, params: z.infer<typeof Parameters.createAdjustmentParameters>, ) => { try { const adjustment = await paddle.adjustments.create(params); return adjustment; } catch (error) { return error; } }; - src/tools.ts:480-491 (schema)The tool schema defining the input parameters (Zod schema), description, name, method, and required permissions/actions for the create_adjustment tool.
{ method: "create_adjustment", name: "Create an adjustment", description: prompts.createAdjustmentPrompt, parameters: params.createAdjustmentParameters, actions: { adjustments: { write: true, create: true, }, }, }, - src/api.ts:26-26 (registration)Registration of the createAdjustment handler function in the toolMap dictionary used by the PaddleAPI class to map tool method names to their implementations.
[TOOL_METHODS.CREATE_ADJUSTMENT]: funcs.createAdjustment, - src/constants.ts:18-18 (helper)Constant defining the string identifier for the CREATE_ADJUSTMENT tool method, used in registration and schema.
CREATE_ADJUSTMENT: "create_adjustment",