> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt). # subscription.activated Occurs when a subscription becomes active. --- Occurs when a subscription becomes active. Its `status` field changes to `active`. This means any trial period has elapsed and Paddle has successfully billed the customer. [`subscription.updated`](https://developer.paddle.com/webhooks/subscriptions/subscription-updated.md) typically follows as Paddle completes processing. [`subscription.past_due`](https://developer.paddle.com/webhooks/subscriptions/subscription-past-due.md), [`subscription.paused`](https://developer.paddle.com/webhooks/subscriptions/subscription-paused.md), or [`subscription.canceled`](https://developer.paddle.com/webhooks/subscriptions/subscription-canceled.md) may occur later in the subscription lifecycle. Payload includes the complete subscription entity, except `management_urls`. Subscription management links are temporary, so they're not included. [Get a subscription using the API](https://developer.paddle.com/api-reference/subscriptions/get-subscription) to get management links for a subscription. ## 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": "^sub_[a-z\\d]{26}$", "description": "Unique Paddle ID for this subscription entity, prefixed with `sub_`.", "title": "Subscription ID", "examples": [ "sub_01h04vsc0qhwtsbsxh3422wjs4" ] }, "status": { "type": "string", "enum": [ "active", "canceled", "past_due", "paused", "trialing" ], "description": "Status of this subscription. Set automatically by Paddle. Use the pause subscription or cancel subscription operations to change.", "title": "SubscriptionStatus", "x-enum-descriptions": { "active": { "description": "Subscription is active. Paddle is billing for this subscription and related transactions aren't past due." }, "canceled": { "description": "Subscription is canceled. Automatically set by Paddle when a subscription is canceled. When a subscription is set to cancel on the next billing period, a scheduled change for the cancellation is created. The subscription status moves to canceled when the scheduled change takes effect." }, "past_due": { "description": "Subscription has an overdue payment. Automatically set by Paddle when payment fails for an automatically-collected transaction, or when payment terms have elapsed for a manually-collected transaction (an invoice)." }, "paused": { "description": "Subscription is paused. Automatically set by Paddle when a subscription is paused. When a subscription is set to pause on the next billing period, a scheduled change for the pause is created. The subscription status moves to `paused` when the scheduled change takes effect." }, "trialing": { "description": "Subscription is in trial." } } }, "customer_id": { "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" ] }, "address_id": { "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" ] }, "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" } ] }, "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" } } }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 datetime string.", "title": "Timestamp", "examples": [ "2024-10-12T07:20:50.52Z" ] }, "updated_at": { "type": "string", "format": "date-time", "description": "RFC 3339 datetime string.", "title": "Timestamp", "examples": [ "2024-10-12T07:20:50.52Z" ] }, "started_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 subscription started. This may be different from `first_billed_at` if the subscription started in trial." }, "first_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 subscription was first billed. This may be different from `started_at` if the subscription started in trial." }, "next_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 subscription is next scheduled to be billed." }, "paused_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 subscription was paused. Set automatically by Paddle when the pause subscription operation is used. `null` if not paused." }, "canceled_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 subscription was canceled. Set automatically by Paddle when the cancel subscription operation is used. `null` if not canceled." }, "discount": { "anyOf": [ { "type": "object", "required": [ "id", "starts_at", "ends_at", "type" ], "properties": { "id": { "type": "string", "pattern": "^dsc_[a-z\\d]{26}$", "description": "Unique Paddle ID for this discount, prefixed with `dsc_`.", "title": "Discount ID", "examples": [ "dsc_01gv5kpg05xp104ek2fmgjwttf" ] }, "starts_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 discount was first applied. `null` for canceled subscriptions where a discount was redeemed but never applied to a transaction." }, "ends_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 discount no longer applies. Where a discount has `maximum_recurring_intervals`, this is the date of the last billing period where this discount applies. `null` where a discount recurs forever." }, "type": { "type": "string", "enum": [ "recurring", "one-off" ], "description": "Whether this discount applies for multiple billing periods.", "title": "SubscriptionDiscountType", "x-enum-descriptions": { "recurring": { "description": "Discount applies to multiple billing periods." }, "one-off": { "description": "Discount applies to a single billing period only. Returned when a subscription is created in trial with a discount. The discount is removed from the subscription on renewal." } } } }, "description": "Details of the discount applied to this subscription.", "title": "SubscriptionDiscountTimePeriod" }, { "type": "null" } ] }, "collection_mode": { "anyOf": [ { "type": "string", "enum": [ "automatic", "manual" ], "description": "How payment is collected. `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`." } } }, { "type": "null" } ], "description": "How payment is collected for transactions created for this subscription. `automatic` for checkout, `manual` for invoices." }, "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" } ] }, "current_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": "Current billing period for this subscription. Set automatically by Paddle based on the billing cycle. `null` for `paused` and `canceled` subscriptions." }, "billing_cycle": { "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 often this subscription renews. Set automatically by Paddle based on the prices on this subscription." }, "scheduled_change": { "anyOf": [ { "type": "object", "required": [ "action", "effective_at", "resume_at" ], "properties": { "action": { "type": "string", "enum": [ "cancel", "pause", "resume" ], "description": "Kind of change that's scheduled to be applied to this subscription.", "title": "ScheduledChangeAction", "x-enum-descriptions": { "cancel": { "description": "Subscription is scheduled to cancel. Its status changes to `canceled` on the `effective_at` date." }, "pause": { "description": "Subscription is scheduled to pause. Its status changes to `paused` on the `effective_at` date." }, "resume": { "description": "Subscription is scheduled to resume. Its status changes to `active` on the `effective_at` date." } } }, "effective_at": { "type": "string", "format": "date-time", "description": "RFC 3339 datetime string of when this scheduled change takes effect.", "title": "Timestamp", "examples": [ "2024-10-12T07:20:50.52Z" ] }, "resume_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 paused subscription should resume. Only used for `pause` scheduled changes." } }, "description": "Change that's scheduled to be applied to a subscription. Use the pause subscription, cancel subscription, and resume subscription operations to create scheduled changes. `null` if no scheduled changes.", "title": "Subscription scheduled change" }, { "type": "null" } ] }, "items": { "type": "array", "items": { "type": "object", "required": [ "status", "quantity", "recurring", "created_at", "updated_at", "previously_billed_at", "next_billed_at", "trial_dates", "price", "product" ], "properties": { "status": { "type": "string", "enum": [ "active", "inactive", "trialing" ], "description": "Status of this subscription item. Set automatically by Paddle.", "title": "SubscriptionItemStatus", "x-enum-descriptions": { "active": { "description": "This item is active. It is not in trial and Paddle bills for it." }, "inactive": { "description": "This item is not active. Set when the related subscription is paused." }, "trialing": { "description": "This item is in trial. Paddle has not billed for it." } } }, "quantity": { "type": "number", "minimum": 1, "description": "Quantity of this item on the subscription." }, "recurring": { "type": "boolean", "description": "Whether this is a recurring item. `false` if one-time." }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 datetime string of when this item was added to this subscription.", "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 item was last updated on this subscription.", "title": "Updated at", "examples": [ "2024-10-13T07:20:50.52Z" ] }, "previously_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 item was last billed." }, "next_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 item is next scheduled to be billed." }, "trial_dates": { "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": "Trial dates for this item." }, "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": "Related price entity for this item. This reflects the price entity at the time it was added to the subscription.", "title": "Price" }, "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 item. This reflects the product entity at the time it was added to the subscription.", "title": "Product" } }, "description": "Represents a subscription item.", "title": "Subscription item" } }, "consent_requirements": { "anyOf": [ { "type": "array", "items": { "type": "object", "required": [ "id", "requirement", "status", "created_at", "consent_period", "granted_at", "voided_at" ], "properties": { "id": { "type": "string", "pattern": "^subconreq_[a-z\\d]{26}$", "description": "Unique Paddle ID for this subscription consent requirement entity, prefixed with `subconreq_`.", "title": "Subscription Consent Requirement ID", "examples": [ "subconreq_01gm302t81w94gyjpjpqypkzkf" ] }, "requirement": { "type": "string", "enum": [ "trial_ending", "introductory_discount_ending" ], "description": "Type of consent required for successful renewal.", "x-enum-descriptions": { "trial_ending": { "description": "Consent required because the trial period is ending." }, "introductory_discount_ending": { "description": "Consent required because an initial discount is ending." } } }, "status": { "type": "string", "enum": [ "pending", "granted", "voided" ], "description": "Status of this consent requirement.", "x-enum-descriptions": { "pending": { "description": "Consent not yet granted. Subscription is canceled on next renewal." }, "granted": { "description": "Consent granted. Subscription renews normally." }, "voided": { "description": "Consent voided. Consent requirement is no longer applicable, either because the consent is no longer required, or another consent requirement has replaced it." } } }, "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" ] }, "consent_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": "Period during which consent for this subscription can be granted. `null` if there is no `next_billed_at` or the consent requirement does not apply to the current billing period." }, "granted_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 the customer granted their consent. `null` if not yet granted." }, "voided_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 consent was voided or no longer required. `null` if not voided." } }, "description": "Represents a specific condition under which explicit customer consent is, or was, mandated for a subscription renewal.", "title": "SubscriptionConsentRequirement" } }, { "type": "null" } ], "description": "List of active consent requirements for the subscription's current billing period." }, "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" } ] } }, "required": [ "id", "status", "customer_id", "address_id", "business_id", "currency_code", "created_at", "updated_at", "started_at", "first_billed_at", "next_billed_at", "paused_at", "canceled_at", "discount", "collection_mode", "billing_details", "current_billing_period", "billing_cycle", "scheduled_change", "items", "consent_requirements", "custom_data", "import_meta" ], "type": "object", "description": "New or changed entity." } } } ``` ## Example ```json { "event_id": "evt_01hv8x2adt2hy58b2w89p4py4d", "event_type": "subscription.activated", "occurred_at": "2024-04-12T10:18:49.658605Z", "notification_id": "ntf_01hv8x2ag2hadnwngnf1qvegrp", "data": { "id": "sub_01hv8x29kz0t586xy6zn1a62ny", "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", "import_meta": null, "trial_period": null, "billing_cycle": { "interval": "month", "frequency": 1 }, "unit_price_overrides": [] }, "product": { "id": "pro_01gsz4t5hdjse780zja8vvr7jg", "name": "AeroEdit Pro", "type": "standard", "tax_category": "standard", "description": "Designed for professional pilots, including all features plus in Basic plus compliance monitoring, route optimization, and third-party integrations.", "image_url": "https://paddle.s3.amazonaws.com/user/165798/bT1XUOJAQhOUxGs83cbk_pro.png", "custom_data": { "features": { "aircraft_performance": true, "compliance_monitoring": true, "flight_log_management": true, "payment_by_invoice": false, "route_planning": true, "sso": false }, "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." }, "status": "active", "import_meta": null, "created_at": "2023-02-23T12:43:46.605Z", "updated_at": "2024-04-05T15:53:44.687Z" }, "status": "active", "quantity": 10, "recurring": true, "created_at": "2024-04-12T10:18:48.831Z", "updated_at": "2024-04-12T10:18:48.831Z", "trial_dates": null, "next_billed_at": "2024-05-12T10:18:47.635628Z", "previously_billed_at": "2024-04-12T10:18:47.635628Z" }, { "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", "import_meta": null, "trial_period": null, "billing_cycle": { "interval": "month", "frequency": 1 }, "unit_price_overrides": [] }, "product": { "id": "pro_01h1vjes1y163xfj1rh1tkfb65", "name": "Analytics addon", "type": "standard", "tax_category": "standard", "description": "Unlock advanced insights into your flight data with enhanced analytics and reporting features. Includes customizable reporting templates and trend analysis across flights.", "image_url": "https://paddle.s3.amazonaws.com/user/165798/97dRpA6SXzcE6ekK9CAr_analytics.png", "custom_data": null, "status": "active", "import_meta": null, "created_at": "2023-06-01T13:30:50.302Z", "updated_at": "2024-04-05T15:47:17.163Z" }, "status": "active", "quantity": 1, "recurring": true, "created_at": "2024-04-12T10:18:48.831Z", "updated_at": "2024-04-12T10:18:48.831Z", "trial_dates": null, "next_billed_at": "2024-05-12T10:18:47.635628Z", "previously_billed_at": "2024-04-12T10:18:47.635628Z" } ], "status": "active", "discount": null, "paused_at": null, "address_id": "add_01hv8gq3318ktkfengj2r75gfx", "created_at": "2024-04-12T10:18:48.831Z", "started_at": "2024-04-12T10:18:47.635628Z", "updated_at": "2024-04-12T10:18:48.831Z", "business_id": null, "canceled_at": null, "custom_data": null, "customer_id": "ctm_01hv6y1jedq4p1n0yqn5ba3ky4", "import_meta": null, "billing_cycle": { "interval": "month", "frequency": 1 }, "currency_code": "USD", "next_billed_at": "2024-05-12T10:18:47.635628Z", "billing_details": null, "collection_mode": "automatic", "first_billed_at": "2024-04-12T10:18:47.635628Z", "scheduled_change": null, "consent_requirements": [], "current_billing_period": { "ends_at": "2024-05-12T10:18:47.635628Z", "starts_at": "2024-04-12T10:18:47.635628Z" } } } ```