GET
/subscriptions/{subscription_id}/history Returns a paginated list of history entries for a subscription. Use the query parameters to filter and page through results.
Subscription history records the changes made to a subscription over its lifetime, so you can see what changed, when it happened, where it originated, and who made the change. Each change is a separate history entry, and some entries also include a reason.
Paddle began recording subscription history on June 29, 2026. For subscriptions that existed before then, Paddle automatically creates subscription_created and subscription_canceled entries and attempts to infer details from the subscription's initial state.
History entries are ordered by newest first by default (occurred_at in descending order).
Requires
subscription_history.read
permission.
Path parameters
subscription_idstringrequired
Example:
sub_01h04vsc0qhwtsbsxh3422wjs4Unique Paddle ID for this subscription entity, prefixed with
sub_.Pattern:
^sub_[a-z\d]{26}$Query parameters
actionarray
Return history entries that match the specified action. Use a comma-separated list to specify multiple action values.
Values
subscription_activatedReturn history entries where the action issubscription_activated. The subscription's status becameactive.subscription_address_updatedReturn history entries where the action issubscription_address_updated. The address on the subscription was changed.subscription_billing_cycle_updatedReturn history entries where the action issubscription_billing_cycle_updated. The billing cycle that sets how often the subscription renews was changed.subscription_billing_date_updatedReturn history entries where the action issubscription_billing_date_updated. The date the subscription next renews was changed.subscription_billing_details_updatedReturn history entries where the action issubscription_billing_details_updated. The billing details for the subscription's invoices were changed.
+ Show all values− Hide values
subscription_business_addedReturn history entries where the action issubscription_business_added. A business was added to the subscription.subscription_business_removedReturn history entries where the action issubscription_business_removed. The business was removed from the subscription.subscription_business_updatedReturn history entries where the action issubscription_business_updated. The business on the subscription was changed.subscription_canceledReturn history entries where the action issubscription_canceled. The subscription's status becamecanceled.subscription_collection_mode_updatedReturn history entries where the action issubscription_collection_mode_updated. How the subscription is collected, automatically or manually, was changed.subscription_consent_requirement_grantedReturn history entries where the action issubscription_consent_requirement_granted. A consent requirement on the subscription was granted.subscription_createdReturn history entries where the action issubscription_created. The subscription was created.subscription_currency_updatedReturn history entries where the action issubscription_currency_updated. The currency the subscription is billed in was changed.subscription_custom_data_updatedReturn history entries where the action issubscription_custom_data_updated. The custom data on the subscription was changed.subscription_customer_updatedReturn history entries where the action issubscription_customer_updated. The customer the subscription belongs to was changed.subscription_discount_addedReturn history entries where the action issubscription_discount_added. A discount was added to the subscription.subscription_discount_expiredReturn history entries where the action issubscription_discount_expired. A discount on the subscription reached its end date and expired.subscription_discount_removedReturn history entries where the action issubscription_discount_removed. A discount was removed from the subscription.subscription_item_addedReturn history entries where the action issubscription_item_added. An item was added to the subscription.subscription_item_quantity_updatedReturn history entries where the action issubscription_item_quantity_updated. The quantity of an item on the subscription was changed.subscription_item_removedReturn history entries where the action issubscription_item_removed. An item was removed from the subscription.subscription_one_off_charge_appliedReturn history entries where the action issubscription_one_off_charge_applied. A one-time charge was applied to the subscription.subscription_past_dueReturn history entries where the action issubscription_past_due. The subscription's status becamepast_dueafter a payment failed.subscription_pausedReturn history entries where the action issubscription_paused. The subscription's status becamepaused.subscription_payment_attemptedReturn history entries where the action issubscription_payment_attempted. A payment for a change to the subscription was attempted and failed.subscription_payment_method_addedReturn history entries where the action issubscription_payment_method_added. A payment method was added to the subscription.subscription_payment_method_removedReturn history entries where the action issubscription_payment_method_removed. A payment method was removed from the subscription.subscription_payment_method_updatedReturn history entries where the action issubscription_payment_method_updated. The payment method on the subscription was changed.subscription_renewedReturn history entries where the action issubscription_renewed. The subscription renewed for a new billing period.subscription_resumedReturn history entries where the action issubscription_resumed. The subscription's status becameactiveafter being paused.subscription_scheduled_change_addedReturn history entries where the action issubscription_scheduled_change_added. A scheduled change was added to the subscription.subscription_scheduled_change_removedReturn history entries where the action issubscription_scheduled_change_removed. A scheduled change was removed from the subscription.subscription_scheduled_change_updatedReturn history entries where the action issubscription_scheduled_change_updated. A scheduled change on the subscription was changed.
sourcearray
Return history entries that match the specified source. Use a comma-separated list to specify multiple source values.
Values
systemReturn history entries where the source issystem. The entry originated from an internal system process.apiReturn history entries where the source isapi. The entry originated from the Paddle API.dashboardReturn history entries where the source isdashboard. The entry originated from the dashboard.customer_portalReturn history entries where the source iscustomer_portal. The entry originated from the customer portal.support_botReturn history entries where the source issupport_bot. The entry originated from Paddle.net.
+ Show all values− Hide values
retainReturn history entries where the source isretain. The entry originated from Paddle Retain.checkoutReturn history entries where the source ischeckout. The entry originated from Paddle Checkout.external_providerReturn history entries where the source isexternal_provider. The entry originated from an import from an external provider.paddle_classicReturn history entries where the source ispaddle_classic. The entry originated from an import from Paddle Classic.unknownReturn history entries where the source isunknown. The entry happened before history recording began and its source couldn't be determined.
actor_typearray
Return history entries that match the specified actor type. Use a comma-separated list to specify multiple actor type values.
Values
customerReturn history entries where the actor type iscustomer. The action was performed by a customer.userReturn history entries where the actor type isuser. The action was performed by a Paddle user account.api_keyReturn history entries where the actor type isapi_key. The action was performed by an API key.paddle_staffReturn history entries where the actor type ispaddle_staff. The action was performed by a member of the Paddle team.publisherReturn history entries where the actor type ispublisher. The action was performed by a publisher (app) acting on behalf of a user or seller.
+ Show all values− Hide values
systemReturn history entries where the actor type issystem. The action was performed by an internal system process.
actor_idarray
Return history entries that match the specified actor ID. Use a comma-separated list to specify multiple actor ID values. Only applicable if
actor_type is also selected.reasonarray
Return history entries that match the specified reason. Use a comma-separated list to specify multiple reason values.
Values
cardless_trial_endedReturn history entries where the reason iscardless_trial_ended.import_issueReturn history entries where the reason isimport_issue.missing_consentReturn history entries where the reason ismissing_consent.seller_requestReturn history entries where the reason isseller_request.customer_requestReturn history entries where the reason iscustomer_request.
+ Show all values− Hide values
chargebackReturn history entries where the reason ischargeback.
occurred_atstring
Return entities that occurred at a specific time. Use
[LTE] (less than or equal to) or [GTE] (greater than or equal to) operators with an RFC 3339 datetime string. For example, occurred_at[LTE]=2023-04-18T17:03:26 or occurred_at[GTE]=2023-04-18T17:03:26.afterstring
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_pageinteger
Default:
50Set 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.
Max: 200
order_bystring
Default:
occurred_at[DESC]Order returned entities by the specified field and direction ([ASC] or [DESC]). For example, ?order_by=occurred_at[DESC].
Valid fields for ordering: occurred_at.
Header parameters
Skip-Countstring
Set to
true to skip the count query on list operations. When set, meta.pagination.estimated_total returns -1 instead of an exact count.Response (200)
dataarrayrequired
idstringrequired
Example:
subhis_01kagxfkdpvsdvnm7xw4avwvspUnique Paddle ID for this subscription history entry, prefixed with
subhis_.Pattern:
^subhis_[a-z\d]{26}$group_idstringrequired
Example:
subhisgrp_01kagxffkcme9fhd6srqgkmssdUnique Paddle ID for this subscription history group, prefixed with
subhisgrp_. History entries that occurred as part of the same request share the same group ID.Pattern:
^subhisgrp_[a-z\d]{26}$subscription_idstringrequired
Example:
sub_01h04vsc0qhwtsbsxh3422wjs4Paddle ID of the subscription that this history entry relates to, prefixed with
sub_.Pattern:
^sub_[a-z\d]{26}$occurred_atstring (date-time)required
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when the entry happened.
sourcestringrequired
Where the entry originated from.
Values
systemEntry originated from an internal system process.apiEntry originated from the Paddle API.dashboardEntry originated from the dashboard.customer_portalEntry originated from the customer portal.support_botEntry originated from Paddle.net.
+ Show all values− Hide values
retainEntry originated from Paddle Retain.checkoutEntry originated from Paddle Checkout.external_providerEntry originated from an import from an external provider.paddle_classicEntry originated from an import from Paddle Classic.unknownEntry happened before history recording began. Its source couldn't be determined.
actorobjectrequired
Details about the actor that performed the action that created this entry.
typestringrequired
The type of actor that performed this action.
Values
customerAction was performed by a customer.userAction was performed by a Paddle user account.api_keyAction was performed by an API key.paddle_staffAction was performed by a member of the Paddle team.publisherAction was performed by a publisher (app) acting on behalf of a user or seller.
+ Show all values− Hide values
systemAction was performed by an internal system process.
idstring | nullrequired
The ID of the actor in relation to the
type. null where the type of actor doesn't have an ID.reasonstring | nullrequired
Why the entry was created. Only applicable to certain actions;
null otherwise.Values
cardless_trial_endedThe subscription was a cardless trial and was automatically canceled because no payment method was added. Relates tosubscription_canceledactions.import_issueThe subscription was canceled because of an issue during import. Relates tosubscription_canceledactions.missing_consentThe subscription was automatically canceled because the customer didn't grant a required consent to continue. Relates tosubscription_canceledactions.seller_requestA Paddle user on your account requested that Paddle cancel this subscription. Relates tosubscription_canceledactions.customer_requestThe customer requested that Paddle cancel this subscription. Relates tosubscription_canceledactions.
+ Show all values− Hide values
chargebackThe subscription was automatically canceled because of a chargeback on one of its transactions. Relates tosubscription_canceledactions.
detailobjectrequired
Details specific to the action. The fields returned depend on the value of
action.Activated
Details specific to
subscription_activated actions.actionstringrequired
What happened on the subscription.
Values
subscription_activatedThe subscription's status becameactive.
statusstringrequired
Status of the subscription after activation.
Values
activeSubscription is active. Paddle is billing for this subscription and related transactions aren't past due.canceledSubscription is canceled. Automatically set by Paddle when a subscription is canceled. When a subscription is set to cancel on the next billing period, a scheduled change for the cancellation is created. The subscription status moves to canceled when the scheduled change takes effect.past_dueSubscription has an overdue payment. Automatically set by Paddle when payment fails for an automatically-collected transaction, or when payment terms have elapsed for a manually-collected transaction (an invoice).pausedSubscription is paused. Automatically set by Paddle when a subscription is paused. When a subscription is set to pause on the next billing period, a scheduled change for the pause is created. The subscription status moves topausedwhen the scheduled change takes effect.trialingSubscription is in trial.
first_billed_atstring (date-time) | nullrequired
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when the subscription was first billed.
null when the subscription has never been billed — for example, an imported subscription recovering from past_due.next_billed_atstring (date-time) | nullrequired
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when the subscription was next scheduled to be billed at the time of activation.
null when the subscription has no next billing date — for example, a recovered past_due subscription that is scheduled to cancel or pause.current_billing_periodobjectrequired
Billing period of the subscription at the time of activation.
starts_atstring (date-time)required
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when this period starts.
ends_atstring (date-time)required
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when this period ends.
transaction_idstringrequired
Example:
txn_01h04vsbhqc62t8hmd4z3b578cPaddle ID of the transaction that activated the subscription, prefixed with
txn_.Pattern:
^txn_[a-z\d]{26}$Address updated
Details specific to
subscription_address_updated actions.actionstringrequired
What happened on the subscription.
Values
subscription_address_updatedThe address on the subscription was changed.
addressobjectrequired
Updated address against the subscription. This is what the address was changed to.
idstringrequired
Example:
add_01gm302t81w94gyjpjpqypkzkfUnique Paddle ID for this address entity, prefixed with
add_.Pattern:
^add_[a-z\d]{26}$customer_idstringrequired
Example:
ctm_01grnn4zta5a1mf02jjze7y2ysPaddle ID for the customer related to this address, prefixed with
cus_.Pattern:
^ctm_[a-z\d]{26}$descriptionstring | nullrequired
Example:
Paddle.comMemorable description for this address.
Max length: 1024
first_linestring | nullrequired
Example:
3811 Ditmars BlvdFirst line of this address.
Max length: 1024
second_linestring | nullrequired
Second line of this address.
Max length: 1024
citystring | nullrequired
Example:
AstoriaCity of this address.
Max length: 200
postal_codestring | nullrequired
Example:
11105-1803ZIP or postal code of this address. Required for some countries.
Max length: 200
regionstring | nullrequired
Example:
NYState, county, or region of this address.
Max length: 200
country_codestringrequired
Supported two-letter ISO 3166-1 alpha-2 country code for this address.
Values
ADAndorraAEUnited Arab EmiratesAGAntigua and BarbudaAIAnguillaALAlbania
+ Show all values− Hide values
AMArmeniaAOAngolaARArgentinaASAmerican SamoaATAustriaAUAustraliaAWArubaAXÃ…land IslandsAZAzerbaijanBABosnia and HerzegovinaBBBarbadosBDBangladeshBEBelgiumBFBurkina FasoBGBulgariaBHBahrainBIBurundiBJBeninBLSaint BarthélemyBMBermudaBNBruneiBOBoliviaBQCaribbean Netherlands (Bonaire, Sint Eustatius, and Saba)BRBrazilBSBahamasBTBhutanBVBouvet IslandBWBotswanaBZBelizeCACanadaCCCocos IslandsCGRepublic of CongoCHSwitzerlandCICôte d'Ivoire (Ivory Coast)CKCook IslandsCLChileCMCameroonCNChinaCOColombiaCRCosta RicaCVCape VerdeCWCuraçaoCXChristmas IslandCYCyprusCZCzechia (Czech Republic)DEGermanyDJDjiboutiDKDenmarkDMDominicaDODominican RepublicDZAlgeriaECEcuadorEEEstoniaEGEgyptEHWestern SaharaEREritreaESSpainETEthiopiaFIFinlandFJFijiFKFalkland IslandsFMMicronesiaFOFaroe IslandsFRFranceGAGabonGBUnited KingdomGDGrenadaGEGeorgiaGFFrench GuianaGGGuernseyGHGhanaGIGibraltarGLGreenlandGMGambiaGNGuineaGPGuadeloupeGQEquatorial GuineaGRGreeceGSSouth Georgia and the South Sandwich IslandsGTGuatemalaGUGuamGWGuinea-BissauGYGuyanaHKHong KongHMHeard Island and McDonald IslandsHNHondurasHRCroatiaHUHungaryIDIndonesiaIEIrelandILIsraelIMIsle of ManINIndiaIOBritish Indian Ocean TerritoryIQIraqISIcelandITItalyJEJerseyJMJamaicaJOJordanJPJapanKEKenyaKGKyrgyzstanKHCambodiaKIKiribatiKMComorosKNSaint Kitts and NevisKRSouth KoreaKWKuwaitKYCayman IslandsKZKazakhstanLALao People's Democratic Republic (Laos)LBLebanonLCSaint LuciaLILiechtensteinLKSri LankaLRLiberiaLSLesothoLTLithuaniaLULuxembourgLVLatviaMAMoroccoMCMonacoMDMoldovaMEMontenegroMFSaint MartinMGMadagascarMHMarshall IslandsMKMacedoniaMNMongoliaMOMacaoMPNorthern Mariana IslandsMQMartiniqueMRMauritaniaMSMontserratMTMaltaMUMauritiusMVMaldivesMWMalawiMXMexicoMYMalaysiaMZMozambiqueNANamibiaNCNew CaledoniaNENigerNFNorfolk IslandNGNigeriaNLNetherlandsNONorwayNPNepalNRNauruNUNiueNZNew ZealandOMOmanPAPanamaPEPeruPFFrench PolynesiaPGPapua New GuineaPHPhilippinesPKPakistanPLPolandPMSaint Pierre and MiquelonPNPitcairnPRPuerto RicoPSPalestinian territoriesPTPortugalPWPalauPYParaguayQAQatarREReunionRORomaniaRSRepublic of SerbiaRWRwandaSASaudi ArabiaSBSolomon IslandsSCSeychellesSESwedenSGSingaporeSHSaint HelenaSISloveniaSJSvalbard and Jan MayenSKSlovakiaSLSierra LeoneSMSan MarinoSNSenegalSRSurinameSTSão Tomé and PrÃncipeSVEl SalvadorSXSint MaartenSZSwazilandTCTurks and Caicos IslandsTDChadTFFrench Southern and Antarctic LandsTGTogoTHThailandTJTajikistanTKTokelauTLTimor-LesteTMTurkmenistanTNTunisiaTOTongaTRTurkeyTTTrinidad and TobagoTVTuvaluTWTaiwanTZTanzaniaUAUkraineUGUgandaUMUnited States Minor Outlying IslandsUSUnited StatesUYUruguayUZUzbekistanVAHoly See (Vatican City)VCSaint Vincent and the GrenadinesVGBritish Virgin IslandsVIU.S. Virgin IslandsVNVietnamVUVanuatuWFWallis and FutunaWSSamoaXKKosovoYTMayotteZASouth AfricaZMZambia
custom_dataobject | nullrequired
Example:
{"customer_reference_id":"abcd1234"}Your own structured key-value data.
statusstringrequired
Default:
activeWhether this entity can be used in Paddle.
Values
activeEntity is active and can be used.archivedEntity is archived, so can't be used.
created_atstring (date-time)required
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
updated_atstring (date-time)required
Example:
2024-10-13T07:20:50.52ZRFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
import_metaobject | nullrequired
Import information for this entity.
null if this entity is not imported.external_idstring | null
Example:
9b95b0b8-e10f-441a-862e-1936a6d818abReference or identifier for this entity from the provider where it was imported from.
Length: 1–200
imported_fromstringrequired
Example:
paddle_classicName of the platform or provider where this entity was imported from.
Length: 1–200
Billing cycle updated
Details specific to
subscription_billing_cycle_updated actions.actionstringrequired
What happened on the subscription.
Values
subscription_billing_cycle_updatedThe billing cycle that sets how often the subscription renews was changed.
billing_cycleobjectrequired
Updated billing cycle of the subscription. This is what the billing cycle was changed to.
intervalstringrequired
Unit of time.
Values
dayweekmonthyear
frequencyintegerrequired
Amount of time.
Min: 1
current_billing_periodobjectrequired
Billing period of the subscription after the billing cycle was updated.
starts_atstring (date-time)required
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when this period starts.
ends_atstring (date-time)required
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when this period ends.
next_billed_atstring (date-time) | nullrequired
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when the subscription was next scheduled to be billed after the billing cycle was updated.
null if the subscription has no next billing date (for example, paused without a scheduled resume).Billing date updated
Details specific to
subscription_billing_date_updated actions.actionstringrequired
What happened on the subscription.
Values
subscription_billing_date_updatedThe date the subscription next renews was changed.
next_billed_atstring (date-time) | nullrequired
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of the updated billing date.
null when the subscription has no upcoming billing date, for example when a scheduled pause or cancellation means it will not be billed again.current_billing_periodobjectrequired
Billing period of the subscription after the billing date was updated.
starts_atstring (date-time)required
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when this period starts.
ends_atstring (date-time)required
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when this period ends.
transaction_idstring | nullrequired
Example:
txn_01h04vsbhqc62t8hmd4z3b578cPaddle ID of the transaction created as a result of the billing date change, prefixed with
txn_. null if no transaction was created.Pattern:
^txn_[a-z\d]{26}$proration_billing_modestringrequired
How proration was calculated for this billing date change.
Values
prorated_immediatelyPaddle calculates the prorated amount for the subscription changes based on the current billing cycle, then creates a transaction to collect immediately.prorated_next_billing_periodPaddle calculates the prorated amount for the subscription changes based on the current billing cycle, then schedules them to be billed on the next renewal.full_immediatelyPaddle does not calculate proration for the subscription changes, creating a transaction to collect for the full amount immediately.full_next_billing_periodPaddle does not calculate proration for the subscription changes, scheduling for the full amount for the changes to be billed on the next renewal.do_not_billPaddle does not bill for the subscription changes.
Billing details updated
Details specific to
subscription_billing_details_updated actions.actionstringrequired
What happened on the subscription.
Values
subscription_billing_details_updatedThe billing details for the subscription's invoices were changed.
billing_detailsobjectrequired
Updated billing details on the subscription. This is what the billing details were changed to.
enable_checkoutbooleanrequired
Default:
falseWhether the related transaction may be paid using Paddle Checkout. If omitted when creating a transaction, defaults to
false.purchase_order_numberstringrequired
Customer purchase order number. Appears on invoice documents.
Max length: 100
additional_informationstring | nullrequired
Notes or other information to include on this invoice. Appears on invoice documents.
Max length: 1500
payment_termsobjectrequired
How long a customer has to pay this invoice once issued.
intervalstringrequired
Unit of time.
Values
dayweekmonthyear
frequencyintegerrequired
Amount of time.
Min: 1
Business added
Details specific to
subscription_business_added actions.actionstringrequired
What happened on the subscription.
Values
subscription_business_addedA business was added to the subscription.
businessobjectrequired
New business on the subscription.
idstringrequired
Example:
biz_01grrebrzaee2qj2fqqhmcyzajUnique Paddle ID for this business entity, prefixed with
biz_.Pattern:
^biz_[a-z\d]{26}$customer_idstringrequired
Example:
ctm_01grnn4zta5a1mf02jjze7y2ysPaddle ID for the customer related to this business, prefixed with
cus_.Pattern:
^ctm_[a-z\d]{26}$namestringrequired
Name of this business.
Length: 1–1024
company_numberstring | nullrequired
Example:
123456789Company number for this business.
Max length: 1024
tax_identifierstring | nullrequired
Example:
AB0123456789Tax or VAT Number for this business.
Max length: 1024
statusstringrequired
Default:
activeWhether this entity can be used in Paddle.
Values
activeEntity is active and can be used.archivedEntity is archived, so can't be used.
contactsarrayrequired
List of contacts related to this business, typically used for sending invoices.
Items: max 100, unique
namestringrequired
Full name of this contact.
Max length: 1024
emailstring (email)required
Example:
test@paddle.comEmail address for this contact.
Length: 1–320
created_atstring (date-time)required
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
updated_atstring (date-time)required
Example:
2024-10-13T07:20:50.52ZRFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
custom_dataobject | nullrequired
Example:
{"customer_reference_id":"abcd1234"}Your own structured key-value data.
import_metaobject | nullrequired
Import information for this entity.
null if this entity is not imported.external_idstring | null
Example:
9b95b0b8-e10f-441a-862e-1936a6d818abReference or identifier for this entity from the provider where it was imported from.
Length: 1–200
imported_fromstringrequired
Example:
paddle_classicName of the platform or provider where this entity was imported from.
Length: 1–200
Business removed
Details specific to
subscription_business_removed actions.actionstringrequired
What happened on the subscription.
Values
subscription_business_removedThe business was removed from the subscription.
businessobjectrequired
Business that was removed from the subscription.
idstringrequired
Example:
biz_01grrebrzaee2qj2fqqhmcyzajUnique Paddle ID for this business entity, prefixed with
biz_.Pattern:
^biz_[a-z\d]{26}$customer_idstringrequired
Example:
ctm_01grnn4zta5a1mf02jjze7y2ysPaddle ID for the customer related to this business, prefixed with
cus_.Pattern:
^ctm_[a-z\d]{26}$namestringrequired
Name of this business.
Length: 1–1024
company_numberstring | nullrequired
Example:
123456789Company number for this business.
Max length: 1024
tax_identifierstring | nullrequired
Example:
AB0123456789Tax or VAT Number for this business.
Max length: 1024
statusstringrequired
Default:
activeWhether this entity can be used in Paddle.
Values
activeEntity is active and can be used.archivedEntity is archived, so can't be used.
contactsarrayrequired
List of contacts related to this business, typically used for sending invoices.
Items: max 100, unique
namestringrequired
Full name of this contact.
Max length: 1024
emailstring (email)required
Example:
test@paddle.comEmail address for this contact.
Length: 1–320
created_atstring (date-time)required
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
updated_atstring (date-time)required
Example:
2024-10-13T07:20:50.52ZRFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
custom_dataobject | nullrequired
Example:
{"customer_reference_id":"abcd1234"}Your own structured key-value data.
import_metaobject | nullrequired
Import information for this entity.
null if this entity is not imported.external_idstring | null
Example:
9b95b0b8-e10f-441a-862e-1936a6d818abReference or identifier for this entity from the provider where it was imported from.
Length: 1–200
imported_fromstringrequired
Example:
paddle_classicName of the platform or provider where this entity was imported from.
Length: 1–200
Business updated
Details specific to
subscription_business_updated actions.actionstringrequired
What happened on the subscription.
Values
subscription_business_updatedThe business on the subscription was changed.
businessobjectrequired
Updated business on the subscription. This is what the business was changed to.
idstringrequired
Example:
biz_01grrebrzaee2qj2fqqhmcyzajUnique Paddle ID for this business entity, prefixed with
biz_.Pattern:
^biz_[a-z\d]{26}$customer_idstringrequired
Example:
ctm_01grnn4zta5a1mf02jjze7y2ysPaddle ID for the customer related to this business, prefixed with
cus_.Pattern:
^ctm_[a-z\d]{26}$namestringrequired
Name of this business.
Length: 1–1024
company_numberstring | nullrequired
Example:
123456789Company number for this business.
Max length: 1024
tax_identifierstring | nullrequired
Example:
AB0123456789Tax or VAT Number for this business.
Max length: 1024
statusstringrequired
Default:
activeWhether this entity can be used in Paddle.
Values
activeEntity is active and can be used.archivedEntity is archived, so can't be used.
contactsarrayrequired
List of contacts related to this business, typically used for sending invoices.
Items: max 100, unique
namestringrequired
Full name of this contact.
Max length: 1024
emailstring (email)required
Example:
test@paddle.comEmail address for this contact.
Length: 1–320
created_atstring (date-time)required
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
updated_atstring (date-time)required
Example:
2024-10-13T07:20:50.52ZRFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
custom_dataobject | nullrequired
Example:
{"customer_reference_id":"abcd1234"}Your own structured key-value data.
import_metaobject | nullrequired
Import information for this entity.
null if this entity is not imported.external_idstring | null
Example:
9b95b0b8-e10f-441a-862e-1936a6d818abReference or identifier for this entity from the provider where it was imported from.
Length: 1–200
imported_fromstringrequired
Example:
paddle_classicName of the platform or provider where this entity was imported from.
Length: 1–200
Canceled
Details specific to
subscription_canceled actions.actionstringrequired
What happened on the subscription.
Values
subscription_canceledThe subscription's status becamecanceled.
effective_fromstring | nullrequired
Whether the subscription was canceled immediately, or scheduled to cancel.
Values
immediatelyThe subscription was canceled immediately.next_billing_periodThe subscription was scheduled to cancel at the next billing period.
Collection mode updated
Details specific to
subscription_collection_mode_updated actions.actionstringrequired
What happened on the subscription.
Values
subscription_collection_mode_updatedHow the subscription is collected, automatically or manually, was changed.
collection_modestringrequired
How payment is collected for this subscription. This is what the collection mode was changed to.
Values
automaticPayment is collected automatically using a checkout initially, then using a payment method on file.manualPayment is collected manually. Customers are sent an invoice with payment terms and can make a payment offline or using a checkout. Requiresbilling_details.
Consent requirement granted
Details specific to
subscription_consent_requirement_granted actions.actionstringrequired
What happened on the subscription.
Values
subscription_consent_requirement_grantedA consent requirement on the subscription was granted.
consent_requirementobjectrequired
Details about the consent requirement that was granted.
idstringrequired
Example:
subconreq_01gm302t81w94gyjpjpqypkzkfUnique Paddle ID for this subscription consent requirement entity, prefixed with
subconreq_.Pattern:
^subconreq_[a-z\d]{26}$requirementstringrequired
Type of consent required for successful renewal.
Values
trial_endingConsent required because the trial period is ending.introductory_discount_endingConsent required because an initial discount is ending.
statusstringrequired
Status of this consent requirement.
Values
pendingConsent not yet granted. Subscription is canceled on next renewal.grantedConsent granted. Subscription renews normally.voidedConsent voided. Consent requirement is no longer applicable, either because the consent is no longer required, or another consent requirement has replaced it.
created_atstring (date-time)required
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
consent_periodobject | nullrequired
Period during which consent for this subscription can be granted.
null if there is no next_billed_at or the consent requirement does not apply to the current billing period.starts_atstring (date-time)required
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when this period starts.
ends_atstring (date-time)required
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when this period ends.
granted_atstring (date-time) | nullrequired
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when the customer granted their consent.
null if not yet granted.voided_atstring (date-time) | nullrequired
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when consent was voided or no longer required.
null if not voided.Created
Details specific to
subscription_created actions.actionstringrequired
What happened on the subscription.
Values
subscription_createdThe subscription was created.
statusstring | nullrequired
Status of the subscription when it was created.
null if created before history recording began and this couldn't be determined.Values
activeSubscription is active. Paddle is billing for this subscription and related transactions aren't past due.canceledSubscription is canceled. Automatically set by Paddle when a subscription is canceled. When a subscription is set to cancel on the next billing period, a scheduled change for the cancellation is created. The subscription status moves to canceled when the scheduled change takes effect.past_dueSubscription has an overdue payment. Automatically set by Paddle when payment fails for an automatically-collected transaction, or when payment terms have elapsed for a manually-collected transaction (an invoice).pausedSubscription is paused. Automatically set by Paddle when a subscription is paused. When a subscription is set to pause on the next billing period, a scheduled change for the pause is created. The subscription status moves topausedwhen the scheduled change takes effect.trialingSubscription is in trial.
collection_modestring | nullrequired
The collection mode of the subscription when it was created.
Values
automaticPayment is collected automatically using a checkout initially, then using a payment method on file.manualPayment is collected manually. Customers are sent an invoice with payment terms and can make a payment offline or using a checkout. Requiresbilling_details.
billing_detailsobject | nullrequired
Details for invoicing. Only returned for manually-collected subscriptions (
collection_mode: manual).enable_checkoutbooleanrequired
Default:
falseWhether the related transaction may be paid using Paddle Checkout. If omitted when creating a transaction, defaults to
false.purchase_order_numberstringrequired
Customer purchase order number. Appears on invoice documents.
Max length: 100
additional_informationstring | nullrequired
Notes or other information to include on this invoice. Appears on invoice documents.
Max length: 1500
payment_termsobjectrequired
How long a customer has to pay this invoice once issued.
intervalstringrequired
Unit of time.
Values
dayweekmonthyear
frequencyintegerrequired
Amount of time.
Min: 1
customerobject | nullrequired
Customer for the subscription when it was created.
idstringrequired
Example:
ctm_01grnn4zta5a1mf02jjze7y2ysUnique Paddle ID for this customer entity, prefixed with
ctm_.Pattern:
^ctm_[a-z\d]{26}$namestring | nullrequired
Full name of this customer. Required when creating transactions where
collection_mode is manual (invoices).Max length: 1024
emailstring (email)required
Example:
test@paddle.comEmail address for this customer.
Length: 1–320
marketing_consentbooleanrequired
Default:
falseWhether this customer opted into marketing from you.
false unless customers check the marketing consent box
when using Paddle Checkout. Set automatically by Paddle.statusstringrequired
Default:
activeWhether this entity can be used in Paddle.
Values
activeEntity is active and can be used.archivedEntity is archived, so can't be used.
custom_dataobject | nullrequired
Example:
{"customer_reference_id":"abcd1234"}Your own structured key-value data.
localestringrequired
Default:
enValid IETF BCP 47 short form locale tag. If omitted, defaults to
en.created_atstring (date-time)required
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
updated_atstring (date-time)required
Example:
2024-10-13T07:20:50.52ZRFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
import_metaobject | nullrequired
Import information for this entity.
null if this entity is not imported.external_idstring | null
Example:
9b95b0b8-e10f-441a-862e-1936a6d818abReference or identifier for this entity from the provider where it was imported from.
Length: 1–200
imported_fromstringrequired
Example:
paddle_classicName of the platform or provider where this entity was imported from.
Length: 1–200
addressobject | nullrequired
Address for the subscription when it was created.
idstringrequired
Example:
add_01gm302t81w94gyjpjpqypkzkfUnique Paddle ID for this address entity, prefixed with
add_.Pattern:
^add_[a-z\d]{26}$customer_idstringrequired
Example:
ctm_01grnn4zta5a1mf02jjze7y2ysPaddle ID for the customer related to this address, prefixed with
cus_.Pattern:
^ctm_[a-z\d]{26}$descriptionstring | nullrequired
Example:
Paddle.comMemorable description for this address.
Max length: 1024
first_linestring | nullrequired
Example:
3811 Ditmars BlvdFirst line of this address.
Max length: 1024
second_linestring | nullrequired
Second line of this address.
Max length: 1024
citystring | nullrequired
Example:
AstoriaCity of this address.
Max length: 200
postal_codestring | nullrequired
Example:
11105-1803ZIP or postal code of this address. Required for some countries.
Max length: 200
regionstring | nullrequired
Example:
NYState, county, or region of this address.
Max length: 200
country_codestringrequired
Supported two-letter ISO 3166-1 alpha-2 country code for this address.
Values
ADAndorraAEUnited Arab EmiratesAGAntigua and BarbudaAIAnguillaALAlbania
+ Show all values− Hide values
AMArmeniaAOAngolaARArgentinaASAmerican SamoaATAustriaAUAustraliaAWArubaAXÃ…land IslandsAZAzerbaijanBABosnia and HerzegovinaBBBarbadosBDBangladeshBEBelgiumBFBurkina FasoBGBulgariaBHBahrainBIBurundiBJBeninBLSaint BarthélemyBMBermudaBNBruneiBOBoliviaBQCaribbean Netherlands (Bonaire, Sint Eustatius, and Saba)BRBrazilBSBahamasBTBhutanBVBouvet IslandBWBotswanaBZBelizeCACanadaCCCocos IslandsCGRepublic of CongoCHSwitzerlandCICôte d'Ivoire (Ivory Coast)CKCook IslandsCLChileCMCameroonCNChinaCOColombiaCRCosta RicaCVCape VerdeCWCuraçaoCXChristmas IslandCYCyprusCZCzechia (Czech Republic)DEGermanyDJDjiboutiDKDenmarkDMDominicaDODominican RepublicDZAlgeriaECEcuadorEEEstoniaEGEgyptEHWestern SaharaEREritreaESSpainETEthiopiaFIFinlandFJFijiFKFalkland IslandsFMMicronesiaFOFaroe IslandsFRFranceGAGabonGBUnited KingdomGDGrenadaGEGeorgiaGFFrench GuianaGGGuernseyGHGhanaGIGibraltarGLGreenlandGMGambiaGNGuineaGPGuadeloupeGQEquatorial GuineaGRGreeceGSSouth Georgia and the South Sandwich IslandsGTGuatemalaGUGuamGWGuinea-BissauGYGuyanaHKHong KongHMHeard Island and McDonald IslandsHNHondurasHRCroatiaHUHungaryIDIndonesiaIEIrelandILIsraelIMIsle of ManINIndiaIOBritish Indian Ocean TerritoryIQIraqISIcelandITItalyJEJerseyJMJamaicaJOJordanJPJapanKEKenyaKGKyrgyzstanKHCambodiaKIKiribatiKMComorosKNSaint Kitts and NevisKRSouth KoreaKWKuwaitKYCayman IslandsKZKazakhstanLALao People's Democratic Republic (Laos)LBLebanonLCSaint LuciaLILiechtensteinLKSri LankaLRLiberiaLSLesothoLTLithuaniaLULuxembourgLVLatviaMAMoroccoMCMonacoMDMoldovaMEMontenegroMFSaint MartinMGMadagascarMHMarshall IslandsMKMacedoniaMNMongoliaMOMacaoMPNorthern Mariana IslandsMQMartiniqueMRMauritaniaMSMontserratMTMaltaMUMauritiusMVMaldivesMWMalawiMXMexicoMYMalaysiaMZMozambiqueNANamibiaNCNew CaledoniaNENigerNFNorfolk IslandNGNigeriaNLNetherlandsNONorwayNPNepalNRNauruNUNiueNZNew ZealandOMOmanPAPanamaPEPeruPFFrench PolynesiaPGPapua New GuineaPHPhilippinesPKPakistanPLPolandPMSaint Pierre and MiquelonPNPitcairnPRPuerto RicoPSPalestinian territoriesPTPortugalPWPalauPYParaguayQAQatarREReunionRORomaniaRSRepublic of SerbiaRWRwandaSASaudi ArabiaSBSolomon IslandsSCSeychellesSESwedenSGSingaporeSHSaint HelenaSISloveniaSJSvalbard and Jan MayenSKSlovakiaSLSierra LeoneSMSan MarinoSNSenegalSRSurinameSTSão Tomé and PrÃncipeSVEl SalvadorSXSint MaartenSZSwazilandTCTurks and Caicos IslandsTDChadTFFrench Southern and Antarctic LandsTGTogoTHThailandTJTajikistanTKTokelauTLTimor-LesteTMTurkmenistanTNTunisiaTOTongaTRTurkeyTTTrinidad and TobagoTVTuvaluTWTaiwanTZTanzaniaUAUkraineUGUgandaUMUnited States Minor Outlying IslandsUSUnited StatesUYUruguayUZUzbekistanVAHoly See (Vatican City)VCSaint Vincent and the GrenadinesVGBritish Virgin IslandsVIU.S. Virgin IslandsVNVietnamVUVanuatuWFWallis and FutunaWSSamoaXKKosovoYTMayotteZASouth AfricaZMZambia
custom_dataobject | nullrequired
Example:
{"customer_reference_id":"abcd1234"}Your own structured key-value data.
statusstringrequired
Default:
activeWhether this entity can be used in Paddle.
Values
activeEntity is active and can be used.archivedEntity is archived, so can't be used.
created_atstring (date-time)required
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
updated_atstring (date-time)required
Example:
2024-10-13T07:20:50.52ZRFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
import_metaobject | nullrequired
Import information for this entity.
null if this entity is not imported.external_idstring | null
Example:
9b95b0b8-e10f-441a-862e-1936a6d818abReference or identifier for this entity from the provider where it was imported from.
Length: 1–200
imported_fromstringrequired
Example:
paddle_classicName of the platform or provider where this entity was imported from.
Length: 1–200
businessobject | nullrequired
Business for the subscription when it was created.
idstringrequired
Example:
biz_01grrebrzaee2qj2fqqhmcyzajUnique Paddle ID for this business entity, prefixed with
biz_.Pattern:
^biz_[a-z\d]{26}$customer_idstringrequired
Example:
ctm_01grnn4zta5a1mf02jjze7y2ysPaddle ID for the customer related to this business, prefixed with
cus_.Pattern:
^ctm_[a-z\d]{26}$namestringrequired
Name of this business.
Length: 1–1024
company_numberstring | nullrequired
Example:
123456789Company number for this business.
Max length: 1024
tax_identifierstring | nullrequired
Example:
AB0123456789Tax or VAT Number for this business.
Max length: 1024
statusstringrequired
Default:
activeWhether this entity can be used in Paddle.
Values
activeEntity is active and can be used.archivedEntity is archived, so can't be used.
contactsarrayrequired
List of contacts related to this business, typically used for sending invoices.
Items: max 100, unique
namestringrequired
Full name of this contact.
Max length: 1024
emailstring (email)required
Example:
test@paddle.comEmail address for this contact.
Length: 1–320
created_atstring (date-time)required
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
updated_atstring (date-time)required
Example:
2024-10-13T07:20:50.52ZRFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
custom_dataobject | nullrequired
Example:
{"customer_reference_id":"abcd1234"}Your own structured key-value data.
import_metaobject | nullrequired
Import information for this entity.
null if this entity is not imported.external_idstring | null
Example:
9b95b0b8-e10f-441a-862e-1936a6d818abReference or identifier for this entity from the provider where it was imported from.
Length: 1–200
imported_fromstringrequired
Example:
paddle_classicName of the platform or provider where this entity was imported from.
Length: 1–200
currency_codestring | nullrequired
Supported three-letter ISO 4217 currency code of the subscription when it was created.
Values
USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
current_billing_periodobject | nullrequired
Current billing period of the subscription when it was created.
starts_atstring (date-time)required
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when this period starts.
ends_atstring (date-time)required
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when this period ends.
billing_cycleobject | nullrequired
Billing cycle of the subscription when it was created.
intervalstringrequired
Unit of time.
Values
dayweekmonthyear
frequencyintegerrequired
Amount of time.
Min: 1
itemsarray | nullrequired
Items on the subscription when it was created.
priceobjectrequired
Price on the subscription.
idstringrequired
Example:
pri_01gsz8z1q1n00f12qt82y31smhUnique Paddle ID for this price, prefixed with
pri_.Pattern:
^pri_[a-z\d]{26}$product_idstringrequired
Example:
pro_01gsz97mq9pa4fkyy0wqenepkzPaddle ID for the product that this price is for, prefixed with
pro_.Pattern:
^pro_[a-z\d]{26}$descriptionstringrequired
Internal description for this price, not shown to customers. Typically notes for your team.
Length: 2–500
typestringrequired
Default:
standardType of item. Standard items are considered part of your catalog and are shown in the Paddle dashboard.
Values
customNon-catalog item. Typically created for a specific transaction or subscription. Not returned when listing or shown in the Paddle dashboard.standardStandard item. Can be considered part of your catalog and reused across transactions and subscriptions easily.
namestring | nullrequired
Name of this price, shown to customers at checkout and on invoices. Typically describes how often the related product bills.
Length: 1–150
billing_cycleobject | nullrequired
How often this price should be charged.
null if price is non-recurring (one-time).intervalstringrequired
Unit of time.
Values
dayweekmonthyear
frequencyintegerrequired
Amount of time.
Min: 1
trial_periodobject | nullrequired
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.intervalstringrequired
Unit of time.
Values
dayweekmonthyear
frequencyintegerrequired
Amount of time.
Min: 1
requires_payment_methodbooleanrequired
Default:
trueWhether this price requires a payment method (
true) or not (false) when trialing. If false, customers can sign up for subscription without entering their payment details, often referred to as a "cardless trial."unit_priceobject | null
Trial price. Customers are billed this amount for the duration of the trial period. Applies to all customers except those in countries with
unit_price_overrides. If null, customers are not charged during the trial.amountstringrequired
Amount in the lowest denomination for the currency, e.g. 10 USD = 1000 (cents). Although represented as a string, this value must be a valid integer.
currency_codestring
Supported three-letter ISO 4217 currency code.
Values
USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
unit_price_overridesarray
List of unit price overrides for trial pricing. Use to override base trial price with a custom trial price and currency for a country or group of countries.
Items: max 250
country_codesarrayrequired
Supported two-letter ISO 3166-1 alpha-2 country code. Customers located in the listed countries are charged the override price.
Items: min 1, unique
string
Two-letter ISO 3166-1 alpha-2 representation of a supported country.
Values
ADAndorraAEUnited Arab EmiratesAGAntigua and BarbudaAIAnguillaALAlbania
+ Show all values− Hide values
AMArmeniaAOAngolaARArgentinaASAmerican SamoaATAustriaAUAustraliaAWArubaAXÃ…land IslandsAZAzerbaijanBABosnia and HerzegovinaBBBarbadosBDBangladeshBEBelgiumBFBurkina FasoBGBulgariaBHBahrainBIBurundiBJBeninBLSaint BarthélemyBMBermudaBNBruneiBOBoliviaBQCaribbean Netherlands (Bonaire, Sint Eustatius, and Saba)BRBrazilBSBahamasBTBhutanBVBouvet IslandBWBotswanaBZBelizeCACanadaCCCocos IslandsCGRepublic of CongoCHSwitzerlandCICôte d'Ivoire (Ivory Coast)CKCook IslandsCLChileCMCameroonCNChinaCOColombiaCRCosta RicaCVCape VerdeCWCuraçaoCXChristmas IslandCYCyprusCZCzechia (Czech Republic)DEGermanyDJDjiboutiDKDenmarkDMDominicaDODominican RepublicDZAlgeriaECEcuadorEEEstoniaEGEgyptEHWestern SaharaEREritreaESSpainETEthiopiaFIFinlandFJFijiFKFalkland IslandsFMMicronesiaFOFaroe IslandsFRFranceGAGabonGBUnited KingdomGDGrenadaGEGeorgiaGFFrench GuianaGGGuernseyGHGhanaGIGibraltarGLGreenlandGMGambiaGNGuineaGPGuadeloupeGQEquatorial GuineaGRGreeceGSSouth Georgia and the South Sandwich IslandsGTGuatemalaGUGuamGWGuinea-BissauGYGuyanaHKHong KongHMHeard Island and McDonald IslandsHNHondurasHRCroatiaHUHungaryIDIndonesiaIEIrelandILIsraelIMIsle of ManINIndiaIOBritish Indian Ocean TerritoryIQIraqISIcelandITItalyJEJerseyJMJamaicaJOJordanJPJapanKEKenyaKGKyrgyzstanKHCambodiaKIKiribatiKMComorosKNSaint Kitts and NevisKRSouth KoreaKWKuwaitKYCayman IslandsKZKazakhstanLALao People's Democratic Republic (Laos)LBLebanonLCSaint LuciaLILiechtensteinLKSri LankaLRLiberiaLSLesothoLTLithuaniaLULuxembourgLVLatviaMAMoroccoMCMonacoMDMoldovaMEMontenegroMFSaint MartinMGMadagascarMHMarshall IslandsMKMacedoniaMNMongoliaMOMacaoMPNorthern Mariana IslandsMQMartiniqueMRMauritaniaMSMontserratMTMaltaMUMauritiusMVMaldivesMWMalawiMXMexicoMYMalaysiaMZMozambiqueNANamibiaNCNew CaledoniaNENigerNFNorfolk IslandNGNigeriaNLNetherlandsNONorwayNPNepalNRNauruNUNiueNZNew ZealandOMOmanPAPanamaPEPeruPFFrench PolynesiaPGPapua New GuineaPHPhilippinesPKPakistanPLPolandPMSaint Pierre and MiquelonPNPitcairnPRPuerto RicoPSPalestinian territoriesPTPortugalPWPalauPYParaguayQAQatarREReunionRORomaniaRSRepublic of SerbiaRWRwandaSASaudi ArabiaSBSolomon IslandsSCSeychellesSESwedenSGSingaporeSHSaint HelenaSISloveniaSJSvalbard and Jan MayenSKSlovakiaSLSierra LeoneSMSan MarinoSNSenegalSRSurinameSTSão Tomé and PrÃncipeSVEl SalvadorSXSint MaartenSZSwazilandTCTurks and Caicos IslandsTDChadTFFrench Southern and Antarctic LandsTGTogoTHThailandTJTajikistanTKTokelauTLTimor-LesteTMTurkmenistanTNTunisiaTOTongaTRTurkeyTTTrinidad and TobagoTVTuvaluTWTaiwanTZTanzaniaUAUkraineUGUgandaUMUnited States Minor Outlying IslandsUSUnited StatesUYUruguayUZUzbekistanVAHoly See (Vatican City)VCSaint Vincent and the GrenadinesVGBritish Virgin IslandsVIU.S. Virgin IslandsVNVietnamVUVanuatuWFWallis and FutunaWSSamoaXKKosovoYTMayotteZASouth AfricaZMZambia
unit_priceobjectrequired
Override price. This price applies to customers located in the countries for this unit price override.
amountstringrequired
Amount in the lowest denomination for the currency, e.g. 10 USD = 1000 (cents). Although represented as a string, this value must be a valid integer.
currency_codestring
Supported three-letter ISO 4217 currency code.
Values
USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
tax_modestringrequired
Default:
account_settingHow tax is calculated for this price.
Values
account_settingPrices use the setting from your account.externalPrices are exclusive of tax.internalPrices are inclusive of tax.locationPrices are inclusive or exclusive of tax, depending on the country of the transaction.
unit_priceobjectrequired
Base price. This price applies to all customers, except for customers located in countries where you have
unit_price_overrides.amountstringrequired
Amount in the lowest denomination for the currency, e.g. 10 USD = 1000 (cents). Although represented as a string, this value must be a valid integer.
currency_codestringrequired
Supported three-letter ISO 4217 currency code.
Values
USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
unit_price_overridesarrayrequired
List of unit price overrides. Use to override the base price with a custom price and currency for a country or group of countries.
Items: max 250
country_codesarrayrequired
Supported two-letter ISO 3166-1 alpha-2 country code. Customers located in the listed countries are charged the override price.
Items: min 1, unique
string
Two-letter ISO 3166-1 alpha-2 representation of a supported country.
Values
ADAndorraAEUnited Arab EmiratesAGAntigua and BarbudaAIAnguillaALAlbania
+ Show all values− Hide values
AMArmeniaAOAngolaARArgentinaASAmerican SamoaATAustriaAUAustraliaAWArubaAXÃ…land IslandsAZAzerbaijanBABosnia and HerzegovinaBBBarbadosBDBangladeshBEBelgiumBFBurkina FasoBGBulgariaBHBahrainBIBurundiBJBeninBLSaint BarthélemyBMBermudaBNBruneiBOBoliviaBQCaribbean Netherlands (Bonaire, Sint Eustatius, and Saba)BRBrazilBSBahamasBTBhutanBVBouvet IslandBWBotswanaBZBelizeCACanadaCCCocos IslandsCGRepublic of CongoCHSwitzerlandCICôte d'Ivoire (Ivory Coast)CKCook IslandsCLChileCMCameroonCNChinaCOColombiaCRCosta RicaCVCape VerdeCWCuraçaoCXChristmas IslandCYCyprusCZCzechia (Czech Republic)DEGermanyDJDjiboutiDKDenmarkDMDominicaDODominican RepublicDZAlgeriaECEcuadorEEEstoniaEGEgyptEHWestern SaharaEREritreaESSpainETEthiopiaFIFinlandFJFijiFKFalkland IslandsFMMicronesiaFOFaroe IslandsFRFranceGAGabonGBUnited KingdomGDGrenadaGEGeorgiaGFFrench GuianaGGGuernseyGHGhanaGIGibraltarGLGreenlandGMGambiaGNGuineaGPGuadeloupeGQEquatorial GuineaGRGreeceGSSouth Georgia and the South Sandwich IslandsGTGuatemalaGUGuamGWGuinea-BissauGYGuyanaHKHong KongHMHeard Island and McDonald IslandsHNHondurasHRCroatiaHUHungaryIDIndonesiaIEIrelandILIsraelIMIsle of ManINIndiaIOBritish Indian Ocean TerritoryIQIraqISIcelandITItalyJEJerseyJMJamaicaJOJordanJPJapanKEKenyaKGKyrgyzstanKHCambodiaKIKiribatiKMComorosKNSaint Kitts and NevisKRSouth KoreaKWKuwaitKYCayman IslandsKZKazakhstanLALao People's Democratic Republic (Laos)LBLebanonLCSaint LuciaLILiechtensteinLKSri LankaLRLiberiaLSLesothoLTLithuaniaLULuxembourgLVLatviaMAMoroccoMCMonacoMDMoldovaMEMontenegroMFSaint MartinMGMadagascarMHMarshall IslandsMKMacedoniaMNMongoliaMOMacaoMPNorthern Mariana IslandsMQMartiniqueMRMauritaniaMSMontserratMTMaltaMUMauritiusMVMaldivesMWMalawiMXMexicoMYMalaysiaMZMozambiqueNANamibiaNCNew CaledoniaNENigerNFNorfolk IslandNGNigeriaNLNetherlandsNONorwayNPNepalNRNauruNUNiueNZNew ZealandOMOmanPAPanamaPEPeruPFFrench PolynesiaPGPapua New GuineaPHPhilippinesPKPakistanPLPolandPMSaint Pierre and MiquelonPNPitcairnPRPuerto RicoPSPalestinian territoriesPTPortugalPWPalauPYParaguayQAQatarREReunionRORomaniaRSRepublic of SerbiaRWRwandaSASaudi ArabiaSBSolomon IslandsSCSeychellesSESwedenSGSingaporeSHSaint HelenaSISloveniaSJSvalbard and Jan MayenSKSlovakiaSLSierra LeoneSMSan MarinoSNSenegalSRSurinameSTSão Tomé and PrÃncipeSVEl SalvadorSXSint MaartenSZSwazilandTCTurks and Caicos IslandsTDChadTFFrench Southern and Antarctic LandsTGTogoTHThailandTJTajikistanTKTokelauTLTimor-LesteTMTurkmenistanTNTunisiaTOTongaTRTurkeyTTTrinidad and TobagoTVTuvaluTWTaiwanTZTanzaniaUAUkraineUGUgandaUMUnited States Minor Outlying IslandsUSUnited StatesUYUruguayUZUzbekistanVAHoly See (Vatican City)VCSaint Vincent and the GrenadinesVGBritish Virgin IslandsVIU.S. Virgin IslandsVNVietnamVUVanuatuWFWallis and FutunaWSSamoaXKKosovoYTMayotteZASouth AfricaZMZambia
unit_priceobjectrequired
Override price. This price applies to customers located in the countries for this unit price override.
amountstringrequired
Amount in the lowest denomination for the currency, e.g. 10 USD = 1000 (cents). Although represented as a string, this value must be a valid integer.
currency_codestringrequired
Supported three-letter ISO 4217 currency code.
Values
USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
quantityobjectrequired
Example:
{"minimum":1,"maximum":100}Limits on how many times the related product can be purchased at this price. Useful for discount campaigns.
minimumintegerrequired
Default:
1Example:
1Minimum quantity of the product related to this price that can be bought. Required if
maximum set.Range: 1–999999999
maximumintegerrequired
Default:
100Example:
100Maximum quantity of the product related to this price that can be bought. Required if
minimum set. Must be greater than or equal to the minimum value.Range: 1–999999999
statusstringrequired
Default:
activeWhether this entity can be used in Paddle.
Values
activeEntity is active and can be used.archivedEntity is archived, so can't be used.
custom_dataobject | nullrequired
Example:
{"customer_reference_id":"abcd1234"}Your own structured key-value data.
import_metaobject | nullrequired
Import information for this entity.
null if this entity is not imported.external_idstring | null
Example:
9b95b0b8-e10f-441a-862e-1936a6d818abReference or identifier for this entity from the provider where it was imported from.
Length: 1–200
imported_fromstringrequired
Example:
paddle_classicName of the platform or provider where this entity was imported from.
Length: 1–200
created_atstring (date-time)required
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
updated_atstring (date-time)required
Example:
2024-10-13T07:20:50.52ZRFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
quantityintegerrequired
Quantity of the item on the subscription at the time of the history entry.
custom_dataobject | nullrequired
Example:
{"customer_reference_id":"abcd1234"}Custom data of the subscription when it was created.
discountobject | nullrequired
Discount attached to the subscription when it was created.
discountobjectrequired
Discount on the subscription.
idstringrequired
Example:
dsc_01gv5kpg05xp104ek2fmgjwttfUnique Paddle ID for this discount, prefixed with
dsc_.Pattern:
^dsc_[a-z\d]{26}$statusstringrequired
Default:
activeWhether this entity can be used in Paddle.
Values
activeEntity is active and can be used.archivedEntity is archived, so can't be used.
descriptionstringrequired
Short description for this discount for your reference. Not shown to customers.
Length: 1–500
enabled_for_checkoutbooleanrequired
Default:
trueWhether this discount can be redeemed by customers at checkout (
true) or not (false).codestring | nullrequired
Unique code that customers can use to redeem this discount at checkout. Not case-sensitive.
Length: 1–32
Pattern:
^[a-zA-Z0-9]{1,32}$typestringrequired
Type of discount. Determines how this discount impacts the checkout or transaction total.
Values
flatDiscounts a checkout or transaction by a flat amount, for example -$100. Requirescurrency_code.flat_per_seatDiscounts a checkout or transaction by a flat amount per unit, for example -$100 per user. Requirescurrency_code.percentageDiscounts a checkout or transaction by a percentage of the total, for example -10%. Maximum 100%.
modestringrequired
Default:
standardDiscount mode. Standard discounts are considered part of your catalog and are shown in the Paddle dashboard.
Values
standardStandard discount. Can be considered part of your catalog and reused across transactions and subscriptions easily.customNon-catalog discount. Can be created via the API, or by Paddle for checkout recovery discounts. Not returned when listing or shown in the Paddle dashboard.
amountstringrequired
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_codestring | nullrequired
Supported three-letter ISO 4217 currency code. Required where discount type is
flat or flat_per_seat.Values
USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
recurbooleanrequired
Default:
falseWhether this discount applies for multiple subscription billing periods (
true) or not (false).maximum_recurring_intervalsinteger | nullrequired
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.
Min: 1
usage_limitinteger | nullrequired
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.
Min: 1
restrict_toarray | nullrequired
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.Items: unique
expires_atstring (date-time) | nullrequired
Example:
2024-10-12T07:20:50.52ZRFC 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_dataobject | nullrequired
Example:
{"customer_reference_id":"abcd1234"}Your own structured key-value data.
times_usedintegerrequired
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.
discount_group_idstring | nullrequired
Example:
dsg_01js2gqehzccfkywgx1jk2mtspPaddle ID for the discount group related to this discount, prefixed with
dsg_. null if not in a discount group.Pattern:
^dsg_[a-z\d]{26}$created_atstring (date-time)required
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
updated_atstring (date-time)required
Example:
2024-10-13T07:20:50.52ZRFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
import_metaobject | nullrequired
Import information for this entity.
null if this entity is not imported.external_idstring | null
Example:
9b95b0b8-e10f-441a-862e-1936a6d818abReference or identifier for this entity from the provider where it was imported from.
Length: 1–200
imported_fromstringrequired
Example:
paddle_classicName of the platform or provider where this entity was imported from.
Length: 1–200
typestringrequired
The type of discount.
Values
recurringDiscount applies to multiple billing periods.one-offDiscount applies to a single billing period.
starts_atstring (date-time)required
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when the discount is effective from on the subscription.
ends_atstring (date-time) | nullrequired
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when the discount stops being effective on the subscription.
null if the discount does not have an end date.has_payment_methodboolean | nullrequired
Whether the subscription had a payment method when it was created.
null if this couldn't be determined.Currency updated
Details specific to
subscription_currency_updated actions.actionstringrequired
What happened on the subscription.
Values
subscription_currency_updatedThe currency the subscription is billed in was changed.
currency_codestringrequired
Updated three-letter ISO 4217 currency code for the currency on this subscription. This is what the currency was changed to.
Values
USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
Custom data updated
Details specific to
subscription_custom_data_updated actions.actionstringrequired
What happened on the subscription.
Values
subscription_custom_data_updatedThe custom data on the subscription was changed.
custom_dataobject | nullrequired
Example:
{"customer_reference_id":"abcd1234"}Updated custom data on the subscription.
null if custom data was removed. This is what the custom data was changed to.Customer updated
Details specific to
subscription_customer_updated actions.actionstringrequired
What happened on the subscription.
Values
subscription_customer_updatedThe customer the subscription belongs to was changed.
customerobjectrequired
Updated customer on the subscription. This is what the customer was changed to.
idstringrequired
Example:
ctm_01grnn4zta5a1mf02jjze7y2ysUnique Paddle ID for this customer entity, prefixed with
ctm_.Pattern:
^ctm_[a-z\d]{26}$namestring | nullrequired
Full name of this customer. Required when creating transactions where
collection_mode is manual (invoices).Max length: 1024
emailstring (email)required
Example:
test@paddle.comEmail address for this customer.
Length: 1–320
marketing_consentbooleanrequired
Default:
falseWhether this customer opted into marketing from you.
false unless customers check the marketing consent box
when using Paddle Checkout. Set automatically by Paddle.statusstringrequired
Default:
activeWhether this entity can be used in Paddle.
Values
activeEntity is active and can be used.archivedEntity is archived, so can't be used.
custom_dataobject | nullrequired
Example:
{"customer_reference_id":"abcd1234"}Your own structured key-value data.
localestringrequired
Default:
enValid IETF BCP 47 short form locale tag. If omitted, defaults to
en.created_atstring (date-time)required
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
updated_atstring (date-time)required
Example:
2024-10-13T07:20:50.52ZRFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
import_metaobject | nullrequired
Import information for this entity.
null if this entity is not imported.external_idstring | null
Example:
9b95b0b8-e10f-441a-862e-1936a6d818abReference or identifier for this entity from the provider where it was imported from.
Length: 1–200
imported_fromstringrequired
Example:
paddle_classicName of the platform or provider where this entity was imported from.
Length: 1–200
Discount added
Details specific to
subscription_discount_added actions.actionstringrequired
What happened on the subscription.
Values
subscription_discount_addedA discount was added to the subscription.
discountobjectrequired
Discount added to the subscription.
discountobjectrequired
Discount on the subscription.
idstringrequired
Example:
dsc_01gv5kpg05xp104ek2fmgjwttfUnique Paddle ID for this discount, prefixed with
dsc_.Pattern:
^dsc_[a-z\d]{26}$statusstringrequired
Default:
activeWhether this entity can be used in Paddle.
Values
activeEntity is active and can be used.archivedEntity is archived, so can't be used.
descriptionstringrequired
Short description for this discount for your reference. Not shown to customers.
Length: 1–500
enabled_for_checkoutbooleanrequired
Default:
trueWhether this discount can be redeemed by customers at checkout (
true) or not (false).codestring | nullrequired
Unique code that customers can use to redeem this discount at checkout. Not case-sensitive.
Length: 1–32
Pattern:
^[a-zA-Z0-9]{1,32}$typestringrequired
Type of discount. Determines how this discount impacts the checkout or transaction total.
Values
flatDiscounts a checkout or transaction by a flat amount, for example -$100. Requirescurrency_code.flat_per_seatDiscounts a checkout or transaction by a flat amount per unit, for example -$100 per user. Requirescurrency_code.percentageDiscounts a checkout or transaction by a percentage of the total, for example -10%. Maximum 100%.
modestringrequired
Default:
standardDiscount mode. Standard discounts are considered part of your catalog and are shown in the Paddle dashboard.
Values
standardStandard discount. Can be considered part of your catalog and reused across transactions and subscriptions easily.customNon-catalog discount. Can be created via the API, or by Paddle for checkout recovery discounts. Not returned when listing or shown in the Paddle dashboard.
amountstringrequired
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_codestring | nullrequired
Supported three-letter ISO 4217 currency code. Required where discount type is
flat or flat_per_seat.Values
USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
recurbooleanrequired
Default:
falseWhether this discount applies for multiple subscription billing periods (
true) or not (false).maximum_recurring_intervalsinteger | nullrequired
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.
Min: 1
usage_limitinteger | nullrequired
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.
Min: 1
restrict_toarray | nullrequired
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.Items: unique
expires_atstring (date-time) | nullrequired
Example:
2024-10-12T07:20:50.52ZRFC 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_dataobject | nullrequired
Example:
{"customer_reference_id":"abcd1234"}Your own structured key-value data.
times_usedintegerrequired
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.
discount_group_idstring | nullrequired
Example:
dsg_01js2gqehzccfkywgx1jk2mtspPaddle ID for the discount group related to this discount, prefixed with
dsg_. null if not in a discount group.Pattern:
^dsg_[a-z\d]{26}$created_atstring (date-time)required
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
updated_atstring (date-time)required
Example:
2024-10-13T07:20:50.52ZRFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
import_metaobject | nullrequired
Import information for this entity.
null if this entity is not imported.external_idstring | null
Example:
9b95b0b8-e10f-441a-862e-1936a6d818abReference or identifier for this entity from the provider where it was imported from.
Length: 1–200
imported_fromstringrequired
Example:
paddle_classicName of the platform or provider where this entity was imported from.
Length: 1–200
typestringrequired
The type of discount.
Values
recurringDiscount applies to multiple billing periods.one-offDiscount applies to a single billing period.
starts_atstring (date-time)required
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when the discount is effective from on the subscription.
ends_atstring (date-time) | nullrequired
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when the discount stops being effective on the subscription.
null if the discount does not have an end date.Discount expired
Details specific to
subscription_discount_expired actions. Recorded when a discount is no longer eligible — for example, when the maximum number of billing periods for the discount has been reached.actionstringrequired
What happened on the subscription.
Values
subscription_discount_expiredA discount on the subscription reached its end date and expired.
discountobjectrequired
Discount that expired on the subscription.
ends_at reflects when the discount stopped being effective on the subscription. This is the discount that was removed.discountobjectrequired
Discount on the subscription.
idstringrequired
Example:
dsc_01gv5kpg05xp104ek2fmgjwttfUnique Paddle ID for this discount, prefixed with
dsc_.Pattern:
^dsc_[a-z\d]{26}$statusstringrequired
Default:
activeWhether this entity can be used in Paddle.
Values
activeEntity is active and can be used.archivedEntity is archived, so can't be used.
descriptionstringrequired
Short description for this discount for your reference. Not shown to customers.
Length: 1–500
enabled_for_checkoutbooleanrequired
Default:
trueWhether this discount can be redeemed by customers at checkout (
true) or not (false).codestring | nullrequired
Unique code that customers can use to redeem this discount at checkout. Not case-sensitive.
Length: 1–32
Pattern:
^[a-zA-Z0-9]{1,32}$typestringrequired
Type of discount. Determines how this discount impacts the checkout or transaction total.
Values
flatDiscounts a checkout or transaction by a flat amount, for example -$100. Requirescurrency_code.flat_per_seatDiscounts a checkout or transaction by a flat amount per unit, for example -$100 per user. Requirescurrency_code.percentageDiscounts a checkout or transaction by a percentage of the total, for example -10%. Maximum 100%.
modestringrequired
Default:
standardDiscount mode. Standard discounts are considered part of your catalog and are shown in the Paddle dashboard.
Values
standardStandard discount. Can be considered part of your catalog and reused across transactions and subscriptions easily.customNon-catalog discount. Can be created via the API, or by Paddle for checkout recovery discounts. Not returned when listing or shown in the Paddle dashboard.
amountstringrequired
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_codestring | nullrequired
Supported three-letter ISO 4217 currency code. Required where discount type is
flat or flat_per_seat.Values
USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
recurbooleanrequired
Default:
falseWhether this discount applies for multiple subscription billing periods (
true) or not (false).maximum_recurring_intervalsinteger | nullrequired
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.
Min: 1
usage_limitinteger | nullrequired
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.
Min: 1
restrict_toarray | nullrequired
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.Items: unique
expires_atstring (date-time) | nullrequired
Example:
2024-10-12T07:20:50.52ZRFC 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_dataobject | nullrequired
Example:
{"customer_reference_id":"abcd1234"}Your own structured key-value data.
times_usedintegerrequired
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.
discount_group_idstring | nullrequired
Example:
dsg_01js2gqehzccfkywgx1jk2mtspPaddle ID for the discount group related to this discount, prefixed with
dsg_. null if not in a discount group.Pattern:
^dsg_[a-z\d]{26}$created_atstring (date-time)required
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
updated_atstring (date-time)required
Example:
2024-10-13T07:20:50.52ZRFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
import_metaobject | nullrequired
Import information for this entity.
null if this entity is not imported.external_idstring | null
Example:
9b95b0b8-e10f-441a-862e-1936a6d818abReference or identifier for this entity from the provider where it was imported from.
Length: 1–200
imported_fromstringrequired
Example:
paddle_classicName of the platform or provider where this entity was imported from.
Length: 1–200
typestringrequired
The type of discount.
Values
recurringDiscount applies to multiple billing periods.one-offDiscount applies to a single billing period.
starts_atstring (date-time)required
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when the discount is effective from on the subscription.
ends_atstring (date-time) | nullrequired
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when the discount stops being effective on the subscription.
null if the discount does not have an end date.Discount removed
Details specific to
subscription_discount_removed actions.actionstringrequired
What happened on the subscription.
Values
subscription_discount_removedA discount was removed from the subscription.
discountobjectrequired
Discount removed from the subscription.
discountobjectrequired
Discount on the subscription.
idstringrequired
Example:
dsc_01gv5kpg05xp104ek2fmgjwttfUnique Paddle ID for this discount, prefixed with
dsc_.Pattern:
^dsc_[a-z\d]{26}$statusstringrequired
Default:
activeWhether this entity can be used in Paddle.
Values
activeEntity is active and can be used.archivedEntity is archived, so can't be used.
descriptionstringrequired
Short description for this discount for your reference. Not shown to customers.
Length: 1–500
enabled_for_checkoutbooleanrequired
Default:
trueWhether this discount can be redeemed by customers at checkout (
true) or not (false).codestring | nullrequired
Unique code that customers can use to redeem this discount at checkout. Not case-sensitive.
Length: 1–32
Pattern:
^[a-zA-Z0-9]{1,32}$typestringrequired
Type of discount. Determines how this discount impacts the checkout or transaction total.
Values
flatDiscounts a checkout or transaction by a flat amount, for example -$100. Requirescurrency_code.flat_per_seatDiscounts a checkout or transaction by a flat amount per unit, for example -$100 per user. Requirescurrency_code.percentageDiscounts a checkout or transaction by a percentage of the total, for example -10%. Maximum 100%.
modestringrequired
Default:
standardDiscount mode. Standard discounts are considered part of your catalog and are shown in the Paddle dashboard.
Values
standardStandard discount. Can be considered part of your catalog and reused across transactions and subscriptions easily.customNon-catalog discount. Can be created via the API, or by Paddle for checkout recovery discounts. Not returned when listing or shown in the Paddle dashboard.
amountstringrequired
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_codestring | nullrequired
Supported three-letter ISO 4217 currency code. Required where discount type is
flat or flat_per_seat.Values
USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
recurbooleanrequired
Default:
falseWhether this discount applies for multiple subscription billing periods (
true) or not (false).maximum_recurring_intervalsinteger | nullrequired
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.
Min: 1
usage_limitinteger | nullrequired
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.
Min: 1
restrict_toarray | nullrequired
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.Items: unique
expires_atstring (date-time) | nullrequired
Example:
2024-10-12T07:20:50.52ZRFC 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_dataobject | nullrequired
Example:
{"customer_reference_id":"abcd1234"}Your own structured key-value data.
times_usedintegerrequired
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.
discount_group_idstring | nullrequired
Example:
dsg_01js2gqehzccfkywgx1jk2mtspPaddle ID for the discount group related to this discount, prefixed with
dsg_. null if not in a discount group.Pattern:
^dsg_[a-z\d]{26}$created_atstring (date-time)required
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
updated_atstring (date-time)required
Example:
2024-10-13T07:20:50.52ZRFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
import_metaobject | nullrequired
Import information for this entity.
null if this entity is not imported.external_idstring | null
Example:
9b95b0b8-e10f-441a-862e-1936a6d818abReference or identifier for this entity from the provider where it was imported from.
Length: 1–200
imported_fromstringrequired
Example:
paddle_classicName of the platform or provider where this entity was imported from.
Length: 1–200
typestringrequired
The type of discount.
Values
recurringDiscount applies to multiple billing periods.one-offDiscount applies to a single billing period.
starts_atstring (date-time)required
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when the discount is effective from on the subscription.
ends_atstring (date-time) | nullrequired
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when the discount stops being effective on the subscription.
null if the discount does not have an end date.Item added
Details specific to
subscription_item_added actions.actionstringrequired
What happened on the subscription.
Values
subscription_item_addedAn item was added to the subscription.
priceobjectrequired
Price of the item that was added to the subscription.
idstringrequired
Example:
pri_01gsz8z1q1n00f12qt82y31smhUnique Paddle ID for this price, prefixed with
pri_.Pattern:
^pri_[a-z\d]{26}$product_idstringrequired
Example:
pro_01gsz97mq9pa4fkyy0wqenepkzPaddle ID for the product that this price is for, prefixed with
pro_.Pattern:
^pro_[a-z\d]{26}$descriptionstringrequired
Internal description for this price, not shown to customers. Typically notes for your team.
Length: 2–500
typestringrequired
Default:
standardType of item. Standard items are considered part of your catalog and are shown in the Paddle dashboard.
Values
customNon-catalog item. Typically created for a specific transaction or subscription. Not returned when listing or shown in the Paddle dashboard.standardStandard item. Can be considered part of your catalog and reused across transactions and subscriptions easily.
namestring | nullrequired
Name of this price, shown to customers at checkout and on invoices. Typically describes how often the related product bills.
Length: 1–150
billing_cycleobject | nullrequired
How often this price should be charged.
null if price is non-recurring (one-time).intervalstringrequired
Unit of time.
Values
dayweekmonthyear
frequencyintegerrequired
Amount of time.
Min: 1
trial_periodobject | nullrequired
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.intervalstringrequired
Unit of time.
Values
dayweekmonthyear
frequencyintegerrequired
Amount of time.
Min: 1
requires_payment_methodbooleanrequired
Default:
trueWhether this price requires a payment method (
true) or not (false) when trialing. If false, customers can sign up for subscription without entering their payment details, often referred to as a "cardless trial."unit_priceobject | null
Trial price. Customers are billed this amount for the duration of the trial period. Applies to all customers except those in countries with
unit_price_overrides. If null, customers are not charged during the trial.amountstringrequired
Amount in the lowest denomination for the currency, e.g. 10 USD = 1000 (cents). Although represented as a string, this value must be a valid integer.
currency_codestring
Supported three-letter ISO 4217 currency code.
Values
USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
unit_price_overridesarray
List of unit price overrides for trial pricing. Use to override base trial price with a custom trial price and currency for a country or group of countries.
Items: max 250
country_codesarrayrequired
Supported two-letter ISO 3166-1 alpha-2 country code. Customers located in the listed countries are charged the override price.
Items: min 1, unique
string
Two-letter ISO 3166-1 alpha-2 representation of a supported country.
Values
ADAndorraAEUnited Arab EmiratesAGAntigua and BarbudaAIAnguillaALAlbania
+ Show all values− Hide values
AMArmeniaAOAngolaARArgentinaASAmerican SamoaATAustriaAUAustraliaAWArubaAXÃ…land IslandsAZAzerbaijanBABosnia and HerzegovinaBBBarbadosBDBangladeshBEBelgiumBFBurkina FasoBGBulgariaBHBahrainBIBurundiBJBeninBLSaint BarthélemyBMBermudaBNBruneiBOBoliviaBQCaribbean Netherlands (Bonaire, Sint Eustatius, and Saba)BRBrazilBSBahamasBTBhutanBVBouvet IslandBWBotswanaBZBelizeCACanadaCCCocos IslandsCGRepublic of CongoCHSwitzerlandCICôte d'Ivoire (Ivory Coast)CKCook IslandsCLChileCMCameroonCNChinaCOColombiaCRCosta RicaCVCape VerdeCWCuraçaoCXChristmas IslandCYCyprusCZCzechia (Czech Republic)DEGermanyDJDjiboutiDKDenmarkDMDominicaDODominican RepublicDZAlgeriaECEcuadorEEEstoniaEGEgyptEHWestern SaharaEREritreaESSpainETEthiopiaFIFinlandFJFijiFKFalkland IslandsFMMicronesiaFOFaroe IslandsFRFranceGAGabonGBUnited KingdomGDGrenadaGEGeorgiaGFFrench GuianaGGGuernseyGHGhanaGIGibraltarGLGreenlandGMGambiaGNGuineaGPGuadeloupeGQEquatorial GuineaGRGreeceGSSouth Georgia and the South Sandwich IslandsGTGuatemalaGUGuamGWGuinea-BissauGYGuyanaHKHong KongHMHeard Island and McDonald IslandsHNHondurasHRCroatiaHUHungaryIDIndonesiaIEIrelandILIsraelIMIsle of ManINIndiaIOBritish Indian Ocean TerritoryIQIraqISIcelandITItalyJEJerseyJMJamaicaJOJordanJPJapanKEKenyaKGKyrgyzstanKHCambodiaKIKiribatiKMComorosKNSaint Kitts and NevisKRSouth KoreaKWKuwaitKYCayman IslandsKZKazakhstanLALao People's Democratic Republic (Laos)LBLebanonLCSaint LuciaLILiechtensteinLKSri LankaLRLiberiaLSLesothoLTLithuaniaLULuxembourgLVLatviaMAMoroccoMCMonacoMDMoldovaMEMontenegroMFSaint MartinMGMadagascarMHMarshall IslandsMKMacedoniaMNMongoliaMOMacaoMPNorthern Mariana IslandsMQMartiniqueMRMauritaniaMSMontserratMTMaltaMUMauritiusMVMaldivesMWMalawiMXMexicoMYMalaysiaMZMozambiqueNANamibiaNCNew CaledoniaNENigerNFNorfolk IslandNGNigeriaNLNetherlandsNONorwayNPNepalNRNauruNUNiueNZNew ZealandOMOmanPAPanamaPEPeruPFFrench PolynesiaPGPapua New GuineaPHPhilippinesPKPakistanPLPolandPMSaint Pierre and MiquelonPNPitcairnPRPuerto RicoPSPalestinian territoriesPTPortugalPWPalauPYParaguayQAQatarREReunionRORomaniaRSRepublic of SerbiaRWRwandaSASaudi ArabiaSBSolomon IslandsSCSeychellesSESwedenSGSingaporeSHSaint HelenaSISloveniaSJSvalbard and Jan MayenSKSlovakiaSLSierra LeoneSMSan MarinoSNSenegalSRSurinameSTSão Tomé and PrÃncipeSVEl SalvadorSXSint MaartenSZSwazilandTCTurks and Caicos IslandsTDChadTFFrench Southern and Antarctic LandsTGTogoTHThailandTJTajikistanTKTokelauTLTimor-LesteTMTurkmenistanTNTunisiaTOTongaTRTurkeyTTTrinidad and TobagoTVTuvaluTWTaiwanTZTanzaniaUAUkraineUGUgandaUMUnited States Minor Outlying IslandsUSUnited StatesUYUruguayUZUzbekistanVAHoly See (Vatican City)VCSaint Vincent and the GrenadinesVGBritish Virgin IslandsVIU.S. Virgin IslandsVNVietnamVUVanuatuWFWallis and FutunaWSSamoaXKKosovoYTMayotteZASouth AfricaZMZambia
unit_priceobjectrequired
Override price. This price applies to customers located in the countries for this unit price override.
amountstringrequired
Amount in the lowest denomination for the currency, e.g. 10 USD = 1000 (cents). Although represented as a string, this value must be a valid integer.
currency_codestring
Supported three-letter ISO 4217 currency code.
Values
USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
tax_modestringrequired
Default:
account_settingHow tax is calculated for this price.
Values
account_settingPrices use the setting from your account.externalPrices are exclusive of tax.internalPrices are inclusive of tax.locationPrices are inclusive or exclusive of tax, depending on the country of the transaction.
unit_priceobjectrequired
Base price. This price applies to all customers, except for customers located in countries where you have
unit_price_overrides.amountstringrequired
Amount in the lowest denomination for the currency, e.g. 10 USD = 1000 (cents). Although represented as a string, this value must be a valid integer.
currency_codestringrequired
Supported three-letter ISO 4217 currency code.
Values
USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
unit_price_overridesarrayrequired
List of unit price overrides. Use to override the base price with a custom price and currency for a country or group of countries.
Items: max 250
country_codesarrayrequired
Supported two-letter ISO 3166-1 alpha-2 country code. Customers located in the listed countries are charged the override price.
Items: min 1, unique
string
Two-letter ISO 3166-1 alpha-2 representation of a supported country.
Values
ADAndorraAEUnited Arab EmiratesAGAntigua and BarbudaAIAnguillaALAlbania
+ Show all values− Hide values
AMArmeniaAOAngolaARArgentinaASAmerican SamoaATAustriaAUAustraliaAWArubaAXÃ…land IslandsAZAzerbaijanBABosnia and HerzegovinaBBBarbadosBDBangladeshBEBelgiumBFBurkina FasoBGBulgariaBHBahrainBIBurundiBJBeninBLSaint BarthélemyBMBermudaBNBruneiBOBoliviaBQCaribbean Netherlands (Bonaire, Sint Eustatius, and Saba)BRBrazilBSBahamasBTBhutanBVBouvet IslandBWBotswanaBZBelizeCACanadaCCCocos IslandsCGRepublic of CongoCHSwitzerlandCICôte d'Ivoire (Ivory Coast)CKCook IslandsCLChileCMCameroonCNChinaCOColombiaCRCosta RicaCVCape VerdeCWCuraçaoCXChristmas IslandCYCyprusCZCzechia (Czech Republic)DEGermanyDJDjiboutiDKDenmarkDMDominicaDODominican RepublicDZAlgeriaECEcuadorEEEstoniaEGEgyptEHWestern SaharaEREritreaESSpainETEthiopiaFIFinlandFJFijiFKFalkland IslandsFMMicronesiaFOFaroe IslandsFRFranceGAGabonGBUnited KingdomGDGrenadaGEGeorgiaGFFrench GuianaGGGuernseyGHGhanaGIGibraltarGLGreenlandGMGambiaGNGuineaGPGuadeloupeGQEquatorial GuineaGRGreeceGSSouth Georgia and the South Sandwich IslandsGTGuatemalaGUGuamGWGuinea-BissauGYGuyanaHKHong KongHMHeard Island and McDonald IslandsHNHondurasHRCroatiaHUHungaryIDIndonesiaIEIrelandILIsraelIMIsle of ManINIndiaIOBritish Indian Ocean TerritoryIQIraqISIcelandITItalyJEJerseyJMJamaicaJOJordanJPJapanKEKenyaKGKyrgyzstanKHCambodiaKIKiribatiKMComorosKNSaint Kitts and NevisKRSouth KoreaKWKuwaitKYCayman IslandsKZKazakhstanLALao People's Democratic Republic (Laos)LBLebanonLCSaint LuciaLILiechtensteinLKSri LankaLRLiberiaLSLesothoLTLithuaniaLULuxembourgLVLatviaMAMoroccoMCMonacoMDMoldovaMEMontenegroMFSaint MartinMGMadagascarMHMarshall IslandsMKMacedoniaMNMongoliaMOMacaoMPNorthern Mariana IslandsMQMartiniqueMRMauritaniaMSMontserratMTMaltaMUMauritiusMVMaldivesMWMalawiMXMexicoMYMalaysiaMZMozambiqueNANamibiaNCNew CaledoniaNENigerNFNorfolk IslandNGNigeriaNLNetherlandsNONorwayNPNepalNRNauruNUNiueNZNew ZealandOMOmanPAPanamaPEPeruPFFrench PolynesiaPGPapua New GuineaPHPhilippinesPKPakistanPLPolandPMSaint Pierre and MiquelonPNPitcairnPRPuerto RicoPSPalestinian territoriesPTPortugalPWPalauPYParaguayQAQatarREReunionRORomaniaRSRepublic of SerbiaRWRwandaSASaudi ArabiaSBSolomon IslandsSCSeychellesSESwedenSGSingaporeSHSaint HelenaSISloveniaSJSvalbard and Jan MayenSKSlovakiaSLSierra LeoneSMSan MarinoSNSenegalSRSurinameSTSão Tomé and PrÃncipeSVEl SalvadorSXSint MaartenSZSwazilandTCTurks and Caicos IslandsTDChadTFFrench Southern and Antarctic LandsTGTogoTHThailandTJTajikistanTKTokelauTLTimor-LesteTMTurkmenistanTNTunisiaTOTongaTRTurkeyTTTrinidad and TobagoTVTuvaluTWTaiwanTZTanzaniaUAUkraineUGUgandaUMUnited States Minor Outlying IslandsUSUnited StatesUYUruguayUZUzbekistanVAHoly See (Vatican City)VCSaint Vincent and the GrenadinesVGBritish Virgin IslandsVIU.S. Virgin IslandsVNVietnamVUVanuatuWFWallis and FutunaWSSamoaXKKosovoYTMayotteZASouth AfricaZMZambia
unit_priceobjectrequired
Override price. This price applies to customers located in the countries for this unit price override.
amountstringrequired
Amount in the lowest denomination for the currency, e.g. 10 USD = 1000 (cents). Although represented as a string, this value must be a valid integer.
currency_codestringrequired
Supported three-letter ISO 4217 currency code.
Values
USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
quantityobjectrequired
Example:
{"minimum":1,"maximum":100}Limits on how many times the related product can be purchased at this price. Useful for discount campaigns.
minimumintegerrequired
Default:
1Example:
1Minimum quantity of the product related to this price that can be bought. Required if
maximum set.Range: 1–999999999
maximumintegerrequired
Default:
100Example:
100Maximum quantity of the product related to this price that can be bought. Required if
minimum set. Must be greater than or equal to the minimum value.Range: 1–999999999
statusstringrequired
Default:
activeWhether this entity can be used in Paddle.
Values
activeEntity is active and can be used.archivedEntity is archived, so can't be used.
custom_dataobject | nullrequired
Example:
{"customer_reference_id":"abcd1234"}Your own structured key-value data.
import_metaobject | nullrequired
Import information for this entity.
null if this entity is not imported.external_idstring | null
Example:
9b95b0b8-e10f-441a-862e-1936a6d818abReference or identifier for this entity from the provider where it was imported from.
Length: 1–200
imported_fromstringrequired
Example:
paddle_classicName of the platform or provider where this entity was imported from.
Length: 1–200
created_atstring (date-time)required
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
updated_atstring (date-time)required
Example:
2024-10-13T07:20:50.52ZRFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
quantityintegerrequired
Quantity of the item on the subscription after being added.
update_summaryobjectrequired
Summary of the quantity change. For a new item,
quantity_delta matches the resulting quantity since the previous quantity was zero.quantity_deltaintegerrequired
Signed change in quantity. Positive when the quantity increased (or an item was added), negative when the quantity decreased (or an item was removed).
proration_billing_modestringrequired
How Paddle calculated proration for the item added.
Values
prorated_immediatelyPaddle calculates the prorated amount for the subscription changes based on the current billing cycle, then creates a transaction to collect immediately.prorated_next_billing_periodPaddle calculates the prorated amount for the subscription changes based on the current billing cycle, then schedules them to be billed on the next renewal.full_immediatelyPaddle does not calculate proration for the subscription changes, creating a transaction to collect for the full amount immediately.full_next_billing_periodPaddle does not calculate proration for the subscription changes, scheduling for the full amount for the changes to be billed on the next renewal.do_not_billPaddle does not bill for the subscription changes.
on_payment_failurestringrequired
How Paddle handled payment failure for the operation.
Values
prevent_changeIn case of payment failure, prevent the change to the subscription from applying.apply_changeIn case of payment failure, apply the change and update the subscription.
transaction_idstring | nullrequired
Example:
txn_01h04vsbhqc62t8hmd4z3b578cPaddle ID of the transaction created as a result of the item being added, prefixed with
txn_. null if no transaction was created.Pattern:
^txn_[a-z\d]{26}$Item quantity updated
Details specific to
subscription_item_quantity_updated actions.actionstringrequired
What happened on the subscription.
Values
subscription_item_quantity_updatedThe quantity of an item on the subscription was changed.
priceobjectrequired
Price of the item where the quantity was updated.
idstringrequired
Example:
pri_01gsz8z1q1n00f12qt82y31smhUnique Paddle ID for this price, prefixed with
pri_.Pattern:
^pri_[a-z\d]{26}$product_idstringrequired
Example:
pro_01gsz97mq9pa4fkyy0wqenepkzPaddle ID for the product that this price is for, prefixed with
pro_.Pattern:
^pro_[a-z\d]{26}$descriptionstringrequired
Internal description for this price, not shown to customers. Typically notes for your team.
Length: 2–500
typestringrequired
Default:
standardType of item. Standard items are considered part of your catalog and are shown in the Paddle dashboard.
Values
customNon-catalog item. Typically created for a specific transaction or subscription. Not returned when listing or shown in the Paddle dashboard.standardStandard item. Can be considered part of your catalog and reused across transactions and subscriptions easily.
namestring | nullrequired
Name of this price, shown to customers at checkout and on invoices. Typically describes how often the related product bills.
Length: 1–150
billing_cycleobject | nullrequired
How often this price should be charged.
null if price is non-recurring (one-time).intervalstringrequired
Unit of time.
Values
dayweekmonthyear
frequencyintegerrequired
Amount of time.
Min: 1
trial_periodobject | nullrequired
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.intervalstringrequired
Unit of time.
Values
dayweekmonthyear
frequencyintegerrequired
Amount of time.
Min: 1
requires_payment_methodbooleanrequired
Default:
trueWhether this price requires a payment method (
true) or not (false) when trialing. If false, customers can sign up for subscription without entering their payment details, often referred to as a "cardless trial."unit_priceobject | null
Trial price. Customers are billed this amount for the duration of the trial period. Applies to all customers except those in countries with
unit_price_overrides. If null, customers are not charged during the trial.amountstringrequired
Amount in the lowest denomination for the currency, e.g. 10 USD = 1000 (cents). Although represented as a string, this value must be a valid integer.
currency_codestring
Supported three-letter ISO 4217 currency code.
Values
USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
unit_price_overridesarray
List of unit price overrides for trial pricing. Use to override base trial price with a custom trial price and currency for a country or group of countries.
Items: max 250
country_codesarrayrequired
Supported two-letter ISO 3166-1 alpha-2 country code. Customers located in the listed countries are charged the override price.
Items: min 1, unique
string
Two-letter ISO 3166-1 alpha-2 representation of a supported country.
Values
ADAndorraAEUnited Arab EmiratesAGAntigua and BarbudaAIAnguillaALAlbania
+ Show all values− Hide values
AMArmeniaAOAngolaARArgentinaASAmerican SamoaATAustriaAUAustraliaAWArubaAXÃ…land IslandsAZAzerbaijanBABosnia and HerzegovinaBBBarbadosBDBangladeshBEBelgiumBFBurkina FasoBGBulgariaBHBahrainBIBurundiBJBeninBLSaint BarthélemyBMBermudaBNBruneiBOBoliviaBQCaribbean Netherlands (Bonaire, Sint Eustatius, and Saba)BRBrazilBSBahamasBTBhutanBVBouvet IslandBWBotswanaBZBelizeCACanadaCCCocos IslandsCGRepublic of CongoCHSwitzerlandCICôte d'Ivoire (Ivory Coast)CKCook IslandsCLChileCMCameroonCNChinaCOColombiaCRCosta RicaCVCape VerdeCWCuraçaoCXChristmas IslandCYCyprusCZCzechia (Czech Republic)DEGermanyDJDjiboutiDKDenmarkDMDominicaDODominican RepublicDZAlgeriaECEcuadorEEEstoniaEGEgyptEHWestern SaharaEREritreaESSpainETEthiopiaFIFinlandFJFijiFKFalkland IslandsFMMicronesiaFOFaroe IslandsFRFranceGAGabonGBUnited KingdomGDGrenadaGEGeorgiaGFFrench GuianaGGGuernseyGHGhanaGIGibraltarGLGreenlandGMGambiaGNGuineaGPGuadeloupeGQEquatorial GuineaGRGreeceGSSouth Georgia and the South Sandwich IslandsGTGuatemalaGUGuamGWGuinea-BissauGYGuyanaHKHong KongHMHeard Island and McDonald IslandsHNHondurasHRCroatiaHUHungaryIDIndonesiaIEIrelandILIsraelIMIsle of ManINIndiaIOBritish Indian Ocean TerritoryIQIraqISIcelandITItalyJEJerseyJMJamaicaJOJordanJPJapanKEKenyaKGKyrgyzstanKHCambodiaKIKiribatiKMComorosKNSaint Kitts and NevisKRSouth KoreaKWKuwaitKYCayman IslandsKZKazakhstanLALao People's Democratic Republic (Laos)LBLebanonLCSaint LuciaLILiechtensteinLKSri LankaLRLiberiaLSLesothoLTLithuaniaLULuxembourgLVLatviaMAMoroccoMCMonacoMDMoldovaMEMontenegroMFSaint MartinMGMadagascarMHMarshall IslandsMKMacedoniaMNMongoliaMOMacaoMPNorthern Mariana IslandsMQMartiniqueMRMauritaniaMSMontserratMTMaltaMUMauritiusMVMaldivesMWMalawiMXMexicoMYMalaysiaMZMozambiqueNANamibiaNCNew CaledoniaNENigerNFNorfolk IslandNGNigeriaNLNetherlandsNONorwayNPNepalNRNauruNUNiueNZNew ZealandOMOmanPAPanamaPEPeruPFFrench PolynesiaPGPapua New GuineaPHPhilippinesPKPakistanPLPolandPMSaint Pierre and MiquelonPNPitcairnPRPuerto RicoPSPalestinian territoriesPTPortugalPWPalauPYParaguayQAQatarREReunionRORomaniaRSRepublic of SerbiaRWRwandaSASaudi ArabiaSBSolomon IslandsSCSeychellesSESwedenSGSingaporeSHSaint HelenaSISloveniaSJSvalbard and Jan MayenSKSlovakiaSLSierra LeoneSMSan MarinoSNSenegalSRSurinameSTSão Tomé and PrÃncipeSVEl SalvadorSXSint MaartenSZSwazilandTCTurks and Caicos IslandsTDChadTFFrench Southern and Antarctic LandsTGTogoTHThailandTJTajikistanTKTokelauTLTimor-LesteTMTurkmenistanTNTunisiaTOTongaTRTurkeyTTTrinidad and TobagoTVTuvaluTWTaiwanTZTanzaniaUAUkraineUGUgandaUMUnited States Minor Outlying IslandsUSUnited StatesUYUruguayUZUzbekistanVAHoly See (Vatican City)VCSaint Vincent and the GrenadinesVGBritish Virgin IslandsVIU.S. Virgin IslandsVNVietnamVUVanuatuWFWallis and FutunaWSSamoaXKKosovoYTMayotteZASouth AfricaZMZambia
unit_priceobjectrequired
Override price. This price applies to customers located in the countries for this unit price override.
amountstringrequired
Amount in the lowest denomination for the currency, e.g. 10 USD = 1000 (cents). Although represented as a string, this value must be a valid integer.
currency_codestring
Supported three-letter ISO 4217 currency code.
Values
USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
tax_modestringrequired
Default:
account_settingHow tax is calculated for this price.
Values
account_settingPrices use the setting from your account.externalPrices are exclusive of tax.internalPrices are inclusive of tax.locationPrices are inclusive or exclusive of tax, depending on the country of the transaction.
unit_priceobjectrequired
Base price. This price applies to all customers, except for customers located in countries where you have
unit_price_overrides.amountstringrequired
Amount in the lowest denomination for the currency, e.g. 10 USD = 1000 (cents). Although represented as a string, this value must be a valid integer.
currency_codestringrequired
Supported three-letter ISO 4217 currency code.
Values
USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
unit_price_overridesarrayrequired
List of unit price overrides. Use to override the base price with a custom price and currency for a country or group of countries.
Items: max 250
country_codesarrayrequired
Supported two-letter ISO 3166-1 alpha-2 country code. Customers located in the listed countries are charged the override price.
Items: min 1, unique
string
Two-letter ISO 3166-1 alpha-2 representation of a supported country.
Values
ADAndorraAEUnited Arab EmiratesAGAntigua and BarbudaAIAnguillaALAlbania
+ Show all values− Hide values
AMArmeniaAOAngolaARArgentinaASAmerican SamoaATAustriaAUAustraliaAWArubaAXÃ…land IslandsAZAzerbaijanBABosnia and HerzegovinaBBBarbadosBDBangladeshBEBelgiumBFBurkina FasoBGBulgariaBHBahrainBIBurundiBJBeninBLSaint BarthélemyBMBermudaBNBruneiBOBoliviaBQCaribbean Netherlands (Bonaire, Sint Eustatius, and Saba)BRBrazilBSBahamasBTBhutanBVBouvet IslandBWBotswanaBZBelizeCACanadaCCCocos IslandsCGRepublic of CongoCHSwitzerlandCICôte d'Ivoire (Ivory Coast)CKCook IslandsCLChileCMCameroonCNChinaCOColombiaCRCosta RicaCVCape VerdeCWCuraçaoCXChristmas IslandCYCyprusCZCzechia (Czech Republic)DEGermanyDJDjiboutiDKDenmarkDMDominicaDODominican RepublicDZAlgeriaECEcuadorEEEstoniaEGEgyptEHWestern SaharaEREritreaESSpainETEthiopiaFIFinlandFJFijiFKFalkland IslandsFMMicronesiaFOFaroe IslandsFRFranceGAGabonGBUnited KingdomGDGrenadaGEGeorgiaGFFrench GuianaGGGuernseyGHGhanaGIGibraltarGLGreenlandGMGambiaGNGuineaGPGuadeloupeGQEquatorial GuineaGRGreeceGSSouth Georgia and the South Sandwich IslandsGTGuatemalaGUGuamGWGuinea-BissauGYGuyanaHKHong KongHMHeard Island and McDonald IslandsHNHondurasHRCroatiaHUHungaryIDIndonesiaIEIrelandILIsraelIMIsle of ManINIndiaIOBritish Indian Ocean TerritoryIQIraqISIcelandITItalyJEJerseyJMJamaicaJOJordanJPJapanKEKenyaKGKyrgyzstanKHCambodiaKIKiribatiKMComorosKNSaint Kitts and NevisKRSouth KoreaKWKuwaitKYCayman IslandsKZKazakhstanLALao People's Democratic Republic (Laos)LBLebanonLCSaint LuciaLILiechtensteinLKSri LankaLRLiberiaLSLesothoLTLithuaniaLULuxembourgLVLatviaMAMoroccoMCMonacoMDMoldovaMEMontenegroMFSaint MartinMGMadagascarMHMarshall IslandsMKMacedoniaMNMongoliaMOMacaoMPNorthern Mariana IslandsMQMartiniqueMRMauritaniaMSMontserratMTMaltaMUMauritiusMVMaldivesMWMalawiMXMexicoMYMalaysiaMZMozambiqueNANamibiaNCNew CaledoniaNENigerNFNorfolk IslandNGNigeriaNLNetherlandsNONorwayNPNepalNRNauruNUNiueNZNew ZealandOMOmanPAPanamaPEPeruPFFrench PolynesiaPGPapua New GuineaPHPhilippinesPKPakistanPLPolandPMSaint Pierre and MiquelonPNPitcairnPRPuerto RicoPSPalestinian territoriesPTPortugalPWPalauPYParaguayQAQatarREReunionRORomaniaRSRepublic of SerbiaRWRwandaSASaudi ArabiaSBSolomon IslandsSCSeychellesSESwedenSGSingaporeSHSaint HelenaSISloveniaSJSvalbard and Jan MayenSKSlovakiaSLSierra LeoneSMSan MarinoSNSenegalSRSurinameSTSão Tomé and PrÃncipeSVEl SalvadorSXSint MaartenSZSwazilandTCTurks and Caicos IslandsTDChadTFFrench Southern and Antarctic LandsTGTogoTHThailandTJTajikistanTKTokelauTLTimor-LesteTMTurkmenistanTNTunisiaTOTongaTRTurkeyTTTrinidad and TobagoTVTuvaluTWTaiwanTZTanzaniaUAUkraineUGUgandaUMUnited States Minor Outlying IslandsUSUnited StatesUYUruguayUZUzbekistanVAHoly See (Vatican City)VCSaint Vincent and the GrenadinesVGBritish Virgin IslandsVIU.S. Virgin IslandsVNVietnamVUVanuatuWFWallis and FutunaWSSamoaXKKosovoYTMayotteZASouth AfricaZMZambia
unit_priceobjectrequired
Override price. This price applies to customers located in the countries for this unit price override.
amountstringrequired
Amount in the lowest denomination for the currency, e.g. 10 USD = 1000 (cents). Although represented as a string, this value must be a valid integer.
currency_codestringrequired
Supported three-letter ISO 4217 currency code.
Values
USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
quantityobjectrequired
Example:
{"minimum":1,"maximum":100}Limits on how many times the related product can be purchased at this price. Useful for discount campaigns.
minimumintegerrequired
Default:
1Example:
1Minimum quantity of the product related to this price that can be bought. Required if
maximum set.Range: 1–999999999
maximumintegerrequired
Default:
100Example:
100Maximum quantity of the product related to this price that can be bought. Required if
minimum set. Must be greater than or equal to the minimum value.Range: 1–999999999
statusstringrequired
Default:
activeWhether this entity can be used in Paddle.
Values
activeEntity is active and can be used.archivedEntity is archived, so can't be used.
custom_dataobject | nullrequired
Example:
{"customer_reference_id":"abcd1234"}Your own structured key-value data.
import_metaobject | nullrequired
Import information for this entity.
null if this entity is not imported.external_idstring | null
Example:
9b95b0b8-e10f-441a-862e-1936a6d818abReference or identifier for this entity from the provider where it was imported from.
Length: 1–200
imported_fromstringrequired
Example:
paddle_classicName of the platform or provider where this entity was imported from.
Length: 1–200
created_atstring (date-time)required
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
updated_atstring (date-time)required
Example:
2024-10-13T07:20:50.52ZRFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
quantityintegerrequired
Total quantity of the item on the subscription after the change.
update_summaryobjectrequired
Summary of the quantity change.
quantity_delta is positive when the quantity increased, negative when it decreased.quantity_deltaintegerrequired
Signed change in quantity. Positive when the quantity increased (or an item was added), negative when the quantity decreased (or an item was removed).
proration_billing_modestringrequired
How Paddle calculated proration for the quantity change.
Values
prorated_immediatelyPaddle calculates the prorated amount for the subscription changes based on the current billing cycle, then creates a transaction to collect immediately.prorated_next_billing_periodPaddle calculates the prorated amount for the subscription changes based on the current billing cycle, then schedules them to be billed on the next renewal.full_immediatelyPaddle does not calculate proration for the subscription changes, creating a transaction to collect for the full amount immediately.full_next_billing_periodPaddle does not calculate proration for the subscription changes, scheduling for the full amount for the changes to be billed on the next renewal.do_not_billPaddle does not bill for the subscription changes.
on_payment_failurestringrequired
How Paddle handled payment failure for the operation.
Values
prevent_changeIn case of payment failure, prevent the change to the subscription from applying.apply_changeIn case of payment failure, apply the change and update the subscription.
transaction_idstring | nullrequired
Example:
txn_01h04vsbhqc62t8hmd4z3b578cPaddle ID of the transaction created as a result of the quantity change, prefixed with
txn_. null if no transaction was created.Pattern:
^txn_[a-z\d]{26}$Item removed
Details specific to
subscription_item_removed actions.actionstringrequired
What happened on the subscription.
Values
subscription_item_removedAn item was removed from the subscription.
priceobjectrequired
Price of the item that was removed from the subscription.
idstringrequired
Example:
pri_01gsz8z1q1n00f12qt82y31smhUnique Paddle ID for this price, prefixed with
pri_.Pattern:
^pri_[a-z\d]{26}$product_idstringrequired
Example:
pro_01gsz97mq9pa4fkyy0wqenepkzPaddle ID for the product that this price is for, prefixed with
pro_.Pattern:
^pro_[a-z\d]{26}$descriptionstringrequired
Internal description for this price, not shown to customers. Typically notes for your team.
Length: 2–500
typestringrequired
Default:
standardType of item. Standard items are considered part of your catalog and are shown in the Paddle dashboard.
Values
customNon-catalog item. Typically created for a specific transaction or subscription. Not returned when listing or shown in the Paddle dashboard.standardStandard item. Can be considered part of your catalog and reused across transactions and subscriptions easily.
namestring | nullrequired
Name of this price, shown to customers at checkout and on invoices. Typically describes how often the related product bills.
Length: 1–150
billing_cycleobject | nullrequired
How often this price should be charged.
null if price is non-recurring (one-time).intervalstringrequired
Unit of time.
Values
dayweekmonthyear
frequencyintegerrequired
Amount of time.
Min: 1
trial_periodobject | nullrequired
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.intervalstringrequired
Unit of time.
Values
dayweekmonthyear
frequencyintegerrequired
Amount of time.
Min: 1
requires_payment_methodbooleanrequired
Default:
trueWhether this price requires a payment method (
true) or not (false) when trialing. If false, customers can sign up for subscription without entering their payment details, often referred to as a "cardless trial."unit_priceobject | null
Trial price. Customers are billed this amount for the duration of the trial period. Applies to all customers except those in countries with
unit_price_overrides. If null, customers are not charged during the trial.amountstringrequired
Amount in the lowest denomination for the currency, e.g. 10 USD = 1000 (cents). Although represented as a string, this value must be a valid integer.
currency_codestring
Supported three-letter ISO 4217 currency code.
Values
USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
unit_price_overridesarray
List of unit price overrides for trial pricing. Use to override base trial price with a custom trial price and currency for a country or group of countries.
Items: max 250
country_codesarrayrequired
Supported two-letter ISO 3166-1 alpha-2 country code. Customers located in the listed countries are charged the override price.
Items: min 1, unique
string
Two-letter ISO 3166-1 alpha-2 representation of a supported country.
Values
ADAndorraAEUnited Arab EmiratesAGAntigua and BarbudaAIAnguillaALAlbania
+ Show all values− Hide values
AMArmeniaAOAngolaARArgentinaASAmerican SamoaATAustriaAUAustraliaAWArubaAXÃ…land IslandsAZAzerbaijanBABosnia and HerzegovinaBBBarbadosBDBangladeshBEBelgiumBFBurkina FasoBGBulgariaBHBahrainBIBurundiBJBeninBLSaint BarthélemyBMBermudaBNBruneiBOBoliviaBQCaribbean Netherlands (Bonaire, Sint Eustatius, and Saba)BRBrazilBSBahamasBTBhutanBVBouvet IslandBWBotswanaBZBelizeCACanadaCCCocos IslandsCGRepublic of CongoCHSwitzerlandCICôte d'Ivoire (Ivory Coast)CKCook IslandsCLChileCMCameroonCNChinaCOColombiaCRCosta RicaCVCape VerdeCWCuraçaoCXChristmas IslandCYCyprusCZCzechia (Czech Republic)DEGermanyDJDjiboutiDKDenmarkDMDominicaDODominican RepublicDZAlgeriaECEcuadorEEEstoniaEGEgyptEHWestern SaharaEREritreaESSpainETEthiopiaFIFinlandFJFijiFKFalkland IslandsFMMicronesiaFOFaroe IslandsFRFranceGAGabonGBUnited KingdomGDGrenadaGEGeorgiaGFFrench GuianaGGGuernseyGHGhanaGIGibraltarGLGreenlandGMGambiaGNGuineaGPGuadeloupeGQEquatorial GuineaGRGreeceGSSouth Georgia and the South Sandwich IslandsGTGuatemalaGUGuamGWGuinea-BissauGYGuyanaHKHong KongHMHeard Island and McDonald IslandsHNHondurasHRCroatiaHUHungaryIDIndonesiaIEIrelandILIsraelIMIsle of ManINIndiaIOBritish Indian Ocean TerritoryIQIraqISIcelandITItalyJEJerseyJMJamaicaJOJordanJPJapanKEKenyaKGKyrgyzstanKHCambodiaKIKiribatiKMComorosKNSaint Kitts and NevisKRSouth KoreaKWKuwaitKYCayman IslandsKZKazakhstanLALao People's Democratic Republic (Laos)LBLebanonLCSaint LuciaLILiechtensteinLKSri LankaLRLiberiaLSLesothoLTLithuaniaLULuxembourgLVLatviaMAMoroccoMCMonacoMDMoldovaMEMontenegroMFSaint MartinMGMadagascarMHMarshall IslandsMKMacedoniaMNMongoliaMOMacaoMPNorthern Mariana IslandsMQMartiniqueMRMauritaniaMSMontserratMTMaltaMUMauritiusMVMaldivesMWMalawiMXMexicoMYMalaysiaMZMozambiqueNANamibiaNCNew CaledoniaNENigerNFNorfolk IslandNGNigeriaNLNetherlandsNONorwayNPNepalNRNauruNUNiueNZNew ZealandOMOmanPAPanamaPEPeruPFFrench PolynesiaPGPapua New GuineaPHPhilippinesPKPakistanPLPolandPMSaint Pierre and MiquelonPNPitcairnPRPuerto RicoPSPalestinian territoriesPTPortugalPWPalauPYParaguayQAQatarREReunionRORomaniaRSRepublic of SerbiaRWRwandaSASaudi ArabiaSBSolomon IslandsSCSeychellesSESwedenSGSingaporeSHSaint HelenaSISloveniaSJSvalbard and Jan MayenSKSlovakiaSLSierra LeoneSMSan MarinoSNSenegalSRSurinameSTSão Tomé and PrÃncipeSVEl SalvadorSXSint MaartenSZSwazilandTCTurks and Caicos IslandsTDChadTFFrench Southern and Antarctic LandsTGTogoTHThailandTJTajikistanTKTokelauTLTimor-LesteTMTurkmenistanTNTunisiaTOTongaTRTurkeyTTTrinidad and TobagoTVTuvaluTWTaiwanTZTanzaniaUAUkraineUGUgandaUMUnited States Minor Outlying IslandsUSUnited StatesUYUruguayUZUzbekistanVAHoly See (Vatican City)VCSaint Vincent and the GrenadinesVGBritish Virgin IslandsVIU.S. Virgin IslandsVNVietnamVUVanuatuWFWallis and FutunaWSSamoaXKKosovoYTMayotteZASouth AfricaZMZambia
unit_priceobjectrequired
Override price. This price applies to customers located in the countries for this unit price override.
amountstringrequired
Amount in the lowest denomination for the currency, e.g. 10 USD = 1000 (cents). Although represented as a string, this value must be a valid integer.
currency_codestring
Supported three-letter ISO 4217 currency code.
Values
USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
tax_modestringrequired
Default:
account_settingHow tax is calculated for this price.
Values
account_settingPrices use the setting from your account.externalPrices are exclusive of tax.internalPrices are inclusive of tax.locationPrices are inclusive or exclusive of tax, depending on the country of the transaction.
unit_priceobjectrequired
Base price. This price applies to all customers, except for customers located in countries where you have
unit_price_overrides.amountstringrequired
Amount in the lowest denomination for the currency, e.g. 10 USD = 1000 (cents). Although represented as a string, this value must be a valid integer.
currency_codestringrequired
Supported three-letter ISO 4217 currency code.
Values
USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
unit_price_overridesarrayrequired
List of unit price overrides. Use to override the base price with a custom price and currency for a country or group of countries.
Items: max 250
country_codesarrayrequired
Supported two-letter ISO 3166-1 alpha-2 country code. Customers located in the listed countries are charged the override price.
Items: min 1, unique
string
Two-letter ISO 3166-1 alpha-2 representation of a supported country.
Values
ADAndorraAEUnited Arab EmiratesAGAntigua and BarbudaAIAnguillaALAlbania
+ Show all values− Hide values
AMArmeniaAOAngolaARArgentinaASAmerican SamoaATAustriaAUAustraliaAWArubaAXÃ…land IslandsAZAzerbaijanBABosnia and HerzegovinaBBBarbadosBDBangladeshBEBelgiumBFBurkina FasoBGBulgariaBHBahrainBIBurundiBJBeninBLSaint BarthélemyBMBermudaBNBruneiBOBoliviaBQCaribbean Netherlands (Bonaire, Sint Eustatius, and Saba)BRBrazilBSBahamasBTBhutanBVBouvet IslandBWBotswanaBZBelizeCACanadaCCCocos IslandsCGRepublic of CongoCHSwitzerlandCICôte d'Ivoire (Ivory Coast)CKCook IslandsCLChileCMCameroonCNChinaCOColombiaCRCosta RicaCVCape VerdeCWCuraçaoCXChristmas IslandCYCyprusCZCzechia (Czech Republic)DEGermanyDJDjiboutiDKDenmarkDMDominicaDODominican RepublicDZAlgeriaECEcuadorEEEstoniaEGEgyptEHWestern SaharaEREritreaESSpainETEthiopiaFIFinlandFJFijiFKFalkland IslandsFMMicronesiaFOFaroe IslandsFRFranceGAGabonGBUnited KingdomGDGrenadaGEGeorgiaGFFrench GuianaGGGuernseyGHGhanaGIGibraltarGLGreenlandGMGambiaGNGuineaGPGuadeloupeGQEquatorial GuineaGRGreeceGSSouth Georgia and the South Sandwich IslandsGTGuatemalaGUGuamGWGuinea-BissauGYGuyanaHKHong KongHMHeard Island and McDonald IslandsHNHondurasHRCroatiaHUHungaryIDIndonesiaIEIrelandILIsraelIMIsle of ManINIndiaIOBritish Indian Ocean TerritoryIQIraqISIcelandITItalyJEJerseyJMJamaicaJOJordanJPJapanKEKenyaKGKyrgyzstanKHCambodiaKIKiribatiKMComorosKNSaint Kitts and NevisKRSouth KoreaKWKuwaitKYCayman IslandsKZKazakhstanLALao People's Democratic Republic (Laos)LBLebanonLCSaint LuciaLILiechtensteinLKSri LankaLRLiberiaLSLesothoLTLithuaniaLULuxembourgLVLatviaMAMoroccoMCMonacoMDMoldovaMEMontenegroMFSaint MartinMGMadagascarMHMarshall IslandsMKMacedoniaMNMongoliaMOMacaoMPNorthern Mariana IslandsMQMartiniqueMRMauritaniaMSMontserratMTMaltaMUMauritiusMVMaldivesMWMalawiMXMexicoMYMalaysiaMZMozambiqueNANamibiaNCNew CaledoniaNENigerNFNorfolk IslandNGNigeriaNLNetherlandsNONorwayNPNepalNRNauruNUNiueNZNew ZealandOMOmanPAPanamaPEPeruPFFrench PolynesiaPGPapua New GuineaPHPhilippinesPKPakistanPLPolandPMSaint Pierre and MiquelonPNPitcairnPRPuerto RicoPSPalestinian territoriesPTPortugalPWPalauPYParaguayQAQatarREReunionRORomaniaRSRepublic of SerbiaRWRwandaSASaudi ArabiaSBSolomon IslandsSCSeychellesSESwedenSGSingaporeSHSaint HelenaSISloveniaSJSvalbard and Jan MayenSKSlovakiaSLSierra LeoneSMSan MarinoSNSenegalSRSurinameSTSão Tomé and PrÃncipeSVEl SalvadorSXSint MaartenSZSwazilandTCTurks and Caicos IslandsTDChadTFFrench Southern and Antarctic LandsTGTogoTHThailandTJTajikistanTKTokelauTLTimor-LesteTMTurkmenistanTNTunisiaTOTongaTRTurkeyTTTrinidad and TobagoTVTuvaluTWTaiwanTZTanzaniaUAUkraineUGUgandaUMUnited States Minor Outlying IslandsUSUnited StatesUYUruguayUZUzbekistanVAHoly See (Vatican City)VCSaint Vincent and the GrenadinesVGBritish Virgin IslandsVIU.S. Virgin IslandsVNVietnamVUVanuatuWFWallis and FutunaWSSamoaXKKosovoYTMayotteZASouth AfricaZMZambia
unit_priceobjectrequired
Override price. This price applies to customers located in the countries for this unit price override.
amountstringrequired
Amount in the lowest denomination for the currency, e.g. 10 USD = 1000 (cents). Although represented as a string, this value must be a valid integer.
currency_codestringrequired
Supported three-letter ISO 4217 currency code.
Values
USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
quantityobjectrequired
Example:
{"minimum":1,"maximum":100}Limits on how many times the related product can be purchased at this price. Useful for discount campaigns.
minimumintegerrequired
Default:
1Example:
1Minimum quantity of the product related to this price that can be bought. Required if
maximum set.Range: 1–999999999
maximumintegerrequired
Default:
100Example:
100Maximum quantity of the product related to this price that can be bought. Required if
minimum set. Must be greater than or equal to the minimum value.Range: 1–999999999
statusstringrequired
Default:
activeWhether this entity can be used in Paddle.
Values
activeEntity is active and can be used.archivedEntity is archived, so can't be used.
custom_dataobject | nullrequired
Example:
{"customer_reference_id":"abcd1234"}Your own structured key-value data.
import_metaobject | nullrequired
Import information for this entity.
null if this entity is not imported.external_idstring | null
Example:
9b95b0b8-e10f-441a-862e-1936a6d818abReference or identifier for this entity from the provider where it was imported from.
Length: 1–200
imported_fromstringrequired
Example:
paddle_classicName of the platform or provider where this entity was imported from.
Length: 1–200
created_atstring (date-time)required
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
updated_atstring (date-time)required
Example:
2024-10-13T07:20:50.52ZRFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
quantityintegerrequired
Quantity of the item on the subscription after the removal. Always
0 since the item no longer exists on the subscription.update_summaryobjectrequired
Summary of the quantity change.
quantity_delta is negative, reflecting the amount removed.quantity_deltaintegerrequired
Signed change in quantity. Positive when the quantity increased (or an item was added), negative when the quantity decreased (or an item was removed).
proration_billing_modestringrequired
How Paddle calculated proration for the item removal.
Values
prorated_immediatelyPaddle calculates the prorated amount for the subscription changes based on the current billing cycle, then creates a transaction to collect immediately.prorated_next_billing_periodPaddle calculates the prorated amount for the subscription changes based on the current billing cycle, then schedules them to be billed on the next renewal.full_immediatelyPaddle does not calculate proration for the subscription changes, creating a transaction to collect for the full amount immediately.full_next_billing_periodPaddle does not calculate proration for the subscription changes, scheduling for the full amount for the changes to be billed on the next renewal.do_not_billPaddle does not bill for the subscription changes.
on_payment_failurestringrequired
How Paddle handled payment failure for the operation.
Values
prevent_changeIn case of payment failure, prevent the change to the subscription from applying.apply_changeIn case of payment failure, apply the change and update the subscription.
transaction_idstring | nullrequired
Example:
txn_01h04vsbhqc62t8hmd4z3b578cPaddle ID of the transaction created as a result of the item being removed, prefixed with
txn_. null if no transaction was created.Pattern:
^txn_[a-z\d]{26}$One-off charge applied
Details specific to
subscription_one_off_charge_applied actions.actionstringrequired
What happened on the subscription.
Values
subscription_one_off_charge_appliedA one-time charge was applied to the subscription.
effective_fromstringrequired
When the customer was billed for the one-off charge.
Values
immediatelyThe one-off charge was billed at the time of this action — a transaction was created right away.next_billing_periodThe one-off charge was added to the transaction created when the subscription next renews. The customer will be billed for it as part of that renewal.
itemsarrayrequired
Items that were charged as part of the one-off charge.
priceobjectrequired
Price on the subscription.
idstringrequired
Example:
pri_01gsz8z1q1n00f12qt82y31smhUnique Paddle ID for this price, prefixed with
pri_.Pattern:
^pri_[a-z\d]{26}$product_idstringrequired
Example:
pro_01gsz97mq9pa4fkyy0wqenepkzPaddle ID for the product that this price is for, prefixed with
pro_.Pattern:
^pro_[a-z\d]{26}$descriptionstringrequired
Internal description for this price, not shown to customers. Typically notes for your team.
Length: 2–500
typestringrequired
Default:
standardType of item. Standard items are considered part of your catalog and are shown in the Paddle dashboard.
Values
customNon-catalog item. Typically created for a specific transaction or subscription. Not returned when listing or shown in the Paddle dashboard.standardStandard item. Can be considered part of your catalog and reused across transactions and subscriptions easily.
namestring | nullrequired
Name of this price, shown to customers at checkout and on invoices. Typically describes how often the related product bills.
Length: 1–150
billing_cycleobject | nullrequired
How often this price should be charged.
null if price is non-recurring (one-time).intervalstringrequired
Unit of time.
Values
dayweekmonthyear
frequencyintegerrequired
Amount of time.
Min: 1
trial_periodobject | nullrequired
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.intervalstringrequired
Unit of time.
Values
dayweekmonthyear
frequencyintegerrequired
Amount of time.
Min: 1
requires_payment_methodbooleanrequired
Default:
trueWhether this price requires a payment method (
true) or not (false) when trialing. If false, customers can sign up for subscription without entering their payment details, often referred to as a "cardless trial."unit_priceobject | null
Trial price. Customers are billed this amount for the duration of the trial period. Applies to all customers except those in countries with
unit_price_overrides. If null, customers are not charged during the trial.amountstringrequired
Amount in the lowest denomination for the currency, e.g. 10 USD = 1000 (cents). Although represented as a string, this value must be a valid integer.
currency_codestring
Supported three-letter ISO 4217 currency code.
Values
USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
unit_price_overridesarray
List of unit price overrides for trial pricing. Use to override base trial price with a custom trial price and currency for a country or group of countries.
Items: max 250
country_codesarrayrequired
Supported two-letter ISO 3166-1 alpha-2 country code. Customers located in the listed countries are charged the override price.
Items: min 1, unique
string
Two-letter ISO 3166-1 alpha-2 representation of a supported country.
Values
ADAndorraAEUnited Arab EmiratesAGAntigua and BarbudaAIAnguillaALAlbania
+ Show all values− Hide values
AMArmeniaAOAngolaARArgentinaASAmerican SamoaATAustriaAUAustraliaAWArubaAXÃ…land IslandsAZAzerbaijanBABosnia and HerzegovinaBBBarbadosBDBangladeshBEBelgiumBFBurkina FasoBGBulgariaBHBahrainBIBurundiBJBeninBLSaint BarthélemyBMBermudaBNBruneiBOBoliviaBQCaribbean Netherlands (Bonaire, Sint Eustatius, and Saba)BRBrazilBSBahamasBTBhutanBVBouvet IslandBWBotswanaBZBelizeCACanadaCCCocos IslandsCGRepublic of CongoCHSwitzerlandCICôte d'Ivoire (Ivory Coast)CKCook IslandsCLChileCMCameroonCNChinaCOColombiaCRCosta RicaCVCape VerdeCWCuraçaoCXChristmas IslandCYCyprusCZCzechia (Czech Republic)DEGermanyDJDjiboutiDKDenmarkDMDominicaDODominican RepublicDZAlgeriaECEcuadorEEEstoniaEGEgyptEHWestern SaharaEREritreaESSpainETEthiopiaFIFinlandFJFijiFKFalkland IslandsFMMicronesiaFOFaroe IslandsFRFranceGAGabonGBUnited KingdomGDGrenadaGEGeorgiaGFFrench GuianaGGGuernseyGHGhanaGIGibraltarGLGreenlandGMGambiaGNGuineaGPGuadeloupeGQEquatorial GuineaGRGreeceGSSouth Georgia and the South Sandwich IslandsGTGuatemalaGUGuamGWGuinea-BissauGYGuyanaHKHong KongHMHeard Island and McDonald IslandsHNHondurasHRCroatiaHUHungaryIDIndonesiaIEIrelandILIsraelIMIsle of ManINIndiaIOBritish Indian Ocean TerritoryIQIraqISIcelandITItalyJEJerseyJMJamaicaJOJordanJPJapanKEKenyaKGKyrgyzstanKHCambodiaKIKiribatiKMComorosKNSaint Kitts and NevisKRSouth KoreaKWKuwaitKYCayman IslandsKZKazakhstanLALao People's Democratic Republic (Laos)LBLebanonLCSaint LuciaLILiechtensteinLKSri LankaLRLiberiaLSLesothoLTLithuaniaLULuxembourgLVLatviaMAMoroccoMCMonacoMDMoldovaMEMontenegroMFSaint MartinMGMadagascarMHMarshall IslandsMKMacedoniaMNMongoliaMOMacaoMPNorthern Mariana IslandsMQMartiniqueMRMauritaniaMSMontserratMTMaltaMUMauritiusMVMaldivesMWMalawiMXMexicoMYMalaysiaMZMozambiqueNANamibiaNCNew CaledoniaNENigerNFNorfolk IslandNGNigeriaNLNetherlandsNONorwayNPNepalNRNauruNUNiueNZNew ZealandOMOmanPAPanamaPEPeruPFFrench PolynesiaPGPapua New GuineaPHPhilippinesPKPakistanPLPolandPMSaint Pierre and MiquelonPNPitcairnPRPuerto RicoPSPalestinian territoriesPTPortugalPWPalauPYParaguayQAQatarREReunionRORomaniaRSRepublic of SerbiaRWRwandaSASaudi ArabiaSBSolomon IslandsSCSeychellesSESwedenSGSingaporeSHSaint HelenaSISloveniaSJSvalbard and Jan MayenSKSlovakiaSLSierra LeoneSMSan MarinoSNSenegalSRSurinameSTSão Tomé and PrÃncipeSVEl SalvadorSXSint MaartenSZSwazilandTCTurks and Caicos IslandsTDChadTFFrench Southern and Antarctic LandsTGTogoTHThailandTJTajikistanTKTokelauTLTimor-LesteTMTurkmenistanTNTunisiaTOTongaTRTurkeyTTTrinidad and TobagoTVTuvaluTWTaiwanTZTanzaniaUAUkraineUGUgandaUMUnited States Minor Outlying IslandsUSUnited StatesUYUruguayUZUzbekistanVAHoly See (Vatican City)VCSaint Vincent and the GrenadinesVGBritish Virgin IslandsVIU.S. Virgin IslandsVNVietnamVUVanuatuWFWallis and FutunaWSSamoaXKKosovoYTMayotteZASouth AfricaZMZambia
unit_priceobjectrequired
Override price. This price applies to customers located in the countries for this unit price override.
amountstringrequired
Amount in the lowest denomination for the currency, e.g. 10 USD = 1000 (cents). Although represented as a string, this value must be a valid integer.
currency_codestring
Supported three-letter ISO 4217 currency code.
Values
USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
tax_modestringrequired
Default:
account_settingHow tax is calculated for this price.
Values
account_settingPrices use the setting from your account.externalPrices are exclusive of tax.internalPrices are inclusive of tax.locationPrices are inclusive or exclusive of tax, depending on the country of the transaction.
unit_priceobjectrequired
Base price. This price applies to all customers, except for customers located in countries where you have
unit_price_overrides.amountstringrequired
Amount in the lowest denomination for the currency, e.g. 10 USD = 1000 (cents). Although represented as a string, this value must be a valid integer.
currency_codestringrequired
Supported three-letter ISO 4217 currency code.
Values
USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
unit_price_overridesarrayrequired
List of unit price overrides. Use to override the base price with a custom price and currency for a country or group of countries.
Items: max 250
country_codesarrayrequired
Supported two-letter ISO 3166-1 alpha-2 country code. Customers located in the listed countries are charged the override price.
Items: min 1, unique
string
Two-letter ISO 3166-1 alpha-2 representation of a supported country.
Values
ADAndorraAEUnited Arab EmiratesAGAntigua and BarbudaAIAnguillaALAlbania
+ Show all values− Hide values
AMArmeniaAOAngolaARArgentinaASAmerican SamoaATAustriaAUAustraliaAWArubaAXÃ…land IslandsAZAzerbaijanBABosnia and HerzegovinaBBBarbadosBDBangladeshBEBelgiumBFBurkina FasoBGBulgariaBHBahrainBIBurundiBJBeninBLSaint BarthélemyBMBermudaBNBruneiBOBoliviaBQCaribbean Netherlands (Bonaire, Sint Eustatius, and Saba)BRBrazilBSBahamasBTBhutanBVBouvet IslandBWBotswanaBZBelizeCACanadaCCCocos IslandsCGRepublic of CongoCHSwitzerlandCICôte d'Ivoire (Ivory Coast)CKCook IslandsCLChileCMCameroonCNChinaCOColombiaCRCosta RicaCVCape VerdeCWCuraçaoCXChristmas IslandCYCyprusCZCzechia (Czech Republic)DEGermanyDJDjiboutiDKDenmarkDMDominicaDODominican RepublicDZAlgeriaECEcuadorEEEstoniaEGEgyptEHWestern SaharaEREritreaESSpainETEthiopiaFIFinlandFJFijiFKFalkland IslandsFMMicronesiaFOFaroe IslandsFRFranceGAGabonGBUnited KingdomGDGrenadaGEGeorgiaGFFrench GuianaGGGuernseyGHGhanaGIGibraltarGLGreenlandGMGambiaGNGuineaGPGuadeloupeGQEquatorial GuineaGRGreeceGSSouth Georgia and the South Sandwich IslandsGTGuatemalaGUGuamGWGuinea-BissauGYGuyanaHKHong KongHMHeard Island and McDonald IslandsHNHondurasHRCroatiaHUHungaryIDIndonesiaIEIrelandILIsraelIMIsle of ManINIndiaIOBritish Indian Ocean TerritoryIQIraqISIcelandITItalyJEJerseyJMJamaicaJOJordanJPJapanKEKenyaKGKyrgyzstanKHCambodiaKIKiribatiKMComorosKNSaint Kitts and NevisKRSouth KoreaKWKuwaitKYCayman IslandsKZKazakhstanLALao People's Democratic Republic (Laos)LBLebanonLCSaint LuciaLILiechtensteinLKSri LankaLRLiberiaLSLesothoLTLithuaniaLULuxembourgLVLatviaMAMoroccoMCMonacoMDMoldovaMEMontenegroMFSaint MartinMGMadagascarMHMarshall IslandsMKMacedoniaMNMongoliaMOMacaoMPNorthern Mariana IslandsMQMartiniqueMRMauritaniaMSMontserratMTMaltaMUMauritiusMVMaldivesMWMalawiMXMexicoMYMalaysiaMZMozambiqueNANamibiaNCNew CaledoniaNENigerNFNorfolk IslandNGNigeriaNLNetherlandsNONorwayNPNepalNRNauruNUNiueNZNew ZealandOMOmanPAPanamaPEPeruPFFrench PolynesiaPGPapua New GuineaPHPhilippinesPKPakistanPLPolandPMSaint Pierre and MiquelonPNPitcairnPRPuerto RicoPSPalestinian territoriesPTPortugalPWPalauPYParaguayQAQatarREReunionRORomaniaRSRepublic of SerbiaRWRwandaSASaudi ArabiaSBSolomon IslandsSCSeychellesSESwedenSGSingaporeSHSaint HelenaSISloveniaSJSvalbard and Jan MayenSKSlovakiaSLSierra LeoneSMSan MarinoSNSenegalSRSurinameSTSão Tomé and PrÃncipeSVEl SalvadorSXSint MaartenSZSwazilandTCTurks and Caicos IslandsTDChadTFFrench Southern and Antarctic LandsTGTogoTHThailandTJTajikistanTKTokelauTLTimor-LesteTMTurkmenistanTNTunisiaTOTongaTRTurkeyTTTrinidad and TobagoTVTuvaluTWTaiwanTZTanzaniaUAUkraineUGUgandaUMUnited States Minor Outlying IslandsUSUnited StatesUYUruguayUZUzbekistanVAHoly See (Vatican City)VCSaint Vincent and the GrenadinesVGBritish Virgin IslandsVIU.S. Virgin IslandsVNVietnamVUVanuatuWFWallis and FutunaWSSamoaXKKosovoYTMayotteZASouth AfricaZMZambia
unit_priceobjectrequired
Override price. This price applies to customers located in the countries for this unit price override.
amountstringrequired
Amount in the lowest denomination for the currency, e.g. 10 USD = 1000 (cents). Although represented as a string, this value must be a valid integer.
currency_codestringrequired
Supported three-letter ISO 4217 currency code.
Values
USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
quantityobjectrequired
Example:
{"minimum":1,"maximum":100}Limits on how many times the related product can be purchased at this price. Useful for discount campaigns.
minimumintegerrequired
Default:
1Example:
1Minimum quantity of the product related to this price that can be bought. Required if
maximum set.Range: 1–999999999
maximumintegerrequired
Default:
100Example:
100Maximum quantity of the product related to this price that can be bought. Required if
minimum set. Must be greater than or equal to the minimum value.Range: 1–999999999
statusstringrequired
Default:
activeWhether this entity can be used in Paddle.
Values
activeEntity is active and can be used.archivedEntity is archived, so can't be used.
custom_dataobject | nullrequired
Example:
{"customer_reference_id":"abcd1234"}Your own structured key-value data.
import_metaobject | nullrequired
Import information for this entity.
null if this entity is not imported.external_idstring | null
Example:
9b95b0b8-e10f-441a-862e-1936a6d818abReference or identifier for this entity from the provider where it was imported from.
Length: 1–200
imported_fromstringrequired
Example:
paddle_classicName of the platform or provider where this entity was imported from.
Length: 1–200
created_atstring (date-time)required
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
updated_atstring (date-time)required
Example:
2024-10-13T07:20:50.52ZRFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
quantityintegerrequired
Quantity of the item on the subscription at the time of the history entry.
on_payment_failurestringrequired
How Paddle handled payment failure for the one-off charge.
Values
prevent_changeIn case of payment failure, prevent the change to the subscription from applying.apply_changeIn case of payment failure, apply the change and update the subscription.
transaction_idstring | nullrequired
Example:
txn_01h04vsbhqc62t8hmd4z3b578cPaddle ID of the transaction created for the one-off charge, prefixed with
txn_. null if no transaction was created.Pattern:
^txn_[a-z\d]{26}$Past due
Details specific to
subscription_past_due actions.actionstringrequired
What happened on the subscription.
Values
subscription_past_dueThe subscription's status becamepast_dueafter a payment failed.
statusstringrequired
The status of the subscription after becoming past due.
Values
activeSubscription is active. Paddle is billing for this subscription and related transactions aren't past due.canceledSubscription is canceled. Automatically set by Paddle when a subscription is canceled. When a subscription is set to cancel on the next billing period, a scheduled change for the cancellation is created. The subscription status moves to canceled when the scheduled change takes effect.past_dueSubscription has an overdue payment. Automatically set by Paddle when payment fails for an automatically-collected transaction, or when payment terms have elapsed for a manually-collected transaction (an invoice).pausedSubscription is paused. Automatically set by Paddle when a subscription is paused. When a subscription is set to pause on the next billing period, a scheduled change for the pause is created. The subscription status moves topausedwhen the scheduled change takes effect.trialingSubscription is in trial.
transaction_idstringrequired
Example:
txn_01h04vsbhqc62t8hmd4z3b578cPaddle ID of the failed transaction, prefixed with
txn_.Pattern:
^txn_[a-z\d]{26}$Paused
Details specific to
subscription_paused actions.actionstringrequired
What happened on the subscription.
Values
subscription_pausedThe subscription's status becamepaused.
effective_fromstringrequired
Whether the subscription was paused immediately, or scheduled to pause.
Values
immediatelyThe subscription was paused immediately.next_billing_periodThe subscription was scheduled to pause at the next billing period.
statusstringrequired
The status of the subscription after pausing.
Values
activeSubscription is active. Paddle is billing for this subscription and related transactions aren't past due.canceledSubscription is canceled. Automatically set by Paddle when a subscription is canceled. When a subscription is set to cancel on the next billing period, a scheduled change for the cancellation is created. The subscription status moves to canceled when the scheduled change takes effect.past_dueSubscription has an overdue payment. Automatically set by Paddle when payment fails for an automatically-collected transaction, or when payment terms have elapsed for a manually-collected transaction (an invoice).pausedSubscription is paused. Automatically set by Paddle when a subscription is paused. When a subscription is set to pause on the next billing period, a scheduled change for the pause is created. The subscription status moves topausedwhen the scheduled change takes effect.trialingSubscription is in trial.
Payment attempted
Details specific to
subscription_payment_attempted actions. Recorded when a payment attempt fails for an operation that attempts a payment, like a subscription update or one-time charge. Successful payment outcomes are captured by the relevant action, like subscription_item_added, subscription_one_off_charge_applied, or subscription_activated.actionstringrequired
What happened on the subscription.
Values
subscription_payment_attemptedA payment for a change to the subscription was attempted and failed.
operationstringrequired
Operation that resulted in the failed payment attempt. Use the related transaction ID to get the full details of the attempted change.
Values
subscription_updateAn update to the subscription — for example, an item add, remove, quantity change, or billing date move.subscription_one_off_chargeA one-off charge applied to the subscription.subscription_activateAn activation of a trialing subscription.
transaction_idstringrequired
Example:
txn_01h04vsbhqc62t8hmd4z3b578cPaddle ID of the failed transaction, prefixed with
txn_.Pattern:
^txn_[a-z\d]{26}$Payment method added
Details specific to
subscription_payment_method_added actions.actionstringrequired
What happened on the subscription.
Values
subscription_payment_method_addedA payment method was added to the subscription.
Payment method removed
Details specific to
subscription_payment_method_removed actions.actionstringrequired
What happened on the subscription.
Values
subscription_payment_method_removedA payment method was removed from the subscription.
Payment method updated
Details specific to
subscription_payment_method_updated actions.actionstringrequired
What happened on the subscription.
Values
subscription_payment_method_updatedThe payment method on the subscription was changed.
Renewed
Details specific to
subscription_renewed actions.actionstringrequired
What happened on the subscription.
Values
subscription_renewedThe subscription renewed for a new billing period.
next_billed_atstring (date-time)required
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when the subscription was next scheduled to be billed after this renewal.
current_billing_periodobjectrequired
Billing period of the subscription after renewal.
starts_atstring (date-time)required
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when this period starts.
ends_atstring (date-time)required
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when this period ends.
transaction_idstringrequired
Example:
txn_01h04vsbhqc62t8hmd4z3b578cPaddle ID of the transaction created for this renewal, prefixed with
txn_.Pattern:
^txn_[a-z\d]{26}$Resumed
Details specific to
subscription_resumed actions.actionstringrequired
What happened on the subscription.
Values
subscription_resumedThe subscription's status becameactiveafter being paused.
statusstringrequired
The status of the subscription after resuming.
Values
activeSubscription is active. Paddle is billing for this subscription and related transactions aren't past due.canceledSubscription is canceled. Automatically set by Paddle when a subscription is canceled. When a subscription is set to cancel on the next billing period, a scheduled change for the cancellation is created. The subscription status moves to canceled when the scheduled change takes effect.past_dueSubscription has an overdue payment. Automatically set by Paddle when payment fails for an automatically-collected transaction, or when payment terms have elapsed for a manually-collected transaction (an invoice).pausedSubscription is paused. Automatically set by Paddle when a subscription is paused. When a subscription is set to pause on the next billing period, a scheduled change for the pause is created. The subscription status moves topausedwhen the scheduled change takes effect.trialingSubscription is in trial.
on_resumestringrequired
How the subscription was resumed. Indicates whether a new billing period was started or the existing one continued.
Values
continue_existing_billing_periodWhen resuming, continue the existing billing period. If the customer resumes before the end date of the existing billing period, there's no immediate charge. If after, an error is returned.start_new_billing_periodWhen resuming, start a new billing period. Thecurrent_billing_period.starts_atdate is set to the resume date, and Paddle immediately charges the full amount for the new billing period.
Scheduled change added
Details specific to
subscription_scheduled_change_added actions.actionstringrequired
What happened on the subscription.
Values
subscription_scheduled_change_addedA scheduled change was added to the subscription.
scheduled_changeobjectrequired
Details of the scheduled change that was added to the subscription.
actionstringrequired
Kind of change that's scheduled to be applied to this subscription.
Values
cancelSubscription is scheduled to cancel. Its status changes tocanceledon theeffective_atdate.pauseSubscription is scheduled to pause. Its status changes topausedon theeffective_atdate.resumeSubscription is scheduled to resume. Its status changes toactiveon theeffective_atdate.
effective_atstring (date-time)required
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when this scheduled change takes effect.
resume_atstring (date-time) | nullrequired
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when a paused subscription should resume. Only used for
pause scheduled changes.Scheduled change removed
Details specific to
subscription_scheduled_change_removed actions.actionstringrequired
What happened on the subscription.
Values
subscription_scheduled_change_removedA scheduled change was removed from the subscription.
scheduled_changeobjectrequired
Details of the scheduled change that was removed from the subscription.
actionstringrequired
Kind of change that's scheduled to be applied to this subscription.
Values
cancelSubscription is scheduled to cancel. Its status changes tocanceledon theeffective_atdate.pauseSubscription is scheduled to pause. Its status changes topausedon theeffective_atdate.resumeSubscription is scheduled to resume. Its status changes toactiveon theeffective_atdate.
effective_atstring (date-time)required
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when this scheduled change takes effect.
resume_atstring (date-time) | nullrequired
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when a paused subscription should resume. Only used for
pause scheduled changes.Scheduled change updated
Details specific to
subscription_scheduled_change_updated actions.actionstringrequired
What happened on the subscription.
Values
subscription_scheduled_change_updatedA scheduled change on the subscription was changed.
scheduled_changeobjectrequired
Details of the updated scheduled change on the subscription. This is what the scheduled change was changed to.
actionstringrequired
Kind of change that's scheduled to be applied to this subscription.
Values
cancelSubscription is scheduled to cancel. Its status changes tocanceledon theeffective_atdate.pauseSubscription is scheduled to pause. Its status changes topausedon theeffective_atdate.resumeSubscription is scheduled to resume. Its status changes toactiveon theeffective_atdate.
effective_atstring (date-time)required
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when this scheduled change takes effect.
resume_atstring (date-time) | nullrequired
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when a paused subscription should resume. Only used for
pause scheduled changes.metaobjectrequired
Information about this response.
request_idstringrequired
Example:
b15ec92e-8688-40d4-a04d-f44cbec93355Unique ID for the request relating to this response. Provide this when contacting Paddle support about a specific request.
paginationobjectrequired
Keys used for working with paginated results.
per_pageintegerrequired
Number of entities per page for this response. May differ from the number requested if the requested number is greater than the maximum.
nextstring (uri)required
URL containing the query parameters of the original request, along with the
after parameter that marks the starting point of the next page. Always returned, even if has_more is false.has_morebooleanrequired
Whether this response has another page.
estimated_totalinteger
Example:
999Estimated number of entities for this response.
For datasets with 100,000 or fewer matches, returns the exact count. For datasets with more than 100,000 matches, returns 100001 to indicate that more than 100,000 entities match. Returns -1 when counting is skipped or couldn't be calculated.
Use has_more and next to page through all results rather than relying on estimated_total for an exact count.
{ "data": [ { "id": "subhis_01k0w2m6p8x9y0z1a2b3c4d5e6", "group_id": "subhisgrp_01k0w2m6p8x9y0z1a2b3c4d5e6", "subscription_id": "sub_01hv959anj4zrw503h2acawb3p", "occurred_at": "2024-05-02T11:20:31Z", "source": "customer_portal", "actor": { "type": "customer", "id": "ctm_01hv8wt8nffez4p2t6typn4a5j" }, "reason": "customer_request", "detail": { "action": "subscription_canceled", "effective_from": "next_billing_period" } }, { "id": "subhis_01k0w1f5n7w8x9y0z1a2b3c4d5", "group_id": "subhisgrp_01k0w1f5n7w8x9y0z1a2b3c4d5", "subscription_id": "sub_01hv959anj4zrw503h2acawb3p", "occurred_at": "2024-04-12T12:42:28Z", "source": "system", "actor": { "type": "system", "id": null }, "reason": null, "detail": { "action": "subscription_activated", "status": "active", "first_billed_at": "2024-04-12T12:42:28Z", "current_billing_period": { "starts_at": "2024-04-12T12:42:28Z", "ends_at": "2024-05-12T12:42:28Z" }, "transaction_id": "txn_01h89231k3a1q8mn6p4r5s7t9v" } }, { "id": "subhis_01k0w0a4m6v7w8x9y0z1a2b3c4", "group_id": "subhisgrp_01k0w0a4m6v7w8x9y0z1a2b3c4", "subscription_id": "sub_01hv959anj4zrw503h2acawb3p", "occurred_at": "2024-04-12T12:42:27Z", "source": "checkout", "actor": { "type": "customer", "id": "ctm_01hv8wt8nffez4p2t6typn4a5j" }, "reason": null, "detail": { "action": "subscription_created", "status": "active", "collection_mode": "automatic", "billing_details": null, "customer": null, "address": null, "business": null, "currency_code": "USD", "current_billing_period": { "starts_at": "2024-04-12T12:42:27Z", "ends_at": "2024-05-12T12:42:27Z" }, "billing_cycle": { "frequency": 1, "interval": "month" }, "items": null, "custom_data": null, "discount": null, "has_payment_method": true } } ], "meta": { "request_id": "170e71a2-ed13-4f45-b002-45693f5361b4", "pagination": { "per_page": 50, "next": "https://api.paddle.com/subscriptions/sub_01hv959anj4zrw503h2acawb3p/history?after=subhis_01k0w0a4m6v7w8x9y0z1a2b3c4", "has_more": false, "estimated_total": 3 } }}