{"note":"OpenAPI conversion -- returning structured metadata","name":"paddle","description":"Paddle API","version":"1.0","base_url":"https://sandbox-api.paddle.com","endpoints":87,"raw":"@lap v0.3\n# Machine-readable API spec. Each @endpoint block is one API call.\n@api Paddle API\n@base https://sandbox-api.paddle.com\n@version 1.0\n@auth Bearer Bearer\n@endpoints 87\n@hint download_for_search\n@toc customers(18), adjustments(3), client-tokens(4), discount-groups(4), discounts(4), event-types(1), events(1), ips(1), notification-settings(5), notifications(4), prices(4), pricing-preview(1), products(4), reports(4), simulation-types(1), simulations(10), subscriptions(11), transactions(7)\n\n@group customers\n@endpoint GET /customers/{customer_id}/addresses\n@desc List addresses for a customer\n@required {customer_id: str # Paddle ID of the customer entity to work with.}\n@optional {id: [str] # Return only the IDs specified. Use a comma-separated list to get multiple entities., after: str # Return entities after the specified Paddle ID when working with paginated endpoints. Used in the `meta.pagination.next` URL in responses for list operations., per_page: int=50 # Set how many entities are returned per page. Paddle returns the maximum number of results if a number greater than the maximum is requested. Check `meta.pagination.per_page` in the response to see how many were returned.  Default: `50`; Maximum: `200`., order_by: str=id[DESC] # Order returned entities by the specified field and direction (`[ASC]` or `[DESC]`). For example, `?order_by=id[ASC]`.  Valid fields for ordering: `id`., status: [str]=active # Return entities that match the specified status. Use a comma-separated list to specify multiple status values., search: str # Return entities that match a search query. Searches all fields except `status`, `created_at`, and `updated_at`.}\n@returns(200) {data: [map], meta: map{request_id: str, pagination: map{per_page: int, next: str(uri), has_more: bool, estimated_total: int}}} # The request has succeeded.\n\n@endpoint POST /customers/{customer_id}/addresses\n@desc Create an address for a customer\n@required {customer_id: str # Paddle ID of the customer entity to work with., country_code: any # Supported two-letter ISO 3166-1 alpha-2 country code for this address.}\n@optional {id: any, description: any # Memorable description for this address., first_line: any # First line of this address., second_line: any # Second line of this address., city: any # City of this address., postal_code: any # ZIP or postal code of this address. Required for some countries., region: any # State, county, or region of this address., custom_data: any # Your own structured key-value data., import_meta: any # Import information for this entity. `null` if this entity is not imported.}\n@returns(201) {data: map{id: any, customer_id: any, description: any, first_line: any, second_line: any, city: any, postal_code: any, region: any, country_code: any, custom_data: any, status: any, created_at: any, updated_at: any, import_meta: any}, meta: map{request_id: str}} # The request has succeeded and a new resource has been created as a result.\n@example_request {\"description\":\"Head Office\",\"first_line\":\"4050 Jefferson Plaza, 41st Floor\",\"city\":\"New York\",\"postal_code\":\"10021\",\"region\":\"NY\",\"country_code\":\"US\"}\n\n@endpoint GET /customers/{customer_id}/addresses/{address_id}\n@desc Get an address for a customer\n@required {address_id: str # Paddle ID of the address entity to work with., customer_id: str # Paddle ID of the customer entity to work with.}\n@returns(200) {data: map{id: any, customer_id: any, description: any, first_line: any, second_line: any, city: any, postal_code: any, region: any, country_code: any, custom_data: any, status: any, created_at: any, updated_at: any, import_meta: any}, meta: map{request_id: str}} # The request has succeeded.\n\n@endpoint PATCH /customers/{customer_id}/addresses/{address_id}\n@desc Update an address for a customer\n@required {address_id: str # Paddle ID of the address entity to work with., customer_id: str # Paddle ID of the customer entity to work with.}\n@optional {description: any # Memorable description for this address., first_line: any # First line of this address., second_line: any # Second line of this address., city: any # City of this address., postal_code: any # ZIP or postal code of this address. Required for some countries., region: any # State, county, or region of this address., country_code: any # Supported two-letter ISO 3166-1 alpha-2 country code for this address., custom_data: any # Your own structured key-value data., status: str(active/archived) # Whether this entity can be used in Paddle.}\n@returns(200) {data: map{id: any, customer_id: any, description: any, first_line: any, second_line: any, city: any, postal_code: any, region: any, country_code: any, custom_data: any, status: any, created_at: any, updated_at: any, import_meta: any}, meta: map{request_id: str}} # The request has succeeded.\n@example_request {\"description\":\"California Office\",\"first_line\":\"5400 E Washington Drive, Floor 2\",\"city\":\"San Jose\",\"region\":\"CA\",\"custom_data\":{\"crm_id\":\"08bcfb7a-41d8-4747-9ade-3d885c287d0f\"}}\n\n@endgroup\n\n@group adjustments\n@endpoint GET /adjustments\n@desc List adjustments\n@optional {id: [str] # Return only the IDs specified. Use a comma-separated list to get multiple entities., after: str # Return entities after the specified Paddle ID when working with paginated endpoints. Used in the `meta.pagination.next` URL in responses for list operations., action: str # Return entities for the specified action., customer_id: [str] # Return entities related to the specified customer. Use a comma-separated list to specify multiple customer IDs., order_by: str=id[DESC] # Order returned entities by the specified field and direction (`[ASC]` or `[DESC]`). For example, `?order_by=id[ASC]`.  Valid fields for ordering: `id`., per_page: int=10 # Set how many entities are returned per page. Paddle returns the maximum number of results if a number greater than the maximum is requested. Check `meta.pagination.per_page` in the response to see how many were returned.  Default: `10`; Maximum: `50`., status: [str] # Return entities that match the specified status. Use a comma-separated list to specify multiple status values., subscription_id: [str] # Return entities related to the specified subscription. Use a comma-separated list to specify multiple subscription IDs., transaction_id: [str] # Return entities related to the specified transaction. Use a comma-separated list to specify multiple transaction IDs.}\n@returns(200) {data: [map], meta: map{request_id: str, pagination: map{per_page: int, next: str(uri), has_more: bool, estimated_total: int}}} # The request has succeeded.\n\n@endpoint POST /adjustments\n@desc Create an adjustment\n@required {action: str(credit/refund/chargeback/chargeback_reverse/chargeback_warning/chargeback_warning_reverse/credit_reverse) # How this adjustment impacts the related transaction., transaction_id: any # Paddle ID of the transaction that this adjustment is for, prefixed with `txn_`.  Automatically-collected transactions must be `completed`; manually-collected transactions must have a status of `billed` or `past_due`  You can't create an adjustment for a transaction that has a refund that's pending approval., reason: str # Why this adjustment was created. Appears in the Paddle dashboard. Retained for recordkeeping purposes.}\n@optional {type: any=partial, tax_mode: any=internal, items: any # List of transaction items to adjust. Required if `type` is not populated or set to `partial`.}\n@returns(201) {data: map{id: any, action: str, type: any, transaction_id: any, subscription_id: any, customer_id: any, reason: str, credit_applied_to_balance: any, currency_code: any, status: any, items: [map], totals: any, payout_totals: any, tax_rates_used: [map], created_at: any, updated_at: any}, meta: map{request_id: str}} # The request has succeeded and a new resource has been created as a result.\n@example_request {\"action\":\"refund\",\"items\":[{\"item_id\":\"txnitm_01hvcc94b7qgz60qmrqmbm19zw\",\"type\":\"partial\",\"amount\":\"100\"}],\"reason\":\"error\",\"transaction_id\":\"txn_01hvcc93znj3mpqt1tenkjb04y\"}\n\n@endpoint GET /adjustments/{adjustment_id}/credit-note\n@desc Get a PDF credit note for an adjustment\n@required {adjustment_id: str # Paddle ID of the adjustment entity to work with.}\n@optional {disposition: str=attachment # Determine whether the generated URL should download the PDF as an attachment saved locally, or open it inline in the browser.  Default: `attachment`.}\n@returns(200) {data: map{url: str}, meta: map{request_id: str}} # The request has succeeded.\n\n@endgroup\n\n@group customers\n@endpoint GET /customers/{customer_id}/businesses\n@desc List businesses for a customer\n@required {customer_id: str # Paddle ID of the customer entity to work with.}\n@optional {id: [str] # Return only the IDs specified. Use a comma-separated list to get multiple entities., after: str # Return entities after the specified Paddle ID when working with paginated endpoints. Used in the `meta.pagination.next` URL in responses for list operations., per_page: int=50 # Set how many entities are returned per page. Paddle returns the maximum number of results if a number greater than the maximum is requested. Check `meta.pagination.per_page` in the response to see how many were returned.  Default: `50`; Maximum: `200`., order_by: str=id[DESC] # Order returned entities by the specified field and direction (`[ASC]` or `[DESC]`). For example, `?order_by=id[ASC]`.  Valid fields for ordering: `id`., status: [str]=active # Return entities that match the specified status. Use a comma-separated list to specify multiple status values., search: str # Return entities that match a search query. Searches all fields, including contacts, except `status`, `created_at`, and `updated_at`.}\n@returns(200) {data: [map], meta: map{request_id: str, pagination: map{per_page: int, next: str(uri), has_more: bool, estimated_total: int}}} # The request has succeeded.\n\n@endpoint POST /customers/{customer_id}/businesses\n@desc Create a business for a customer\n@required {customer_id: str # Paddle ID of the customer entity to work with., name: any # Name of this business.}\n@optional {id: any, company_number: any # Company number for this business., tax_identifier: any # Tax or VAT Number for this business., contacts: any # List of contacts related to this business, typically used for sending invoices., custom_data: any # Your own structured key-value data., import_meta: any # Import information for this entity. `null` if this entity is not imported.}\n@returns(201) {data: map{id: any, customer_id: any, name: any, company_number: any, tax_identifier: any, status: any, contacts: [map], created_at: any, updated_at: any, custom_data: any, import_meta: any}, meta: map{request_id: str}} # The request has succeeded and a new resource has been created as a result.\n@example_request {\"name\":\"Uplift Inc.\",\"company_number\":\"555775291485\",\"tax_identifier\":\"555952383\",\"contacts\":[{\"name\":\"Parker Jones\",\"email\":\"parker@example.com\"}]}\n\n@endpoint GET /customers/{customer_id}/businesses/{business_id}\n@desc Get a business for a customer\n@required {business_id: str # Paddle ID of the business entity to work with., customer_id: str # Paddle ID of the customer entity to work with.}\n@returns(200) {data: map{id: any, customer_id: any, name: any, company_number: any, tax_identifier: any, status: any, contacts: [map], created_at: any, updated_at: any, custom_data: any, import_meta: any}, meta: map{request_id: str}} # The request has succeeded.\n\n@endpoint PATCH /customers/{customer_id}/businesses/{business_id}\n@desc Update a business for a customer\n@required {business_id: str # Paddle ID of the business entity to work with., customer_id: str # Paddle ID of the customer entity to work with.}\n@optional {name: any # Name of this business., company_number: any # Company number for this business., tax_identifier: any # Tax or VAT Number for this business., status: str(active/archived) # Whether this entity can be used in Paddle., contacts: any # List of contacts related to this business, typically used for sending invoices., custom_data: any # Your own structured key-value data.}\n@returns(200) {data: map{id: any, customer_id: any, name: any, company_number: any, tax_identifier: any, status: any, contacts: [map], created_at: any, updated_at: any, custom_data: any, import_meta: any}, meta: map{request_id: str}} # The request has succeeded.\n@example_request {\"contacts\":[{\"name\":\"Parker Jones\",\"email\":\"parker@example.com\"},{\"name\":\"Jo Riley\",\"email\":\"jo@example.com\"},{\"name\":\"Jesse Garcia\",\"email\":\"jo@example.com\"}],\"custom_data\":{\"customer_reference_id\":\"eb9b8d9b-7dd6-48e6-8c39-8557bba5eaa9\"}}\n\n@endgroup\n\n@group client-tokens\n@endpoint GET /client-tokens\n@desc List client-side tokens\n@optional {after: str # Return entities after the specified Paddle ID when working with paginated endpoints. Used in the `meta.pagination.next` URL in responses for list operations., per_page: int=50 # Set how many entities are returned per page. Paddle returns the maximum number of results if a number greater than the maximum is requested. Check `meta.pagination.per_page` in the response to see how many were returned.  Default: `50`; Maximum: `200`., order_by: str=id[DESC] # Order returned entities by the specified field and direction (`[ASC]` or `[DESC]`). For example, `?order_by=id[ASC]`.  Valid fields for ordering: `id`., status: [str]=active # Return entities that match the specified status. Use a comma-separated list to specify multiple status values.}\n@returns(200) {data: [map], meta: map{request_id: str, pagination: map{per_page: int, next: str(uri), has_more: bool, estimated_total: int}}} # The request has succeeded.\n\n@endpoint POST /client-tokens\n@desc Create a client-side token\n@required {name: str # Short name of this client-side token. Typically unique and human-identifiable.}\n@optional {description: any}\n@returns(201) {data: map{id: any, token: any, name: str, description: any, status: any, revoked_at: any, created_at: any, updated_at: any}, meta: map{request_id: str}} # The request has succeeded and a new resource has been created as a result.\n@example_request {\"name\":\"Pricing page integration\",\"description\":\"Used to display prices and open checkout within our pricing page on our marketing domain.\"}\n\n@endpoint GET /client-tokens/{client_token_id}\n@desc Get a client-side token\n@required {client_token_id: str # Paddle ID of the client-side token entity.}\n@returns(200) {data: map{id: any, token: any, name: str, description: any, status: any, revoked_at: any, created_at: any, updated_at: any}, meta: map{request_id: str}} # The request has succeeded.\n\n@endpoint PATCH /client-tokens/{client_token_id}\n@desc Update a client-side token\n@required {client_token_id: str # Paddle ID of the client-side token entity., status: any=active}\n@returns(200) {data: map{id: any, token: any, name: str, description: any, status: any, revoked_at: any, created_at: any, updated_at: any}, meta: map{request_id: str}} # The request has succeeded.\n@example_request {\"status\":\"revoked\"}\n\n@endgroup\n\n@group customers\n@endpoint GET /customers\n@desc List customers\n@optional {id: [str] # Return only the IDs specified. Use a comma-separated list to get multiple entities., after: str # Return entities after the specified Paddle ID when working with paginated endpoints. Used in the `meta.pagination.next` URL in responses for list operations., per_page: int=50 # Set how many entities are returned per page. Paddle returns the maximum number of results if a number greater than the maximum is requested. Check `meta.pagination.per_page` in the response to see how many were returned.  Default: `50`; Maximum: `200`., email: [str] # Return entities that exactly match the specified email address. Use a comma-separated list to specify multiple email addresses. Recommended for precise matching of email addresses., order_by: str=id[DESC] # Order returned entities by the specified field and direction (`[ASC]` or `[DESC]`). For example, `?order_by=id[ASC]`.  Valid fields for ordering: `id`., status: [str]=active # Return entities that match the specified status. Use a comma-separated list to specify multiple status values., search: str # Return entities that match a search query. Searches `id`, `name`, and `email` fields. Use the `email` query parameter for precise matching of email addresses.}\n@returns(200) {data: [map], meta: map{request_id: str, pagination: map{per_page: int, next: str(uri), has_more: bool, estimated_total: int}}} # The request has succeeded.\n\n@endpoint POST /customers\n@desc Create a customer\n@required {email: any # Email address for this customer.}\n@optional {id: any, name: any # Full name of this customer. Required when creating transactions where `collection_mode` is `manual` (invoices)., marketing_consent: bool=false # Whether this customer opted into marketing from you. `false` unless customers check the marketing consent box when using Paddle Checkout. Set automatically by Paddle., custom_data: any # Your own structured key-value data., locale: str=en # Valid IETF BCP 47 short form locale tag. If omitted, defaults to `en`., import_meta: any # Import information for this entity. `null` if this entity is not imported.}\n@returns(201) {data: map{id: any, name: any, email: any, marketing_consent: bool, status: any, custom_data: any, locale: str, created_at: any, updated_at: any, import_meta: any}, meta: map{request_id: str}} # The request has succeeded and a new resource has been created as a result.\n@example_request {\"email\":\"jo@example.com\",\"name\":\"Jo Brown\"}\n\n@endpoint GET /customers/{customer_id}\n@desc Get a customer\n@required {customer_id: str # Paddle ID of the customer entity to work with.}\n@returns(200) {data: map{id: any, name: any, email: any, marketing_consent: bool, status: any, custom_data: any, locale: str, created_at: any, updated_at: any, import_meta: any}, meta: map{request_id: str}} # The request has succeeded.\n\n@endpoint PATCH /customers/{customer_id}\n@desc Update a customer\n@required {customer_id: str # Paddle ID of the customer entity to work with.}\n@optional {name: any # Full name of this customer. Required when creating transactions where `collection_mode` is `manual` (invoices)., email: any # Email address for this customer., marketing_consent: bool=false # Whether this customer opted into marketing from you. `false` unless customers check the marketing consent box when using Paddle Checkout. Set automatically by Paddle., status: str(active/archived) # Whether this entity can be used in Paddle., custom_data: any # Your own structured key-value data., locale: str=en # Valid IETF BCP 47 short form locale tag., import_meta: any # Import information for this entity. `null` if this entity is not imported.}\n@returns(200) {data: map{id: any, name: any, email: any, marketing_consent: bool, status: any, custom_data: any, locale: str, created_at: any, updated_at: any, import_meta: any}, meta: map{request_id: str}} # The request has succeeded.\n@example_request {\"name\":\"Jo Brown-Anderson\"}\n\n@endpoint GET /customers/{customer_id}/credit-balances\n@desc List credit balances for a customer\n@required {customer_id: str # Paddle ID of the customer entity to work with.}\n@optional {currency_code: [str] # Return entities that match the currency code. Use a comma-separated list to specify multiple currency codes.}\n@returns(200) {data: [map], meta: map{request_id: str}} # The request has succeeded.\n\n@endpoint POST /customers/{customer_id}/auth-token\n@desc Generate an authentication token for a customer\n@required {customer_id: str # Paddle ID of the customer entity to work with.}\n@returns(200) {data: map{customer_auth_token: str, expires_at: any}, meta: map{request_id: str}} # The request has succeeded.\n\n@endpoint POST /customers/{customer_id}/portal-sessions\n@desc Create a customer portal session\n@required {customer_id: str # Paddle ID of the customer entity to work with.}\n@optional {subscription_ids: [str] # List of subscriptions to create authenticated customer portal deep links for.}\n@returns(201) {data: map{id: any, customer_id: any, urls: any, created_at: any}, meta: map{request_id: str}} # The request has succeeded and a new resource has been created as a result.\n@example_request {\"subscription_ids\":[\"sub_01h04vsc0qhwtsbsxh3422wjs4\"]}\n\n@endgroup\n\n@group discount-groups\n@endpoint GET /discount-groups\n@desc List discount groups\n@optional {id: [str] # Return only the IDs specified. Use a comma-separated list to get multiple entities., after: str # Return entities after the specified Paddle ID when working with paginated endpoints. Used in the `meta.pagination.next` URL in responses for list operations., per_page: int=50 # Set how many entities are returned per page. Paddle returns the maximum number of results if a number greater than the maximum is requested. Check `meta.pagination.per_page` in the response to see how many were returned.  Default: `50`; Maximum: `200`., order_by: str=id[DESC] # Order returned entities by the specified field and direction (`[ASC]` or `[DESC]`). For example, `?order_by=id[ASC]`.  Valid fields for ordering: `created_at` and `id`.}\n@returns(200) {data: [map], meta: map{request_id: str, pagination: map{per_page: int, next: str(uri), has_more: bool, estimated_total: int}}} # The request has succeeded.\n\n@endpoint POST /discount-groups\n@desc Create a discount group\n@required {name: str # Name of this discount group, typically something short and memorable for categorization. Not shown to customers.}\n@returns(201) {data: map{id: any, name: str, status: str, created_at: any, updated_at: any, import_meta: any}, meta: map{request_id: str}} # The request has succeeded and a new resource has been created as a result.\n@example_request {\"name\":\"Black Friday 2024\"}\n\n@endpoint GET /discount-groups/{discount_group_id}\n@desc Get a discount group\n@required {discount_group_id: str # Paddle ID of the discount group entity to work with.}\n@returns(200) {data: map{id: any, name: str, status: str, created_at: any, updated_at: any, import_meta: any}, meta: map{request_id: str}} # The request has succeeded.\n\n@endpoint PATCH /discount-groups/{discount_group_id}\n@desc Update a discount group\n@required {discount_group_id: str # Paddle ID of the discount group entity to work with.}\n@optional {status: str(active/archived) # Whether this entity can be used in Paddle., name: str # Name of this discount group, typically something short and memorable for categorization. Not shown to customers.}\n@returns(200) {data: map{id: any, name: str, status: str, created_at: any, updated_at: any, import_meta: any}, meta: map{request_id: str}} # The request has succeeded.\n@example_request {\"name\":\"Cyber Monday 2025\"}\n\n@endgroup\n\n@group discounts\n@endpoint GET /discounts\n@desc List discounts\n@optional {id: [str] # Return only the IDs specified. Use a comma-separated list to get multiple entities., after: str # Return entities after the specified Paddle ID when working with paginated endpoints. Used in the `meta.pagination.next` URL in responses for list operations., per_page: int=50 # Set how many entities are returned per page. Paddle returns the maximum number of results if a number greater than the maximum is requested. Check `meta.pagination.per_page` in the response to see how many were returned.  Default: `50`; Maximum: `200`., include: [str] # Include related entities in the response. Use a comma-separated list to specify multiple entities., code: [str] # Return entities that match the discount code. Use a comma-separated list to specify multiple discount codes., order_by: str=id[DESC] # Order returned entities by the specified field and direction (`[ASC]` or `[DESC]`). For example, `?order_by=id[ASC]`.  Valid fields for ordering: `created_at` and `id`., status: [str]=active # Return entities that match the specified status. Use a comma-separated list to specify multiple status values., mode: str # Return entities that match the specified mode., discount_group_id: [str] # Return entities related to the specified discount group. Use a comma-separated list to specify multiple discount group IDs.}\n@returns(200) {data: [map], meta: map{request_id: str, pagination: map{per_page: int, next: str(uri), has_more: bool, estimated_total: int}}} # The request has succeeded.\n\n@endpoint POST /discounts\n@desc Create a discount\n@required {description: str # Short description for this discount for your reference. Not shown to customers., type: any # Type of discount. Determines how this discount impacts the checkout or transaction total., amount: str # Amount to discount by. For `percentage` discounts, must be an amount between `0.01` and `100`. For `flat` and `flat_per_seat` discounts, amount in the lowest denomination for a currency.}\n@optional {id: any, status: any=active, enabled_for_checkout: bool=true # Whether this discount can be redeemed by customers at checkout (`true`) or not (`false`)., code: any # Unique code that customers can use to redeem this discount at checkout. Use letters and numbers only, up to 32 characters. Not case-sensitive.  If omitted and `enabled_for_checkout` is `true`, Paddle generates a random 10-character code., mode: any=standard # Discount mode. Standard discounts are considered part of your catalog and are shown in the Paddle dashboard. If omitted, defaults to `standard`., currency_code: any # Supported three-letter ISO 4217 currency code. Required where discount type is `flat` or `flat_per_seat`., recur: bool=false # Whether this discount applies for multiple subscription billing periods (`true`) or not (`false`). If omitted, defaults to `false`., maximum_recurring_intervals: any # Number of subscription billing periods that this discount recurs for. Requires `recur`. `null` if this discount recurs forever.  Subscription renewals, midcycle changes, and one-time charges billed to a subscription aren't considered a redemption. `times_used` is not incremented in these cases., usage_limit: any # Maximum number of times this discount can be redeemed. This is an overall limit for this discount, rather than a per-customer limit. `null` if this discount can be redeemed an unlimited amount of times.  Paddle counts a usage as a redemption on a checkout, transaction, or the initial application against a subscription. Transactions created for subscription renewals, midcycle changes, and one-time charges aren't considered a redemption., restrict_to: any # Product or price IDs that this discount is for. When including a product ID, all prices for that product can be discounted. `null` if this discount applies to all products and prices., expires_at: any # RFC 3339 datetime string of when this discount expires. Discount can no longer be redeemed after this date has elapsed. `null` if this discount can be redeemed forever.  Expired discounts can't be redeemed against transactions or checkouts, but can be applied when updating subscriptions., custom_data: any # Your own structured key-value data., times_used: int # How many times this discount has been redeemed. Automatically incremented by Paddle.  Paddle counts a usage as a redemption on a checkout, transaction, or subscription. Transactions created for subscription renewals, midcycle changes, and one-time charges aren't considered a redemption., created_at: any, updated_at: any, discount_group_id: any # Paddle ID for the discount group related to this discount, prefixed with `dsg_`. `null` if not in a discount group., import_meta: any # Import information for this entity. `null` if this entity is not imported.}\n@returns(201) {data: map{id: any, status: any, description: str, enabled_for_checkout: bool, code: any, type: str, mode: any, amount: str, currency_code: any, recur: bool, maximum_recurring_intervals: any, usage_limit: any, restrict_to: any, expires_at: any, custom_data: any, times_used: int, discount_group_id: any, created_at: any, updated_at: any, import_meta: any}, meta: map{request_id: str}} # The request has succeeded and a new resource has been created as a result.\n@example_request {\"description\":\"All orders (10% off)\",\"type\":\"percentage\",\"amount\":\"10\",\"code\":\"BF10OFF\",\"enabled_for_checkout\":true,\"recur\":true,\"maximum_recurring_intervals\":3,\"expires_at\":\"2024-12-03T00:00:00Z\",\"discount_group_id\":\"dsg_01js2gqehzccfkywgx1jk2mtsp\"}\n\n@endpoint GET /discounts/{discount_id}\n@desc Get a discount\n@required {discount_id: str # Paddle ID of the discount entity to work with.}\n@optional {include: [str] # Include related entities in the response. Use a comma-separated list to specify multiple entities.}\n@returns(200) {data: map{id: any, status: any, description: str, enabled_for_checkout: bool, code: any, type: str, mode: any, amount: str, currency_code: any, recur: bool, maximum_recurring_intervals: any, usage_limit: any, restrict_to: any, expires_at: any, custom_data: any, times_used: int, discount_group_id: any, created_at: any, updated_at: any, import_meta: any, discount_group: any}, meta: map{request_id: str}} # The request has succeeded.\n\n@endpoint PATCH /discounts/{discount_id}\n@desc Update a discount\n@required {discount_id: str # Paddle ID of the discount entity to work with.}\n@optional {id: any, status: str(active/archived) # Whether this entity can be used in Paddle., description: str # Short description for this discount for your reference. Not shown to customers., enabled_for_checkout: bool=true # Whether this discount can be redeemed by customers at checkout (`true`) or not (`false`)., code: any # Unique code that customers can use to redeem this discount at checkout. Not case-sensitive., type: any # Type of discount. Determines how this discount impacts the checkout or transaction total., mode: any=standard # Discount mode. Standard discounts are considered part of your catalog and are shown in the Paddle dashboard., amount: str # Amount to discount by. For `percentage` discounts, must be an amount between `0.01` and `100`. For `flat` and `flat_per_seat` discounts, amount in the lowest denomination for a currency., currency_code: any # Supported three-letter ISO 4217 currency code. Required where discount type is `flat` or `flat_per_seat`., recur: bool=false # Whether this discount applies for multiple subscription billing periods (`true`) or not (`false`)., maximum_recurring_intervals: any # Number of subscription billing periods that this discount recurs for. Requires `recur`. `null` if this discount recurs forever.  Subscription renewals, midcycle changes, and one-time charges billed to a subscription aren't considered a redemption. `times_used` is not incremented in these cases., usage_limit: any # Maximum number of times this discount can be redeemed. This is an overall limit for this discount, rather than a per-customer limit. `null` if this discount can be redeemed an unlimited amount of times.  Paddle counts a usage as a redemption on a checkout, transaction, or the initial application against a subscription. Transactions created for subscription renewals, midcycle changes, and one-time charges aren't considered a redemption., restrict_to: any # Product or price IDs that this discount is for. When including a product ID, all prices for that product can be discounted. `null` if this discount applies to all products and prices., expires_at: any # RFC 3339 datetime string of when this discount expires. Discount can no longer be redeemed after this date has elapsed. `null` if this discount can be redeemed forever.  Expired discounts can't be redeemed against transactions or checkouts, but can be applied when updating subscriptions., custom_data: any # Your own structured key-value data., times_used: int # How many times this discount has been redeemed. Automatically incremented by Paddle.  Paddle counts a usage as a redemption on a checkout, transaction, or subscription. Transactions created for subscription renewals, midcycle changes, and one-time charges aren't considered a redemption., created_at: any, updated_at: any, discount_group_id: any # Paddle ID for the discount group related to this discount, prefixed with `dsg_`. `null` if not in a discount group., import_meta: any # Import information for this entity. `null` if this entity is not imported.}\n@returns(200) {data: map{id: any, status: any, description: str, enabled_for_checkout: bool, code: any, type: str, mode: any, amount: str, currency_code: any, recur: bool, maximum_recurring_intervals: any, usage_limit: any, restrict_to: any, expires_at: any, custom_data: any, times_used: int, discount_group_id: any, created_at: any, updated_at: any, import_meta: any}, meta: map{request_id: str}} # The request has succeeded.\n@example_request {\"code\":\"NEWCODE\",\"restrict_to\":[\"pro_01gsz4t5hdjse780zja8vvr7jg\",\"pro_01gsz4s0w61y0pp88528f1wvvb\"],\"discount_group_id\":\"dsg_01js2gqehzccfkywgx1jk2mtsp\"}\n\n@endgroup\n\n@group event-types\n@endpoint GET /event-types\n@desc List events types\n@returns(200) {data: [map], meta: map{request_id: str}} # The request has succeeded.\n\n@endgroup\n\n@group events\n@endpoint GET /events\n@desc List events\n@optional {after: str # Return entities after the specified Paddle ID when working with paginated endpoints. Used in the `meta.pagination.next` URL in responses for list operations., per_page: int=50 # Set how many entities are returned per page. Paddle returns the maximum number of results if a number greater than the maximum is requested. Check `meta.pagination.per_page` in the response to see how many were returned.  Default: `50`; Maximum: `200`., order_by: str=id[DESC] # Order returned entities by the specified field and direction (`[ASC]` or `[DESC]`). For example, `?order_by=id[ASC]`.  Valid fields for ordering: `id` (for `event_id`)., event_type: [str] # Return events that match the specified event type. Use a comma-separated list to specify multiple event types.}\n@returns(200) {data: [map], meta: map{request_id: str, pagination: map{per_page: int, next: str(uri), has_more: bool, estimated_total: int}}} # The request has succeeded.\n\n@endgroup\n\n@group ips\n@endpoint GET /ips\n@desc Get Paddle IP addresses\n@returns(200) {data: map{ipv4_cidrs: [str]}, meta: map{request_id: str}} # The request has succeeded.\n\n@endgroup\n\n@group notification-settings\n@endpoint GET /notification-settings\n@desc List notification settings\n@optional {after: str # Return entities after the specified Paddle ID when working with paginated endpoints. Used in the `meta.pagination.next` URL in responses for list operations., per_page: int=200 # Set how many entities are returned per page. Paddle returns the maximum number of results if a number greater than the maximum is requested. Check `meta.pagination.per_page` in the response to see how many were returned.  Default: `200`; Maximum: `200`., order_by: str=id[DESC] # Order returned entities by the specified field and direction (`[ASC]` or `[DESC]`). For example, `?order_by=id[ASC]`.  Valid fields for ordering: `id`., active: bool # Determine whether returned entities are active (`true`) or not (`false`)., traffic_source: str # Return entities that match the specified traffic source.}\n@returns(200) {data: [map], meta: map{request_id: str, pagination: map{per_page: int, next: str(uri), has_more: bool, estimated_total: int}}} # The request has succeeded.\n\n@endpoint POST /notification-settings\n@desc Create a notification setting\n@required {description: str # Short description for this notification destination. Shown in the Paddle Dashboard., type: any # Where notifications should be sent for this destination., destination: str # Webhook endpoint URL or email address., subscribed_events: [str] # Subscribed events for this notification destination. When creating or updating a notification destination, pass an array of event type names only. Paddle returns the complete event type object.}\n@optional {id: any, active: bool=true # Whether Paddle should try to deliver events to this notification destination., api_version: int # API version that returned objects for events should conform to. Must be a valid version of the Paddle API. Can't be a version older than your account default. If omitted, defaults to your account default version., include_sensitive_fields: bool=false # Whether potentially sensitive fields should be sent to this notification destination. If omitted, defaults to `false`., endpoint_secret_key: str # Webhook destination secret key, prefixed with `pdl_ntfset_`. Used for signature verification., traffic_source: any=platform # Whether Paddle should deliver real platform events, simulation events or both to this notification destination. If omitted, defaults to `platform`.}\n@returns(201) {data: map{id: any, description: str, type: any, destination: str, active: bool, api_version: int, include_sensitive_fields: bool, subscribed_events: [map], endpoint_secret_key: str, traffic_source: any}, meta: map{request_id: str}} # The request has succeeded and a new resource has been created as a result.\n@example_request {\"description\":\"Slack notifications\",\"type\":\"url\",\"destination\":\"https://hooks.slack.com/example\",\"api_version\":1,\"traffic_source\":\"all\",\"subscribed_events\":[\"transaction.billed\",\"transaction.canceled\",\"transaction.completed\",\"transaction.created\",\"transaction.payment_failed\",\"transaction.ready\",\"transaction.updated\",\"subscription.activated\",\"subscription.created\",\"subscription.past_due\",\"subscription.paused\",\"subscription.resumed\",\"subscription.trialing\",\"subscription.updated\"]}\n\n@endpoint GET /notification-settings/{notification_setting_id}\n@desc Get a notification setting\n@required {notification_setting_id: str # Paddle ID of the notification setting entity (notification destination) to work with.}\n@returns(200) {data: map{id: any, description: str, type: any, destination: str, active: bool, api_version: int, include_sensitive_fields: bool, subscribed_events: [map], endpoint_secret_key: str, traffic_source: any}, meta: map{request_id: str}} # The request has succeeded.\n\n@endpoint PATCH /notification-settings/{notification_setting_id}\n@desc Update a notification setting\n@required {notification_setting_id: str # Paddle ID of the notification setting entity (notification destination) to work with.}\n@optional {description: str # Short description for this notification destination. Shown in the Paddle Dashboard., destination: str # Webhook endpoint URL or email address., active: bool=true # Whether Paddle should try to deliver events to this notification destination., api_version: int # API version that returned objects for events should conform to. Must be a valid version of the Paddle API. Can't be a version older than your account default. Defaults to your account default if omitted., include_sensitive_fields: bool=false # Whether potentially sensitive fields should be sent to this notification destination., subscribed_events: [str] # Subscribed events for this notification destination. When creating or updating a notification destination, pass an array of event type names only. Paddle returns the complete event type object., traffic_source: any # Whether Paddle should deliver real platform events, simulation events or both to this notification destination.}\n@returns(200) {data: map{id: any, description: str, type: any, destination: str, active: bool, api_version: int, include_sensitive_fields: bool, subscribed_events: [map], endpoint_secret_key: str, traffic_source: any}, meta: map{request_id: str}} # The request has succeeded.\n@example_request {\"description\":\"Slack notifications (old)\",\"active\":false}\n\n@endpoint DELETE /notification-settings/{notification_setting_id}\n@desc Delete a notification setting\n@required {notification_setting_id: str # Paddle ID of the notification setting entity (notification destination) to work with.}\n@returns(204) There is no content to send for this request, but the headers may be useful.\n\n@endgroup\n\n@group notifications\n@endpoint GET /notifications\n@desc List notifications\n@optional {after: str # Return entities after the specified Paddle ID when working with paginated endpoints. Used in the `meta.pagination.next` URL in responses for list operations., per_page: int=50 # Set how many entities are returned per page. Paddle returns the maximum number of results if a number greater than the maximum is requested. Check `meta.pagination.per_page` in the response to see how many were returned.  Default: `50`; Maximum: `200`., notification_setting_id: [str] # Return entities related to the specified notification destination. Use a comma-separated list to specify multiple notification destination IDs., order_by: str=id[DESC] # Order returned entities by the specified field and direction (`[ASC]` or `[DESC]`). For example, `?order_by=id[ASC]`.  Valid fields for ordering: `id`., search: str # Return entities that match a search query. Searches `id` and `type` fields., status: [str] # Return entities that match the specified status. Use a comma-separated list to specify multiple status values., filter: str # Return entities that contain the Paddle ID specified. Pass a transaction, customer, or subscription ID., to: str # Return entities up to a specific time. Pass an RFC 3339 datetime string., from: str # Return entities from a specific time. Pass an RFC 3339 datetime string.}\n@returns(200) {data: [map], meta: map{request_id: str, pagination: map{per_page: int, next: str(uri), has_more: bool, estimated_total: int}}} # The request has succeeded.\n\n@endpoint GET /notifications/{notification_id}\n@desc Get a notification\n@required {notification_id: str # Paddle ID of the notification entity to work with.}\n@returns(200) {data: map{id: any, type: any, status: any, payload: any, occurred_at: any, delivered_at: any, replayed_at: any, origin: any, last_attempt_at: any, retry_at: any, times_attempted: int, notification_setting_id: any}, meta: map{request_id: str}} # The request has succeeded.\n\n@endpoint GET /notifications/{notification_id}/logs\n@desc List logs for a notification\n@required {notification_id: str # Paddle ID of the notification entity to work with.}\n@optional {after: str # Return entities after the specified Paddle ID when working with paginated endpoints. Used in the `meta.pagination.next` URL in responses for list operations., per_page: int=50 # Set how many entities are returned per page. Paddle returns the maximum number of results if a number greater than the maximum is requested. Check `meta.pagination.per_page` in the response to see how many were returned.  Default: `50`; Maximum: `200`.}\n@returns(200) {data: [map], meta: map{request_id: str, pagination: map{per_page: int, next: str(uri), has_more: bool, estimated_total: int}}} # The request has succeeded.\n\n@endpoint POST /notifications/{notification_id}/replay\n@desc Replay a notification\n@required {notification_id: str # Paddle ID of the notification entity to work with.}\n@returns(202) {data: map{notification_id: str}, meta: map{request_id: str}} # The request has been accepted for processing, but processing has not yet completed.\n\n@endgroup\n\n@group customers\n@endpoint GET /customers/{customer_id}/payment-methods\n@desc List payment methods for a customer\n@required {customer_id: str # Paddle ID of the customer entity to work with.}\n@optional {after: str # Return entities after the specified Paddle ID when working with paginated endpoints. Used in the `meta.pagination.next` URL in responses for list operations., per_page: int=50 # Set how many entities are returned per page. Paddle returns the maximum number of results if a number greater than the maximum is requested. Check `meta.pagination.per_page` in the response to see how many were returned.  Default: `50`; Maximum: `200`., address_id: [str] # Return entities related to the specified address. Use a comma-separated list to specify multiple address IDs., order_by: str=id[DESC] # Order returned entities by the specified field and direction (`[ASC]` or `[DESC]`). For example, `?order_by=id[ASC]`.  Valid fields for ordering: `id`., supports_checkout: bool # Return entities that support being presented at checkout (`true`) or not (`false`).}\n@returns(200) {data: [map], meta: map{request_id: str, pagination: map{per_page: int, next: str(uri), has_more: bool, estimated_total: int}}} # The request has succeeded.\n\n@endpoint GET /customers/{customer_id}/payment-methods/{payment_method_id}\n@desc Get a payment method for a customer\n@required {customer_id: str # Paddle ID of the customer entity to work with., payment_method_id: str # Paddle ID of the payment method entity to work with.}\n@returns(200) {data: map{id: any, customer_id: any, address_id: any, type: any, card: any, paypal: any, underlying_details: any, south_korea_local_card: any, origin: any, saved_at: any, updated_at: any}, meta: map{request_id: str}} # The request has succeeded.\n\n@endpoint DELETE /customers/{customer_id}/payment-methods/{payment_method_id}\n@desc Delete a payment method for a customer\n@required {customer_id: str # Paddle ID of the customer entity to work with., payment_method_id: str # Paddle ID of the payment method entity to work with.}\n@returns(204) There is no content to send for this request, but the headers may be useful.\n\n@endgroup\n\n@group prices\n@endpoint GET /prices\n@desc List prices\n@optional {id: [str] # Return only the IDs specified. Use a comma-separated list to get multiple entities., after: str # Return entities after the specified Paddle ID when working with paginated endpoints. Used in the `meta.pagination.next` URL in responses for list operations., per_page: int=50 # Set how many entities are returned per page. Paddle returns the maximum number of results if a number greater than the maximum is requested. Check `meta.pagination.per_page` in the response to see how many were returned.  Default: `50`; Maximum: `200`., include: [str] # Include related entities in the response., order_by: str=id[DESC] # Order returned entities by the specified field and direction (`[ASC]` or `[DESC]`). For example, `?order_by=id[ASC]`.  Valid fields for ordering: `billing_cycle.frequency`, `billing_cycle.interval`, `id`, `product_id`, `quantity.maximum`, `quantity.minimum`, `status`, `tax_mode`, `unit_price.amount`, and `unit_price.currency_code`., product_id: [str] # Return entities related to the specified product. Use a comma-separated list to specify multiple product IDs., status: [str]=active # Return entities that match the specified status. Use a comma-separated list to specify multiple status values., recurring: bool # Determine whether returned entities are for recurring prices (`true`) or one-time prices (`false`)., type: str # Return items that match the specified type.}\n@returns(200) {data: [map], meta: map{request_id: str, pagination: map{per_page: int, next: str(uri), has_more: bool, estimated_total: int}}} # The request has succeeded.\n\n@endpoint POST /prices\n@desc Create a price\n@required {description: str # Internal description for this price, not shown to customers. Typically notes for your team., product_id: any # Paddle ID for the product that this price is for, prefixed with `pro_`., unit_price: any # Base price. This price applies to all customers, except for customers located in countries where you have `unit_price_overrides`.}\n@optional {id: any, type: any=standard # Type of item. Standard items are considered part of your catalog and are shown in the Paddle dashboard. If omitted, defaults to `standard`., name: any, billing_cycle: any # How often this price should be charged. `null` if price is non-recurring (one-time). If omitted, defaults to `null`., trial_period: any # 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`. If omitted, defaults to `null`., tax_mode: any=account_setting # How tax is calculated for this price. If omitted, defaults to `account_setting`., unit_price_overrides: [map{country_codes!: [any], unit_price!: any}] # 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: any # Limits on how many times the related product can be purchased at this price. Useful for discount campaigns. If omitted, defaults to 1-100., custom_data: any # Your own structured key-value data., import_meta: any # Import information for this entity. `null` if this entity is not imported.}\n@returns(201) {data: map{id: any, product_id: any, description: str, type: any, name: any, billing_cycle: any, trial_period: any, tax_mode: any, unit_price: any, unit_price_overrides: [map], quantity: any, status: any, custom_data: any, import_meta: any, created_at: any, updated_at: any}, meta: map{request_id: str}} # The request has succeeded and a new resource has been created as a result.\n@example_request {\"description\":\"Monthly (per seat) with 14 day trial\",\"name\":\"Monthly (per seat)\",\"product_id\":\"pro_01htz88xpr0mm7b3ta2pjkr7w2\",\"unit_price\":{\"amount\":\"500\",\"currency_code\":\"USD\"},\"billing_cycle\":{\"interval\":\"month\",\"frequency\":1},\"trial_period\":{\"interval\":\"day\",\"frequency\":14},\"tax_mode\":\"account_setting\"}\n\n@endpoint GET /prices/{price_id}\n@desc Get a price\n@required {price_id: str # Paddle ID of the price entity to work with.}\n@optional {include: [str] # Include related entities in the response.}\n@returns(200) {data: map{id: any, product_id: any, description: str, type: any, name: any, billing_cycle: any, trial_period: any, tax_mode: any, unit_price: any, unit_price_overrides: [map], quantity: any, status: any, custom_data: any, import_meta: any, created_at: any, updated_at: any, product: any}, meta: map{request_id: str}} # The request has succeeded.\n\n@endpoint PATCH /prices/{price_id}\n@desc Update a price\n@required {price_id: str # Paddle ID of the price entity to work with.}\n@optional {description: str # Internal description for this price, not shown to customers. Typically notes for your team., type: any=standard, name: any, billing_cycle: any # How often this price should be charged. `null` if price is non-recurring (one-time)., trial_period: any # 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: any=account_setting, unit_price: any # Base price. This price applies to all customers, except for customers located in countries where you have `unit_price_overrides`., unit_price_overrides: [map{country_codes!: [any], unit_price!: any}] # 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: any # Limits on how many times the related product can be purchased at this price. Useful for discount campaigns., status: str(active/archived) # Whether this entity can be used in Paddle., custom_data: any # Your own structured key-value data.}\n@returns(200) {data: map{id: any, product_id: any, description: str, type: any, name: any, billing_cycle: any, trial_period: any, tax_mode: any, unit_price: any, unit_price_overrides: [map], quantity: any, status: any, custom_data: any, import_meta: any, created_at: any, updated_at: any}, meta: map{request_id: str}} # The request has succeeded.\n@example_request {\"unit_price\":{\"amount\":\"500\",\"currency_code\":\"USD\"},\"unit_price_overrides\":[{\"country_codes\":[\"IE\",\"FR\",\"DE\"],\"unit_price\":{\"amount\":\"700\",\"currency_code\":\"EUR\"}},{\"country_codes\":[\"GB\"],\"unit_price\":{\"amount\":\"600\",\"currency_code\":\"GBP\"}}],\"billing_cycle\":{\"interval\":\"month\",\"frequency\":1}}\n\n@endgroup\n\n@group pricing-preview\n@endpoint POST /pricing-preview\n@desc Preview prices\n@required {items: [map{price_id: any, quantity!: int}] # List of items to preview price calculations for.}\n@optional {customer_id: any # Paddle ID of the customer that this preview is for, prefixed with `ctm_`., address_id: any # Paddle ID of the address that this preview is for, prefixed with `add_`. Send one of `address_id`, `customer_ip_address`, or the `address` object when previewing., business_id: any # Paddle ID of the business that this preview is for, prefixed with `biz_`., currency_code: any # Supported three-letter ISO 4217 currency code., discount_id: any # Paddle ID of the discount applied to this preview, prefixed with `dsc_`., address: any # Address for this preview. Send one of `address_id`, `customer_ip_address`, or the `address` object when previewing., customer_ip_address: any # IP address for this transaction preview. Send one of `address_id`, `customer_ip_address`, or the `address` object when previewing.}\n@returns(200) {data: map{customer_id: any, address_id: any, business_id: any, currency_code: any, discount_id: any, address: any, customer_ip_address: any, details: any, available_payment_methods: [str]}, meta: map{request_id: str}} # The request has succeeded.\n@example_request {\"items\":[{\"quantity\":20,\"price_id\":\"pri_01gsz8z1q1n00f12qt82y31smh\"},{\"quantity\":1,\"price_id\":\"pri_01h1vjfevh5etwq3rb416a23h2\"}],\"currency_code\":\"USD\",\"discount_id\":\"dsc_01gtgztp8fpchantd5g1wrksa3\",\"customer_ip_address\":\"34.232.58.13\"}\n\n@endgroup\n\n@group products\n@endpoint GET /products\n@desc List products\n@optional {id: [str] # Return only the IDs specified. Use a comma-separated list to get multiple entities., after: str # Return entities after the specified Paddle ID when working with paginated endpoints. Used in the `meta.pagination.next` URL in responses for list operations., per_page: int=50 # Set how many entities are returned per page. Paddle returns the maximum number of results if a number greater than the maximum is requested. Check `meta.pagination.per_page` in the response to see how many were returned.  Default: `50`; Maximum: `200`., include: [str] # Include related entities in the response. Use a comma-separated list to specify multiple entities., order_by: str=id[DESC] # Order returned entities by the specified field and direction (`[ASC]` or `[DESC]`). For example, `?order_by=id[ASC]`.  Valid fields for ordering: `created_at`, `custom_data`, `description`, `id`, `image_url`, `name`, `status`, `tax_category`, and `updated_at`., status: [str]=active # Return entities that match the specified status. Use a comma-separated list to specify multiple status values., tax_category: [str] # Return entities that match the specified tax category. Use a comma-separated list to specify multiple tax categories., type: str # Return items that match the specified type.}\n@returns(200) {data: [map], meta: map{request_id: str, pagination: map{per_page: int, next: str(uri), has_more: bool, estimated_total: int}}} # The request has succeeded.\n\n@endpoint POST /products\n@desc Create a product\n@required {name: str # Name of this product., tax_category: str(digital-goods/ebooks/implementation-services/professional-services/saas/software-programming-services/standard/training-services/website-hosting) # Tax category for this product. Used for charging the correct rate of tax. Selected tax category must be enabled on your Paddle account.}\n@optional {id: any, description: any # Short description for this product., type: any=standard # Type of item. Standard items are considered part of your catalog and are shown in the Paddle dashboard. If omitted, defaults to `standard`., image_url: any # Image for this product. Included in the checkout and on some customer documents., custom_data: any # Your own structured key-value data., import_meta: any # Import information for this entity. `null` if this entity is not imported.}\n@returns(201) {data: map{id: any, name: str, description: any, type: any, tax_category: str, image_url: any, custom_data: any, status: any, import_meta: any, created_at: any, updated_at: any}, meta: map{request_id: str}} # The request has succeeded and a new resource has been created as a result.\n@example_request {\"name\":\"AeroEdit Student\",\"tax_category\":\"standard\",\"description\":\"Essential tools for student pilots to manage flight logs, analyze performance, and plan routes, and ensure compliance. Valid student pilot certificate from the FAA required.\",\"image_url\":\"https://paddle.s3.amazonaws.com/user/165798/bT1XUOJAQhOUxGs83cbk_pro.png\",\"custom_data\":{\"features\":{\"aircraft_performance\":true,\"compliance_monitoring\":false,\"flight_log_management\":true,\"payment_by_invoice\":false,\"route_planning\":true,\"sso\":false},\"suggested_addons\":[\"pro_01h1vjes1y163xfj1rh1tkfb65\",\"pro_01gsz97mq9pa4fkyy0wqenepkz\"],\"upgrade_description\":null}}\n\n@endpoint GET /products/{product_id}\n@desc Get a product\n@required {product_id: str # Paddle ID of the product entity to work with.}\n@optional {include: [str] # Include related entities in the response. Use a comma-separated list to specify multiple entities.}\n@returns(200) {data: map{id: any, name: str, description: any, type: any, tax_category: str, image_url: any, custom_data: any, status: any, import_meta: any, created_at: any, updated_at: any, prices: [map]}, meta: map{request_id: str}} # The request has succeeded.\n\n@endpoint PATCH /products/{product_id}\n@desc Update a product\n@required {product_id: str # Paddle ID of the product entity to work with.}\n@optional {name: str # Name of this product., description: any # Short description for this product., type: any=standard, tax_category: str(digital-goods/ebooks/implementation-services/professional-services/saas/software-programming-services/standard/training-services/website-hosting) # Tax category for this product. Used for charging the correct rate of tax. Selected tax category must be enabled on your Paddle account., image_url: any # Image for this product. Included in the checkout and on some customer documents., custom_data: any # Your own structured key-value data., status: str(active/archived) # Whether this entity can be used in Paddle.}\n@returns(200) {data: map{id: any, name: str, description: any, type: any, tax_category: str, image_url: any, custom_data: any, status: any, import_meta: any, created_at: any, updated_at: any}, meta: map{request_id: str}} # The request has succeeded.\n@example_request {\"name\":\"AeroEdit for learner pilots\"}\n\n@endgroup\n\n@group reports\n@endpoint GET /reports\n@desc List reports\n@optional {after: str # Return entities after the specified Paddle ID when working with paginated endpoints. Used in the `meta.pagination.next` URL in responses for list operations., per_page: int=50 # Set how many entities are returned per page. Paddle returns the maximum number of results if a number greater than the maximum is requested. Check `meta.pagination.per_page` in the response to see how many were returned.  Default: `50`; Maximum: `200`., order_by: str=id[DESC] # Order returned entities by the specified field and direction (`[ASC]` or `[DESC]`). For example, `?order_by=id[ASC]`.  Valid fields for ordering: `id`., status: [str] # Return entities that match the specified status. Use a comma-separated list to specify multiple status values.}\n@returns(200) {data: [any], meta: map{request_id: str, pagination: map{per_page: int, next: str(uri), has_more: bool, estimated_total: int}}} # The request has succeeded.\n\n@endpoint POST /reports\n@desc Create a report\n@returns(201) {data: any, meta: map{request_id: str}} # The request has succeeded and a new resource has been created as a result.\n@example_request {\"type\":\"transactions\",\"filters\":[{\"name\":\"collection_mode\",\"value\":[\"manual\"]},{\"name\":\"updated_at\",\"value\":\"2024-04-15\",\"operator\":\"lt\"},{\"name\":\"updated_at\",\"value\":\"2024-01-01\",\"operator\":\"gte\"}]}\n\n@endpoint GET /reports/{report_id}\n@desc Get a report\n@required {report_id: str # Paddle ID of the report entity.}\n@returns(200) {data: any, meta: map{request_id: str}} # The request has succeeded.\n\n@endpoint GET /reports/{report_id}/download-url\n@desc Get a CSV file for a report\n@required {report_id: str # Paddle ID of the report entity.}\n@returns(200) {meta: map{request_id: str}, data: map{url: str}} # The request has succeeded.\n\n@endgroup\n\n@group simulation-types\n@endpoint GET /simulation-types\n@desc List simulation types\n@returns(200) {data: [map], meta: map{request_id: str}} # The request has succeeded.\n\n@endgroup\n\n@group simulations\n@endpoint GET /simulations\n@desc List simulations\n@optional {id: [str] # Return only the IDs specified. Use a comma-separated list to get multiple entities., after: str # Return entities after the specified Paddle ID when working with paginated endpoints. Used in the `meta.pagination.next` URL in responses for list operations., per_page: int=50 # Set how many entities are returned per page. Paddle returns the maximum number of results if a number greater than the maximum is requested. Check `meta.pagination.per_page` in the response to see how many were returned.  Default: `50`; Maximum: `200`., notification_setting_id: [str] # Return entities related to the specified notification destination. Use a comma-separated list to specify multiple notification destination IDs., order_by: str=id[DESC] # Order returned entities by the specified field and direction (`[ASC]` or `[DESC]`). For example, `?order_by=id[ASC]`.  Valid fields for ordering: `id`., status: [str]=active # Return entities that match the specified status. Use a comma-separated list to specify multiple status values.}\n@returns(200) {data: [any], meta: map{request_id: str, pagination: map{per_page: int, next: str(uri), has_more: bool, estimated_total: int}}} # The request has succeeded.\n\n@endpoint POST /simulations\n@desc Create a simulation\n@returns(201) {data: any, meta: map{request_id: str}} # The request has succeeded and a new resource has been created as a result.\n@example_request {\"notification_setting_id\":\"ntfset_01j82d983j814ypzx7m1fw2jpz\",\"name\":\"Create a failed subscription renewal simulation with subscription ID\",\"type\":\"subscription_renewal\",\"config\":{\"subscription_renewal\":{\"entities\":{\"subscription_id\":\"sub_01h04vsc0qhwtsbsxh3422wjs4\"},\"options\":{\"payment_outcome\":\"failed\",\"dunning_exhausted_action\":\"subscription_canceled\"}}}}\n\n@endpoint GET /simulations/{simulation_id}\n@desc Get a simulation\n@required {simulation_id: str # Paddle ID of the simulation entity to work with.}\n@returns(200) {data: any, meta: map{request_id: str}} # The request has succeeded.\n\n@endpoint PATCH /simulations/{simulation_id}\n@desc Update a simulation\n@required {simulation_id: str # Paddle ID of the simulation entity to work with.}\n@returns(200) {data: any, meta: map{request_id: str}} # The request has succeeded.\n@example_request {\"name\":\"Refund approved\",\"type\":\"adjustment.updated\",\"payload\":{\"id\":\"adj_01hvgf2s84dr6reszzg29zbvcm\",\"action\":\"refund\",\"transaction_id\":\"txn_01hvcc93znj3mpqt1tenkjb04y\",\"subscription_id\":\"sub_01hvccbx32q2gb40sqx7n42430\",\"customer_id\":\"ctm_01hrffh7gvp29kc7xahm8wddwa\",\"reason\":\"error\",\"credit_applied_to_balance\":null,\"currency_code\":\"USD\",\"status\":\"approved\",\"items\":[{\"id\":\"adjitm_01hvgf2s84dr6reszzg2gx70gj\",\"item_id\":\"txnitm_01hvcc94b7qgz60qmrqmbm19zw\",\"type\":\"partial\",\"amount\":\"100\",\"proration\":null,\"totals\":{\"subtotal\":\"92\",\"tax\":\"8\",\"total\":\"100\"}}],\"totals\":{\"subtotal\":\"92\",\"tax\":\"8\",\"total\":\"100\",\"fee\":\"5\",\"earnings\":\"87\",\"currency_code\":\"USD\"},\"payout_totals\":{\"subtotal\":\"92\",\"tax\":\"8\",\"total\":\"100\",\"fee\":\"5\",\"earnings\":\"87\",\"currency_code\":\"USD\"},\"created_at\":\"2024-04-15T08:48:20.239695Z\",\"updated_at\":\"2024-04-15T08:48:20.239695Z\"}}\n\n@endpoint GET /simulations/{simulation_id}/runs\n@desc List runs for a simulation\n@required {simulation_id: str # Paddle ID of the simulation entity to work with.}\n@optional {id: [str] # Return only the IDs specified. Use a comma-separated list to get multiple entities., after: str # Return entities after the specified Paddle ID when working with paginated endpoints. Used in the `meta.pagination.next` URL in responses for list operations., per_page: int=50 # Set how many entities are returned per page. Paddle returns the maximum number of results if a number greater than the maximum is requested. Check `meta.pagination.per_page` in the response to see how many were returned.  Default: `50`; Maximum: `200`., include: [str] # Include related entities in the response., order_by: str=id[DESC] # Order returned entities by the specified field and direction (`[ASC]` or `[DESC]`). For example, `?order_by=id[ASC]`.  Valid fields for ordering: `id`.}\n@returns(200) {data: [any], meta: map{request_id: str, pagination: map{per_page: int, next: str(uri), has_more: bool, estimated_total: int}}} # The request has succeeded.\n\n@endpoint POST /simulations/{simulation_id}/runs\n@desc Create a run for a simulation\n@required {simulation_id: str # Paddle ID of the simulation entity to work with.}\n@returns(201) {data: any, meta: map{request_id: str}} # The request has succeeded and a new resource has been created as a result.\n\n@endpoint GET /simulations/{simulation_id}/runs/{simulation_run_id}\n@desc Get a run for a simulation\n@required {simulation_id: str # Paddle ID of the simulation entity to work with., simulation_run_id: str # Paddle ID of the simulation run entity to work with.}\n@optional {include: [str] # Include related entities in the response.}\n@returns(200) {data: any, meta: map{request_id: str}} # The request has succeeded.\n\n@endpoint GET /simulations/{simulation_id}/runs/{simulation_run_id}/events\n@desc List events for a simulation run\n@required {simulation_id: str # Paddle ID of the simulation entity to work with., simulation_run_id: str # Paddle ID of the simulation run entity to work with.}\n@optional {id: [str] # Return only the IDs specified. Use a comma-separated list to get multiple entities., after: str # Return entities after the specified Paddle ID when working with paginated endpoints. Used in the `meta.pagination.next` URL in responses for list operations., per_page: int=50 # Set how many entities are returned per page. Paddle returns the maximum number of results if a number greater than the maximum is requested. Check `meta.pagination.per_page` in the response to see how many were returned.  Default: `50`; Maximum: `200`., order_by: str=id[DESC] # Order returned entities by the specified field and direction (`[ASC]` or `[DESC]`). For example, `?order_by=id[ASC]`.  Valid fields for ordering: `id`.}\n@returns(200) {data: [map], meta: map{request_id: str, pagination: map{per_page: int, next: str(uri), has_more: bool, estimated_total: int}}} # The request has succeeded.\n\n@endpoint GET /simulations/{simulation_id}/runs/{simulation_run_id}/events/{simulation_event_id}\n@desc Get an event for a simulation run\n@required {simulation_id: str # Paddle ID of the simulation entity to work with., simulation_run_id: str # Paddle ID of the simulation run entity to work with., simulation_event_id: str # Paddle ID of the simulation event entity to work with.}\n@returns(200) {data: map{id: any, status: any, event_type: any, payload: any, request: any, response: any, created_at: any, updated_at: any}, meta: map{request_id: str}} # The request has succeeded.\n\n@endpoint POST /simulations/{simulation_id}/runs/{simulation_run_id}/events/{simulation_event_id}/replay\n@desc Replay an event for a simulation run\n@required {simulation_id: str # Paddle ID of the simulation entity to work with., simulation_run_id: str # Paddle ID of the simulation run entity to work with., simulation_event_id: str # Paddle ID of the simulation event entity to work with.}\n@returns(202) {data: map{id: any, status: any, event_type: any, payload: any, request: any, response: any, created_at: any, updated_at: any}, meta: map{request_id: str}} # The request has been accepted for processing, but processing has not yet completed.\n\n@endgroup\n\n@group subscriptions\n@endpoint GET /subscriptions\n@desc List subscriptions\n@optional {id: [str] # Return only the IDs specified. Use a comma-separated list to get multiple entities., after: str # Return entities after the specified Paddle ID when working with paginated endpoints. Used in the `meta.pagination.next` URL in responses for list operations., per_page: int=50 # Set how many entities are returned per page. Paddle returns the maximum number of results if a number greater than the maximum is requested. Check `meta.pagination.per_page` in the response to see how many were returned.  Default: `50`; Maximum: `200`., address_id: [str] # Return entities related to the specified address. Use a comma-separated list to specify multiple address IDs., collection_mode: str # Return entities that match the specified collection mode., customer_id: [str] # Return entities related to the specified customer. Use a comma-separated list to specify multiple customer IDs., order_by: str=id[DESC] # Order returned entities by the specified field and direction (`[ASC]` or `[DESC]`). For example, `?order_by=id[ASC]`.  Valid fields for ordering: `id`., price_id: [str] # Return entities related to the specified price. Use a comma-separated list to specify multiple price IDs., scheduled_change_action: [str] # Return subscriptions that have a scheduled change. Use a comma-separated list to specify multiple scheduled change actions., status: [str] # Return entities that match the specified status. Use a comma-separated list to specify multiple status values.}\n@returns(200) {data: [map], meta: map{request_id: str, pagination: map{per_page: int, next: str(uri), has_more: bool, estimated_total: int}}} # The request has succeeded.\n\n@endpoint GET /subscriptions/{subscription_id}\n@desc Get a subscription\n@required {subscription_id: str # Paddle ID of the subscription entity to work with.}\n@optional {include: [str] # Include related entities in the response. Use a comma-separated list to specify multiple entities.}\n@returns(200) {data: map{id: any, status: any, customer_id: any, address_id: any, business_id: any, currency_code: any, created_at: any, updated_at: any, started_at: any, first_billed_at: any, next_billed_at: any, paused_at: any, canceled_at: any, discount: any, collection_mode: any, billing_details: any, current_billing_period: any, billing_cycle: any, scheduled_change: any, management_urls: any, items: [map], custom_data: any, import_meta: any, next_transaction: any, recurring_transaction_details: any}, meta: map{request_id: str}} # The request has succeeded.\n\n@endpoint PATCH /subscriptions/{subscription_id}\n@desc Update a subscription\n@required {subscription_id: str # Paddle ID of the subscription entity to work with.}\n@optional {customer_id: any # Paddle ID of the customer that this subscription is for, prefixed with `ctm_`. Include to change the customer for a subscription., address_id: any # Paddle ID of the address that this subscription is for, prefixed with `add_`. Include to change the address for a subscription., business_id: any # Paddle ID of the business that this subscription is for, prefixed with `biz_`. Include to change the business for a subscription., currency_code: any # Supported three-letter ISO 4217 currency code. Include to change the currency that a subscription bills in. When changing `collection_mode` to `manual`, you may need to change currency code to `USD`, `EUR`, or `GBP`., next_billed_at: any # RFC 3339 datetime string of when this subscription is next scheduled to be billed. Include to change the next billing date., discount: any # Details of the discount applied to this subscription. Include to add a discount to a subscription. `null` to remove a discount., collection_mode: any # How payment is collected for transactions created for this subscription. `automatic` for checkout, `manual` for invoices., billing_details: any # Details for invoicing. Required if `collection_mode` is `manual`. `null` if changing `collection_mode` to `automatic`., scheduled_change: null # Change that's scheduled to be applied to a subscription. When updating, you may only set to `null` to remove a scheduled change. Use the pause subscription, cancel subscription, and resume subscription operations to create scheduled changes., items: [any] # List of items on this subscription. Only recurring items may be added. Send the complete list of items that should be on this subscription, including existing items to retain., custom_data: any # Your own structured key-value data., proration_billing_mode: str(prorated_immediately/prorated_next_billing_period/full_immediately/full_next_billing_period/do_not_bill) # How Paddle should handle proration calculation for changes made to a subscription or its items. Required when making changes that impact billing.  For automatically-collected subscriptions, responses may take longer than usual if a proration billing mode that collects for payment immediately is used., on_payment_failure: any=prevent_change}\n@returns(200) {data: map{id: any, status: any, customer_id: any, address_id: any, business_id: any, currency_code: any, created_at: any, updated_at: any, started_at: any, first_billed_at: any, next_billed_at: any, paused_at: any, canceled_at: any, discount: any, collection_mode: any, billing_details: any, current_billing_period: any, billing_cycle: any, scheduled_change: any, management_urls: any, items: [map], custom_data: any, import_meta: any}, meta: map{request_id: str}} # The request has succeeded.\n@example_request {\"items\":[{\"price_id\":\"pri_01gsz8x8sawmvhz1pv30nge1ke\",\"quantity\":20},{\"price_id\":\"pri_01h1vjfevh5etwq3rb416a23h2\",\"quantity\":1},{\"price_id\":\"pri_01gsz95g2zrkagg294kpstx54r\",\"quantity\":1}],\"proration_billing_mode\":\"prorated_immediately\"}\n\n@endpoint POST /subscriptions/{subscription_id}/cancel\n@desc Cancel a subscription\n@required {subscription_id: str # Paddle ID of the subscription entity to work with.}\n@optional {effective_from: any=next_billing_period}\n@returns(200) {data: map{id: any, status: any, customer_id: any, address_id: any, business_id: any, currency_code: any, created_at: any, updated_at: any, started_at: any, first_billed_at: any, next_billed_at: any, paused_at: any, canceled_at: any, discount: any, collection_mode: any, billing_details: any, current_billing_period: any, billing_cycle: any, scheduled_change: any, management_urls: any, items: [map], custom_data: any, import_meta: any}, meta: map{request_id: str}} # The request has succeeded.\n@example_request {\"effective_from\":\"immediately\"}\n\n@endpoint POST /subscriptions/{subscription_id}/pause\n@desc Pause a subscription\n@required {subscription_id: str # Paddle ID of the subscription entity to work with.}\n@optional {effective_from: any=next_billing_period, resume_at: any # RFC 3339 datetime string of when the paused subscription should resume. Omit to pause indefinitely until resumed., on_resume: any=start_new_billing_period}\n@returns(200) {data: map{id: any, status: any, customer_id: any, address_id: any, business_id: any, currency_code: any, created_at: any, updated_at: any, started_at: any, first_billed_at: any, next_billed_at: any, paused_at: any, canceled_at: any, discount: any, collection_mode: any, billing_details: any, current_billing_period: any, billing_cycle: any, scheduled_change: any, management_urls: any, items: [map], custom_data: any, import_meta: any}, meta: map{request_id: str}} # The request has succeeded.\n@example_request {\"effective_from\":\"next_billing_period\",\"resume_at\":\"2024-09-01T16:30:00Z\"}\n\n@endpoint POST /subscriptions/{subscription_id}/resume\n@desc Resume a paused subscription\n@required {subscription_id: str # Paddle ID of the subscription entity to work with.}\n@returns(200) {data: map{id: any, status: any, customer_id: any, address_id: any, business_id: any, currency_code: any, created_at: any, updated_at: any, started_at: any, first_billed_at: any, next_billed_at: any, paused_at: any, canceled_at: any, discount: any, collection_mode: any, billing_details: any, current_billing_period: any, billing_cycle: any, scheduled_change: any, management_urls: any, items: [map], custom_data: any, import_meta: any}, meta: map{request_id: str}} # The request has succeeded.\n@example_request {\"effective_from\":\"immediately\"}\n\n@endpoint POST /subscriptions/{subscription_id}/activate\n@desc Activate a trialing subscription\n@required {subscription_id: str # Paddle ID of the subscription entity to work with.}\n@returns(200) {data: map{id: any, status: any, customer_id: any, address_id: any, business_id: any, currency_code: any, created_at: any, updated_at: any, started_at: any, first_billed_at: any, next_billed_at: any, paused_at: any, canceled_at: any, discount: any, collection_mode: any, billing_details: any, current_billing_period: any, billing_cycle: any, scheduled_change: any, management_urls: any, items: [map], custom_data: any, import_meta: any}, meta: map{request_id: str}} # The request has succeeded.\n\n@endpoint GET /subscriptions/{subscription_id}/update-payment-method-transaction\n@desc Get a transaction to update payment method\n@required {subscription_id: str # Paddle ID of the subscription entity to work with.}\n@returns(200) {data: map{id: any, status: str, customer_id: any, address_id: any, business_id: any, custom_data: any, currency_code: any, origin: any, subscription_id: any, invoice_id: any, invoice_number: any, collection_mode: any, discount_id: any, billing_details: any, billing_period: any, items: [map], details: any, payments: [map], checkout: any, created_at: any, updated_at: any, billed_at: any, revised_at: any, customer: any, address: any, business: any, discount: any, adjustments: [map], adjustments_totals: any, available_payment_methods: [str]}, meta: map{request_id: str}} # The request has succeeded.\n\n@endpoint PATCH /subscriptions/{subscription_id}/preview\n@desc Preview an update to a subscription\n@required {subscription_id: str # Paddle ID of the subscription entity to work with.}\n@optional {customer_id: any # Paddle ID of the customer that this subscription is for, prefixed with `ctm_`. Include to change the customer for a subscription., address_id: any # Paddle ID of the address that this subscription is for, prefixed with `add_`. Include to change the address for a subscription., business_id: any # Paddle ID of the business that this subscription is for, prefixed with `biz_`. Include to change the business for a subscription., currency_code: any # Supported three-letter ISO 4217 currency code. Include to change the currency that a subscription bills in. When changing `collection_mode` to `manual`, you may need to change currency code to `USD`, `EUR`, or `GBP`., next_billed_at: any # RFC 3339 datetime string of when this subscription is next scheduled to be billed. Include to change the next billing date., discount: any # Details of the discount applied to this subscription. Include to add a discount to a subscription. `null` to remove a discount., collection_mode: any # How payment is collected for transactions created for this subscription. `automatic` for checkout, `manual` for invoices., billing_details: any # Details for invoicing. Required if `collection_mode` is `manual`. `null` if changing `collection_mode` to `automatic`., scheduled_change: null # Change that's scheduled to be applied to a subscription. When updating, you may only set to `null` to remove a scheduled change. Use the pause subscription, cancel subscription, and resume subscription operations to create scheduled changes., items: [any] # List of items on this subscription. Only recurring items may be added. Send the complete list of items that should be on this subscription, including existing items to retain., custom_data: any # Your own structured key-value data., proration_billing_mode: str(prorated_immediately/prorated_next_billing_period/full_immediately/full_next_billing_period/do_not_bill) # How Paddle should handle proration calculation for changes made to a subscription or its items. Required when making changes that impact billing.  For automatically-collected subscriptions, responses may take longer than usual if a proration billing mode that collects for payment immediately is used., on_payment_failure: any=prevent_change}\n@returns(200) {data: map{status: any, customer_id: any, address_id: any, business_id: any, currency_code: any, created_at: any, updated_at: any, started_at: any, first_billed_at: any, next_billed_at: any, paused_at: any, canceled_at: any, discount: any, collection_mode: any, billing_details: any, current_billing_period: any, billing_cycle: any, scheduled_change: any, management_urls: any, items: [map], custom_data: any, immediate_transaction: any, next_transaction: any, recurring_transaction_details: any, update_summary: any, import_meta: any}, meta: map{request_id: str}} # The request has succeeded.\n@example_request {\"items\":[{\"price_id\":\"pri_01gsz8x8sawmvhz1pv30nge1ke\",\"quantity\":20},{\"price_id\":\"pri_01h1vjfevh5etwq3rb416a23h2\",\"quantity\":1},{\"price_id\":\"pri_01gsz95g2zrkagg294kpstx54r\",\"quantity\":1}],\"proration_billing_mode\":\"prorated_immediately\"}\n\n@endpoint POST /subscriptions/{subscription_id}/charge\n@desc Create a one-time charge for a subscription\n@required {subscription_id: str # Paddle ID of the subscription entity to work with., effective_from: any # When one-time charges should be billed., items: [any] # List of one-time charges to bill for. Only prices where the `billing_cycle` is `null` may be added.  You can charge for items that you've added to your catalog by passing the Paddle ID of an existing price entity, or you can charge for non-catalog items by passing a price object.  Non-catalog items can be for existing products, or you can pass a product object as part of your price to charge for a non-catalog product.}\n@optional {on_payment_failure: any=prevent_change}\n@returns(201) {data: map{id: any, status: any, customer_id: any, address_id: any, business_id: any, currency_code: any, created_at: any, updated_at: any, started_at: any, first_billed_at: any, next_billed_at: any, paused_at: any, canceled_at: any, discount: any, collection_mode: any, billing_details: any, current_billing_period: any, billing_cycle: any, scheduled_change: any, management_urls: any, items: [map], custom_data: any, import_meta: any}, meta: map{request_id: str}} # The request has succeeded and a new resource has been created as a result.\n@example_request {\"effective_from\":\"immediately\",\"items\":[{\"price_id\":\"pri_01gsz98e27ak2tyhexptwc58yk\",\"quantity\":1}]}\n\n@endpoint POST /subscriptions/{subscription_id}/charge/preview\n@desc Preview a one-time charge for a subscription\n@required {subscription_id: str # Paddle ID of the subscription entity to work with., effective_from: any # When one-time charges should be billed., items: [any] # List of one-time charges to bill for. Only prices where the `billing_cycle` is `null` may be added.  You can charge for items that you've added to your catalog by passing the Paddle ID of an existing price entity, or you can charge for non-catalog items by passing a price object.  Non-catalog items can be for existing products, or you can pass a product object as part of your price to charge for a non-catalog product.}\n@optional {on_payment_failure: any=prevent_change}\n@returns(200) {data: map{status: any, customer_id: any, address_id: any, business_id: any, currency_code: any, created_at: any, updated_at: any, started_at: any, first_billed_at: any, next_billed_at: any, paused_at: any, canceled_at: any, discount: any, collection_mode: any, billing_details: any, current_billing_period: any, billing_cycle: any, scheduled_change: any, management_urls: any, items: [map], custom_data: any, immediate_transaction: any, next_transaction: any, recurring_transaction_details: any, update_summary: any, import_meta: any}, meta: map{request_id: str}} # The request has succeeded.\n@example_request {\"effective_from\":\"immediately\",\"items\":[{\"price_id\":\"pri_01gsz98e27ak2tyhexptwc58yk\",\"quantity\":1}]}\n\n@endgroup\n\n@group transactions\n@endpoint GET /transactions\n@desc List transactions\n@optional {include: [str] # Include related entities in the response. Use a comma-separated list to specify multiple entities., id: [str] # Return only the IDs specified. Use a comma-separated list to get multiple entities., after: str # Return entities after the specified Paddle ID when working with paginated endpoints. Used in the `meta.pagination.next` URL in responses for list operations., billed_at: str # Return entities billed at a specific time. Pass an RFC 3339 datetime string, or use `[LT]` (less than), `[LTE]` (less than or equal to), `[GT]` (greater than), or `[GTE]` (greater than or equal to) operators. For example, `billed_at=2023-04-18T17:03:26` or `billed_at[LT]=2023-04-18T17:03:26`., collection_mode: str # Return entities that match the specified collection mode., created_at: str # Return entities created at a specific time. Pass an RFC 3339 datetime string, or use `[LT]` (less than), `[LTE]` (less than or equal to), `[GT]` (greater than), or `[GTE]` (greater than or equal to) operators. For example, `created_at=2023-04-18T17:03:26` or `created_at[LT]=2023-04-18T17:03:26`., customer_id: [str] # Return entities related to the specified customer. Use a comma-separated list to specify multiple customer IDs., invoice_number: [str] # Return entities that match the invoice number. Use a comma-separated list to specify multiple invoice numbers., origin: [str] # Return entities related to the specified origin. Use a comma-separated list to specify multiple origins., order_by: str=id[DESC] # Order returned entities by the specified field and direction (`[ASC]` or `[DESC]`). For example, `?order_by=id[ASC]`.  Valid fields for ordering: `billed_at`, `created_at`, `id`, and `updated_at`., status: [str] # Return entities that match the specified status. Use a comma-separated list to specify multiple status values., subscription_id: any # Return entities related to the specified subscription. Use a comma-separated list to specify multiple subscription IDs. Pass `null` to return entities that aren't related to any subscription., per_page: int=30 # Set how many entities are returned per page. Paddle returns the maximum number of results if a number greater than the maximum is requested. Check `meta.pagination.per_page` in the response to see how many were returned.  Default: `30`; Maximum: `30`., updated_at: str # Return entities updated at a specific time. Pass an RFC 3339 datetime string, or use `[LT]` (less than), `[LTE]` (less than or equal to), `[GT]` (greater than), or `[GTE]` (greater than or equal to) operators. For example, `updated_at=2023-04-18T17:03:26` or `updated_at[LT]=2023-04-18T17:03:26`.}\n@returns(200) {data: [map], meta: map{request_id: str, pagination: map{per_page: int, next: str(uri), has_more: bool, estimated_total: int}}} # The request has succeeded.\n\n@endpoint POST /transactions\n@desc Create a transaction\n@required {items: [any] # List of items to charge for. You can charge for items that you've added to your catalog by passing the Paddle ID of an existing price entity, or you can charge for non-catalog items by passing a price object.  Non-catalog items can be for existing products, or you can pass a product object as part of your price to charge for a non-catalog product.}\n@optional {include: [str] # Include related entities in the response. Use a comma-separated list to specify multiple entities., id: any, status: any # Status of this transaction. You may set a transaction to `billed` when creating, or omit to let Paddle set the status. Transactions are created as `ready` if they have an `address_id`, `customer_id`, and `items`, otherwise they are created as `draft`.  Marking as `billed` when creating is typically used when working with manually-collected transactions as part of an invoicing workflow. Billed transactions cannot be updated, only canceled., customer_id: any # Paddle ID of the customer that this transaction is for, prefixed with `ctm_`. If omitted, transaction status is `draft`., address_id: any # Paddle ID of the address that this transaction is for, prefixed with `add_`. Requires `customer_id`. If omitted, transaction status is `draft`., business_id: any # Paddle ID of the business that this transaction is for, prefixed with `biz_`. Requires `customer_id`., custom_data: any # Your own structured key-value data., currency_code: any # Supported three-letter ISO 4217 currency code. Must be `USD`, `EUR`, or `GBP` if `collection_mode` is `manual`., origin: any, subscription_id: any # Paddle ID of the subscription that this transaction is for, prefixed with `sub_`., invoice_id: any # 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., invoice_number: any # Invoice number for this transaction. Automatically generated by Paddle when you mark a transaction as `billed` where `collection_mode` is `manual`., collection_mode: any=automatic # How payment is collected for this transaction. `automatic` for checkout, `manual` for invoices. If omitted, defaults to `automatic`., discount_id: any # Paddle ID of the discount to apply to this transaction, prefixed with `dsc_`., billing_details: any # Details for invoicing. Required if `collection_mode` is `manual`., billing_period: any # Time period that this transaction is for. Set automatically by Paddle for subscription renewals to describe the period that charges are for., details: any, payments: [map{payment_attempt_id!: str, stored_payment_method_id!: str, payment_method_id!: any, amount!: str, status!: str, error_code!: any, method_details!: map, created_at!: str(date-time), captured_at!: any}] # 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: any # Paddle Checkout details for this transaction. You may pass a URL when creating or updating an automatically-collected transaction, or when creating or updating a manually-collected transaction where `billing_details.enable_checkout` is `true`., created_at: any, updated_at: any, billed_at: any # 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.}\n@returns(201) {data: map{id: any, status: str, customer_id: any, address_id: any, business_id: any, custom_data: any, currency_code: any, origin: any, subscription_id: any, invoice_id: any, invoice_number: any, collection_mode: any, discount_id: any, billing_details: any, billing_period: any, items: [map], details: any, payments: [map], checkout: any, created_at: any, updated_at: any, billed_at: any, revised_at: any, address: any, adjustments: [map], adjustments_totals: any, business: any, customer: any, discount: any, available_payment_methods: [str]}, meta: map{request_id: str}} # The request has succeeded and a new resource has been created as a result.\n@example_request {\"items\":[{\"quantity\":20,\"price_id\":\"pri_01gsz91wy9k1yn7kx82aafwvea\"},{\"quantity\":1,\"price_id\":\"pri_01gsz96z29d88jrmsf2ztbfgjg\"},{\"quantity\":1,\"price_id\":\"pri_01gsz98e27ak2tyhexptwc58yk\"}],\"customer_id\":\"ctm_01hv6y1jedq4p1n0yqn5ba3ky4\",\"address_id\":\"add_01hv8gq3318ktkfengj2r75gfx\",\"currency_code\":\"USD\",\"collection_mode\":\"manual\",\"billing_details\":{\"enable_checkout\":false,\"purchase_order_number\":\"PO-123\",\"payment_terms\":{\"interval\":\"day\",\"frequency\":14}},\"billing_period\":{\"starts_at\":\"2024-04-12T00:00:00Z\",\"ends_at\":\"2025-04-11T23:59:00Z\"}}\n\n@endpoint GET /transactions/{transaction_id}\n@desc Get a transaction\n@required {transaction_id: str # Paddle ID of the transaction entity to work with.}\n@optional {include: [str] # Include related entities in the response. Use a comma-separated list to specify multiple entities.}\n@returns(200) {data: map{id: any, status: str, customer_id: any, address_id: any, business_id: any, custom_data: any, currency_code: any, origin: any, subscription_id: any, invoice_id: any, invoice_number: any, collection_mode: any, discount_id: any, billing_details: any, billing_period: any, items: [map], details: any, payments: [map], checkout: any, created_at: any, updated_at: any, billed_at: any, revised_at: any, address: any, adjustments: [map], adjustments_totals: any, business: any, customer: any, discount: any, available_payment_methods: [str]}, meta: map{request_id: str}} # The request has succeeded.\n\n@endpoint PATCH /transactions/{transaction_id}\n@desc Update a transaction\n@required {transaction_id: str # Paddle ID of the transaction entity to work with.}\n@optional {include: [str] # Include related entities in the response. Use a comma-separated list to specify multiple entities., id: any, status: any # Status of this transaction. You may set a transaction to `billed` or `canceled`. Billed transactions cannot be changed.  For manually-collected transactions, marking as `billed` is essentially issuing an invoice., customer_id: any # Paddle ID of the customer that this transaction is for, prefixed with `ctm_`., address_id: any # Paddle ID of the address that this transaction is for, prefixed with `add_`., business_id: any # Paddle ID of the business that this transaction is for, prefixed with `biz_`., custom_data: any # Your own structured key-value data., currency_code: any # Supported three-letter ISO 4217 currency code. Must be `USD`, `EUR`, or `GBP` if `collection_mode` is `manual`., origin: any, subscription_id: any # Paddle ID of the subscription that this transaction is for, prefixed with `sub_`., invoice_id: any # 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., invoice_number: any # Invoice number for this transaction. Automatically generated by Paddle when you mark a transaction as `billed` where `collection_mode` is `manual`., collection_mode: any # How payment is collected for this transaction. `automatic` for checkout, `manual` for invoices., discount_id: any # Paddle ID of the discount to apply to this transaction, prefixed with `dsc_`., billing_details: any # Details for invoicing. Required if `collection_mode` is `manual`., billing_period: any # Time period that this transaction is for. Set automatically by Paddle for subscription renewals to describe the period that charges are for., items: [any] # List of items on this transaction.  When making a request, each object must contain either a `price_id` or a `price` object, and a `quantity`.  Include a `price_id` to charge for an existing catalog item, or a `price` object to charge for a non-catalog item., details: any, payments: [map{payment_attempt_id!: str, stored_payment_method_id!: str, payment_method_id!: any, amount!: str, status!: str, error_code!: any, method_details!: map, created_at!: str(date-time), captured_at!: any}] # 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: any # Paddle Checkout details for this transaction. You may pass a URL when creating or updating an automatically-collected transaction, or when creating or updating a manually-collected transaction where `billing_details.enable_checkout` is `true`., created_at: any, updated_at: any, billed_at: any # 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.}\n@returns(200) {data: map{id: any, status: str, customer_id: any, address_id: any, business_id: any, custom_data: any, currency_code: any, origin: any, subscription_id: any, invoice_id: any, invoice_number: any, collection_mode: any, discount_id: any, billing_details: any, billing_period: any, items: [map], details: any, payments: [map], checkout: any, created_at: any, updated_at: any, billed_at: any, revised_at: any, address: any, adjustments: [map], adjustments_totals: any, business: any, customer: any, discount: any, available_payment_methods: [str]}, meta: map{request_id: str}} # The request has succeeded.\n@example_request {\"discount_id\":\"dsc_01gtgztp8fpchantd5g1wrksa3\",\"items\":[{\"quantity\":50,\"price_id\":\"pri_01gsz91wy9k1yn7kx82aafwvea\"},{\"quantity\":1,\"price_id\":\"pri_01gsz96z29d88jrmsf2ztbfgjg\"},{\"quantity\":1,\"price_id\":\"pri_01gsz98e27ak2tyhexptwc58yk\"}]}\n\n@endpoint POST /transactions/preview\n@desc Preview a transaction\n@returns(200) {data: map{customer_id: any, address_id: any, business_id: any, currency_code: any, discount_id: any, customer_ip_address: any, address: any, ignore_trials: bool, items: [map], details: any, available_payment_methods: [str]}, meta: map{request_id: str}} # The request has succeeded.\n@example_request {\"items\":[{\"quantity\":20,\"price_id\":\"pri_01gsz8x8sawmvhz1pv30nge1ke\"},{\"quantity\":1,\"price_id\":\"pri_01h1vjfevh5etwq3rb416a23h2\"},{\"quantity\":1,\"price_id\":\"pri_01gsz98e27ak2tyhexptwc58yk\",\"include_in_totals\":false}],\"discount_id\":\"dsc_01gtgztp8fpchantd5g1wrksa3\",\"address\":{\"country_code\":\"US\"},\"currency_code\":\"USD\"}\n\n@endpoint POST /transactions/{transaction_id}/revise\n@desc Revise customer information on a billed or completed transaction\n@required {transaction_id: str # Paddle ID of the transaction entity to work with.}\n@optional {customer: any # Revised customer information for this transaction., business: any # Revised business information for this transaction., address: any # Revised address information for this transaction.}\n@returns(200) {data: map{id: any, status: str, customer_id: any, address_id: any, business_id: any, custom_data: any, currency_code: any, origin: any, subscription_id: any, invoice_id: any, invoice_number: any, collection_mode: any, discount_id: any, billing_details: any, billing_period: any, items: [map], details: any, payments: [map], checkout: any, created_at: any, updated_at: any, billed_at: any, revised_at: any}, meta: map{request_id: str}} # The request has succeeded.\n@example_request {\"customer\":{\"name\":\"Sam Miller\"},\"business\":{\"tax_identifier\":\"AB0123456789\"},\"address\":{\"first_line\":\"3811 Ditmars Blvd\"}}\n\n@endpoint GET /transactions/{transaction_id}/invoice\n@desc Get a PDF invoice for a transaction\n@required {transaction_id: str # Paddle ID of the transaction entity to work with.}\n@optional {disposition: str=attachment # Determine whether the generated URL should download the PDF as an attachment saved locally, or open it inline in the browser.  Default: `attachment`.}\n@returns(200) {meta: map{request_id: str}, data: map{url: str}} # The request has succeeded.\n\n@endgroup\n\n@end\n"}