create_transaction
Create new transactions in Paddle for automated checkout payments or manual invoicing workflows, handling customer billing and subscription setup.
Instructions
This tool will create a new transaction in Paddle.
Don't use this tool without checking with the user first. Avoid using before gaining explicit approval.
The collectionMode against a transaction determines how Paddle tries to collect for payment:
Manually-collected transactions are for sales-assisted billing. Paddle sends an invoice to the customer when a transaction is billed. Payment is often by wire transfer. Requires billingDetails, and an address which has country, postalCode, region, city, and firstLine.
Automatically-collected transactions are for payments collected automatically using a self-serve checkout where payment is collected using a checkout. Pass the transaction to a checkout or use the returned checkout.url to collect for payment. checkout.url is a unique Paddle payment link composed of the URL passed as checkout.url, or the default payment URL on the account, with ?_ptxn= and the Paddle ID for this transaction appended to the URL.
Transactions have a status. Set the status or omit it to have Paddle set it. It's only recommended to set the status manually if working with manually-collected transactions as part of an invoicing workflow. Options are:
billed: Marks as finalized and can't be updated, only canceled. This is essentially issuing an invoice. At this point, it becomes a legal record so it can't be changed. Paddle automatically assigns an invoice number, creates a related subscription, and sends it to the customer.
canceled: Canceled transactions are no longer due. This is only for record purposes on creation.
When status is omitted, transactions are initially created with the status of draft or ready:
Draft transactions have items against them, but don't have all of the required fields for billing. Paddle creates draft transactions automatically when a checkout is opened.
Paddle automatically marks transactions as ready when all of the required fields are present for billing. This includes customerId and addressId for automatically-collected transactions, and billingDetails for manually-collected transactions.
When a transaction has items which are recurring, and the transaction has a status of billed when manually-collected or completed when automatically-collected, Paddle automatically creates a related subscription for the items on the transaction. Use the returned subscriptionId to get the subscription entity.
Use the include parameter to include related entities in the response:
address: An object for the address entity related to this transaction. Only returned if an address is set against the transaction with addressId.
available_payment_methods: An array of payment methods that are available to use for this transaction.
business: An object for the business entity related to this transaction. Only returned if a business is set against the transaction with businessId.
customer: An object for the customer entity related to this transaction. Only returned if a customer is set against the transaction with customerId.
discount: An object for the discount entity related to this transaction. Only returned if a discount is set against the transaction with discount or discountId.
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.
Consider using the preview_transaction_create tool to preview and confirm the transaction before creating it.
If successful, the response includes a copy of the new transaction entity.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | Status of this transaction. Either set a transaction to `billed` or `canceled` when creating, or omit to let Paddle set the status. Transactions are created as `ready` if they have an `addressId`, `customerId`, and `items`, otherwise they are created as `draft`. Marking as `billed` when creating is typically used when working with manually-collected transactions as part of an invoicing workflow. Billed transactions cannot be updated, only canceled. | |
| customerId | No | Paddle ID of the customer that this transaction is for, prefixed with `ctm_`. If omitted, transaction status is `draft`. | |
| addressId | No | Paddle ID of the address that this transaction is for, prefixed with `add_`. Requires `customerId`. If omitted, transaction status is `draft`. | |
| businessId | No | Paddle ID of the business that this transaction is for, prefixed with `biz_`. Requires `customerId`. | |
| customData | No | Any structured custom key-value data needed outside of Paddle's standard fields. Occasionally used by third-parties. | |
| currencyCode | No | Supported three-letter ISO 4217 currency code. Must be `USD`, `EUR`, or `GBP` if `collectionMode` is `manual`. | |
| collectionMode | No | How payment is collected for this transaction. `automatic` for checkout, `manual` for invoices. If omitted, defaults to `automatic`. | |
| discountId | No | Paddle ID of the discount applied to this transaction, prefixed with `dsc_`. | |
| billingDetails | No | Details for invoicing. Required if `collectionMode` is `manual`. | |
| billingPeriod | No | Time period that this transaction is for. Set automatically by Paddle for subscription renewals to describe the period that charges are for. | |
| items | Yes | List of items to charge for. Charge for items that have been added to the catalog by passing the Paddle ID of an existing price entity, or charge for non-catalog items by passing a price object. Non-catalog items can be for existing products, or pass a product object as part of the price to charge for a non-catalog product. | |
| checkout | No | Paddle Checkout details for this transaction. Used for automatically-collected transactions, or when creating or updating a manually-collected transaction where `billingDetails.enableCheckout` is `true`. | |
| include | No | Include related entities in the response. Use a comma-separated list to specify multiple entities. |
Implementation Reference
- src/functions.ts:136-146 (handler)The main handler function that implements the logic for creating a transaction using the Paddle SDK by calling paddle.transactions.create(params).
export const createTransaction = async ( paddle: Paddle, params: z.infer<typeof Parameters.createTransactionParameters>, ) => { try { const transaction = await paddle.transactions.create(params); return transaction; } catch (error) { return error; } }; - src/tools.ts:385-395 (schema)Tool schema definition specifying the method name, description from prompts, input parameters Zod schema, and required actions (write/create on transactions).
method: "create_transaction", name: "Create a transaction", description: prompts.createTransactionPrompt, parameters: params.createTransactionParameters, actions: { transactions: { write: true, create: true, }, }, }, - src/api.ts:19-19 (registration)Maps the CREATE_TRANSACTION tool method to the createTransaction handler function in the API's toolMap.
[TOOL_METHODS.CREATE_TRANSACTION]: funcs.createTransaction, - src/constants.ts:11-11 (helper)Constant exporting the string identifier for the create_transaction tool method.
CREATE_TRANSACTION: "create_transaction",