Paddle MCP Server

This tool will list products in the account's catalog.

Use the maximum perPage by default (200) to ensure comprehensive results. Filter products by id, status, taxCategory, and type as needed. Results are paginated - use the 'after' parameter with the last ID from previous results to get the next page. Sort and order results using the orderBy parameter. Amounts are in the smallest currency unit (e.g., cents).

Use the include parameter to include related entities in the response:

• prices: An array of price entities tied to the product.

This tool will create a new product in Paddle.

Product entities describe the items that customers can purchase. Products work with prices, which describe how much a product costs and how often it's billed.

For imageUrl, images must be hosted on an HTTPS server that's publicly accessible. Paddle doesn't upload product images to a CDN. It's recommended to use square images (1:1 ratio).

When selecting a taxCategory, choose the one that best describes the product:

• digital-goods: Non-customizable digital files or media (not software) acquired with an up front payment that can be accessed without any physical product being delivered.

• ebooks: Digital books and educational material which is sold with permanent rights for use by the customer.

• implementation-services: Remote configuration, set-up, and integrating software on behalf of a customer.

• professional-services: Services that involve the application of expertise and specialized knowledge of a software product.

• saas: Products that allow users to connect to and use online or cloud-based applications over the Internet.

• software-programming-services: Services that can be used to customize and white label software products.

• standard: Software products that are pre-written and can be downloaded and installed onto a local device.

• training-services: Training and education services related to software products.

• website-hosting: Cloud storage service for personal or corporate information, assets, or intellectual property.

The tax category affects how taxes are calculated in different jurisdictions. Choose carefully as it impacts customers' tax rates. When using the standard tax category, remind the user to review the tax category in the Paddle dashboard.

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 product entity. Once a product has been created, relate it to a price.

This tool will retrieve a product from Paddle by its ID.

Use the include parameter to include related entities in the response:

• prices: An array of price entities available for the product.

This tool will list prices in the account's catalog.

Use the maximum perPage by default (200) to ensure comprehensive results. Filter prices by id, productId, status, recurring, and type as needed. Results are paginated - use the 'after' parameter with the last ID from previous results to get the next page. Sort and order results using the orderBy parameter. Amounts are in the smallest currency unit (e.g., cents).

Use the include parameter to include related entities in the response:

• product: An object for the product entity that's tied to the price.

This tool will create a new price in Paddle.

Prices describe how to charge for products. Always include a productId in the request to relate the price to a product.

If the quantity object is omitted, Paddle automatically sets a minimum of 1 and a maximum of 100. This means the most units that a customer can buy is 100. Set a quantity to offer a different amount.

When selecting type, choose the one that best describes the use case:

• custom: Non-catalog item. Typically created for a specific transaction or subscription. Not returned when listing or shown in the Paddle dashboard.

• standard: Standard item. Can be considered part of the catalog and reused across transactions and subscriptions easily.

When selecting taxMode, choose the one that best describes how the tax should be calculated for the price:

• account_setting: Price uses the setting from the account. Default.

• external: Price is exclusive of tax. Common in European countries.

• internal: Price is inclusive of tax. Common in countries like the United States and Canada.

When using unitPriceOverrides:

• Group countries based on purchasing power parity (PPP), not just currency zones

• Create separate overrides for countries with different economic conditions even if they share the same currency (e.g., Greece and Ireland should have different price points)

• Adjust prices relative to local economic conditions - higher in wealthy markets, lower in developing economies

• For optimal conversion rates, set prices using local market research and willingness-to-pay data

• Use local currencies where preferred by the customer

Example unitPriceOverrides structure: [ { "countryCodes": ["GB"], "unitPrice": { "amount": "8500", "currencyCode": "GBP" } }, { "countryCodes": ["IE"], "unitPrice": { "amount": "9500", "currencyCode": "EUR" } }, { "countryCodes": ["GR"], "unitPrice": { "amount": "6500", "currencyCode": "EUR" } }, { "countryCodes": ["IN"], "unitPrice": { "amount": "30000", "currencyCode": "INR" } }, { "countryCodes": ["CN"], "unitPrice": { "amount": "20000", "currencyCode": "CNY" } } ]

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 price entity.

This tool will retrieve a price from Paddle by its ID.

Use the include parameter to include related entities in the response:

• product: An object for the product entity tied to the price.

This tool will list discounts in the account's catalog.

Use the maximum perPage by default (200) to ensure comprehensive results. Filter discounts by code, id, status, and mode as needed. Results are paginated - use the 'after' parameter with the last ID from previous results to get the next page. Sort and order results using the orderBy parameter.

Amounts are in the smallest currency unit (e.g., cents).

This tool will create a new discount in Paddle.

Discounts reduce a transaction total. They're sometimes called coupons or promo codes.

Use discount codes to let customers apply discounts themselves at checkout, or apply discounts manually to transactions as part of the sales process.

Discounts can be added to a discount group to organize them. Only one discount group can be added at a time. List discounts by discount groups with the list_discount_groups tool to see which discounts are in which groups.

When selecting type, choose the one that best describes how to apply the discount to the total:

• flat: Discounts a checkout or transaction by a flat amount, for example -$100. Requires currencyCode.

• flat_per_seat: Discounts a checkout or transaction by a flat amount per unit, for example -$100 per user. Requires currencyCode.

• percentage: Discounts a checkout or transaction by a percentage of the total, for example -10%. Maximum 100%.

When selecting mode, choose the one that best describes the use case:

• standard: Standard discount. Can be considered part of the listed catalog and reused across transactions and subscriptions easily.

• custom: Non-catalog discount. Custom, one-off discounts. Includes checkout recovery discounts. Not returned when listing or shown in the Paddle dashboard.

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 discount entity. Discounts can be applied to transactions, subscriptions, or passed to checkout through Paddle.js.

This tool will retrieve a discount from Paddle by its ID.

This tool will list discount groups in the account's catalog.

Use the maximum perPage by default (200) to ensure comprehensive results. Filter discount groups by id as needed. Results are paginated - use the 'after' parameter with the last ID from previous results to get the next page. Sort and order results using the orderBy parameter.

This tool will create a new discount group in Paddle.

Discount groups are used to organize and manage related discounts under a group name. Create one when managing multiple discounts together, like for a campaign, promotion, or team.

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 discount group entity.

This tool will retrieve a discount group from Paddle by its ID.

This tool will list customers in Paddle.

Use the maximum perPage by default (200) to ensure comprehensive results. Filter customers by email, id, search (fuzzy search on the customer's name), and status as needed. Results are paginated - use the 'after' parameter with the last ID from previous results to get the next page. Sort and order results using the orderBy parameter.

This tool will create a new customer in Paddle.

Customer entities hold information about the people and businesses that make purchases.

Customers have two sub-entities:

• addresses: Customers require an address to make a purchase, which can be created through the create_address tool. Can have multiple addresses.

• businesses: Customers can optionally be associated with businesses, which can be created through the create_business tool.

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 customer entity.

This tool will retrieve a customer from Paddle by its ID.

This tool will list addresses for a customer in Paddle.

Use the maximum perPage by default (200) to ensure comprehensive results. Filter addresses by id, search (fuzzy search on the address's street, city, state, postalCode, or country), and status as needed. Results are paginated - use the 'after' parameter with the last ID from previous results to get the next page. Sort and order results using the orderBy parameter.

This tool will create a new address for a customer in Paddle.

Address entities hold billing address information for a customer. Customers must have an address to make a purchase. A transaction can be created without an address, but it can't go past a status of draft until an address is added.

To make buying as frictionless as possible, Paddle only requires a country. For tax calculation, fraud prevention, and compliance purposes, postalCode is required when creating addresses for some countries, like ZIP codes in the USA and postcodes in the UK.

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 address entity.

This tool will retrieve an address for a customer from Paddle using its ID and related customer ID.

This tool will list businesses for a customer in Paddle.

Use the maximum perPage by default (200) to ensure comprehensive results. Filter businesses by id, search (fuzzy search on the business's name or tax or VAT number), and status as needed. Results are paginated - use the 'after' parameter with the last ID from previous results to get the next page. Sort and order results using the orderBy parameter.

This tool will create a new business for a customer in Paddle.

Business entities hold business information for a customer when working with a business rather than an individual. Customers do not need to have a business to make a purchase, but should if working with a business.

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 business entity.

This tool will retrieve a business for a customer from Paddle using its ID and related customer ID.

This tool will list transactions in Paddle.

Use the maximum perPage by default (30) to ensure comprehensive results. Filter transactions by billedAt, collectionMode, createdAt, customerId, id, invoiceNumber, origin, status, subscriptionId, and updatedAt as needed. Results are paginated - use the 'after' parameter with the last ID from previous results to get the next page. Sort and order results using the orderBy parameter. Amounts are in the smallest currency unit (e.g., cents).

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.

• adjustments: An array of adjustment entities related to this transaction. Only returned if adjustments have been created against the transaction.

• adjustments_totals: An object containing totals for all adjustments on a transaction. Only returned if adjustments have been created against the transaction.

• 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.

• customer: An object for the customer entity related to this transaction. Only returned if a customer is set against the transaction.

• discount: An object for the discount entity related to this transaction. Only returned if a discount is set against the transaction.

Transactions have a collectionMode that determines how Paddle tries to collect for payment:

• automatic: Payment is collected automatically using a checkout initially, then using a payment method on file.

• manual: Payment is collected manually. Customers are sent an invoice with payment terms and can make a payment offline or using a checkout. Requires billingDetails.

Transactions have a status that determines the current state of the transaction:

• draft: Transaction is missing required fields. Typically the first stage of a checkout before customer details are captured.

• ready: Transaction has all of the required fields to be marked as billed or completed.

• billed: Transaction has been updated to billed. Billed transactions get an invoice number and are considered a legal record. They can't be changed. Typically used as part of an invoice workflow.

• paid: Transaction is fully paid, but has not yet been processed internally.

• completed: Transaction is fully paid and processed.

• canceled: Transaction has been updated to canceled. If an invoice, it's no longer due.

• past_due: Transaction is past due. Occurs for automatically-collected transactions when the related subscription is in dunning, and for manually-collected transactions when payment terms have elapsed.

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.

This tool will retrieve a transaction from Paddle by its ID.

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.

• adjustments: An array of adjustment entities related to this transaction. Only returned if adjustments have been created against the transaction.

• adjustments_totals: An object containing totals for all adjustments on a transaction. Only returned if adjustments have been created against the transaction.

• 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.

• customer: An object for the customer entity related to this transaction. Only returned if a customer is set against the transaction.

• discount: An object for the discount entity related to this transaction. Only returned if a discount is set against the transaction.

Transactions have a collectionMode that determines how Paddle tries to collect for payment:

• automatic: Payment is collected automatically using a checkout initially, then using a payment method on file.

• manual: Payment is collected manually. Customers are sent an invoice with payment terms and can make a payment offline or using a checkout. Requires billingDetails.

Transactions have a status that determines the current state of the transaction:

• draft: Transaction is missing required fields. Typically the first stage of a checkout before customer details are captured.

• ready: Transaction has all of the required fields to be marked as billed or completed.

• billed: Transaction has been updated to billed. Billed transactions get an invoice number and are considered a legal record. They can't be changed. Typically used as part of an invoice workflow.

• paid: Transaction is fully paid, but has not yet been processed internally.

• completed: Transaction is fully paid and processed.

• canceled: Transaction has been updated to canceled. If an invoice, it's no longer due.

• past_due: Transaction is past due. Occurs for automatically-collected transactions when the related subscription is in dunning, and for manually-collected transactions when payment terms have elapsed.

This tool will preview price calculations for one or more prices.

Consider using the preview_transaction_create tool for more advanced and accurate pricing calculations or for all manually-collected invoiced transactions.

Providing location information when previewing prices allows Paddle to calculate tax or automatically localize prices. Provide one of the following:

• customer_ip_address: Paddle fetches location using the IP address to calculate totals.

• address: Paddle uses the country and ZIP code (where supplied) to calculate totals.

• customerId, addressId, businessId: Paddle uses existing customer data to calculate totals. Typically used for logged-in customers.

Each line item includes formattedUnitTotals and formattedTotals objects that return totals formatted for the country or region being worked with, including the currency symbol.

If successful, the response includes the data sent with a details object that includes totals for the supplied prices.

This tool will preview a transaction without creating a transaction entity.

Consider using the preview_prices tool for simpler pricing calculations where payment is often taken through checkout.

Providing location information when previewing a transaction allows Paddle to calculate tax or automatically localize prices. Provide one of the following:

• customer_ip_address: Paddle fetches location using the IP address to calculate totals.

• address: Paddle uses the country and ZIP code (where supplied) to calculate totals.

• customerId, addressId, businessId: Paddle uses existing customer data to calculate totals. Typically used for logged-in customers.

Exclude items from the total calculation using the includeInTotals boolean.

By default, recurring items with trials are considered to have a zero charge when previewing. Set ignoreTrials to true to ignore trial periods against prices for transaction preview calculations.

Transaction previews don't create transactions, so no id is returned.

If successful, the response includes the data sent with a details object that includes totals for the supplied prices.

This tool will retrieve a link to an invoice PDF for a transaction from Paddle.

Invoice PDFs are available for both automatically and manually-collected transactions:

• The PDF for manually-collected transactions includes payment terms, purchase order number, and notes for the customer. It's a demand for payment from the customer. Available for transactions billed or completed.

• The PDF for automatically-collected transactions lets the customer know that payment was taken successfully. Customers may require this for for tax-reporting purposes. Available for transactions completed.

Invoice PDFs aren't available for zero-value transactions.

The link returned isn't a permanent link. It expires after an hour.

This tool will list adjustments in Paddle.

Use the maximum perPage by default (50) to ensure comprehensive results. Filter adjustments by action, customerId, status, subscriptionId, transactionId, and id as needed. Results are paginated - use the 'after' parameter with the last ID from previous results to get the next page. Sort and order results using the orderBy parameter.

Amounts are in the smallest currency unit (e.g., cents).

Adjustments have an action that determines how the adjustment impacts the related transaction:

• credit: Credits some or all the related transaction. Can be created manually.

• refund: Refunds some or all the related transaction. Must be approved by Paddle in most cases. Can be created manually.

• chargeback: Chargeback for the related transaction. Automatically created by Paddle when a customer successfully disputes a charge.

• chargeback_reverse: Reversal of a chargeback for the related transaction. Automatically created by Paddle when Paddle contests a chargeback successfully.

• chargeback_warning: Warning of an upcoming chargeback for the related transaction. Automatically created by Paddle.

• chargeback_warning_reverse: Reversal of a chargeback warning for the related transaction. Automatically created by Paddle.

• credit_reverse: Reversal of a credit for the related transaction. Automatically created by Paddle.

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.

This tool will retrieve a link to a credit note PDF for an adjustment from Paddle.

Credit note PDFs are created for refunds and credits as a record of an adjustment. Return this if record is needed to be given to the customer immediately after the adjustment is created.

The link returned is not a permanent link. It expires after an hour.

This tool will list credit balances in each currency for a customer.

Credit balances are created automatically by Paddle when a customer takes an action that results in Paddle creating a credit for a customer, like making prorated changes to a subscription. These are transaction credits, not promotional credits like from discounts.

Each balance has three totals:

• available: Total available to use.

• reserved: Total temporarily reserved for billed transactions.

• used: Total amount of credit used.

Credit is added to the available total initially. When used, it moves to the used total.

The reserved total is used when a credit balance is applied to a transaction that's marked as billed, like when working with an issued invoice. It's not available for other transactions at this point, but isn't considered used until the transaction is completed. If a billed transaction is canceled, any reserved credit moves back to available.

A credit balance can only be used for transactions in the same currency.

Adding to a credit balance directly isn't possible. Create a credit adjustment with the create_adjustment tool to reduce the amount due to pay for a transaction instead.

Filter credit balances by currencyCode as needed. Amounts are in the smallest currency unit (e.g., cents).

The response isn't paginated. An empty array is returned if a customer has no credit balances.

This tool will retrieve a subscription from Paddle by its ID.

Use the include parameter to include related entities in the response:

• next_transaction: Include an object with a preview of the next transaction for this subscription. May include prorated charges that aren't yet billed and one-time charges.

• recurring_transaction_details: Include an object with a preview of the recurring transaction for this subscription. This is what the customer can expect to be billed when there are no prorated or one-time charges.

This tool will list subscriptions in Paddle.

Use the maximum perPage by default (200) to ensure comprehensive results. Filter subscriptions by addressId, collectionMode, customerId, id, priceId, scheduledChangeAction, and status as needed. Results are paginated - use the 'after' parameter with the last ID from previous results to get the next page. Sort and order results using the orderBy parameter.

Amounts are in the smallest currency unit (e.g., cents).

This tool will preview an update for a subscription without applying those changes.

It's best practice to preview every time before updating the subscription to confirm the changes are as expected, especially when making updates to items, billing periods, and anything affecting proration.

The updateSummary object contains details of prorated credits and charges created, along with the overall result of the update.

If successful, the response includes immediateTransaction, nextTransaction, and recurringTransactionDetails to see expected transactions for the changes.

This tool will create a one-time charge for a subscription in Paddle. Use to bill non-recurring items to a subscription. Non-recurring items are price entities where the billingCycle is null.

Don't use this tool without checking with the user first. Avoid using before gaining explicit approval.

When selecting effectiveFrom, choose the one that best describes when the one-time charges should be billed:

• next_billing_period: Bill for one-time charges on the next billing period. Paddle adds the charges to the transaction created when the subscription next renews.

• immediately: Bill for one-time charges now. Paddle creates a transaction for them right away. For automatically-collected subscriptions, responses may take longer than usual while a payment attempt is processed.

When selecting onPaymentFailure, choose the one that best describes how Paddle should handle subscription updates when payment fails during one-time charges:

• prevent_change: Prevent the change to the subscription from applying.

• apply_change: Apply the change and update the subscription.

Once created, to get details of a one-time charge:

• When created with effectiveFrom as next_billing_period, get the subscription the charge was billed to and use the include query parameter with the nextTransaction value.

• When created with effectiveFrom as immediately, list transactions and use the subscriptionId query parameter with the subscription ID of the subscription the charge was billed to.

When an update results in an immediate charge, responses may take longer than usual while a payment attempt is processed.

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 updated subscription entity. However, one-time charges aren't held against the subscription entity, so the charges billed aren't returned in the response.

This tool will preview creating a one-time charge for a subscription without billing that charge, typically used for previewing calculations before making changes to a subscription.

One-time charges are non-recurring items. These are price entities where the billingCycle is null.

If successful, the response includes immediateTransaction, nextTransaction, and recurringTransactionDetails to see expected transactions for the changes.

This tool will list payment methods for a customer in Paddle.

These are payment methods saved by the customer at checkout to be presented for future purchases. They aren't payment methods stored for transactions related to a recurring subscription. View a customers most recently used payment method for purchases or subscriptions by listing transactions (with the list_transactions tool) with a filter of customerId or subscriptionId, and looking at the returned payments[].methodDetails object.

Use the maximum perPage by default (200) to ensure comprehensive results. Filter payment methods by addressId and supportsCheckout as needed. Results are paginated - use the 'after' parameter with the last ID from previous results to get the next page. Sort and order results using the orderBy parameter.

This tool will retrieve a payment method for a customer from Paddle using its ID and related customer ID.

These are payment methods saved by the customer at checkout to be presented for future purchases. They aren't payment methods stored for transactions related to a recurring subscription. View a customers most recently used payment method for purchases or subscriptions by listing transactions (with the list_transactions tool) with a filter of customerId or subscriptionId, and looking at the returned payments[].methodDetails object.

This tool will create a customer portal session for a customer in Paddle.

The customer portal is a secure, Paddle-hosted site that allows customers and authorized individuals to:

• View transaction history

• Download invoices

• Update saved payment methods for future purchases

• Update stored payment methods for subscriptions

• Manage their subscriptions including cancellations

• Revise details on completed transactions

Don't use this tool without checking with the user first. Avoid using before gaining explicit approval.

Authenticated links are returned which automatically sign in the customer. Ensure those creating a customer portal session are authorized to access the customer portal.

• urls.general.overview: Allows the customer to view their account information, transactions, and subscriptions.

Provide subscriptionIds to return urls.subscriptions[] to manage one or more subscriptions directly:

• urls.subscriptions[].updateSubscriptionPaymentMethod: Allows the customer to update the payment method for a subscription.

• urls.subscriptions[].cancelSubscription: Allows the customer to cancel a subscription.

If subscriptions are paused or canceled, links open the overview page for a subscription.

If successful, the response includes a copy of the new customer portal session entity with the urls to open up the customer portal for access. Customer portal sessions are temporary and shouldn't be cached.

This tool will list notification settings in Paddle.

Use the maximum perPage by default (200) to ensure comprehensive results. Filter notification settings by active and trafficSource as needed. Results are paginated - use the 'after' parameter with the last ID from previous results to get the next page. Sort and order results using the orderBy parameter.

The endpointSecretKey is returned for webhook signature verification, but is a secure value and should never be shared, never be made publicly-accessible, and should only be stored securely.

This tool will create a new notification setting (notification destination) in Paddle.

Create notification destinations to get notifications, like webhooks, for events that happen in Paddle. Paddle recommends handling the storage and provisioning of access after purchase and subscription using webhooks.

The type describes how and where the event should be sent:

• email: Deliver to an email address. Add the email address to the destination parameter.

• url: Deliver to a webhook endpoint. Add the full URL including the path to the destination parameter.

The destination URL must be publicly accessible. localhost is not a valid address. For local development, use a tunnelling service like ngrok or Hookdeck to generate a public URL.

Pass an array of event type names to subscribedEvents to say which events should be subscribed to. Paddle responds with the full event type object for each event type.

Provide the trafficSource to define if the notification destination should be sent real events and/or simulated test events:

• platform: Deliver real platform events. These are sent when real events which are subscribed to take place.

• simulation: Deliver simulated events. These are sent when simulations are run to test single events or scenarios, usually to verify implementations of Paddle.

• all: Deliver both platform (real) and simulation (test) events.

Create notification destinations as many as needed, but only 10 can be active as per the active boolean parameter. Prompt users to toggle in the dashboard. Alternatively, use the list_notification_setting tool, verify which should be active, and use the update_notification_setting tool to toggle the boolean accordingly.

If successful, the response includes a copy of the new notification setting entity. The endpointSecretKey is returned for webhook signature verification, but is a secure value and should never be shared, never be made publicly-accessible, and should only be stored securely.

This tool will retrieve a notification setting (notification destination) from Paddle by its ID.

The endpointSecretKey is returned for webhook signature verification, but is a secure value and should never be shared, never be made publicly-accessible, and should only be stored securely.

This tool will list events in Paddle.

When something notable occurs, Paddle creates an event entity with information about what happened. Events are created for actions regardless of how they happened and regardless of whether a notification setting is subscribed to be notified by Paddle.

Some actions might create multiple events. For example, resuming a subscription typically results in a subscription.resumed, transaction.created, and other transaction events being created.

Use the maximum perPage by default (200) to ensure comprehensive results. Results are paginated - use the 'after' parameter with the last ID from previous results to get the next page. Sort and order results using the orderBy parameter.

This tool will list notifications in Paddle.

When an event that has a notification destination occurs, Paddle creates a notification entity with information about the notification.

A single event might create multiple notifications. This is common when working with multiple notification destinations that are subscribed to the same events. When an event occurs, Paddle creates a separate notification entity for each notification destination. They'll share the same eventId, but have different notificationId.

Notifications older than 90 days aren't retained and won't be returned.

Use the maximum perPage by default (200) to ensure comprehensive results. Filter notifications by notificationSettingId, search (fuzzy search on the event's type or id), status, filter (pass a transaction, customer, or subscription ID), to, and from as needed. Results are paginated - use the 'after' parameter with the last ID from previous results to get the next page. Sort and order results using the orderBy parameter.

Check the following details to understand the success or failure of the notification delivery according to Paddle and debug issues:

• status: Status of the notification.

  • notAttempted: Paddle hasn't yet tried to deliver this notification.

  • needsRetry: Paddle tried to deliver this notification, but it failed. It's scheduled to be retried.

  • delivered: Paddle delivered this notification successfully.

  • failed: Paddle tried to deliver this notification, but all attempts failed. It's not scheduled to be retried.

• origin: Describes how this notification was created.

  • event: Notification created when a subscribed event occurred.

  • replay: Notification created when a notification with the origin event was replayed.

• deliveredAt: RFC 3339 datetime string of when this notification was delivered. null if not yet delivered successfully.

• lastAttemptAt: RFC 3339 datetime string of when this notification was last attempted.

• retryAt: RFC 3339 datetime string of when this notification is scheduled to be retried.

• timesAttempted: How many times delivery of this notification has been attempted.

This tool will retrieve a notification from Paddle by its ID.

When an event that has a notification destination occurs, Paddle creates a notification entity with information about the notification.

Notifications older than 90 days aren't retained. If trying to get a notification that's no longer retained, Paddle returns an error.

Check the following details to understand the success or failure of the notification according to Paddle and debug issues:

• status: Status of the notification.

  • notAttempted: Paddle hasn't yet tried to deliver this notification.

  • needsRetry: Paddle tried to deliver this notification, but it failed. It's scheduled to be retried.

  • delivered: Paddle delivered this notification successfully.

  • failed: Paddle tried to deliver this notification, but all attempts failed. It's not scheduled to be retried.

• origin: Describes how this notification was created.

  • event: Notification created when a subscribed event occurred.

  • replay: Notification created when a notification with the origin event was replayed.

• deliveredAt: RFC 3339 datetime string of when this notification was delivered. null if not yet delivered successfully.

• lastAttemptAt: RFC 3339 datetime string of when this notification was last attempted.

• retryAt: RFC 3339 datetime string of when this notification is scheduled to be retried.

• timesAttempted: How many times delivery of this notification has been attempted.

This tool will list notification logs in Paddle.

When Paddle sends a notification to a webhook endpoint or email address, it records information about each delivery attempt as a log against the notification.

Every delivered notification has at least one log with information about the response that Paddle received on delivery.

Where a notification isn't delivered successfully, Paddle tries to deliver the notification again. Each delivery attempt is logged against a notification.

Use the maximum perPage by default (200) to ensure comprehensive results. Results are paginated - use the 'after' parameter with the last ID from previous results to get the next page.

Check the following details to understand the success or failure of each delivery attempt and debug issues:

• responseCode: HTTP code sent by the responding server.

• responseContentType: Content-Type sent by the responding server.

• responseBody: Response body sent by the responding server. Typically empty for success responses.

• attemptedAt: RFC 3339 datetime string of when Paddle attempted to deliver the related notification.

This tool will resend a delivered or failed notification, like a webhook notification, using its ID.

Don't use this tool without checking with the user first. Avoid using before gaining explicit approval.

Paddle creates a new notification entity for the replay, related to the same eventId. The response includes the new notificationId of the created notification.

Notifications older than 90 days aren't retained. If trying to replay a notification that's no longer retained, Paddle returns an error.

Only notifications with the origin of event can be replayed. Replaying a notification created for a replay isn't possible.

Check the following details to understand the success or failure of the notification according to Paddle and debug issues:

• status: Status of the notification.

  • notAttempted: Paddle hasn't yet tried to deliver this notification.

  • needsRetry: Paddle tried to deliver this notification, but it failed. It's scheduled to be retried.

  • delivered: Paddle delivered this notification successfully.

  • failed: Paddle tried to deliver this notification, but all attempts failed. It's not scheduled to be retried.

• origin: Describes how this notification was created.

  • event: Notification created when a subscribed event occurred.

  • replay: Notification created when a notification with the origin event was replayed.

• deliveredAt: RFC 3339 datetime string of when this notification was delivered. null if not yet delivered successfully.

• lastAttemptAt: RFC 3339 datetime string of when this notification was last attempted.

• retryAt: RFC 3339 datetime string of when this notification is scheduled to be retried.

• timesAttempted: How many times delivery of this notification has been attempted.

This tool will list simulations in Paddle.

These are the configurations for simulations, as opposed to the simulation runs which are used to send the events to the notification destination.

Use the maximum perPage by default (200) to ensure comprehensive results. Filter simulations by notificationSettingId, id, and status as needed. Results are paginated - use the 'after' parameter with the last ID from previous results to get the next page. Sort and order results using the orderBy parameter.

This tool will create a new simulation for a notification setting (notification destination) in Paddle.

Test webhooks can be sent through the webhook simulator in the dashboard or via the API by creating and running a simulation. Simulations configure which test webhooks are sent by Paddle when run. They can simulate the sending of single events or scenarios which send multiple events, like subscription renewals or cancellations. This is ideal for testing webhook implementations and validating data before sending real events. If implementing webhooks or making changes to an implementation, create and run a simulation prior to sending real events.

For scenario simulations (type of subscription_creation, subscription_renewal, subscription_pause, subscription_resume, subscription_cancellation), config objects can be provided. The config object contains a key matching the scenario type (e.g., for type "subscription_creation", use config.subscription_creation). This nested object can contain entities and options fields to control which webhooks are sent and populate payloads with real entity data. If provided, the config object must match the scenario type selected.

Option values for scenario simulations:

subscriptionCancellation and subscriptionPause:

• options.effectiveFrom:

  • next_billing_period: Simulates as if the subscription cancels or pauses at the start of next billing period.

  • immediately: Simulates as if the subscription cancels or pauses immediately.

subscriptionResume and subscriptionRenewal:

• options.paymentOutcome:

  • success: Simulates as if the payment for the subscription is successful.

  • recovered_existing_payment_method: Simulates as if the payment for the subscription fails initially and the payment is recovered when retrying the existing payment method.

  • recovered_updated_payment_method: Simulates as if the payment for the subscription fails initially and the customer updates their payment method to successfully pay.

  • failed: Simulates as if the payment for the subscription is unsuccessful after all payment recovery attempts are exhausted.

• options.dunningExhaustedAction (only valid when paymentOutcome is "failed"):

  • subscription_paused: Simulates as if the subscription is paused after all payment recovery attempts are exhausted.

  • subscription_canceled: Simulates as if the subscription is canceled after all payment recovery attempts are exhausted.

subscriptionCreation:

• options.customerSimulatedAs:

  • new: Simulates as if a new customer enters their details at checkout and Paddle creates a new customer.

  • existing_email_matched: Simulates as if an existing customer enters their details at checkout. Paddle matches it to an existing customer based on the email supplied and creates a new address for that customer.

  • existing_details_prefilled: Simulates as if existing customer details are prefilled at checkout by passing them to Paddle.js.

• options.businessSimulatedAs:

  • not_provided: Simulates as if no business is provided.

  • new: Simulates as if a customer enters their business details at checkout and Paddle creates a new business.

  • existing_details_prefilled: Simulates as if an existing business is prefilled at checkout by passing it to Paddle.js.

• options.discountSimulatedAs:

  • not_provided: Simulates as if no discount is entered.

  • prefilled: Simulates as if a discount is prefilled at checkout by passing it to Paddle.js. Requires entities.discountId.

  • entered_by_customer: Simulates as if a customer entered a discount at checkout. Requires entities.discountId.

If config.entities are not provided, simulated webhook payloads are populated with static demo examples.

If successful, the response includes a copy of the new simulation entity. The simulation can then be run to send the events to the notification destination with the create_simulation_run tool.

This tool will retrieve a simulation from Paddle by its ID.

This is for the configuration of a simulation, as opposed to the simulation run which is used to send the events to the notification destination.

This tool will list simulation runs in Paddle.

Use the maximum perPage by default (200) to ensure comprehensive results. Filter simulationRuns by id as needed. Results are paginated - use the 'after' parameter with the last ID from previous results to get the next page. Sort and order results using the orderBy parameter.

Use the include parameter to include related entities in the response:

• events: An array of events entities for events sent by this simulation run.

This tool will create a new simulation run for a simulation in Paddle.

Test webhooks can be sent through the webhook simulator in the dashboard or via the API by creating and running a simulation. Simulation runs are used to send the test webhook events to the notification destination once the simulation has been configured.

If successful, the response includes a copy of the new simulation run entity. All events sent by the simulation run can be seen using the list_simulations_events tool or including the 'events' parameter in the response when fetching the individual simulation run using the get_simulation_run tool.

This tool will retrieve a simulation run from Paddle by its ID.

Use the include parameter to include related entities in the response:

• events: An array of events entities for events sent by this simulation run.

This tool will list simulation run events in Paddle.

Use the maximum perPage by default (200) to ensure comprehensive results. Filter simulationRunEvents by id as needed. Results are paginated - use the 'after' parameter with the last ID from previous results to get the next page. Sort and order results using the orderBy parameter.

Check the following details to understand the success or failure of the event according to Paddle and debug issues:

• status: Status of the event according to Paddle.

  • pending: No attempt has been made to deliver the event yet.

  • success: The event was delivered successfully.

  • failure: Paddle tried to deliver the simulated event, but it failed. If response object is null, no response received from the server. Check the notification setting endpoint configuration.

  • aborted: Paddle couldn't attempt delivery of the simulated event.

• payload: Payload sent by Paddle for this event within the simulation.

• request.body: Request body sent by Paddle.

• response.body: Response body sent by the responding server. May be empty for success responses.

• response.statusCode: HTTP status code sent by the responding server.

If the destination URL is using a tunnel or proxy service, the response may be from the tunnel or proxy service, not the original server. Don't assume success or failure based on the status and response alone. Check the logs of the tunnel/proxy service and the destination server.

This tool will retrieve an event sent by a simulation run from Paddle by its ID.

Check the following details to understand the success or failure of the event according to Paddle and debug issues:

• status: Status of the event according to Paddle.

  • pending: No attempt has been made to deliver the event yet.

  • success: The event was delivered successfully.

  • failure: Paddle tried to deliver the simulated event, but it failed. If response object is null, no response received from the server. Check the notification setting endpoint configuration.

  • aborted: Paddle couldn't attempt delivery of the simulated event.

• payload: Payload sent by Paddle for this event within the simulation.

• request.body: Request body sent by Paddle.

• response.body: Response body sent by the responding server. May be empty for success responses.

• response.statusCode: HTTP status code sent by the responding server.

If the destination URL is using a tunnel or proxy service, the response may be from the tunnel or proxy service, not the original server. Don't assume success or failure based on the status and response alone. Check the logs of the tunnel/proxy service and the destination server.

This tool will resend an event sent by a simulation run from Paddle using its ID.

This is useful to retest the sending of an individual event within a simulation run rather than creating a new simulation run and sending all events again.

Paddle creates a new simulation run event entity for the replay, related to the same simulation run.

If successful, the response includes the new simulation run event entity.

Check the following details to understand the success or failure of the event according to Paddle and debug issues:

• status: Status of the event according to Paddle.

  • pending: No attempt has been made to deliver the event yet.

  • success: The event was delivered successfully.

  • failure: Paddle tried to deliver the simulated event, but it failed. If response object is null, no response received from the server. Check the notification setting endpoint configuration.

  • aborted: Paddle couldn't attempt delivery of the simulated event.

• payload: Payload sent by Paddle for this event within the simulation.

• request.body: Request body sent by Paddle.

• response.body: Response body sent by the responding server. May be empty for success responses.

• response.statusCode: HTTP status code sent by the responding server.

This tool will list reports in Paddle.

Use the maximum perPage by default (200) to ensure comprehensive results. Filter reports by status as needed. Results are paginated - use the 'after' parameter with the last ID from previous results to get the next page. Sort and order results using the orderBy parameter.

Amounts are in the smallest currency unit (e.g., cents).

This tool will create a new report in Paddle.

Use this tool when detailed financial data for analysis, reconciliation, or export to spreadsheet applications is needed. Use this tool over listTransactions when trying to gather larger amounts of data from Paddle.

Reports are generated asynchronously - a report ID will be returned that can be used to check status. Reports initially have 'pending' status, then move to 'ready' when available to download. Reports are available in CSV format and can be downloaded once ready using the get_report_csv tool. Reports expire after a certain period and are no longer available to download after they expire.

There are different report types available:

• adjustments: For information about refunds, credits, and chargebacks

• adjustment_line_items: For information about refunds, credits, and chargebacks, broken down by line item level

• transactions: For information about revenue received, past due invoices, draft and issued invoices, and canceled transactions

• transaction_line_items: For information about revenue received, past due invoices, draft and issued invoices, and canceled transactions, broken down by line item level

• products_prices: For information about the products and prices. May include non-catalog products and prices.

• discounts: For information about the product and checkout discounts

Each report type has different filters which can be used:

• action: adjustments and adjustment_line_items. Pass an array of strings containing any of 'refund', 'credit', 'chargeback', 'chargeback_reverse', 'chargeback_warning', 'chargeback_warning_reverse', 'credit_reverse' as values.

• collection_mode: transactions and transaction_line_items. Pass an array of strings containing any of 'automatic' and 'manual' as values.

• currency_code: adjustments, adjustment_line_items, transactions, and transaction_line_items. Pass an array of strings containing any valid supported three-letter ISO 4217 currency code.

• origin: transactions and transaction_line_items. Pass an array of strings containing any of 'api', 'subscription_charge', 'subscription_payment_method_change', 'subscription_recurring', 'subscription_update', and 'web' as values.

• product_status: products_prices. Pass an array of strings containing any of 'active' and 'archived' as values.

• price_status: products_prices. Pass an array of strings containing any of 'active' and 'archived' as values.

• product_type: products_prices. Pass an array of strings containing any of 'custom' and 'standard' as values.

• price_type: products_prices. Pass an array of strings containing any of 'custom' and 'standard' as values.

• product_updated_at: products_prices. Pass an RFC 3339 datetime string.

• price_updated_at: products_prices. Pass an RFC 3339 datetime string.

• status: adjustments, adjustment_line_items, transactions, transaction_line_items, and discounts. Pass an array of strings containing any valid value for the status field against an adjustment, transaction, or discount.

• type: discounts and products_prices. Pass an array of strings containing any of 'custom' and 'standard' as values.

• updated_at: adjustments, adjustment_line_items, transactions, transaction_line_items, and discounts. Pass an RFC 3339 datetime string. Use the operator parameter to specify the operator to use when filtering.

If successful, the response includes a copy of the new report entity.

This tool will retrieve a report entity from Paddle by its ID. It only contains information about the report, like the ID, status, and the date it was created.

Use this tool to check the status of a generated report, or to get the ID of a report, to then use with the get_report_csv tool to download the CSV.

This tool will retrieve a link to a CSV file for a report from Paddle by its ID.

Only returned for reports that are ready. This means Paddle has completed processing the report and it's ready to download. The status of a report can be checked using the get_report tool.

The link returned isn't a permanent link. It expires after 3 minutes.

This tool will list client-side tokens in Paddle.

Client-side tokens are needed to authenticate with Paddle.js. A token is provided when initializing Paddle.js.

Use the maximum perPage by default (200) to ensure comprehensive results. Filter client-side tokens by status as needed. Results are paginated - use the 'after' parameter with the last ID from previous results to get the next page. Sort and order results using the orderBy parameter.

The returned token field is the client-side token that needs to be provided when initializing Paddle.js. Can be exposed client-side safely. If it starts with:

• test_: The token is a test token for a sandbox environment and shouldn't be used in production.

• live_: The token is a live token for a production environment. It can be used to test too but Paddle.js checkouts require real cards.

Client-side tokens have a status:

• active: Client-side token can be used to authenticate with Paddle.js.

• revoked: Client-side token has been revoked and can no longer be used to authenticate with Paddle.js.

This tool will create a new client-side token in Paddle.

Client-side tokens are needed to authenticate with Paddle.js. A token is provided when initializing Paddle.js.

When creating a client-side token, provide a descriptive name to help identify its purpose. Usually created for each application or environment that needs to authenticate with Paddle.js.

If successful, the response includes a copy of the new client-side token entity. The returned token field is the client-side token that needs to be provided when initializing Paddle.js. Can be exposed client-side safely. If it starts with:

• test_: The token is a test token for a sandbox environment and shouldn't be used in production.

• live_: The token is a live token for a production environment. It can be used to test too but Paddle.js checkouts require real cards.

This tool will retrieve a client-side token from Paddle by its ID.

The returned token field is the client-side token that needs to be provided when initializing Paddle.js. Can be exposed client-side safely. If it starts with:

• test_: The token is a test token for a sandbox environment and shouldn't be used in production.

• live_: The token is a live token for a production environment. It can be used to test too but Paddle.js checkouts require real cards.

Client-side tokens have a status:

• active: Client-side token can be used to authenticate with Paddle.js.

• revoked: Client-side token has been revoked and can no longer be used to authenticate with Paddle.js.