> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt). # transaction.canceled Occurs when a transaction is canceled. Its `status` field changes to `canceled`. --- Occurs when a transaction is canceled. Its `status` field changes to `canceled`. Marking a transaction as canceled is typically used when working with manually-collected transactions to say that an invoice was created in error. It's not typically part of checkout workflows, where collection mode is automatic. Transactions are marked as canceled when: - You update its status to `canceled` using the API. - You cancel an invoice (a manually-collected transaction) using the Paddle dashboard. ## Schema ```json { "type": "object", "required": [ "event_id", "event_type", "occurred_at", "notification_id", "data" ], "properties": { "event_id": { "type": "string", "pattern": "^evt_[a-z\\d]{26}$", "description": "Unique Paddle ID for this event, prefixed with `evt_`.", "title": "Event ID", "examples": [ "evt_01gks14ge726w50ch2tmaw2a1x" ] }, "event_type": { "type": "string", "enum": [ "address.created", "address.imported", "address.updated", "adjustment.created", "adjustment.updated", "api_key.created", "api_key.expired", "api_key.expiring", "api_key.revoked", "api_key.updated", "api_key_exposure.created", "business.created", "business.imported", "business.updated", "client_token.created", "client_token.revoked", "client_token.updated", "customer.created", "customer.imported", "customer.updated", "discount.created", "discount.imported", "discount.updated", "discount_group.created", "discount_group.updated", "payment_method.saved", "payment_method.deleted", "payout.created", "payout.paid", "price.created", "price.imported", "price.updated", "product.created", "product.imported", "product.updated", "report.created", "report.updated", "subscription.activated", "subscription.canceled", "subscription.created", "subscription.imported", "subscription.past_due", "subscription.paused", "subscription.resumed", "subscription.trialing", "subscription.updated", "transaction.billed", "transaction.canceled", "transaction.completed", "transaction.created", "transaction.paid", "transaction.past_due", "transaction.payment_failed", "transaction.ready", "transaction.revised", "transaction.updated" ], "description": "Type of event sent by Paddle, in the format `entity.event_type`.", "title": "Event type name", "x-enum-descriptions": { "address.created": { "description": "An [`address.created`](https://developer.paddle.com/webhooks/addresses/address-created) event." }, "address.imported": { "description": "An [`address.imported`](https://developer.paddle.com/webhooks/addresses/address-imported) event." }, "address.updated": { "description": "An [`address.updated`](https://developer.paddle.com/webhooks/addresses/address-updated) event." }, "adjustment.created": { "description": "An [`adjustment.created`](https://developer.paddle.com/webhooks/adjustments/adjustment-created) event." }, "adjustment.updated": { "description": "An [`adjustment.updated`](https://developer.paddle.com/webhooks/adjustments/adjustment-updated) event." }, "api_key.created": { "description": "An [`api_key.created`](https://developer.paddle.com/webhooks/api-keys/api-key-created) event." }, "api_key.expired": { "description": "An [`api_key.expired`](https://developer.paddle.com/webhooks/api-keys/api-key-expired) event." }, "api_key.expiring": { "description": "An [`api_key.expiring`](https://developer.paddle.com/webhooks/api-keys/api-key-expiring) event." }, "api_key.revoked": { "description": "An [`api_key.revoked`](https://developer.paddle.com/webhooks/api-keys/api-key-revoked) event." }, "api_key.updated": { "description": "An [`api_key.updated`](https://developer.paddle.com/webhooks/api-keys/api-key-updated) event." }, "api_key_exposure.created": { "description": "An [`api_key_exposure.created`](https://developer.paddle.com/webhooks/api-key-exposures/api-key-exposure-created) event." }, "business.created": { "description": "A [`business.created`](https://developer.paddle.com/webhooks/businesses/business-created) event." }, "business.imported": { "description": "A [`business.imported`](https://developer.paddle.com/webhooks/businesses/business-imported) event." }, "business.updated": { "description": "A [`business.updated`](https://developer.paddle.com/webhooks/businesses/business-updated) event." }, "client_token.created": { "description": "A [`client_token.created`](https://developer.paddle.com/webhooks/client-tokens/client-token-created) event." }, "client_token.revoked": { "description": "A [`client_token.revoked`](https://developer.paddle.com/webhooks/client-tokens/client-token-revoked) event." }, "client_token.updated": { "description": "A [`client_token.updated`](https://developer.paddle.com/webhooks/client-tokens/client-token-updated) event." }, "customer.created": { "description": "A [`customer.created`](https://developer.paddle.com/webhooks/customers/customer-created) event." }, "customer.imported": { "description": "A [`customer.imported`](https://developer.paddle.com/webhooks/customers/customer-imported) event." }, "customer.updated": { "description": "A [`customer.updated`](https://developer.paddle.com/webhooks/customers/customer-updated) event." }, "discount.created": { "description": "A [`discount.created`](https://developer.paddle.com/webhooks/discounts/discount-created) event." }, "discount.imported": { "description": "A [`discount.imported`](https://developer.paddle.com/webhooks/discounts/discount-imported) event." }, "discount.updated": { "description": "A [`discount.updated`](https://developer.paddle.com/webhooks/discounts/discount-updated) event." }, "discount_group.created": { "description": "A [`discount_group.created`](https://developer.paddle.com/webhooks/discount-groups/discount-group-created) event." }, "discount_group.updated": { "description": "A [`discount_group.updated`](https://developer.paddle.com/webhooks/discount-groups/discount-group-updated) event." }, "payment_method.saved": { "description": "A [`payment_method.saved`](https://developer.paddle.com/webhooks/payment-methods/payment-method-saved) event." }, "payment_method.deleted": { "description": "A [`payment_method.deleted`](https://developer.paddle.com/webhooks/payment-methods/payment-method-deleted) event." }, "payout.created": { "description": "A [`payout.created`](https://developer.paddle.com/webhooks/payouts/payout-created) event." }, "payout.paid": { "description": "A [`payout.paid`](https://developer.paddle.com/webhooks/payouts/payout-paid) event." }, "price.created": { "description": "A [`price.created`](https://developer.paddle.com/webhooks/prices/price-created) event." }, "price.imported": { "description": "A [`price.imported`](https://developer.paddle.com/webhooks/prices/price-imported) event." }, "price.updated": { "description": "A [`price.updated`](https://developer.paddle.com/webhooks/prices/price-updated) event." }, "product.created": { "description": "A [`product.created`](https://developer.paddle.com/webhooks/products/product-created) event." }, "product.imported": { "description": "A [`product.imported`](https://developer.paddle.com/webhooks/products/product-imported) event." }, "product.updated": { "description": "A [`product.updated`](https://developer.paddle.com/webhooks/products/product-updated) event." }, "report.created": { "description": "A [`report.created`](https://developer.paddle.com/webhooks/reports/report-created) event." }, "report.updated": { "description": "A [`report.updated`](https://developer.paddle.com/webhooks/reports/report-updated) event." }, "subscription.activated": { "description": "A [`subscription.activated`](https://developer.paddle.com/webhooks/subscriptions/subscription-activated) event." }, "subscription.canceled": { "description": "A [`subscription.canceled`](https://developer.paddle.com/webhooks/subscriptions/subscription-canceled) event." }, "subscription.created": { "description": "A [`subscription.created`](https://developer.paddle.com/webhooks/subscriptions/subscription-created) event." }, "subscription.imported": { "description": "A [`subscription.imported`](https://developer.paddle.com/webhooks/subscriptions/subscription-imported) event." }, "subscription.past_due": { "description": "A [`subscription.past_due`](https://developer.paddle.com/webhooks/subscriptions/subscription-past-due) event." }, "subscription.paused": { "description": "A [`subscription.paused`](https://developer.paddle.com/webhooks/subscriptions/subscription-paused) event." }, "subscription.resumed": { "description": "A [`subscription.resumed`](https://developer.paddle.com/webhooks/subscriptions/subscription-resumed) event." }, "subscription.trialing": { "description": "A [`subscription.trialing`](https://developer.paddle.com/webhooks/subscriptions/subscription-trialing) event." }, "subscription.updated": { "description": "A [`subscription.updated`](https://developer.paddle.com/webhooks/subscriptions/subscription-updated) event." }, "transaction.billed": { "description": "A [`transaction.billed`](https://developer.paddle.com/webhooks/transactions/transaction-billed) event." }, "transaction.canceled": { "description": "A [`transaction.canceled`](https://developer.paddle.com/webhooks/transactions/transaction-canceled) event." }, "transaction.completed": { "description": "A [`transaction.completed`](https://developer.paddle.com/webhooks/transactions/transaction-completed) event." }, "transaction.created": { "description": "A [`transaction.created`](https://developer.paddle.com/webhooks/transactions/transaction-created) event." }, "transaction.paid": { "description": "A [`transaction.paid`](https://developer.paddle.com/webhooks/transactions/transaction-paid) event." }, "transaction.past_due": { "description": "A [`transaction.past_due`](https://developer.paddle.com/webhooks/transactions/transaction-past-due) event." }, "transaction.payment_failed": { "description": "A [`transaction.payment_failed`](https://developer.paddle.com/webhooks/transactions/transaction-payment-failed) event." }, "transaction.ready": { "description": "A [`transaction.ready`](https://developer.paddle.com/webhooks/transactions/transaction-ready) event." }, "transaction.revised": { "description": "A [`transaction.revised`](https://developer.paddle.com/webhooks/transactions/transaction-revised) event." }, "transaction.updated": { "description": "A [`transaction.updated`](https://developer.paddle.com/webhooks/transactions/transaction-updated) event." } } }, "occurred_at": { "type": "string", "format": "date-time", "description": "RFC 3339 datetime string of when this event occurred.", "title": "Timestamp", "examples": [ "2024-10-12T07:20:50.52Z" ] }, "notification_id": { "type": "string", "pattern": "^ntf_[a-z\\d]{26}$", "description": "Unique Paddle ID for this notification, prefixed with `ntf_`.", "title": "Notification ID", "examples": [ "ntf_01ghbkd0frb9k95cnhwd1bxpvk" ] }, "data": { "properties": { "id": { "type": "string", "pattern": "^txn_[a-z\\d]{26}$", "description": "Unique Paddle ID for this transaction entity, prefixed with `txn_`.", "title": "Transaction ID", "examples": [ "txn_01h04vsbhqc62t8hmd4z3b578c" ] }, "status": { "type": "string", "enum": [ "draft", "ready", "billed", "paid", "completed", "canceled", "past_due" ], "description": "Status of this transaction. You may set a transaction to `billed` or `canceled`, other statuses are set automatically by Paddle. Automatically-collected transactions may return `completed` if payment is captured successfully, or `past_due` if payment failed.", "x-enum-descriptions": { "draft": { "description": "Transaction is missing required fields. Typically the first stage of a checkout before customer details are captured." }, "ready": { "description": "Transaction has all of the required fields to be marked as `billed` or `completed`." }, "billed": { "description": "Transaction has been updated to `billed`. Billed transactions get an invoice number and are considered a legal record. They cannot be changed. Typically used as part of an invoice workflow." }, "paid": { "description": "Transaction is fully paid, but has not yet been processed internally." }, "completed": { "description": "Transaction is fully paid and processed." }, "canceled": { "description": "Transaction has been updated to `canceled`. If an invoice, it's no longer due." }, "past_due": { "description": "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." } } }, "customer_id": { "anyOf": [ { "type": "string", "pattern": "^ctm_[a-z\\d]{26}$", "description": "Unique Paddle ID for this customer entity, prefixed with `ctm_`.", "title": "Customer ID", "examples": [ "ctm_01grnn4zta5a1mf02jjze7y2ys" ] }, { "type": "null" } ], "description": "Paddle ID of the customer that this transaction is for, prefixed with `ctm_`." }, "address_id": { "anyOf": [ { "type": "string", "pattern": "^add_[a-z\\d]{26}$", "description": "Unique Paddle ID for this address entity, prefixed with `add_`.", "title": "Address ID", "examples": [ "add_01gm302t81w94gyjpjpqypkzkf" ] }, { "type": "null" } ], "description": "Paddle ID of the address that this transaction is for, prefixed with `add_`." }, "business_id": { "anyOf": [ { "type": "string", "pattern": "^biz_[a-z\\d]{26}$", "description": "Unique Paddle ID for this business entity, prefixed with `biz_`.", "title": "Business ID", "examples": [ "biz_01grrebrzaee2qj2fqqhmcyzaj" ] }, { "type": "null" } ], "description": "Paddle ID of the business that this transaction is for, prefixed with `biz_`." }, "custom_data": { "anyOf": [ { "type": "object", "unevaluatedProperties": {}, "description": "Your own structured key-value data.", "title": "Custom Data", "example": { "customer_reference_id": "abcd1234" } }, { "type": "null" } ], "description": "Your own structured key-value data." }, "currency_code": { "type": "string", "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" ], "description": "Supported three-letter ISO 4217 currency code. Must be `USD`, `EUR`, or `GBP` if `collection_mode` is `manual`.", "title": "Currency code", "x-enum-descriptions": { "USD": { "description": "United States Dollar" }, "EUR": { "description": "Euro" }, "GBP": { "description": "Pound Sterling" }, "JPY": { "description": "Japanese Yen" }, "AUD": { "description": "Australian Dollar" }, "CAD": { "description": "Canadian Dollar" }, "CHF": { "description": "Swiss Franc" }, "HKD": { "description": "Hong Kong Dollar" }, "SGD": { "description": "Singapore Dollar" }, "SEK": { "description": "Swedish Krona" }, "ARS": { "description": "Argentine Peso" }, "BRL": { "description": "Brazilian Real" }, "CLP": { "description": "Chilean Peso" }, "CNY": { "description": "Chinese Yuan" }, "COP": { "description": "Colombian Peso" }, "CZK": { "description": "Czech Koruna" }, "DKK": { "description": "Danish Krone" }, "HUF": { "description": "Hungarian Forint" }, "ILS": { "description": "Israeli Shekel" }, "INR": { "description": "Indian Rupee" }, "KRW": { "description": "South Korean Won" }, "MXN": { "description": "Mexican Peso" }, "NOK": { "description": "Norwegian Krone" }, "NZD": { "description": "New Zealand Dollar" }, "PEN": { "description": "Peruvian Sol" }, "PLN": { "description": "Polish Zloty" }, "RUB": { "description": "Russian Ruble" }, "THB": { "description": "Thai Baht" }, "TRY": { "description": "Turkish Lira" }, "TWD": { "description": "New Taiwan Dollar" }, "UAH": { "description": "Ukrainian Hryvnia" }, "VND": { "description": "Vietnamese Dong" }, "ZAR": { "description": "South African Rand" } } }, "origin": { "oneOf": [ { "type": "string", "enum": [ "api", "subscription_charge", "subscription_payment_method_change", "subscription_recurring", "subscription_update", "web" ], "x-enum-descriptions": { "api": { "description": "Transaction created via the Paddle API." }, "subscription_charge": { "description": "Transaction created automatically by Paddle as a result of a one-time charge for a subscription." }, "subscription_payment_method_change": { "description": "Transaction created automatically as part of updating a payment method. May be a zero value transaction." }, "subscription_recurring": { "description": "Transaction created automatically by Paddle as a result of a subscription renewal." }, "subscription_update": { "description": "Transaction created automatically by Paddle as a result of an update to a subscription." }, "web": { "description": "Transaction created automatically by Paddle.js for a checkout." } } } ], "description": "Describes how this transaction was created." }, "subscription_id": { "anyOf": [ { "type": "string", "pattern": "^sub_[a-z\\d]{26}$", "description": "Unique Paddle ID for this subscription entity, prefixed with `sub_`.", "title": "Subscription ID", "examples": [ "sub_01h04vsc0qhwtsbsxh3422wjs4" ] }, { "type": "null" } ], "description": "Paddle ID of the subscription that this transaction is for, prefixed with `sub_`." }, "invoice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "pattern": "^inv_[a-z\\d]{26}$", "description": "Paddle ID of the invoice that this transaction is related to, prefixed with `inv_`. Used for compatibility with the Paddle Invoice API, which is now deprecated. This field is scheduled to be removed in the next version of the Paddle API.", "deprecated": true, "examples": [ "inv_01ghbk4xjn4qdsmstcwzgcgg35" ] }, "invoice_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Invoice number for this transaction. Automatically generated by Paddle when you mark a transaction as `billed` where `collection_mode` is `manual`.", "examples": [ "123-45678" ] }, "collection_mode": { "type": "string", "enum": [ "automatic", "manual" ], "description": "How payment is collected for this transaction. `automatic` for checkout, `manual` for invoices.", "title": "Collection mode", "x-enum-descriptions": { "automatic": { "description": "Payment is collected automatically using a checkout initially, then using a payment method on file." }, "manual": { "description": "Payment is collected manually. Customers are sent an invoice with payment terms and can make a payment offline or using a checkout. Requires `billing_details`." } } }, "discount_id": { "anyOf": [ { "type": "string", "pattern": "^dsc_[a-z\\d]{26}$", "description": "Unique Paddle ID for this discount, prefixed with `dsc_`.", "title": "Discount ID", "examples": [ "dsc_01gv5kpg05xp104ek2fmgjwttf" ] }, { "type": "null" } ], "description": "Paddle ID of the discount applied to this transaction, prefixed with `dsc_`." }, "billing_details": { "anyOf": [ { "type": "object", "required": [ "enable_checkout", "purchase_order_number", "additional_information", "payment_terms" ], "properties": { "enable_checkout": { "type": "boolean", "description": "Whether the related transaction may be paid using Paddle Checkout. If omitted when creating a transaction, defaults to `false`.", "default": false }, "purchase_order_number": { "type": "string", "maxLength": 100, "description": "Customer purchase order number. Appears on invoice documents." }, "additional_information": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "maxLength": 1500, "description": "Notes or other information to include on this invoice. Appears on invoice documents." }, "payment_terms": { "properties": { "interval": { "type": "string", "enum": [ "day", "week", "month", "year" ], "description": "Unit of time." }, "frequency": { "type": "integer", "minimum": 1, "description": "Amount of time." } }, "required": [ "interval", "frequency" ], "type": "object", "title": "Duration", "description": "How long a customer has to pay this invoice once issued." } }, "description": "Details for invoicing. Required if `collection_mode` is `manual`.", "title": "Billing details" }, { "type": "null" } ], "description": "Details for invoicing. Required if `collection_mode` is `manual`." }, "billing_period": { "anyOf": [ { "type": "object", "required": [ "starts_at", "ends_at" ], "properties": { "starts_at": { "type": "string", "format": "date-time", "description": "RFC 3339 datetime string of when this period starts.", "title": "Timestamp", "examples": [ "2024-10-12T07:20:50.52Z" ] }, "ends_at": { "type": "string", "format": "date-time", "description": "RFC 3339 datetime string of when this period ends.", "title": "Timestamp", "examples": [ "2024-10-12T07:20:50.52Z" ] } }, "title": "Time period" }, { "type": "null" } ], "description": "Time period that this transaction is for. Set automatically by Paddle for subscription renewals to describe the period that charges are for." }, "items": { "type": "array", "items": { "type": "object", "required": [ "price", "quantity", "proration" ], "properties": { "price": { "properties": { "id": { "type": "string", "pattern": "^pri_[a-z\\d]{26}$", "description": "Unique Paddle ID for this price, prefixed with `pri_`.", "title": "Price ID", "examples": [ "pri_01gsz8z1q1n00f12qt82y31smh" ] }, "product_id": { "type": "string", "pattern": "^pro_[a-z\\d]{26}$", "description": "Paddle ID for the product that this price is for, prefixed with `pro_`.", "title": "Product ID", "examples": [ "pro_01gsz97mq9pa4fkyy0wqenepkz" ] }, "description": { "type": "string", "minLength": 2, "maxLength": 500, "description": "Internal description for this price, not shown to customers. Typically notes for your team." }, "type": { "type": "string", "enum": [ "custom", "standard" ], "description": "Type of item. Standard items are considered part of your catalog and are shown in the Paddle dashboard.", "title": "CatalogType", "x-enum-descriptions": { "custom": { "description": "Non-catalog item. Typically created for a specific transaction or subscription. Not returned when listing or shown in the Paddle dashboard." }, "standard": { "description": "Standard item. Can be considered part of your catalog and reused across transactions and subscriptions easily." } }, "default": "standard" }, "name": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 150, "description": "Name of this price, shown to customers at checkout and on invoices. Typically describes how often the related product bills.", "title": "Price Name" }, { "type": "null" } ] }, "billing_cycle": { "anyOf": [ { "type": "object", "required": [ "interval", "frequency" ], "properties": { "interval": { "type": "string", "enum": [ "day", "week", "month", "year" ], "description": "Unit of time." }, "frequency": { "type": "integer", "minimum": 1, "description": "Amount of time." } }, "title": "Duration" }, { "type": "null" } ], "description": "How often this price should be charged. `null` if price is non-recurring (one-time)." }, "trial_period": { "anyOf": [ { "type": "object", "required": [ "interval", "frequency", "requires_payment_method" ], "properties": { "interval": { "type": "string", "enum": [ "day", "week", "month", "year" ], "description": "Unit of time." }, "frequency": { "type": "integer", "minimum": 1, "description": "Amount of time." }, "requires_payment_method": { "type": "boolean", "description": "Whether this price requires a payment method (`true`) or not (`false`) when trialing. If `false`, customers can sign up for subscription without entering their payment details, often referred to as a \"cardless trial.\"", "title": "Price Requires Payment Method", "default": true } }, "title": "Price Trial Duration" }, { "type": "null" } ], "description": "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 `billing_cycle`." }, "tax_mode": { "type": "string", "enum": [ "account_setting", "external", "internal", "location" ], "description": "How tax is calculated for this price.", "title": "Tax mode", "x-enum-descriptions": { "account_setting": { "description": "Prices use the setting from your account." }, "external": { "description": "Prices are exclusive of tax." }, "internal": { "description": "Prices are inclusive of tax." }, "location": { "description": "Prices are inclusive or exclusive of tax, depending on the country of the transaction." } }, "default": "account_setting" }, "unit_price": { "properties": { "amount": { "type": "string", "description": "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." }, "currency_code": { "type": "string", "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" ], "description": "Supported three-letter ISO 4217 currency code.", "title": "Currency code", "x-enum-descriptions": { "USD": { "description": "United States Dollar" }, "EUR": { "description": "Euro" }, "GBP": { "description": "Pound Sterling" }, "JPY": { "description": "Japanese Yen" }, "AUD": { "description": "Australian Dollar" }, "CAD": { "description": "Canadian Dollar" }, "CHF": { "description": "Swiss Franc" }, "HKD": { "description": "Hong Kong Dollar" }, "SGD": { "description": "Singapore Dollar" }, "SEK": { "description": "Swedish Krona" }, "ARS": { "description": "Argentine Peso" }, "BRL": { "description": "Brazilian Real" }, "CLP": { "description": "Chilean Peso" }, "CNY": { "description": "Chinese Yuan" }, "COP": { "description": "Colombian Peso" }, "CZK": { "description": "Czech Koruna" }, "DKK": { "description": "Danish Krone" }, "HUF": { "description": "Hungarian Forint" }, "ILS": { "description": "Israeli Shekel" }, "INR": { "description": "Indian Rupee" }, "KRW": { "description": "South Korean Won" }, "MXN": { "description": "Mexican Peso" }, "NOK": { "description": "Norwegian Krone" }, "NZD": { "description": "New Zealand Dollar" }, "PEN": { "description": "Peruvian Sol" }, "PLN": { "description": "Polish Zloty" }, "RUB": { "description": "Russian Ruble" }, "THB": { "description": "Thai Baht" }, "TRY": { "description": "Turkish Lira" }, "TWD": { "description": "New Taiwan Dollar" }, "UAH": { "description": "Ukrainian Hryvnia" }, "VND": { "description": "Vietnamese Dong" }, "ZAR": { "description": "South African Rand" } } } }, "required": [ "amount", "currency_code" ], "type": "object", "description": "Base price. This price applies to all customers, except for customers located in countries where you have `unit_price_overrides`.", "title": "Money" }, "unit_price_overrides": { "type": "array", "items": { "type": "object", "required": [ "country_codes", "unit_price" ], "properties": { "country_codes": { "type": "array", "items": { "oneOf": [ { "type": "string", "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" ], "description": "Two-letter ISO 3166-1 alpha-2 representation of a supported country.", "x-enum-descriptions": { "AD": { "description": "Andorra" }, "AE": { "description": "United Arab Emirates" }, "AG": { "description": "Antigua and Barbuda" }, "AI": { "description": "Anguilla" }, "AL": { "description": "Albania" }, "AM": { "description": "Armenia" }, "AO": { "description": "Angola" }, "AR": { "description": "Argentina" }, "AS": { "description": "American Samoa" }, "AT": { "description": "Austria" }, "AU": { "description": "Australia" }, "AW": { "description": "Aruba" }, "AX": { "description": "Åland Islands" }, "AZ": { "description": "Azerbaijan" }, "BA": { "description": "Bosnia and Herzegovina" }, "BB": { "description": "Barbados" }, "BD": { "description": "Bangladesh" }, "BE": { "description": "Belgium" }, "BF": { "description": "Burkina Faso" }, "BG": { "description": "Bulgaria" }, "BH": { "description": "Bahrain" }, "BI": { "description": "Burundi" }, "BJ": { "description": "Benin" }, "BL": { "description": "Saint Barthélemy" }, "BM": { "description": "Bermuda" }, "BN": { "description": "Brunei" }, "BO": { "description": "Bolivia" }, "BQ": { "description": "Caribbean Netherlands (Bonaire, Sint Eustatius, and Saba)" }, "BR": { "description": "Brazil" }, "BS": { "description": "Bahamas" }, "BT": { "description": "Bhutan" }, "BV": { "description": "Bouvet Island" }, "BW": { "description": "Botswana" }, "BZ": { "description": "Belize" }, "CA": { "description": "Canada" }, "CC": { "description": "Cocos Islands" }, "CG": { "description": "Republic of Congo" }, "CH": { "description": "Switzerland" }, "CI": { "description": "Côte d'Ivoire (Ivory Coast)" }, "CK": { "description": "Cook Islands" }, "CL": { "description": "Chile" }, "CM": { "description": "Cameroon" }, "CN": { "description": "China" }, "CO": { "description": "Colombia" }, "CR": { "description": "Costa Rica" }, "CV": { "description": "Cape Verde" }, "CW": { "description": "Curaçao" }, "CX": { "description": "Christmas Island" }, "CY": { "description": "Cyprus" }, "CZ": { "description": "Czechia (Czech Republic)" }, "DE": { "description": "Germany" }, "DJ": { "description": "Djibouti" }, "DK": { "description": "Denmark" }, "DM": { "description": "Dominica" }, "DO": { "description": "Dominican Republic" }, "DZ": { "description": "Algeria" }, "EC": { "description": "Ecuador" }, "EE": { "description": "Estonia" }, "EG": { "description": "Egypt" }, "EH": { "description": "Western Sahara" }, "ER": { "description": "Eritrea" }, "ES": { "description": "Spain" }, "ET": { "description": "Ethiopia" }, "FI": { "description": "Finland" }, "FJ": { "description": "Fiji" }, "FK": { "description": "Falkland Islands" }, "FM": { "description": "Micronesia" }, "FO": { "description": "Faroe Islands" }, "FR": { "description": "France" }, "GA": { "description": "Gabon" }, "GB": { "description": "United Kingdom" }, "GD": { "description": "Grenada" }, "GE": { "description": "Georgia" }, "GF": { "description": "French Guiana" }, "GG": { "description": "Guernsey" }, "GH": { "description": "Ghana" }, "GI": { "description": "Gibraltar" }, "GL": { "description": "Greenland" }, "GM": { "description": "Gambia" }, "GN": { "description": "Guinea" }, "GP": { "description": "Guadeloupe" }, "GQ": { "description": "Equatorial Guinea" }, "GR": { "description": "Greece" }, "GS": { "description": "South Georgia and the South Sandwich Islands" }, "GT": { "description": "Guatemala" }, "GU": { "description": "Guam" }, "GW": { "description": "Guinea-Bissau" }, "GY": { "description": "Guyana" }, "HK": { "description": "Hong Kong" }, "HM": { "description": "Heard Island and McDonald Islands" }, "HN": { "description": "Honduras" }, "HR": { "description": "Croatia" }, "HU": { "description": "Hungary" }, "ID": { "description": "Indonesia" }, "IE": { "description": "Ireland" }, "IL": { "description": "Israel" }, "IM": { "description": "Isle of Man" }, "IN": { "description": "India" }, "IO": { "description": "British Indian Ocean Territory" }, "IQ": { "description": "Iraq" }, "IS": { "description": "Iceland" }, "IT": { "description": "Italy" }, "JE": { "description": "Jersey" }, "JM": { "description": "Jamaica" }, "JO": { "description": "Jordan" }, "JP": { "description": "Japan" }, "KE": { "description": "Kenya" }, "KG": { "description": "Kyrgyzstan" }, "KH": { "description": "Cambodia" }, "KI": { "description": "Kiribati" }, "KM": { "description": "Comoros" }, "KN": { "description": "Saint Kitts and Nevis" }, "KR": { "description": "South Korea" }, "KW": { "description": "Kuwait" }, "KY": { "description": "Cayman Islands" }, "KZ": { "description": "Kazakhstan" }, "LA": { "description": "Lao People's Democratic Republic (Laos)" }, "LB": { "description": "Lebanon" }, "LC": { "description": "Saint Lucia" }, "LI": { "description": "Liechtenstein" }, "LK": { "description": "Sri Lanka" }, "LR": { "description": "Liberia" }, "LS": { "description": "Lesotho" }, "LT": { "description": "Lithuania" }, "LU": { "description": "Luxembourg" }, "LV": { "description": "Latvia" }, "MA": { "description": "Morocco" }, "MC": { "description": "Monaco" }, "MD": { "description": "Moldova" }, "ME": { "description": "Montenegro" }, "MF": { "description": "Saint Martin" }, "MG": { "description": "Madagascar" }, "MH": { "description": "Marshall Islands" }, "MK": { "description": "Macedonia" }, "MN": { "description": "Mongolia" }, "MO": { "description": "Macao" }, "MP": { "description": "Northern Mariana Islands" }, "MQ": { "description": "Martinique" }, "MR": { "description": "Mauritania" }, "MS": { "description": "Montserrat" }, "MT": { "description": "Malta" }, "MU": { "description": "Mauritius" }, "MV": { "description": "Maldives" }, "MW": { "description": "Malawi" }, "MX": { "description": "Mexico" }, "MY": { "description": "Malaysia" }, "MZ": { "description": "Mozambique" }, "NA": { "description": "Namibia" }, "NC": { "description": "New Caledonia" }, "NE": { "description": "Niger" }, "NF": { "description": "Norfolk Island" }, "NG": { "description": "Nigeria" }, "NL": { "description": "Netherlands" }, "NO": { "description": "Norway" }, "NP": { "description": "Nepal" }, "NR": { "description": "Nauru" }, "NU": { "description": "Niue" }, "NZ": { "description": "New Zealand" }, "OM": { "description": "Oman" }, "PA": { "description": "Panama" }, "PE": { "description": "Peru" }, "PF": { "description": "French Polynesia" }, "PG": { "description": "Papua New Guinea" }, "PH": { "description": "Philippines" }, "PK": { "description": "Pakistan" }, "PL": { "description": "Poland" }, "PM": { "description": "Saint Pierre and Miquelon" }, "PN": { "description": "Pitcairn" }, "PR": { "description": "Puerto Rico" }, "PS": { "description": "Palestinian territories" }, "PT": { "description": "Portugal" }, "PW": { "description": "Palau" }, "PY": { "description": "Paraguay" }, "QA": { "description": "Qatar" }, "RE": { "description": "Reunion" }, "RO": { "description": "Romania" }, "RS": { "description": "Republic of Serbia" }, "RW": { "description": "Rwanda" }, "SA": { "description": "Saudi Arabia" }, "SB": { "description": "Solomon Islands" }, "SC": { "description": "Seychelles" }, "SE": { "description": "Sweden" }, "SG": { "description": "Singapore" }, "SH": { "description": "Saint Helena" }, "SI": { "description": "Slovenia" }, "SJ": { "description": "Svalbard and Jan Mayen" }, "SK": { "description": "Slovakia" }, "SL": { "description": "Sierra Leone" }, "SM": { "description": "San Marino" }, "SN": { "description": "Senegal" }, "SR": { "description": "Suriname" }, "ST": { "description": "São Tomé and Príncipe" }, "SV": { "description": "El Salvador" }, "SX": { "description": "Sint Maarten" }, "SZ": { "description": "Swaziland" }, "TC": { "description": "Turks and Caicos Islands" }, "TD": { "description": "Chad" }, "TF": { "description": "French Southern and Antarctic Lands" }, "TG": { "description": "Togo" }, "TH": { "description": "Thailand" }, "TJ": { "description": "Tajikistan" }, "TK": { "description": "Tokelau" }, "TL": { "description": "Timor-Leste" }, "TM": { "description": "Turkmenistan" }, "TN": { "description": "Tunisia" }, "TO": { "description": "Tonga" }, "TR": { "description": "Turkey" }, "TT": { "description": "Trinidad and Tobago" }, "TV": { "description": "Tuvalu" }, "TW": { "description": "Taiwan" }, "TZ": { "description": "Tanzania" }, "UA": { "description": "Ukraine" }, "UG": { "description": "Uganda" }, "UM": { "description": "United States Minor Outlying Islands" }, "US": { "description": "United States" }, "UY": { "description": "Uruguay" }, "UZ": { "description": "Uzbekistan" }, "VA": { "description": "Holy See (Vatican City)" }, "VC": { "description": "Saint Vincent and the Grenadines" }, "VG": { "description": "British Virgin Islands" }, "VI": { "description": "U.S. Virgin Islands" }, "VN": { "description": "Vietnam" }, "VU": { "description": "Vanuatu" }, "WF": { "description": "Wallis and Futuna" }, "WS": { "description": "Samoa" }, "XK": { "description": "Kosovo" }, "YT": { "description": "Mayotte" }, "ZA": { "description": "South Africa" }, "ZM": { "description": "Zambia" } } } ] }, "minItems": 1, "description": "Supported two-letter ISO 3166-1 alpha-2 country code. Customers located in the listed countries are charged the override price.", "uniqueItems": true }, "unit_price": { "properties": { "amount": { "type": "string", "description": "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." }, "currency_code": { "type": "string", "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" ], "description": "Supported three-letter ISO 4217 currency code.", "title": "Currency code", "x-enum-descriptions": { "USD": { "description": "United States Dollar" }, "EUR": { "description": "Euro" }, "GBP": { "description": "Pound Sterling" }, "JPY": { "description": "Japanese Yen" }, "AUD": { "description": "Australian Dollar" }, "CAD": { "description": "Canadian Dollar" }, "CHF": { "description": "Swiss Franc" }, "HKD": { "description": "Hong Kong Dollar" }, "SGD": { "description": "Singapore Dollar" }, "SEK": { "description": "Swedish Krona" }, "ARS": { "description": "Argentine Peso" }, "BRL": { "description": "Brazilian Real" }, "CLP": { "description": "Chilean Peso" }, "CNY": { "description": "Chinese Yuan" }, "COP": { "description": "Colombian Peso" }, "CZK": { "description": "Czech Koruna" }, "DKK": { "description": "Danish Krone" }, "HUF": { "description": "Hungarian Forint" }, "ILS": { "description": "Israeli Shekel" }, "INR": { "description": "Indian Rupee" }, "KRW": { "description": "South Korean Won" }, "MXN": { "description": "Mexican Peso" }, "NOK": { "description": "Norwegian Krone" }, "NZD": { "description": "New Zealand Dollar" }, "PEN": { "description": "Peruvian Sol" }, "PLN": { "description": "Polish Zloty" }, "RUB": { "description": "Russian Ruble" }, "THB": { "description": "Thai Baht" }, "TRY": { "description": "Turkish Lira" }, "TWD": { "description": "New Taiwan Dollar" }, "UAH": { "description": "Ukrainian Hryvnia" }, "VND": { "description": "Vietnamese Dong" }, "ZAR": { "description": "South African Rand" } } } }, "required": [ "amount", "currency_code" ], "type": "object", "description": "Override price. This price applies to customers located in the countries for this unit price override.", "title": "Money" } }, "title": "Unit price override", "additionalProperties": false }, "maxItems": 250, "description": "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": { "properties": { "minimum": { "type": "integer", "minimum": 1, "maximum": 999999999, "description": "Minimum quantity of the product related to this price that can be bought. Required if `maximum` set.", "examples": [ 1 ], "default": 1 }, "maximum": { "type": "integer", "minimum": 1, "maximum": 999999999, "description": "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.", "examples": [ 100 ], "default": 100 } }, "required": [ "minimum", "maximum" ], "type": "object", "title": "price_quantity", "examples": [ { "minimum": 1, "maximum": 100 } ], "description": "Limits on how many times the related product can be purchased at this price. Useful for discount campaigns." }, "status": { "type": "string", "enum": [ "active", "archived" ], "description": "Whether this entity can be used in Paddle.", "title": "Status", "x-enum-descriptions": { "active": { "description": "Entity is active and can be used." }, "archived": { "description": "Entity is archived, so can't be used." } }, "default": "active" }, "custom_data": { "anyOf": [ { "type": "object", "unevaluatedProperties": {}, "description": "Your own structured key-value data.", "title": "Custom Data", "example": { "customer_reference_id": "abcd1234" } }, { "type": "null" } ], "description": "Your own structured key-value data." }, "import_meta": { "anyOf": [ { "type": "object", "required": [ "imported_from" ], "properties": { "external_id": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200, "description": "Reference or identifier for this entity from the provider where it was imported from.", "title": "External ID", "examples": [ "9b95b0b8-e10f-441a-862e-1936a6d818ab" ] }, { "type": "null" } ] }, "imported_from": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Name of the platform or provider where this entity was imported from.", "examples": [ "paddle_classic" ] } }, "description": "Import information for this entity. `null` if this entity is not imported.", "title": "ImportMeta" }, { "type": "null" } ], "description": "Import information for this entity. `null` if this entity is not imported.", "x-external-readOnly": true }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.", "title": "Created at", "examples": [ "2024-10-12T07:20:50.52Z" ] }, "updated_at": { "type": "string", "format": "date-time", "description": "RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.", "title": "Updated at", "examples": [ "2024-10-13T07:20:50.52Z" ] } }, "required": [ "id", "product_id", "description", "type", "name", "billing_cycle", "trial_period", "tax_mode", "unit_price", "unit_price_overrides", "quantity", "status", "custom_data", "import_meta", "created_at", "updated_at" ], "type": "object", "description": "Represents a price entity.", "title": "Price" }, "quantity": { "type": "integer", "description": "Quantity of this item on the transaction." }, "proration": { "anyOf": [ { "type": "object", "required": [ "rate", "billing_period" ], "properties": { "rate": { "type": "string", "description": "Rate used to calculate proration.", "x-external-readOnly": true }, "billing_period": { "properties": { "starts_at": { "type": "string", "format": "date-time", "description": "RFC 3339 datetime string of when this period starts.", "title": "Timestamp", "examples": [ "2024-10-12T07:20:50.52Z" ] }, "ends_at": { "type": "string", "format": "date-time", "description": "RFC 3339 datetime string of when this period ends.", "title": "Timestamp", "examples": [ "2024-10-12T07:20:50.52Z" ] } }, "required": [ "starts_at", "ends_at" ], "type": "object", "title": "Time period", "description": "Billing period that proration is based on.", "x-external-readOnly": true } }, "description": "How proration was calculated for this item. Populated when a transaction is created from a subscription change, where `proration_billing_mode` was `prorated_immediately` or `prorated_next_billing_period`. Set automatically by Paddle.", "title": "Proration" }, { "type": "null" } ], "description": "How proration was calculated for this item. Populated when a transaction is created from a subscription change, where `proration_billing_mode` was `prorated_immediately` or `prorated_next_billing_period`. Set automatically by Paddle." } }, "title": "TransactionItem" }, "minItems": 1, "maxItems": 100, "description": "List of items on this transaction. For calculated totals, use `details.line_items`." }, "details": { "type": "object", "required": [ "tax_rates_used", "totals", "adjusted_totals", "payout_totals", "adjusted_payout_totals", "line_items" ], "properties": { "tax_rates_used": { "type": "array", "items": { "type": "object", "required": [ "tax_rate", "totals" ], "properties": { "tax_rate": { "type": "string", "description": "Rate used to calculate tax for this transaction.", "examples": [ "0.2" ] }, "totals": { "properties": { "subtotal": { "type": "string", "description": "Subtotal before discount, tax, and deductions. If an item, unit price multiplied by quantity.", "examples": [ "15000" ] }, "discount": { "type": "string", "description": "Total discount as a result of any discounts applied.\n\nExcept for percentage discounts, Paddle applies tax to discounts based on the line item `price.tax_mode`. If `price.tax_mode` for a line item is `internal`, Paddle removes tax from the discount applied.", "examples": [ "0" ] }, "tax": { "type": "string", "description": "Total tax on the subtotal.", "examples": [ "1500" ] }, "total": { "type": "string", "description": "Total after discount and tax.", "examples": [ "16500" ] } }, "required": [ "subtotal", "discount", "tax", "total" ], "type": "object", "description": "Calculated totals for the tax applied to this transaction.", "title": "Totals" } } }, "description": "List of tax rates applied for this transaction." }, "totals": { "type": "object", "required": [ "subtotal", "discount", "tax", "total", "credit", "credit_to_balance", "balance", "grand_total", "grand_total_tax", "fee", "earnings", "currency_code" ], "properties": { "subtotal": { "type": "string", "description": "Subtotal before discount, tax, and deductions. If an item, unit price multiplied by quantity.", "examples": [ "15000" ] }, "discount": { "type": "string", "description": "Total discount as a result of any discounts applied.\n\nExcept for percentage discounts, Paddle applies tax to discounts based on the line item `price.tax_mode`. If `price.tax_mode` for a line item is `internal`, Paddle removes tax from the discount applied.", "examples": [ "0" ] }, "tax": { "type": "string", "description": "Total tax on the subtotal.", "examples": [ "1500" ] }, "total": { "type": "string", "description": "Total after discount and tax.", "examples": [ "16500" ] }, "credit": { "type": "string", "description": "Total credit applied to this transaction. This includes credits applied using a customer's credit balance and adjustments to a `billed` transaction.", "examples": [ "0" ] }, "credit_to_balance": { "type": "string", "description": "Additional credit generated from negative `details.line_items`. This credit is added to the customer balance.", "examples": [ "0" ] }, "balance": { "type": "string", "description": "Total due on a transaction after credits and any payments.", "examples": [ "16500" ] }, "grand_total": { "type": "string", "description": "Total due on a transaction after credits but before any payments.", "examples": [ "16500" ] }, "grand_total_tax": { "type": "string", "description": "Net tax amount included in `grand_total`. Equals the full `tax` amount unless credits are applied, in which case this value is proportionally reduced.", "examples": [ "83" ] }, "fee": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Total fee taken by Paddle for this transaction. `null` until the transaction is `completed` and the fee is processed.", "examples": [ "825" ] }, "earnings": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Total earnings for this transaction. This is the total minus the Paddle fee. `null` until the transaction is `completed` and the fee is processed.", "examples": [ "15675" ] }, "currency_code": { "type": "string", "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" ], "description": "Three-letter ISO 4217 currency code of the currency used for this transaction.", "title": "Currency code", "x-enum-descriptions": { "USD": { "description": "United States Dollar" }, "EUR": { "description": "Euro" }, "GBP": { "description": "Pound Sterling" }, "JPY": { "description": "Japanese Yen" }, "AUD": { "description": "Australian Dollar" }, "CAD": { "description": "Canadian Dollar" }, "CHF": { "description": "Swiss Franc" }, "HKD": { "description": "Hong Kong Dollar" }, "SGD": { "description": "Singapore Dollar" }, "SEK": { "description": "Swedish Krona" }, "ARS": { "description": "Argentine Peso" }, "BRL": { "description": "Brazilian Real" }, "CLP": { "description": "Chilean Peso" }, "CNY": { "description": "Chinese Yuan" }, "COP": { "description": "Colombian Peso" }, "CZK": { "description": "Czech Koruna" }, "DKK": { "description": "Danish Krone" }, "HUF": { "description": "Hungarian Forint" }, "ILS": { "description": "Israeli Shekel" }, "INR": { "description": "Indian Rupee" }, "KRW": { "description": "South Korean Won" }, "MXN": { "description": "Mexican Peso" }, "NOK": { "description": "Norwegian Krone" }, "NZD": { "description": "New Zealand Dollar" }, "PEN": { "description": "Peruvian Sol" }, "PLN": { "description": "Polish Zloty" }, "RUB": { "description": "Russian Ruble" }, "THB": { "description": "Thai Baht" }, "TRY": { "description": "Turkish Lira" }, "TWD": { "description": "New Taiwan Dollar" }, "UAH": { "description": "Ukrainian Hryvnia" }, "VND": { "description": "Vietnamese Dong" }, "ZAR": { "description": "South African Rand" } } } }, "description": "Breakdown of the total for a transaction. These numbers can be negative when dealing with subscription updates that result in credit." }, "adjusted_totals": { "type": "object", "required": [ "subtotal", "tax", "total", "grand_total", "grand_total_tax", "fee", "retained_fee", "earnings", "currency_code" ], "properties": { "subtotal": { "type": "string", "description": "Subtotal before discount, tax, and deductions. If an item, unit price multiplied by quantity.", "examples": [ "15000" ] }, "tax": { "type": "string", "description": "Total tax on the subtotal.", "examples": [ "1500" ] }, "total": { "type": "string", "description": "Total after tax.", "examples": [ "16500" ] }, "grand_total": { "type": "string", "description": "Total due after credits but before any payments.", "examples": [ "16500" ] }, "grand_total_tax": { "type": "string", "description": "Net tax amount included in `grand_total`. Equals the full `tax` amount unless credits are applied, in which case this value is proportionally reduced.", "examples": [ "83" ] }, "fee": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Total fee taken by Paddle for this transaction. `null` until the transaction is `completed` and the fee is processed.", "examples": [ "825" ] }, "retained_fee": { "type": "string", "description": "Total Paddle fees retained for this adjustment.", "examples": [ "300" ] }, "earnings": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Total earnings for this transaction. This is the total minus the Paddle fee.\n`null` until the transaction is `completed` and the fee is processed.", "examples": [ "15675" ] }, "currency_code": { "type": "string", "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" ], "description": "Three-letter ISO 4217 currency code of the currency used for this transaction.", "title": "Currency code", "x-enum-descriptions": { "USD": { "description": "United States Dollar" }, "EUR": { "description": "Euro" }, "GBP": { "description": "Pound Sterling" }, "JPY": { "description": "Japanese Yen" }, "AUD": { "description": "Australian Dollar" }, "CAD": { "description": "Canadian Dollar" }, "CHF": { "description": "Swiss Franc" }, "HKD": { "description": "Hong Kong Dollar" }, "SGD": { "description": "Singapore Dollar" }, "SEK": { "description": "Swedish Krona" }, "ARS": { "description": "Argentine Peso" }, "BRL": { "description": "Brazilian Real" }, "CLP": { "description": "Chilean Peso" }, "CNY": { "description": "Chinese Yuan" }, "COP": { "description": "Colombian Peso" }, "CZK": { "description": "Czech Koruna" }, "DKK": { "description": "Danish Krone" }, "HUF": { "description": "Hungarian Forint" }, "ILS": { "description": "Israeli Shekel" }, "INR": { "description": "Indian Rupee" }, "KRW": { "description": "South Korean Won" }, "MXN": { "description": "Mexican Peso" }, "NOK": { "description": "Norwegian Krone" }, "NZD": { "description": "New Zealand Dollar" }, "PEN": { "description": "Peruvian Sol" }, "PLN": { "description": "Polish Zloty" }, "RUB": { "description": "Russian Ruble" }, "THB": { "description": "Thai Baht" }, "TRY": { "description": "Turkish Lira" }, "TWD": { "description": "New Taiwan Dollar" }, "UAH": { "description": "Ukrainian Hryvnia" }, "VND": { "description": "Vietnamese Dong" }, "ZAR": { "description": "South African Rand" } } } }, "description": "Breakdown of the totals for a transaction after adjustments.", "title": "Transaction totals (adjusted)" }, "payout_totals": { "anyOf": [ { "type": "object", "required": [ "subtotal", "discount", "tax", "total", "credit", "credit_to_balance", "balance", "grand_total", "grand_total_tax", "fee", "earnings", "currency_code", "exchange_rate", "fee_rate" ], "properties": { "subtotal": { "type": "string", "description": "Total before tax and fees.", "examples": [ "15000" ] }, "discount": { "type": "string", "description": "Total discount as a result of any discounts applied.\nExcept for percentage discounts, Paddle applies tax to discounts based on the line item `price.tax_mode`. If `price.tax_mode` for a line item is `internal`, Paddle removes tax from the discount applied.", "examples": [ "0" ] }, "tax": { "type": "string", "description": "Total tax on the subtotal.", "examples": [ "1500" ] }, "total": { "type": "string", "description": "Total after tax.", "examples": [ "16500" ] }, "credit": { "type": "string", "description": "Total credit applied to this transaction. This includes credits applied using a customer's credit balance and adjustments to a `billed` transaction.", "examples": [ "0" ] }, "credit_to_balance": { "type": "string", "description": "Additional credit generated from negative `details.line_items`. This credit is added to the customer balance.", "examples": [ "0" ] }, "balance": { "type": "string", "description": "Total due on a transaction after credits and any payments.", "examples": [ "16500" ] }, "grand_total": { "type": "string", "description": "Total due on a transaction after credits but before any payments.", "examples": [ "16500" ] }, "grand_total_tax": { "type": "string", "description": "Net tax amount included in `grand_total`. Equals the full `tax` amount unless credits are applied, in which case this value is proportionally reduced.", "examples": [ "83" ] }, "fee": { "type": "string", "description": "Total fee taken by Paddle for this payout.", "examples": [ "825" ] }, "earnings": { "type": "string", "description": "Total earnings for this payout. This is the subtotal minus the Paddle fee.", "examples": [ "15675" ] }, "currency_code": { "type": "string", "enum": [ "AUD", "CAD", "CHF", "CNY", "CZK", "DKK", "EUR", "GBP", "HUF", "PLN", "SEK", "USD", "ZAR" ], "description": "Three-letter ISO 4217 currency code used for the payout for this transaction. If your primary currency has changed, this reflects the primary currency at the time the transaction was billed.", "title": "Currency code (payouts)", "x-enum-descriptions": { "AUD": { "description": "Australian Dollar" }, "CAD": { "description": "Canadian Dollar" }, "CHF": { "description": "Swiss Franc" }, "CNY": { "description": "Chinese Yuan" }, "CZK": { "description": "Czech Koruna" }, "DKK": { "description": "Danish Krone" }, "EUR": { "description": "Euro" }, "GBP": { "description": "Pound Sterling" }, "HUF": { "description": "Hungarian Forint" }, "PLN": { "description": "Polish Zloty" }, "SEK": { "description": "Swedish Krona" }, "USD": { "description": "United States Dollar" }, "ZAR": { "description": "South African Rand" } } }, "exchange_rate": { "type": "string", "description": "Currency exchange rate, including margin if applicable. `1.0` if the transaction currency matches your payout currency.", "title": "currency_exchange_rate", "examples": [ "1.0513135" ], "default": "1" }, "fee_rate": { "type": "string", "description": "Paddle fee rate that was applied to this transaction.", "examples": [ "0.05" ] } }, "description": "Breakdown of the payout total for a transaction. `null` until the transaction is `completed`. Returned in your payout currency.", "title": "Transaction payout totals" }, { "type": "null" } ], "description": "Breakdown of the payout total for a transaction. `null` until the transaction is `completed`. Returned in your payout currency." }, "adjusted_payout_totals": { "anyOf": [ { "type": "object", "required": [ "subtotal", "tax", "total", "fee", "retained_fee", "chargeback_fee", "earnings", "currency_code", "exchange_rate" ], "properties": { "subtotal": { "type": "string", "description": "Total before tax and fees.", "examples": [ "15000" ] }, "tax": { "type": "string", "description": "Total tax on the subtotal.", "examples": [ "1500" ] }, "total": { "type": "string", "description": "Total after tax.", "examples": [ "16500" ] }, "fee": { "type": "string", "description": "Total fee taken by Paddle for this payout.", "examples": [ "825" ] }, "retained_fee": { "type": "string", "description": "Paddle fees retained for this adjustment.", "examples": [ "300" ] }, "chargeback_fee": { "properties": { "amount": { "type": "string", "description": "Chargeback fee converted into the payout currency.", "examples": [ "1680" ] }, "original": { "anyOf": [ { "type": "object", "required": [ "amount", "currency_code" ], "properties": { "amount": { "type": "string", "description": "Fee amount for this chargeback in the original currency.", "examples": [ "1500" ] }, "currency_code": { "type": "string", "enum": [ "AUD", "CAD", "EUR", "GBP", "USD" ], "description": "Three-letter ISO 4217 currency code for the original chargeback fee.", "title": "Currency code (chargebacks)", "x-enum-descriptions": { "AUD": { "description": "Australian Dollar" }, "CAD": { "description": "Canadian Dollar" }, "EUR": { "description": "Euro" }, "GBP": { "description": "Pound Sterling" }, "USD": { "description": "United States Dollar" } }, "examples": [ "USD" ] } }, "description": "Chargeback fee before conversion to the payout currency. `null` when the chargeback fee is the same as the payout currency." }, { "type": "null" } ], "description": "Chargeback fee before conversion to the payout currency. `null` when the chargeback fee is the same as the payout currency." } }, "required": [ "amount", "original" ], "type": "object", "description": "Details of any chargeback fees incurred for this transaction." }, "earnings": { "type": "string", "description": "Total earnings for this payout. This is the subtotal minus the Paddle fee, excluding chargeback fees.", "examples": [ "15675" ] }, "currency_code": { "type": "string", "enum": [ "AUD", "CAD", "CHF", "CNY", "CZK", "DKK", "EUR", "GBP", "HUF", "PLN", "SEK", "USD", "ZAR" ], "description": "Three-letter ISO 4217 currency code used for the payout for this transaction. If your primary currency has changed, this reflects the primary currency at the time the transaction was billed.", "title": "Currency code (payouts)", "x-enum-descriptions": { "AUD": { "description": "Australian Dollar" }, "CAD": { "description": "Canadian Dollar" }, "CHF": { "description": "Swiss Franc" }, "CNY": { "description": "Chinese Yuan" }, "CZK": { "description": "Czech Koruna" }, "DKK": { "description": "Danish Krone" }, "EUR": { "description": "Euro" }, "GBP": { "description": "Pound Sterling" }, "HUF": { "description": "Hungarian Forint" }, "PLN": { "description": "Polish Zloty" }, "SEK": { "description": "Swedish Krona" }, "USD": { "description": "United States Dollar" }, "ZAR": { "description": "South African Rand" } } }, "exchange_rate": { "type": "string", "description": "Currency exchange rate, including margin if applicable. `1.0` if the transaction currency matches your payout currency.", "title": "currency_exchange_rate", "examples": [ "1.0513135" ] } }, "description": "Breakdown of the payout total for a transaction after adjustments. `null` until the transaction is `completed`.", "title": "Transaction payout totals (adjusted)" }, { "type": "null" } ], "description": "Breakdown of the payout total for a transaction after adjustments. `null` until the transaction is `completed`." }, "line_items": { "type": "array", "items": { "type": "object", "required": [ "price_id", "quantity", "proration", "tax_rate", "unit_totals", "totals", "product", "id" ], "properties": { "price_id": { "type": "string", "pattern": "^pri_[a-z\\d]{26}$", "description": "Paddle ID for the price related to this transaction line item, prefixed with `pri_`.", "title": "Price ID", "examples": [ "pri_01gsz8z1q1n00f12qt82y31smh" ] }, "quantity": { "type": "integer", "description": "Quantity of this transaction line item." }, "proration": { "anyOf": [ { "type": "object", "required": [ "rate", "billing_period" ], "properties": { "rate": { "type": "string", "description": "Rate used to calculate proration.", "x-external-readOnly": true }, "billing_period": { "properties": { "starts_at": { "type": "string", "format": "date-time", "description": "RFC 3339 datetime string of when this period starts.", "title": "Timestamp", "examples": [ "2024-10-12T07:20:50.52Z" ] }, "ends_at": { "type": "string", "format": "date-time", "description": "RFC 3339 datetime string of when this period ends.", "title": "Timestamp", "examples": [ "2024-10-12T07:20:50.52Z" ] } }, "required": [ "starts_at", "ends_at" ], "type": "object", "title": "Time period", "description": "Billing period that proration is based on.", "x-external-readOnly": true } }, "description": "How proration was calculated for this item. Populated when a transaction is created from a subscription change, where `proration_billing_mode` was `prorated_immediately` or `prorated_next_billing_period`. Set automatically by Paddle.", "title": "Proration" }, { "type": "null" } ], "description": "How proration was calculated for this item. Populated when a transaction is created from a subscription change, where `proration_billing_mode` was `prorated_immediately` or `prorated_next_billing_period`. Set automatically by Paddle." }, "tax_rate": { "type": "string", "description": "Rate used to calculate tax for this transaction line item.", "examples": [ "0.2" ] }, "unit_totals": { "properties": { "subtotal": { "type": "string", "description": "Subtotal before discount, tax, and deductions. If an item, unit price multiplied by quantity.", "examples": [ "15000" ] }, "discount": { "type": "string", "description": "Total discount as a result of any discounts applied.\n\nExcept for percentage discounts, Paddle applies tax to discounts based on the line item `price.tax_mode`. If `price.tax_mode` for a line item is `internal`, Paddle removes tax from the discount applied.", "examples": [ "0" ] }, "tax": { "type": "string", "description": "Total tax on the subtotal.", "examples": [ "1500" ] }, "total": { "type": "string", "description": "Total after discount and tax.", "examples": [ "16500" ] } }, "required": [ "subtotal", "discount", "tax", "total" ], "type": "object", "description": "Breakdown of the charge for one unit in the lowest denomination of a currency (e.g. cents for USD).", "title": "Totals" }, "totals": { "properties": { "subtotal": { "type": "string", "description": "Subtotal before discount, tax, and deductions. If an item, unit price multiplied by quantity.", "examples": [ "15000" ] }, "discount": { "type": "string", "description": "Total discount as a result of any discounts applied.\n\nExcept for percentage discounts, Paddle applies tax to discounts based on the line item `price.tax_mode`. If `price.tax_mode` for a line item is `internal`, Paddle removes tax from the discount applied.", "examples": [ "0" ] }, "tax": { "type": "string", "description": "Total tax on the subtotal.", "examples": [ "1500" ] }, "total": { "type": "string", "description": "Total after discount and tax.", "examples": [ "16500" ] } }, "required": [ "subtotal", "discount", "tax", "total" ], "type": "object", "description": "Breakdown of a charge in the lowest denomination of a currency (e.g. cents for USD).", "title": "Totals" }, "product": { "properties": { "id": { "type": "string", "pattern": "^pro_[a-z\\d]{26}$", "description": "Unique Paddle ID for this product, prefixed with `pro_`.", "title": "Product ID", "examples": [ "pro_01gsz97mq9pa4fkyy0wqenepkz" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Name of this product.", "title": "Product Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "maxLength": 2048, "description": "Short description for this product." }, "type": { "type": "string", "enum": [ "custom", "standard" ], "description": "Type of item. Standard items are considered part of your catalog and are shown in the Paddle dashboard.", "title": "CatalogType", "x-enum-descriptions": { "custom": { "description": "Non-catalog item. Typically created for a specific transaction or subscription. Not returned when listing or shown in the Paddle dashboard." }, "standard": { "description": "Standard item. Can be considered part of your catalog and reused across transactions and subscriptions easily." } }, "default": "standard" }, "tax_category": { "type": "string", "enum": [ "digital-goods", "ebooks", "implementation-services", "professional-services", "saas", "software-programming-services", "standard", "training-services", "website-hosting" ], "description": "Tax category for this product. Used for charging the correct rate of tax. Selected tax category must be enabled on your Paddle account.", "title": "Tax category", "x-enum-descriptions": { "digital-goods": { "description": "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": { "description": "Digital books and educational material which is sold with permanent rights for use by the customer." }, "implementation-services": { "description": "Remote configuration, set-up, and integrating software on behalf of a customer." }, "professional-services": { "description": "Services that involve the application of your expertise and specialized knowledge of a software product." }, "saas": { "description": "Products that allow users to connect to and use online or cloud-based applications over the Internet." }, "software-programmin-services": { "description": "Services that can be used to customize and white label software products." }, "standard": { "description": "Software products that are pre-written and can be downloaded and installed onto a local device." }, "training-services": { "description": "Training and education services related to software products." }, "website-hosting": { "description": "Cloud storage service for personal or corporate information, assets, or intellectual property." } } }, "image_url": { "anyOf": [ { "type": "string", "minLength": 1, "format": "uri", "description": "A URL to an image.", "title": "Image Url" }, { "type": "null" }, { "type": "string", "minLength": 0, "maxLength": 0, "title": "Empty String" } ], "description": "Image for this product. Included in the checkout and on some customer documents." }, "custom_data": { "anyOf": [ { "type": "object", "unevaluatedProperties": {}, "description": "Your own structured key-value data.", "title": "Custom Data", "example": { "customer_reference_id": "abcd1234" } }, { "type": "null" } ], "description": "Your own structured key-value data." }, "status": { "type": "string", "enum": [ "active", "archived" ], "description": "Whether this entity can be used in Paddle.", "title": "Status", "x-enum-descriptions": { "active": { "description": "Entity is active and can be used." }, "archived": { "description": "Entity is archived, so can't be used." } }, "default": "active" }, "import_meta": { "anyOf": [ { "type": "object", "required": [ "imported_from" ], "properties": { "external_id": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200, "description": "Reference or identifier for this entity from the provider where it was imported from.", "title": "External ID", "examples": [ "9b95b0b8-e10f-441a-862e-1936a6d818ab" ] }, { "type": "null" } ] }, "imported_from": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Name of the platform or provider where this entity was imported from.", "examples": [ "paddle_classic" ] } }, "description": "Import information for this entity. `null` if this entity is not imported.", "title": "ImportMeta" }, { "type": "null" } ], "description": "Import information for this entity. `null` if this entity is not imported.", "x-external-readOnly": true }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.", "title": "Created at", "examples": [ "2024-10-12T07:20:50.52Z" ] }, "updated_at": { "type": "string", "format": "date-time", "description": "RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.", "title": "Updated at", "examples": [ "2024-10-13T07:20:50.52Z" ] } }, "required": [ "id", "name", "description", "type", "tax_category", "image_url", "custom_data", "status", "import_meta", "created_at", "updated_at" ], "type": "object", "description": "Related product entity for this transaction line item price. Reflects the entity at the time it was added to the transaction.", "title": "Product" }, "id": { "type": "string", "pattern": "^txnitm_[a-z\\d]{26}$", "description": "Unique Paddle ID for this transaction item, prefixed with `txnitm_`. Used when working with [adjustments](https://developer.paddle.com/build/transactions/create-transaction-adjustments).", "title": "Transaction item ID", "examples": [ "txnitm_01gm302t81w94gyjpjpqypkzkf" ] } } }, "description": "Information about line items for this transaction. Different from transaction `items` as they include totals calculated by Paddle. Considered the source of truth for line item totals." } }, "description": "Calculated totals for a transaction, including proration, discounts, tax, and currency conversion. Considered the source of truth for totals on a transaction.", "title": "TransactionDetails" }, "payments": { "type": "array", "items": { "type": "object", "required": [ "payment_attempt_id", "stored_payment_method_id", "payment_method_id", "amount", "status", "error_code", "method_details", "created_at", "captured_at" ], "properties": { "payment_attempt_id": { "type": "string", "description": "UUID for this payment attempt.", "examples": [ "497f776b-851d-4ebf-89ab-8ba0f75d2d6a" ] }, "stored_payment_method_id": { "type": "string", "description": "UUID for the stored payment method used for this payment attempt. Deprecated - use `payment_method_id` instead.", "deprecated": true, "examples": [ "7636e781-3969-49f4-9c77-8226232e28a6" ] }, "payment_method_id": { "anyOf": [ { "type": "string", "pattern": "^paymtd_[a-z\\d]{26}$", "description": "Unique Paddle ID for this payment method entity, prefixed with `paymtd_`.", "title": "Payment Method ID", "examples": [ "paymtd_01hkm9xwqpbbpr1ksmvg3sx3v1" ] }, { "type": "null" } ], "description": "Paddle ID of the payment method used for this payment attempt, prefixed with `paymtd_`." }, "amount": { "type": "string", "description": "Amount for collection in the lowest denomination of a currency (e.g. cents for USD).", "examples": [ "1050" ] }, "status": { "type": "string", "enum": [ "authorized", "authorized_flagged", "canceled", "captured", "error", "action_required", "pending_no_action_required", "created", "unknown", "dropped" ], "description": "Status of this payment attempt.", "x-enum-descriptions": { "authorized": { "description": "Authorized but not captured. Payment attempt is incomplete." }, "authorized_flagged": { "description": "Authorized but not captured because it has been flagged as potentially fraudulent. Payment attempt is incomplete." }, "canceled": { "description": "Previously authorized payment attempt has been canceled. Typically when `authorized_flagged` payment attempts are rejected." }, "captured": { "description": "Payment captured successfully. Payment attempt is complete." }, "error": { "description": "Something went wrong and the payment attempt was unsuccessful. Check the `error_code` for more information." }, "action_required": { "description": "Customer must complete an action for this payment attempt to proceed. Typically means that the payment attempt requires 3DS." }, "pending_no_action_required": { "description": "Response required from the bank or payment provider. Transaction is pending." }, "created": { "description": "New payment attempt created." }, "unknown": { "description": "Payment attempt status not known." }, "dropped": { "description": "Payment attempt dropped by Paddle." } } }, "error_code": { "anyOf": [ { "type": "string", "enum": [ "already_canceled", "already_refunded", "authentication_failed", "blocked_card", "canceled", "declined", "declined_not_retryable", "expired_card", "fraud", "invalid_amount", "invalid_payment_details", "issuer_unavailable", "not_enough_balance", "preferred_network_not_supported", "psp_error", "redacted_payment_method", "system_error", "transaction_not_permitted", "unknown" ], "description": "Reason why a payment attempt failed. Returns `null` if payment captured successfully.", "title": "Error code", "x-enum-descriptions": { "already_canceled": { "description": "Cancellation not possible because the amount has already been canceled. Not typically returned for payments." }, "already_refunded": { "description": "Refund is not possible because the amount has already been refunded. Not typically returned for payments." }, "authentication_failed": { "description": "Payment required a 3DS2 authentication challenge. The customer completed the challenge but was not successful." }, "blocked_card": { "description": "Payment method issuer has indicated that the card cannot be used as it is frozen, lost, damaged, or stolen." }, "canceled": { "description": "Customer has requested that the mandate for recurring payments be canceled." }, "declined": { "description": "Payment method has been declined, with no other information returned." }, "declined_not_retryable": { "description": "Payment method has been declined, and the issuer has indicated that it should not be retried. This could mean the account is closed or the customer revoked authorization to charge the payment method." }, "expired_card": { "description": "Payment method issuer has indicated that this card is expired. Expired cards may also return `invalid_payment_details`, depending on how a payment is routed." }, "fraud": { "description": "Payment method issuer or payment service provider flagged this payment as potentially fraudulent." }, "invalid_amount": { "description": "Payment method issuer or payment service provider cannot process a payment that is this high or low." }, "invalid_payment_details": { "description": "Payment service provider has indicated the payment method isn't valid. This typically means that it's expired. `expired_card` is returned by the payment method issuer, rather than the payment service provider." }, "issuer_unavailable": { "description": "Payment service provider couldn't reach the payment method issuer." }, "not_enough_balance": { "description": "Payment method declined because of insufficient funds, or fund limits being reached." }, "preferred_network_not_supported": { "description": "Payment method has been declined because the network scheme that the customer selected isn't supported by the payment service provider." }, "psp_error": { "description": "Something went wrong with the payment service provider, with no other information returned." }, "redacted_payment_method": { "description": "Payment service provider didn't receive payment method information as they've been redacted." }, "system_error": { "description": "Something went wrong with the Paddle platform. Try again later, or check status.paddle.com." }, "transaction_not_permitted": { "description": "Payment method issuer doesn't allow this kind of payment because of limits on the account, or legal or compliance reasons." }, "unknown": { "description": "Payment attempt unsuccessful, with no other information returned." } } }, { "type": "null" } ], "description": "Reason why a payment attempt failed. Returns `null` if payment captured successfully." }, "method_details": { "type": "object", "required": [ "type", "underlying_details", "south_korea_local_card", "card", "paypal" ], "properties": { "type": { "type": "string", "enum": [ "alipay", "apple_pay", "bancontact", "blik", "card", "google_pay", "ideal", "kakao_pay", "korea_local", "south_korea_local_card", "mb_way", "naver_pay", "offline", "payco", "paypal", "pix", "samsung_pay", "unknown", "upi", "wechat_pay", "wire_transfer" ], "description": "Type of payment method used for this payment attempt.", "title": "PaymentMethodType", "x-enum-descriptions": { "alipay": { "description": "Alipay, popular in China." }, "apple_pay": { "description": "Apple Pay on a supported Apple device." }, "bancontact": { "description": "Bancontact, popular in Belgium." }, "blik": { "description": "BLIK, a popular payment method in Poland." }, "card": { "description": "Credit or debit card." }, "google_pay": { "description": "Google Pay on a supported Android device, Chromebook, or Google Chrome browser." }, "ideal": { "description": "iDEAL, popular in the Netherlands." }, "kakao_pay": { "description": "Kakao Pay, a popular payment method in Korea." }, "korea_local": { "description": "Korean payment methods, which includes over 20 payment options for the Korean market. Check `underlying_payment_method.korea_local` for information about the Korean payment method used to pay.", "deprecated": true }, "south_korea_local_card": { "description": "Korean local credit or debit card." }, "mb_way": { "description": "MB WAY, a popular payment method in Portugal." }, "naver_pay": { "description": "Naver Pay, a popular payment method in Korea." }, "paypal": { "description": "PayPal." }, "offline": { "description": "Payment recorded offline." }, "payco": { "description": "Payco, a popular payment method in Korea." }, "pix": { "description": "Pix, popular in Brazil. Available in early access." }, "samsung_pay": { "description": "Samsung Pay, a popular payment method in Korea." }, "unknown": { "description": "Payment method not known." }, "upi": { "description": "Unified Payments Interface (UPI), popular in India. Available in early access." }, "wechat_pay": { "description": "WeChat Pay, a popular payment method in China." }, "wire_transfer": { "description": "Wire transfer, sometimes called bank transfer." } } }, "underlying_details": { "anyOf": [ { "type": "object", "required": [ "korea_local" ], "properties": { "korea_local": { "anyOf": [ { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "bc", "citi", "hana", "hyundai", "jeju", "jeonbuk", "kakaobank", "kakaopay", "kbank", "kdbbank", "kookmin", "kwangju", "lotte", "mg", "naverpaycard", "naverpaypoint", "nh", "payco", "post", "samsung", "samsungpay", "savingsbank", "shinhan", "shinhyup", "suhyup", "tossbank", "unknown", "woori" ], "description": "Type of Korean payment method used to pay.", "title": "Korean market underlying payment method type", "x-enum-descriptions": { "bc": { "description": "BC Card (BCard), a kind of card issued in Korea. (비씨카드)" }, "citi": { "description": "Card issued by Citi Bank in Korea. (한국씨티은행)" }, "hana": { "description": "Card issued by Hana Bank in Korea. (하나카드)" }, "hyundai": { "description": "Hyundai Card, a credit card issued by Hyundai in Korea. (현대카드)" }, "jeju": { "description": "Card issued by Jeju Bank in Korea. (제주은행)" }, "jeonbuk": { "description": "Card issued by Jeonbuk Bank in Korea. (전북은행)" }, "kakaobank": { "description": "Card issued by Kakaobank in Korea. (주식회사 카카오뱅크)" }, "kakaopay": { "description": "KakaoPay digital wallet, popular in Korea. (카카오페이)" }, "kbank": { "description": "Card issued by K Bank in Korea. (케이뱅크)" }, "kdbbank": { "description": "Card issued by KDB Bank in Korea. (한국산업은행)" }, "kookmin": { "description": "Card issued by Kookmin Bank in Korea. (국민은행)" }, "kwangju": { "description": "Card issued by Kwangju Bank in Korea. (광주은행)" }, "lotte": { "description": "Lotte Card, a credit card issued by the Lotte Corporation in Korea. (롯데카드)" }, "mg": { "description": "Card issued by MG Community Credit Cooperatives (KFCC) in Korea. (MG새마을금고)" }, "naverpaycard": { "description": "Card issued by Naver Pay in Korea. (네이버 페이)", "deprecated": true }, "naverpaypoint": { "description": "Naver Pay digital wallet, popular in Korea. (네이버 페이)", "deprecated": true }, "nh": { "description": "NH Card, a card issued by Nonghyup Bank in Korea. (NH농협은행)" }, "payco": { "description": "PayCo digital wallet, popular in Korea. (페이코)", "deprecated": true }, "post": { "description": "Card issued by Korea Post. (우체국예금보험)" }, "samsung": { "description": "Samsung Card, a card issued by Samsung in Korea. (삼성카드)" }, "samsungpay": { "description": "Samsung Pay digital wallet, popular in Korea. (삼성 월렛)", "deprecated": true }, "savingsbank": { "description": "Card issued by the Korean Federation of Savings Banks in Korea. (저축은행중앙회)" }, "shinhan": { "description": "Card issued by Shinhan Bank in Korea. (주식회사 신한은행)" }, "shinhyup": { "description": "Card issued by the National Credit Unit Federation of Korea (Shinhyup) in Korea. (신한은행 신협)" }, "suhyup": { "description": "Card issued by the National Federation of Fisheries Cooperation (Suhyup) in Korea. (수협은행)" }, "tossbank": { "description": "Card issued by Toss Bank in Korea. (토스뱅크)" }, "unknown": { "description": "Underlying payment method not recognized." }, "woori": { "description": "Card issued by Woori Bank in Korea. (주식회사 우리은행)" } } } }, "description": "Information about the Korean payment method used to pay. `null` unless the type is `korea_local`.", "title": "Korean market underlying details" }, { "type": "null" } ] } }, "description": "Information about the underlying payment method used to pay. Populated for payment methods that offer multiple payment options, like `korea_local`. Deprecated - use top-level type objects instead.", "title": "PaymentMethodUnderlyingDetails", "deprecated": true }, { "type": "null" } ], "deprecated": true }, "south_korea_local_card": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "bc", "citi", "hana", "hyundai", "jeju", "jeonbuk", "kakaobank", "kbank", "kdbbank", "kookmin", "kwangju", "lotte", "mg", "nh", "post", "samsung", "savingsbank", "shinhan", "shinhyup", "suhyup", "tossbank", "unknown", "woori" ], "description": "Type of Korean payment method used to pay.", "title": "SouthKoreaLocalCardType", "x-enum-descriptions": { "bc": { "description": "BC Card (BCard), a kind of card issued in Korea. (비씨카드)." }, "citi": { "description": "Card issued by Citi Bank in Korea. (한국씨티은행)." }, "hana": { "description": "Card issued by Hana Bank in Korea. (하나카드)." }, "hyundai": { "description": "Hyundai Card, a credit card issued by Hyundai in Korea. (현대카드)." }, "jeju": { "description": "Card issued by Jeju Bank in Korea. (제주은행)." }, "jeonbuk": { "description": "Card issued by Jeonbuk Bank in Korea. (전북은행)." }, "kbank": { "description": "Card issued by K Bank in Korea. (케이뱅크)." }, "kdbbank": { "description": "Card issued by KDB Bank in Korea. (한국산업은행)." }, "kookmin": { "description": "Card issued by Kookmin Bank in Korea. (국민은행)." }, "kwangju": { "description": "Card issued by Kwangju Bank in Korea. (광주은행)." }, "lotte": { "description": "Lotte Card, a credit card issued by the Lotte Corporation in Korea. (롯데카드)." }, "mg": { "description": "Card issued by MG Community Credit Cooperatives (KFCC) in Korea. (MG새마을금고)." }, "nh": { "description": "NH Card, a card issued by Nonghyup Bank in Korea. (NH농협은행)." }, "post": { "description": "Card issued by Korea Post. (우체국예금보험)." }, "samsung": { "description": "Samsung Card, a card issued by Samsung in Korea. (삼성카드)." }, "savingsbank": { "description": "Card issued by the Korean Federation of Savings Banks in Korea. (저축은행중앙회)." }, "shinhan": { "description": "Card issued by Shinhan Bank in Korea. (주식회사 신한은행)." }, "shinhyup": { "description": "Card issued by the National Credit Unit Federation of Korea (Shinhyup) in Korea. (신한은행 신협)." }, "suhyup": { "description": "Card issued by the National Federation of Fisheries Cooperation (Suhyup) in Korea. (수협은행)." }, "tossbank": { "description": "Card issued by Toss Bank in Korea. (토스뱅크)." }, "unknown": { "description": "Underlying payment method not recognized." }, "woori": { "description": "Card issued by Woori Bank in Korea. (주식회사 우리은행)." } } }, "last4": { "type": "string", "description": "Last four digits of the card used to pay.", "title": "Card Last Four", "examples": [ "4242" ] } }, "description": "Information about the Korean payment method used to pay.", "title": "SouthKoreaLocalCard" }, { "type": "null" } ], "description": "Information about the Korean credit or debit card used to pay. `null` unless `type` is `south_korea_local_card`." }, "card": { "anyOf": [ { "type": "object", "required": [ "type", "last4", "expiry_month", "expiry_year", "cardholder_name" ], "properties": { "type": { "type": "string", "enum": [ "american_express", "diners_club", "discover", "jcb", "mada", "maestro", "mastercard", "union_pay", "unknown", "visa" ], "description": "Type of credit or debit card used to pay.", "title": "CardType", "x-enum-descriptions": { "american_express": { "description": "American Express" }, "diners_club": { "description": "Diners Club" }, "discover": { "description": "Discover Card" }, "jcb": { "description": "JCB Card, popular in Japan" }, "mada": { "description": "Mada Card, popular in Saudi Arabia" }, "maestro": { "description": "Maestro (debit card)" }, "mastercard": { "description": "Mastercard" }, "union_pay": { "description": "UnionPay, popular in China" }, "unknown": { "description": "Card type unknown" }, "visa": { "description": "Visa" } } }, "last4": { "type": "string", "description": "Last four digits of the card used to pay.", "title": "Card Last Four", "examples": [ "4242" ] }, "expiry_month": { "type": "integer", "description": "Month of the expiry date of the card used to pay.", "title": "Card Expiry Month", "examples": [ 12 ] }, "expiry_year": { "type": "integer", "description": "Year of the expiry date of the card used to pay.", "title": "Card Expiry Year", "examples": [ 2028 ] }, "cardholder_name": { "type": "string", "description": "The name on the card used to pay.", "title": "Cardholder Name" } }, "description": "Card metadata", "title": "Card" }, { "type": "null" } ], "description": "Information about the credit or debit card used to pay. `null` unless `type` is `card`." }, "paypal": { "anyOf": [ { "type": "object", "required": [ "email", "reference" ], "properties": { "email": { "type": "string", "description": "Email address associated with the PayPal account.", "examples": [ "john.doe@example.com" ] }, "reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "PayPal billing agreement identifier. Only populated for subscription payments where a billing agreement was created between the customer and PayPal. `null` for one-off PayPal payments." } }, "description": "PayPal payment attempt metadata", "title": "PayPal (transaction)" }, { "type": "null" } ], "description": "Information about the PayPal account used to pay. `null` unless `type` is `paypal`." } }, "description": "Information about the payment method used for a payment attempt.", "title": "Method details" }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.", "title": "Created at", "examples": [ "2024-10-12T07:20:50.52Z" ] }, "captured_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 datetime string.", "title": "Timestamp", "examples": [ "2024-10-12T07:20:50.52Z" ] }, { "type": "null" } ], "description": "RFC 3339 datetime string of when this payment was captured. `null` if `status` is not `captured`." } }, "title": "Transaction payment attempt" }, "description": "List of payment attempts for this transaction, including successful payments. Sorted by `created_at` in descending order, so most recent attempts are returned first." }, "checkout": { "anyOf": [ { "type": "object", "required": [ "url" ], "properties": { "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "minLength": 1, "maxLength": 2048, "description": "Paddle Checkout URL for this transaction, composed of the URL passed in the request or your default payment URL + `?_ptxn=` and the Paddle ID for this transaction." } }, "description": "Paddle Checkout details for this transaction. Returned for automatically-collected transactions and where `billing_details.enable_checkout` is `true` for manually-collected transactions; `null` otherwise.", "title": "TransactionCheckout" }, { "type": "null" } ], "description": "Paddle Checkout details for this transaction. Returned for automatically-collected transactions and where `billing_details.enable_checkout` is `true` for manually-collected transactions; `null` otherwise." }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.", "title": "Created at", "examples": [ "2024-10-12T07:20:50.52Z" ] }, "updated_at": { "type": "string", "format": "date-time", "description": "RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.", "title": "Updated at", "examples": [ "2024-10-13T07:20:50.52Z" ] }, "billed_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 datetime string.", "title": "Timestamp", "examples": [ "2024-10-12T07:20:50.52Z" ] }, { "type": "null" } ], "description": "RFC 3339 datetime string of when this transaction was marked as `billed`. `null` for transactions that aren't `billed` or `completed`. Set automatically by Paddle." }, "revised_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 datetime string.", "title": "Timestamp", "examples": [ "2024-10-12T07:20:50.52Z" ] }, { "type": "null" } ], "description": "RFC 3339 datetime string of when a transaction was revised. Revisions describe an update to customer information for a billed or completed transaction. `null` if not revised. Set automatically by Paddle." } }, "required": [ "id", "status", "customer_id", "address_id", "business_id", "custom_data", "currency_code", "origin", "subscription_id", "invoice_id", "invoice_number", "collection_mode", "discount_id", "billing_details", "billing_period", "items", "details", "payments", "checkout", "created_at", "updated_at", "billed_at", "revised_at" ], "type": "object", "description": "New or changed entity." } } } ``` ## Example ```json { "event_id": "evt_01hv8xsew895m2bswfcezebbjw", "event_type": "transaction.canceled", "occurred_at": "2024-04-12T10:31:27.880764Z", "notification_id": "ntf_01hv8xseze1cnv8k83cnhtn4zr", "data": { "id": "txn_01hv8m0mnx3sj85e7gxc6kga03", "items": [ { "price": { "id": "pri_01gsz8x8sawmvhz1pv30nge1ke", "name": "Monthly (per seat)", "type": "standard", "status": "active", "quantity": { "maximum": 999, "minimum": 1 }, "tax_mode": "account_setting", "created_at": "2023-02-23T13:55:22.538367Z", "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg", "unit_price": { "amount": "3000", "currency_code": "USD" }, "updated_at": "2024-04-11T13:54:52.254748Z", "custom_data": null, "description": "Monthly", "trial_period": null, "billing_cycle": { "interval": "month", "frequency": 1 }, "unit_price_overrides": [], "import_meta": null }, "quantity": 10, "proration": null }, { "price": { "id": "pri_01h1vjfevh5etwq3rb416a23h2", "name": "Monthly (recurring addon)", "type": "standard", "status": "active", "quantity": { "maximum": 100, "minimum": 1 }, "tax_mode": "account_setting", "created_at": "2023-06-01T13:31:12.625056Z", "product_id": "pro_01h1vjes1y163xfj1rh1tkfb65", "unit_price": { "amount": "10000", "currency_code": "USD" }, "updated_at": "2024-04-09T07:23:00.907834Z", "custom_data": null, "description": "Monthly", "trial_period": null, "billing_cycle": { "interval": "month", "frequency": 1 }, "unit_price_overrides": [], "import_meta": null }, "quantity": 1, "proration": null }, { "price": { "id": "pri_01gsz98e27ak2tyhexptwc58yk", "name": "One-time addon", "type": "standard", "status": "active", "quantity": { "maximum": 1, "minimum": 1 }, "tax_mode": "account_setting", "created_at": "2023-02-23T14:01:28.391712Z", "product_id": "pro_01gsz97mq9pa4fkyy0wqenepkz", "unit_price": { "amount": "19900", "currency_code": "USD" }, "updated_at": "2024-04-09T07:23:10.921392Z", "custom_data": null, "description": "One-time addon", "trial_period": null, "billing_cycle": null, "unit_price_overrides": [], "import_meta": null }, "quantity": 1, "proration": null } ], "origin": "api", "status": "canceled", "details": { "totals": { "fee": null, "tax": "5315", "total": "65215", "credit": "0", "balance": "65215", "discount": "0", "earnings": null, "subtotal": "59900", "grand_total": "65215", "grand_total_tax": "5315", "currency_code": "USD", "credit_to_balance": "0" }, "line_items": [ { "id": "txnitm_01hv8wt98jahpbm1t1tzr06z6n", "totals": { "tax": "2662", "total": "32662", "discount": "0", "subtotal": "30000" }, "product": { "id": "pro_01gsz4t5hdjse780zja8vvr7jg", "name": "AeroEdit Pro", "type": "standard", "status": "active", "image_url": "https://paddle.s3.amazonaws.com/user/165798/bT1XUOJAQhOUxGs83cbk_pro.png", "created_at": "2023-02-23T12:43:46.605Z", "updated_at": "2024-04-05T15:53:44.687Z", "custom_data": { "features": { "sso": false, "route_planning": true, "payment_by_invoice": false, "aircraft_performance": true, "compliance_monitoring": true, "flight_log_management": true }, "suggested_addons": [ "pro_01h1vjes1y163xfj1rh1tkfb65", "pro_01gsz97mq9pa4fkyy0wqenepkz" ], "upgrade_description": "Move from Basic to Pro to take advantage of aircraft performance, advanced route planning, and compliance monitoring." }, "description": "Designed for professional pilots, including all features plus in Basic plus compliance monitoring, route optimization, and third-party integrations.", "tax_category": "standard", "import_meta": null }, "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke", "quantity": 10, "tax_rate": "0.08875", "proration": null, "unit_totals": { "tax": "266", "total": "3266", "discount": "0", "subtotal": "3000" } }, { "id": "txnitm_01hv8wt98jahpbm1t1v1sd067y", "totals": { "tax": "887", "total": "10887", "discount": "0", "subtotal": "10000" }, "product": { "id": "pro_01h1vjes1y163xfj1rh1tkfb65", "name": "Analytics addon", "type": "standard", "status": "active", "image_url": "https://paddle.s3.amazonaws.com/user/165798/97dRpA6SXzcE6ekK9CAr_analytics.png", "created_at": "2023-06-01T13:30:50.302Z", "updated_at": "2024-04-05T15:47:17.163Z", "custom_data": null, "description": "Unlock advanced insights into your flight data with enhanced analytics and reporting features. Includes customizable reporting templates and trend analysis across flights.", "tax_category": "standard", "import_meta": null }, "price_id": "pri_01h1vjfevh5etwq3rb416a23h2", "quantity": 1, "tax_rate": "0.08875", "proration": null, "unit_totals": { "tax": "887", "total": "10887", "discount": "0", "subtotal": "10000" } }, { "id": "txnitm_01hv8wt98jahpbm1t1v67vqnb6", "totals": { "tax": "1766", "total": "21666", "discount": "0", "subtotal": "19900" }, "product": { "id": "pro_01gsz97mq9pa4fkyy0wqenepkz", "name": "Custom domains", "type": "standard", "status": "active", "image_url": "https://paddle.s3.amazonaws.com/user/165798/XIG7UXoJQHmlIAiKcnkA_custom-domains.png", "created_at": "2023-02-23T14:01:02.441Z", "updated_at": "2024-04-05T15:43:28.971Z", "custom_data": null, "description": "Make AeroEdit truly your own with custom domains. Custom domains reinforce your brand identity and make it easy for your team to access your account.", "tax_category": "standard", "import_meta": null }, "price_id": "pri_01gsz98e27ak2tyhexptwc58yk", "quantity": 1, "tax_rate": "0.08875", "proration": null, "unit_totals": { "tax": "1766", "total": "21666", "discount": "0", "subtotal": "19900" } } ], "payout_totals": null, "adjusted_payout_totals": null, "tax_rates_used": [ { "totals": { "tax": "5315", "total": "65215", "discount": "0", "subtotal": "59900" }, "tax_rate": "0.08875" } ], "adjusted_totals": { "fee": "0", "tax": "5315", "total": "65215", "earnings": "0", "subtotal": "59900", "grand_total": "65215", "grand_total_tax": "5315", "currency_code": "USD", "retained_fee": "0" } }, "checkout": { "url": null }, "payments": [], "billed_at": "2024-04-12T10:30:27.198043Z", "address_id": "add_01hv8gq3318ktkfengj2r75gfx", "created_at": "2024-04-12T07:40:38.00704Z", "invoice_id": "inv_01hv8m0nn5nbvdejcvv9cpg8jf", "updated_at": "2024-04-12T10:31:27.360716923Z", "revised_at": null, "business_id": null, "custom_data": null, "customer_id": "ctm_01hv6y1jedq4p1n0yqn5ba3ky4", "discount_id": "dsc_01gtgztp8fpchantd5g1wrksa3", "currency_code": "USD", "billing_period": { "ends_at": "2025-04-11T23:59:00Z", "starts_at": "2024-04-12T00:00:00Z" }, "invoice_number": "325-10567", "billing_details": { "payment_terms": { "interval": "day", "frequency": 14 }, "enable_checkout": false, "purchase_order_number": "PO-123", "additional_information": null }, "collection_mode": "manual", "subscription_id": "sub_01hv8xqmay5w5rfsnzkxzgy0yp" } } ```