@paddle/paddle-mcp/build/prompts.js

MCP Server for Paddle Billing

const checkBeforeWarning = `
Don't use this tool without checking with the user first. Avoid using before gaining explicit approval.
`;
const additionalDetailsWarning = `
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.
`;
const metricsDateRangeGuidance = `
Pass both from and to as RFC 3339 full date strings. Dates are interpreted at 00:00 UTC.
Choose a date range that matches the reporting window the user is asking for.
`;
const metricsEnvironmentGuidance = `
IMPORTANT: This tool only works with production (live) accounts. It will not return data for sandbox environments.
`;
const metricsReportsGuidance = `
Metrics and reports:
- Reports export entity-level historical data as CSV. Use them for audits, reconciliation, spreadsheets, and lists of individual transactions, refunds, discounts, or products.
- Metrics return aggregated timeseries data directly in the API response. When this MCP server is configured for production, use metrics tools for trend questions, dashboard summaries, and aggregate performance over time.
Rule of thumb: if the user wants a list of rows, use a report. If they want a trend or headline figure, use a metrics tool when this server exposes them; otherwise rely on reports.
`;
export const listProductsPrompt = `
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.
`;
export const createProductPrompt = `
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.

${additionalDetailsWarning}

If successful, the response includes a copy of the new product entity. Once a product has been created, relate it to a price.
`;
export const getProductPrompt = `
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.
`;
export const updateProductPrompt = `
This tool will update a product in Paddle by its ID.

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

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

${additionalDetailsWarning}

If successful, the response includes a copy of the updated product entity.
`;
export const listPricesPrompt = `
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.
`;
export const createPricePrompt = `
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"
    }
  }
]

${additionalDetailsWarning}

If successful, the response includes a copy of the new price entity.
`;
export const getPricePrompt = `
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.
`;
export const updatePricePrompt = `
This tool will update a price in Paddle by its ID.

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"
    }
  }
]

${additionalDetailsWarning}

If successful, the response includes a copy of the updated price entity.
`;
export const listTransactionsPrompt = `
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.
`;
export const createTransactionPrompt = `
This tool will create a new transaction in Paddle.

${checkBeforeWarning}

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.

${additionalDetailsWarning}

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.
`;
export const previewPricesPrompt = `
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.
`;
export const previewTransactionCreatePrompt = `
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.
`;
export const getTransactionPrompt = `
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.
`;
export const updateTransactionPrompt = `
This tool will update a transaction in Paddle by its ID.

${checkBeforeWarning}

Update transactions that are draft or ready. billed and completed transactions are considered records for tax and legal purposes, so they can't be changed. Either:

- Create an adjustment to record a refund or credit for a transaction.
- Cancel a billed transaction by sending a PATCH request to set status to canceled.

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

All other statuses (draft, ready, paid, completed, past_due) are set automatically by Paddle.

When making changes to items on a transaction, send the complete list of items that should be on a transaction — including existing items. For each item, send an object containing priceId and quantity. Paddle responds with the full price object for each item.

The collectionMode of a transaction can be changed to change how Paddle tries to collect for payment. Options are:

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

If changing the collection mode from automatic to manual, always first:

- Check the customer associated to the subscription has a name. If not, get and then set a name on the customer.
- Check the customer has an address. If not, get and then set an address for the customer with a country, postalCode, region, city, and firstLine.
- Check the currencyCode of the subscription is USD, GBP, or EUR. If not, get which currency is preferred and then change the currency of the subscription to the preferred currency.

${additionalDetailsWarning}

If successful, the response includes a copy of the updated transaction entity.
`;
export const reviseTransactionPrompt = `
This tool will revise customer information for a billed or completed transaction where the customer information is incorrect and needs to be rectified on invoice documents generated by Paddle.

${checkBeforeWarning}

Details that don't impact the tax rates on a transaction can be revised. This includes:

- Customer name
- Business name and tax or VAT number (taxIdentifier)
- Address details, apart from the country

Removing a valid tax or VAT number isn't possible, only replacing it with another valid one. If a valid tax or VAT number is added, Paddle automatically creates an adjustment to refund any tax where applicable.

Transactions can only be revised once.

Only the customer information for this transaction is updated. The related customer, address, and business entities aren't updated.

${additionalDetailsWarning}

If successful, the response includes a copy of the transaction entity. Get a transaction using the include parameter with the customer, address, and business values to see the revised customer information.
`;
export const listAdjustmentsPrompt = `
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.
`;
export const createAdjustmentPrompt = `
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.

${checkBeforeWarning}

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.

${additionalDetailsWarning}

If successful, the response includes a copy of the new adjustment entity.
`;
export const getAdjustmentCreditNotePrompt = `
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.
`;
export const listCreditBalancesPrompt = `
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.
`;
export const listCustomersPrompt = `
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.
`;
export const createCustomerPrompt = `
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.

${additionalDetailsWarning}

If successful, the response includes a copy of the new customer entity.
`;
export const getCustomerPrompt = `
This tool will retrieve a customer from Paddle by its ID.
`;
export const updateCustomerPrompt = `
This tool will update a customer in Paddle by its ID.

There's no delete operation for customers. Instead, archive them. Options are:

- active: Entity is active and can be used.
- archived: Entity is archived, so can't be used.

${additionalDetailsWarning}

If successful, the response includes a copy of the updated customer entity.
`;
export const listAddressesPrompt = `
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.
`;
export const createAddressPrompt = `
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.

${additionalDetailsWarning}

If successful, the response includes a copy of the new address entity.
`;
export const getAddressPrompt = `
This tool will retrieve an address for a customer from Paddle using its ID and related customer ID.
`;
export const updateAddressPrompt = `
This tool will update an address for a customer in Paddle using its ID and related customer ID.

There's no delete operation for addresses. Instead, archive them. Options are:

- active: Entity is active and can be used.
- archived: Entity is archived, so can't be used.

${additionalDetailsWarning}

If successful, the response includes a copy of the updated address entity.
`;
export const listBusinessesPrompt = `
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.
`;
export const createBusinessPrompt = `
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.

${additionalDetailsWarning}

If successful, the response includes a copy of the new business entity.
`;
export const getBusinessPrompt = `
This tool will retrieve a business for a customer from Paddle using its ID and related customer ID.
`;
export const updateBusinessPrompt = `
This tool will update a business for a customer in Paddle using its ID and related customer ID.

There's no delete operation for businesses. Instead, archive them. Options are:

- active: Entity is active and can be used.
- archived: Entity is archived, so can't be used.

${additionalDetailsWarning}

If successful, the response includes a copy of the updated business entity.
`;
export const listSavedPaymentMethodsPrompt = `
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.
`;
export const getSavedPaymentMethodPrompt = `
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.
`;
export const deleteSavedPaymentMethodPrompt = `
This tool will delete a customer payment method using its 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. Deleting payment methods stored for subscriptions isn't possible. They must be updated by an authenticated customer using the customer portal (create_customer_portal_session tool) or by using an implementation of the Paddle checkout set up to allow customers to update their payment methods.

${checkBeforeWarning}

When a customer payment method is deleted, it's permanently removed from that customer. There's no way to recover a deleted payment method.
`;
export const createCustomerPortalSessionPrompt = `
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

${checkBeforeWarning}

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.
`;
export const listNotificationSettingsPrompt = `
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.
`;
export const createNotificationSettingPrompt = `
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.
`;
export const getNotificationSettingPrompt = `
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.
`;
export const updateNotificationSettingPrompt = `
This tool will update a notification setting (notification destination) in Paddle by its ID.

When updating subscribed events, send the complete list of event types that should be subscribed to, including existing event types. If event types are omitted, they're removed from the notification setting. Only the event type name needs to be passed. 

Paddle responds with the full event type object for each event type.

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.

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 updated 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.
`;
export const deleteNotificationSettingPrompt = `
This tool will delete a notification setting (notification destination) using its ID.

${checkBeforeWarning}

When deleting a notification setting, it's permanently removed from the account. Paddle stops sending events to the destination, and access is lost to all the logs for this notification setting.

There's no way to recover a deleted notification setting. Deactivate a notification setting using the update_notification_setting tool if log access is required or it needs to be reactivated later on.
`;
export const listNotificationsPrompt = `
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.
`;
export const getNotificationPrompt = `
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.
`;
export const replayNotificationPrompt = `
This tool will resend a delivered or failed notification, like a webhook notification, using its ID.

${checkBeforeWarning}

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.
`;
export const listNotificationLogsPrompt = `
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 no