@paddle/paddle-mcp
Version:
MCP Server for Paddle Billing
1,553 lines • 157 kB
JavaScript
import { z } from "zod";
const currencyCodeEnum = z.enum([
"USD", "EUR", "GBP", "JPY", "AUD", "CAD", "CHF", "HKD", "SGD", "SEK",
"ARS", "BRL", "CLP", "CNY", "COP", "CZK", "DKK", "HUF", "ILS", "INR", "KRW",
"MXN", "NOK", "NZD", "PEN", "PLN", "RUB", "THB", "TRY", "TWD", "UAH", "VND", "ZAR"
]);
const countryCodeEnum = z.enum([
"AD", "AE", "AG", "AI", "AL", "AM", "AO", "AR", "AS", "AT", "AU", "AW", "AX", "AZ",
"BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ",
"BR", "BS", "BT", "BV", "BW", "BZ", "CA", "CC", "CG", "CH", "CI", "CK", "CL", "CM",
"CN", "CO", "CR", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ",
"EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA",
"GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS",
"GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HU", "ID", "IE", "IL", "IM", "IN",
"IO", "IQ", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN",
"KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV",
"MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "MN", "MO", "MP", "MQ", "MR", "MS",
"MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NL", "NO",
"NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN",
"PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RW", "SA", "SB", "SC", "SE",
"SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SR", "ST", "SV", "SX", "SZ", "TC",
"TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW",
"TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VG", "VI", "VN", "VU", "WF",
"WS", "XK", "YT", "ZA", "ZM"
]);
const moneySchema = z.object({
amount: z.string().describe("Amount in the lowest denomination for the currency, e.g. 10 USD = 1000 (cents). Although represented as a string, this value must be a valid integer."),
currencyCode: currencyCodeEnum.describe("Supported three-letter ISO 4217 currency code."),
});
const timePeriodSchema = z.object({
interval: z.enum(["day", "week", "month", "year"]).describe("Unit of time."),
frequency: z.number().describe("Amount of time. Must be a positive integer."),
});
const priceQuantitySchema = z.object({
minimum: z.number().describe("Minimum quantity of the product related to this price that can be bought. Required if `maximum` set."),
maximum: z.number().describe("Maximum quantity of the product related to this price that can be bought. Required if `minimum` set. Must be greater than or equal to the `minimum` value."),
});
const unitPriceOverrideSchema = z.object({
countryCodes: z.array(countryCodeEnum).describe("List of country codes."),
unitPrice: moneySchema.describe("Unit price for the country codes."),
});
const nonCatalogProductSchema = z.object({
name: z.string().describe("Name of this product."),
taxCategory: z.enum([
"digital-goods", "ebooks", "implementation-services", "professional-services",
"saas", "software-programming-services", "standard", "training-services", "website-hosting"
]).describe("Tax category for this product. Used for charging the correct rate of tax. Selected tax category must be enabled at account level or an error is returned."),
description: z.string().optional().describe("Short description for this product."),
imageUrl: z.string().optional().describe("Image for the product. Included in the checkout and on some customer documents."),
customData: z.record(z.any(), z.any()).optional().describe("Custom data for the product."),
});
const nonCatalogPriceSchema = z.union([
z.object({
description: z.string().describe("Internal description for this price, not shown to customers."),
name: z.string().optional().describe("Name of this price, shown to customers at checkout and on invoices. Typically describes how often the related product bills."),
unitPrice: moneySchema.describe("Base unit price for the price."),
productId: z.string().describe("Paddle ID for the product that this price is for, prefixed with `pro_`."),
billingCycle: timePeriodSchema.optional().nullable().describe("How often this price should be charged. `null` if price is non-recurring (one-time)."),
trialPeriod: timePeriodSchema.optional().nullable().describe("Trial period for the product related to this price. The billing cycle begins once the trial period is over. `null` for no trial period. Requires `billingCycle`."),
taxMode: z.enum(["account_setting", "external", "internal"]).optional().describe("How tax is calculated for this price."),
unitPriceOverrides: z.array(unitPriceOverrideSchema).optional().describe("Unit price overrides by country. Used to charge different prices for different countries."),
quantity: priceQuantitySchema.optional().describe("Limits on how many times the related product can be purchased at this price. Useful for discount campaigns. If omitted, defaults to 1-100."),
customData: z.record(z.any(), z.any()).optional().describe("Any structured custom key-value data needed outside of Paddle's standard fields. Occasionally used by third-parties."),
product: z.never().optional(),
}),
z.object({
description: z.string().describe("Internal description for this price, not shown to customers."),
name: z.string().optional().describe("Name of this price, shown to customers at checkout and on invoices. Typically describes how often the related product bills."),
unitPrice: moneySchema.describe("Base unit price for the price."),
product: nonCatalogProductSchema.describe("Product object for a non-catalog item to charge for.."),
billingCycle: timePeriodSchema.optional().nullable().describe("How often this price should be charged. `null` if price is non-recurring (one-time)."),
trialPeriod: timePeriodSchema.optional().nullable().describe("Trial period for the product related to this price. The billing cycle begins once the trial period is over. `null` for no trial period. Requires `billingCycle`."),
taxMode: z.enum(["account_setting", "external", "internal"]).optional().describe("How tax is calculated for this price."),
unitPriceOverrides: z.array(unitPriceOverrideSchema).optional().describe("Unit price overrides by country. Used to charge different prices for different countries."),
quantity: priceQuantitySchema.optional().describe("Limits on how many times the related product can be purchased at this price. Useful for discount campaigns. If omitted, defaults to 1-100."),
customData: z.record(z.any(), z.any()).optional().describe("Any structured custom key-value data needed outside of Paddle's standard fields. Occasionally used by third-parties."),
productId: z.never().optional(),
}),
]);
export const listProductsParameters = z.object({
after: z
.string()
.optional()
.describe("Return entities after the specified Paddle ID when working with paginated endpoints."),
id: z
.array(z.string())
.optional()
.describe("Return only the IDs specified. Use a comma-separated list to get multiple entities."),
include: z
.array(z.enum(["prices"]))
.optional()
.describe("Include related entities in the response. Use a comma-separated list to specify multiple entities."),
orderBy: z
.enum([
"created_at[ASC]",
"created_at[DESC]",
"custom_data[ASC]",
"custom_data[DESC]",
"description[ASC]",
"description[DESC]",
"id[ASC]",
"id[DESC]",
"image_url[ASC]",
"image_url[DESC]",
"name[ASC]",
"name[DESC]",
"status[ASC]",
"status[DESC]",
"tax_category[ASC]",
"tax_category[DESC]",
"updated_at[ASC]",
"updated_at[DESC]",
])
.optional()
.describe("Order returned entities by the specified field and direction."),
perPage: z
.number()
.optional()
.describe("Set how many entities are returned per page. Returns the maximum number of results if a number greater than the maximum is requested."),
status: z
.array(z.enum(["active", "archived"]))
.optional()
.describe("Return entities that match the specified status. Use a comma-separated list to specify multiple status values."),
taxCategory: z
.array(z.enum([
"digital-goods",
"ebooks",
"implementation-services",
"professional-services",
"saas",
"software-programming-services",
"standard",
"training-services",
"website-hosting",
]))
.optional()
.describe("Return entities that match the specified tax category. Use a comma-separated list to specify multiple tax categories."),
type: z
.array(z.enum(["custom", "standard"]))
.optional()
.describe("Return items that match the specified type."),
});
export const createProductParameters = z.object({
name: z.string().describe("Name of this product."),
description: z.string().optional().describe("Short description for this product."),
type: z
.enum(["custom", "standard"])
.optional()
.describe("Type of item. Standard items are considered part of the listed catalog and are shown in the Paddle dashboard."),
taxCategory: z
.enum([
"digital-goods",
"ebooks",
"implementation-services",
"professional-services",
"saas",
"software-programming-services",
"standard",
"training-services",
"website-hosting",
])
.describe("Tax category for this product. Used for charging the correct rate of tax. Selected tax category must be enabled at account level or an error is returned."),
imageUrl: z
.string()
.optional()
.describe("Image for this product. Included in the checkout and on some customer documents."),
customData: z.record(z.any(), z.any()).optional().describe("Any structured custom key-value data needed outside of Paddle's standard fields. Occasionally used by third-parties."),
});
export const getProductParameters = z.object({
productId: z.string().describe("Paddle ID of the product."),
include: z
.array(z.enum(["prices"]))
.optional()
.describe("Include related entities in the response. Use a comma-separated list to specify multiple entities."),
});
export const updateProductParameters = z.object({
productId: z.string().describe("Paddle ID of the product."),
name: z.string().optional().describe("Name of this product."),
description: z.string().optional().describe("Short description for this product."),
type: z
.enum(["custom", "standard"])
.optional()
.describe("Type of item. Standard items are considered part of the listed catalog and are shown in the Paddle dashboard."),
taxCategory: z
.enum([
"digital-goods",
"ebooks",
"implementation-services",
"professional-services",
"saas",
"software-programming-services",
"standard",
"training-services",
"website-hosting",
])
.optional()
.describe("Tax category for this product. Used for charging the correct rate of tax. Selected tax category must be enabled at account level or an error is returned."),
imageUrl: z
.string()
.optional()
.describe("Image for this product. Included in the checkout and on some customer documents."),
customData: z.record(z.any(), z.any()).optional().describe("Any structured custom key-value data needed outside of Paddle's standard fields. Occasionally used by third-parties."),
status: z.enum(["active", "archived"]).optional().describe("Whether this product can be used in Paddle."),
});
export const listPricesParameters = z.object({
after: z
.string()
.optional()
.describe("Return entities after the specified Paddle ID when working with paginated endpoints."),
id: z
.array(z.string())
.optional()
.describe("Return only the IDs specified. Use a comma-separated list to get multiple entities."),
include: z
.array(z.enum(["product"]))
.optional()
.describe("Include related entities in the response."),
orderBy: z
.enum(["billingCycle[ASC]", "billingCycle[DESC]"])
.optional()
.describe("Order returned entities by the specified field and direction."),
perPage: z
.number()
.optional()
.describe("Set how many entities are returned per page. Returns the maximum number of results if a number greater than the maximum is requested."),
productId: z
.array(z.string())
.optional()
.describe("Return entities related to the specified product. Use a comma-separated list to specify multiple product IDs."),
status: z
.array(z.enum(["active", "archived"]))
.optional()
.describe("Return entities that match the specified status. Use a comma-separated list to specify multiple status values."),
recurring: z
.boolean()
.optional()
.describe("Determine whether returned entities are for recurring prices (`true`) or one-time prices (`false`)."),
type: z
.array(z.enum(["custom", "standard"]))
.optional()
.describe("Return items that match the specified type."),
});
export const createPriceParameters = z.object({
description: z
.string()
.describe("Internal description for this price, not shown to customers."),
type: z
.enum(["custom", "standard"])
.optional()
.describe("Type of item. Standard items are considered part of the listed catalog and are shown in the Paddle dashboard."),
name: z
.string()
.optional()
.describe("Name of this price, shown to customers at checkout and on invoices. Typically describes how often the related product bills."),
productId: z.string().describe("Paddle ID for the product that this price is for, prefixed with `pro_`."),
billingCycle: z
.object({
interval: z.enum(["day", "week", "month", "year"]).describe("Unit of time."),
frequency: z.number().describe("Amount of time."),
})
.optional()
.describe("How often this price should be charged. `null` if price is non-recurring (one-time). If omitted, defaults to `null`."),
trialPeriod: z
.object({
interval: z.enum(["day", "week", "month", "year"]).describe("Unit of time."),
frequency: z.number().describe("Amount of time."),
})
.optional()
.describe("Trial period for the product related to this price. The billing cycle begins once the trial period is over. `null` for no trial period. Requires `billingCycle`. If omitted, defaults to `null`."),
taxMode: z
.enum(["account_setting", "external", "internal"])
.optional()
.describe("How tax is calculated for this price."),
unitPrice: z
.object({
amount: z
.string()
.describe("Amount in the lowest denomination for the currency, e.g. 10 USD = 1000 (cents). Although represented as a string, this value must be a valid integer."),
currencyCode: z
.enum([
"USD",
"EUR",
"GBP",
"JPY",
"AUD",
"CAD",
"CHF",
"CLP",
"HKD",
"SGD",
"SEK",
"ARS",
"BRL",
"CNY",
"COP",
"CZK",
"DKK",
"HUF",
"ILS",
"INR",
"KRW",
"MXN",
"NOK",
"NZD",
"PEN",
"PLN",
"RUB",
"THB",
"TRY",
"TWD",
"UAH",
"VND",
"ZAR",
])
.describe("Supported three-letter ISO 4217 currency code."),
})
.describe("Base price. This price applies to all customers, except for customers located in countries where `unitPriceOverrides` are set."),
unitPriceOverrides: z
.array(z.object({
countryCodes: z
.array(z.enum([
"AD",
"AE",
"AG",
"AI",
"AL",
"AM",
"AO",
"AR",
"AS",
"AT",
"AU",
"AW",
"AX",
"AZ",
"BA",
"BB",
"BD",
"BE",
"BF",
"BG",
"BH",
"BI",
"BJ",
"BL",
"BM",
"BN",
"BO",
"BQ",
"BR",
"BS",
"BT",
"BV",
"BW",
"BZ",
"CA",
"CC",
"CG",
"CH",
"CI",
"CK",
"CL",
"CM",
"CN",
"CO",
"CR",
"CV",
"CW",
"CX",
"CY",
"CZ",
"DE",
"DJ",
"DK",
"DM",
"DO",
"DZ",
"EC",
"EE",
"EG",
"EH",
"ER",
"ES",
"ET",
"FI",
"FJ",
"FK",
"FM",
"FO",
"FR",
"GA",
"GB",
"GD",
"GE",
"GF",
"GG",
"GH",
"GI",
"GL",
"GM",
"GN",
"GP",
"GQ",
"GR",
"GS",
"GT",
"GU",
"GW",
"GY",
"HK",
"HM",
"HN",
"HR",
"HU",
"ID",
"IE",
"IL",
"IM",
"IN",
"IO",
"IQ",
"IS",
"IT",
"JE",
"JM",
"JO",
"JP",
"KE",
"KG",
"KH",
"KI",
"KM",
"KN",
"KR",
"KW",
"KY",
"KZ",
"LA",
"LB",
"LC",
"LI",
"LK",
"LR",
"LS",
"LT",
"LU",
"LV",
"MA",
"MC",
"MD",
"ME",
"MF",
"MG",
"MH",
"MK",
"MN",
"MO",
"MP",
"MQ",
"MR",
"MS",
"MT",
"MU",
"MV",
"MW",
"MX",
"MY",
"MZ",
"NA",
"NC",
"NE",
"NF",
"NG",
"NL",
"NO",
"NP",
"NR",
"NU",
"NZ",
"OM",
"PA",
"PE",
"PF",
"PG",
"PH",
"PK",
"PL",
"PM",
"PN",
"PR",
"PS",
"PT",
"PW",
"PY",
"QA",
"RE",
"RO",
"RS",
"RW",
"SA",
"SB",
"SC",
"SE",
"SG",
"SH",
"SI",
"SJ",
"SK",
"SL",
"SM",
"SN",
"SR",
"ST",
"SV",
"SX",
"SZ",
"TC",
"TD",
"TF",
"TG",
"TH",
"TJ",
"TK",
"TL",
"TM",
"TN",
"TO",
"TR",
"TT",
"TV",
"TW",
"TZ",
"UA",
"UG",
"UM",
"US",
"UY",
"UZ",
"VA",
"VC",
"VG",
"VI",
"VN",
"VU",
"WF",
"WS",
"XK",
"YT",
"ZA",
"ZM",
]))
.describe("Supported two-letter ISO 3166-1 alpha-2 country code. Customers located in the listed countries are charged the override price."),
unitPrice: z
.object({
amount: z
.string()
.describe("Amount in the lowest denomination for the currency, e.g. 10 USD = 1000 (cents). Although represented as a string, this value must be a valid integer."),
currencyCode: z
.enum([
"USD",
"EUR",
"GBP",
"JPY",
"AUD",
"CAD",
"CHF",
"HKD",
"SGD",
"SEK",
"ARS",
"BRL",
"CLP",
"CNY",
"COP",
"CZK",
"DKK",
"HUF",
"ILS",
"INR",
"KRW",
"MXN",
"NOK",
"NZD",
"PEN",
"PLN",
"RUB",
"THB",
"TRY",
"TWD",
"UAH",
"VND",
"ZAR",
])
.describe("Supported three-letter ISO 4217 currency code."),
})
.describe("Override price. This price applies to customers located in the countries for this unit price override."),
}))
.optional()
.describe("List of unit price overrides. Use to override the base price with a custom price and currency for a country or group of countries."),
quantity: z
.object({
minimum: z
.number()
.describe("Minimum quantity of the product related to this price that can be bought. Required if `maximum` set."),
maximum: z
.number()
.describe("Maximum quantity of the product related to this price that can be bought. Required if `minimum` set. Must be greater than or equal to the `minimum` value."),
})
.optional()
.describe("Limits on how many times the related product can be purchased at this price. Useful for discount campaigns. If omitted, defaults to 1-100."),
customData: z.record(z.any(), z.any()).optional().describe("Any structured custom key-value data needed outside of Paddle's standard fields. Occasionally used by third-parties."),
});
export const getPriceParameters = z.object({
priceId: z.string().describe("Paddle ID of the price."),
include: z
.array(z.enum(["product"]))
.optional()
.describe("Include related entities in the response."),
});
export const updatePriceParameters = z.object({
priceId: z.string().describe("Paddle ID of the price."),
description: z
.string()
.optional()
.describe("Internal description for this price, not shown to customers."),
type: z
.enum(["custom", "standard"])
.optional()
.describe("Type of item. Standard items are considered part of the listed catalog and are shown in the Paddle dashboard."),
name: z
.string()
.optional()
.describe("Name of this price, shown to customers at checkout and on invoices. Typically describes how often the related product bills."),
billingCycle: z
.object({
interval: z.enum(["day", "week", "month", "year"]).describe("Unit of time."),
frequency: z.number().describe("Amount of time."),
})
.optional()
.describe("How often this price should be charged. `null` if price is non-recurring (one-time)."),
trialPeriod: z
.object({
interval: z.enum(["day", "week", "month", "year"]).describe("Unit of time."),
frequency: z.number().describe("Amount of time."),
})
.optional()
.describe("Trial period for the product related to this price. The billing cycle begins once the trial period is over. `null` for no trial period. Requires `billingCycle`."),
taxMode: z
.enum(["account_setting", "external", "internal"])
.optional()
.describe("How tax is calculated for this price."),
unitPrice: z
.object({
amount: z
.string()
.describe("Amount in the lowest denomination for the currency, e.g. 10 USD = 1000 (cents). Although represented as a string, this value must be a valid integer."),
currencyCode: z
.enum([
"USD",
"EUR",
"GBP",
"JPY",
"AUD",
"CAD",
"CHF",
"CLP",
"HKD",
"SGD",
"SEK",
"ARS",
"BRL",
"CNY",
"COP",
"CZK",
"DKK",
"HUF",
"ILS",
"INR",
"KRW",
"MXN",
"NOK",
"NZD",
"PEN",
"PLN",
"RUB",
"THB",
"TRY",
"TWD",
"UAH",
"VND",
"ZAR",
])
.describe("Supported three-letter ISO 4217 currency code."),
})
.optional()
.describe("Base price. This price applies to all customers, except for customers located in countries where `unitPriceOverrides` are set."),
unitPriceOverrides: z
.array(z.object({
countryCodes: z
.array(z.enum([
"AD",
"AE",
"AG",
"AI",
"AL",
"AM",
"AO",
"AR",
"AS",
"AT",
"AU",
"AW",
"AX",
"AZ",
"BA",
"BB",
"BD",
"BE",
"BF",
"BG",
"BH",
"BI",
"BJ",
"BL",
"BM",
"BN",
"BO",
"BQ",
"BR",
"BS",
"BT",
"BV",
"BW",
"BZ",
"CA",
"CC",
"CG",
"CH",
"CI",
"CK",
"CL",
"CM",
"CN",
"CO",
"CR",
"CV",
"CW",
"CX",
"CY",
"CZ",
"DE",
"DJ",
"DK",
"DM",
"DO",
"DZ",
"EC",
"EE",
"EG",
"EH",
"ER",
"ES",
"ET",
"FI",
"FJ",
"FK",
"FM",
"FO",
"FR",
"GA",
"GB",
"GD",
"GE",
"GF",
"GG",
"GH",
"GI",
"GL",
"GM",
"GN",
"GP",
"GQ",
"GR",
"GS",
"GT",
"GU",
"GW",
"GY",
"HK",
"HM",
"HN",
"HR",
"HU",
"ID",
"IE",
"IL",
"IM",
"IN",
"IO",
"IQ",
"IS",
"IT",
"JE",
"JM",
"JO",
"JP",
"KE",
"KG",
"KH",
"KI",
"KM",
"KN",
"KR",
"KW",
"KY",
"KZ",
"LA",
"LB",
"LC",
"LI",
"LK",
"LR",
"LS",
"LT",
"LU",
"LV",
"MA",
"MC",
"MD",
"ME",
"MF",
"MG",
"MH",
"MK",
"MN",
"MO",
"MP",
"MQ",
"MR",
"MS",
"MT",
"MU",
"MV",
"MW",
"MX",
"MY",
"MZ",
"NA",
"NC",
"NE",
"NF",
"NG",
"NL",
"NO",
"NP",
"NR",
"NU",
"NZ",
"OM",
"PA",
"PE",
"PF",
"PG",
"PH",
"PK",
"PL",
"PM",
"PN",
"PR",
"PS",
"PT",
"PW",
"PY",
"QA",
"RE",
"RO",
"RS",
"RW",
"SA",
"SB",
"SC",
"SE",
"SG",
"SH",
"SI",
"SJ",
"SK",
"SL",
"SM",
"SN",
"SR",
"ST",
"SV",
"SX",
"SZ",
"TC",
"TD",
"TF",
"TG",
"TH",
"TJ",
"TK",
"TL",
"TM",
"TN",
"TO",
"TR",
"TT",
"TV",
"TW",
"TZ",
"UA",
"UG",
"UM",
"US",
"UY",
"UZ",
"VA",
"VC",
"VG",
"VI",
"VN",
"VU",
"WF",
"WS",
"XK",
"YT",
"ZA",
"ZM",
]))
.describe("Supported two-letter ISO 3166-1 alpha-2 country code. Customers located in the listed countries are charged the override price."),
unitPrice: z
.object({
amount: z
.string()
.describe("Amount in the lowest denomination for the currency, e.g. 10 USD = 1000 (cents). Although represented as a string, this value must be a valid integer."),
currencyCode: z
.enum([
"USD",
"EUR",
"GBP",
"JPY",
"AUD",
"CAD",
"CHF",
"HKD",
"SGD",
"SEK",
"ARS",
"BRL",
"CLP",
"CNY",
"COP",
"CZK",
"DKK",
"HUF",
"ILS",
"INR",
"KRW",
"MXN",
"NOK",
"NZD",
"PEN",
"PLN",
"RUB",
"THB",
"TRY",
"TWD",
"UAH",
"VND",
"ZAR",
])
.describe("Supported three-letter ISO 4217 currency code."),
})
.describe("Override price. This price applies to customers located in the countries for this unit price override."),
}))
.optional()
.describe("List of unit price overrides. Use to override the base price with a custom price and currency for a country or group of countries."),
quantity: z
.object({
minimum: z
.number()
.describe("Minimum quantity of the product related to this price that can be bought. Required if `maximum` set."),
maximum: z
.number()
.describe("Maximum quantity of the product related to this price that can be bought. Required if `minimum` set. Must be greater than or equal to the `minimum` value."),
})
.optional()
.describe("Limits on how many times the related product can be purchased at this price. Useful for discount campaigns."),
status: z.enum(["active", "archived"]).optional().describe("Whether this price can be used in Paddle."),
customData: z.record(z.any(), z.any()).optional().describe("Any structured custom key-value data needed outside of Paddle's standard fields. Occasionally used by third-parties."),
});
export const listTransactionsParameters = z.object({
after: z
.string()
.optional()
.describe("Return entities after the specified Paddle ID when working with paginated endpoints."),
billedAt: z
.string()
.optional()
.describe("Return entities billed at this exact time. Pass an RFC 3339 datetime string."),
billedAtLT: z
.string()
.optional()
.describe("Return entities billed before this time. Pass an RFC 3339 datetime string."),
billedAtLTE: z
.string()
.optional()
.describe("Return entities billed at or before this time. Pass an RFC 3339 datetime string."),
billedAtGT: z
.string()
.optional()
.describe("Return entities billed after this time. Pass an RFC 3339 datetime string."),
billedAtGTE: z
.string()
.optional()
.describe("Return entities billed at or after this time. Pass an RFC 3339 datetime string."),
collectionMode: z
.enum(["automatic", "manual"])
.optional()
.describe("Return entities that match the specified collection mode."),
createdAt: z
.string()
.optional()
.describe("Return entities created at this exact time. Pass an RFC 3339 datetime string."),
createdAtLT: z
.string()
.optional()
.describe("Return entities created before this time. Pass an RFC 3339 datetime string."),
createdAtLTE: z
.string()
.optional()
.describe("Return entities created at or before this time. Pass an RFC 3339 datetime string."),
createdAtGT: z
.string()
.optional()
.describe("Return entities created after this time. Pass an RFC 3339 datetime string."),
createdAtGTE: z
.string()
.optional()
.describe("Return entities created at or after this time. Pass an RFC 3339 datetime string."),
customerId: z
.array(z.string())
.optional()
.describe("Return entities related to the specified customer. Use a comma-separated list to specify multiple customer IDs."),
id: z
.array(z.string())
.optional()
.describe("Return only the IDs specified. Use a comma-separated list to get multiple entities."),
include: z
.array(z.enum([
"address",
"adjustments",
"adjustments_totals",
"available_payment_methods",
"business",
"customer",
"discount",
]))
.optional()
.describe("Include related entities in the response. Use a comma-separated list to specify multiple entities."),
invoiceNumber: z
.array(z.string())
.optional()
.describe("Return entities that match the invoice number. Use a comma-separated list to specify multiple invoice numbers."),
origin: z
.array(z.enum([
"api",
"subscription_charge",
"subscription_payment_method_change",
"subscription_recurring",
"subscription_update",
"web",
]))
.optional()
.describe("Return entities related to the specified origin. Use a comma-separated list to specify multiple origins."),
orderBy: z
.enum([
"billed_at[ASC]",
"billed_at[DESC]",
"created_at[ASC]",
"created_at[DESC]",
"id[ASC]",
"id[DESC]",
"updated_at[ASC]",
"updated_at[DESC]",
])
.optional()
.describe("Order returned entities by the specified field and direction."),
status: z
.array(z.enum(["draft", "ready", "billed", "paid", "completed", "canceled", "past_due"]))
.optional()
.describe("Return entities that match the specified status. Use a comma-separated list to specify multiple status values."),
subscriptionId: z
.array(z.string())
.optional()
.describe("Return entities related to the specified subscription. Use a comma-separated list to specify multiple subscription IDs. Pass `null` to return entities that aren't related to any subscription."),
perPage: z.number().optional().describe("Set how many entities are returned per page."),
updatedAt: z
.string()
.optional()
.describe("Return entities updated at this exact time. Pass an RFC 3339 datetime string."),
updatedAtLT: z
.string()
.optional()
.describe("Return entities updated before this time. Pass an RFC 3339 datetime string."),
updatedAtLTE: z
.string()
.optional()
.describe("Return entities updated at or before this time. Pass an RFC 3339 datetime string."),
updatedAtGT: z
.string()
.optional()
.describe("Return entities updated after this time. Pass an RFC 3339 datetime string."),
updatedAtGTE: z
.string()
.optional()
.describe("Return entities updated at or after this time. Pass an RFC 3339 datetime string."),
});
export const createTransactionParameters = z.object({
status: z
.enum(["billed", "canceled"])
.optional()
.describe("Status of this transaction. Either set a transaction to `billed` or `canceled` when creating, or omit to let Paddle set the status. Transactions are created as `ready` if they have an `addressId`, `customerId`, and `items`, otherwise they are created as `draft`. Marking as `billed` when creating is typically used when working with manually-collected transactions as part of an invoicing workflow. Billed transactions cannot be updated, only canceled."),
customerId: z
.string()
.optional()
.describe("Paddle ID of the customer that this transaction is for, prefixed with `ctm_`. If omitted, transaction status is `draft`."),
addressId: z
.string()
.optional()
.describe("Paddle ID of the address that this transaction is for, prefixed with `add_`. Requires `customerId`. If omitted, transaction status is `draft`."),
businessId: z
.string()
.optional()
.describe("Paddle ID of the business that this transaction is for, prefixed with `biz_`. Requires `customerId`. "),
customData: z.record(z.any(), z.any()).optional().describe("Any structured custom key-value data needed outside of Paddle's standard fields. Occasionally used by third-parties."),
currencyCode: z
.enum([
"USD",
"EUR",
"GBP",
"JPY",
"AUD",
"CAD",
"CHF",
"HKD",
"SGD",
"SEK",
"ARS",
"BRL",
"CLP",
"CNY",
"COP",
"CZK",
"DKK",
"HUF",
"ILS",
"INR",
"KRW",
"MXN",
"NOK",
"NZD",
"PEN",
"PLN",
"RUB",
"THB",
"TRY",
"TWD",
"UAH",
"VND",
"ZAR",
])
.optional()
.describe("Supported three-letter ISO 4217 currency code. Must be `USD`, `EUR`, or `GBP` if `collectionMode` is `manual`."),
collectionMode: z
.enum(["automatic", "manual"])
.optional()
.describe("How payment is collected for this transaction. `automatic` for checkout, `manual` for invoices. If omitted, defaults to `automatic`."),
discountId: z
.string()
.optional()
.describe("Paddle ID of the discount applied to this transaction, prefixed with `dsc_`."),
billingDetails: z
.object({
enableCheckout: z
.boolean()
.optional()
.describe("Whether the related transaction may be paid using Paddle Checkout. If omitted when creating a transaction, defaults to `false`."),
purchaseOrderNumber: z
.string()
.optional()
.describe("Customer purchase order number. Appears on invoice documents."),
additionalInformation: z
.string()
.optional()
.describe("Notes or other information to include on this invoice. Appears on invoice documents."),
paymentTerms: z
.object({
interval: z.enum(["day", "week", "month", "year"]).describe("Unit of time."),
frequency: z.number().describe("Amount of time."),
})
.describe("How long a customer has to pay this invoice once issued."),
})
.optional()
.describe("Details for invoicing. Required if `collectionMode` is `manual`."),
billingPeriod: z
.object({
startsAt: z.string().describe("RFC 3339 datetime string of when this period starts."),
endsAt: z.string().describe("RFC 3339 datetime string of when this period ends."),
})
.optional()
.describe("Time period that this transaction is for. Set automatically by Paddle for subscription renewals to describe the period that charges are for."),
items: z
.array(z.union([
z.object({
priceId: z.string().describe("Paddle ID of an existing catalog price to add to this transaction, prefixed with `pri_`."),
quantity: z.number().describe("Quantity of the item to charge for."),
price: z.never().optional(),
}),
z.object({
price: nonCatalogPriceSchema.describe("Non-catalog price object."),
quantity: z.number().describe("Quantity of the item to charge for."),
priceId: z.never().optional(),
}),
]))
.describe("List of items to charge for. Charge for items that have been added to the catalog by passing the Paddle ID of an existing price entity, or charge for non-catalog items by passing a price object. Non-catalog items can be for existing products, or pass a product object as part of the price to charge for a non-catalog product."),
checkout: z
.object({
url: z.string().describe("Checkout URL to use for the payment link for this transaction. Passed URLs must be approved on the account, or omit to the default payment URL on the account."),
})
.optional()
.describe("Paddle Checkout details for this transaction. Used for automatically-collected transactions, or when creating or updating a manually-collected transaction where `billingDetails.enableCheckout` is `true`."),
include: z
.array(z.enum([
"address",
"adjustments",
"adjustments_totals",
"available_payment_methods",
"business",
"customer",
"discount",
]))
.optional()
.describe("Include related entities in the response. Use a comma-separated list to specify multiple entities."),
});
export const previewPricesParameters = z.object({
customerId: z
.string()
.optional()
.describe("Paddle ID of the customer that this preview is for, prefixed with `ctm_`."),
addressId: z
.string()
.optional()
.describe("Paddle ID of the address that this preview is for, prefixed with `add_`. Send one of `addressId`, `customerIpAddress`, or the `address` object when previewing."),
businessId: z
.string()
.optional()
.describe("Paddle ID of the business that this preview is for, prefixed with `biz_`."),
currencyCode: z
.enum([
"USD",
"EUR",
"GBP",
"JPY",
"AUD",
"CAD",
"CHF",
"HKD",
"SGD",
"SEK",
"ARS",
"BRL",
"CLP",
"CNY",
"COP",
"CZK",
"DKK",
"HUF",
"ILS",
"INR",
"KRW",
"MXN",
"NOK",
"NZD",
"PEN",
"PLN",
"RUB",
"THB",
"TRY",
"TWD",
"UAH",
"VND",
"ZAR",
])
.optional()
.describe("Supported three-letter ISO 4217 currency code."),
discountId: z
.string()
.optional()
.describe("Paddle ID of the discount applied to this preview, prefixed with `dsc_`."),
address: z
.object({
postalCode: z
.string()
.optional()
.describe("ZIP or postal code of this address. Include for more accurate tax calculations."),
countryCode: z
.enum([
"AD",
"AE",
"AG",
"AI",
"AL",
"AM",
"AO",
"AR",
"AS",
"AT",
"AU",
"AW",
"AX",
"AZ",
"BA",
"BB",
"BD",
"BE",
"BF",
"BG",
"BH",
"BI",
"BJ",
"BL",
"BM",
"BN",
"BO",
"BQ",
"BR",
"BS",
"BT",
"BV",
"BW",
"BZ",
"CA",
"CC",
"CG",
"CH",
"CI",
"CK",
"CL",
"CM",
"CN",
"CO",
"CR",
"CV",
"CW",
"CX",
"CY",
"CZ",
"DE",
"DJ",
"DK",
"DM",
"DO",
"DZ",
"EC",
"EE",
"EG",
"EH",
"ER",
"ES",
"ET",
"FI",
"FJ",
"FK",
"FM",
"FO",
"FR",
"GA",
"GB",
"GD",
"GE",
"GF",
"GG",
"GH",
"GI",
"GL",
"GM",
"GN",
"GP",
"GQ",
"GR",
"GS",
"GT",
"GU",
"GW",
"GY",
"HK",
"HM",
"HN",
"HR",
"HU",
"ID",
"IE",
"IL",
"IM",
"IN",
"IO",
"IQ",
"IS",
"IT",
"JE",
"JM",
"JO",
"JP",
"KE",
"KG",
"KH",
"KI",
"KM",
"KN",
"KR",
"KW",
"KY",
"KZ",
"LA",
"LB",
"LC",
"LI",
"LK",
"LR",
"LS",
"LT",
"LU",
"LV",
"MA",
"MC",
"MD",
"ME",
"MF",
"MG",
"MH",
"MK",
"MN",
"MO",
"MP",
"MQ",
"MR",
"MS",
"MT",
"MU",
"MV",
"MW",
"MX",
"MY",
"MZ",
"NA",
"NC",
"NE",
"NF",
"NG",
"NL",
"NO",
"NP",
"NR",
"NU",
"NZ",
"OM",
"PA",
"PE",
"PF",
"PG",
"PH",
"PK",
"PL",
"PM",
"PN",
"PR",
"PS",
"PT",
"PW",
"PY",
"QA",
"RE",
"RO",
"RS",
"RW",
"SA",
"SB",
"SC",
"SE",
"SG",
"SH",
"SI",
"SJ",
"SK",
"SL",
"SM",
"SN",
"SR",
"ST",
"SV",
"SX",
"SZ",
"TC",
"TD",
"TF",
"TG",
"TH",
"TJ",
"TK",
"TL",
"TM",
"TN",
"TO",
"TR",
"TT",
"TV",
"TW",
"TZ",
"UA",
"UG",
"UM",
"US",
"UY",
"UZ",
"VA",
"VC",
"VG",
"VI",
"VN",
"VU",
"WF",
"WS",
"XK",
"YT",
"ZA",
"ZM",
])
.describe("Two-letter ISO 3166-1 alpha-2 country code."),
})
.optional()
.describe("Address for this preview. Send one of `addressId`, `customerIpAddress`, or the `address` object when previewing."),
customerIpAddress: z
.string()
.optional()
.describe("IP address for this transaction preview. Send one of `addressId`, `customerIpAddress`, or the `address` object when previewing."),
items: z
.array(z.object({
priceId: z.string().describe("Paddle ID for the price to add to this transaction, prefixed with `pri_`."),
quantity: z.number().describe("Quantity of the item to preview."),
}))
.describe("List of items to pre