What's new?
We updated the Paddle API so that now you can pass null as a value to the subscription_id query parameter when listing transactions. You can use this to filter to see single purchase transactions that aren't related to a subscription.
/transactions?subscription_id=null Return entities related to the specified subscription. Use a comma-separated list to specify multiple subscription IDs. Pass null to return entities that aren't related to any subscription
How it works
Transactions and subscriptions are closely related entities in Paddle. For example:
- Where a transaction for recurring items completes, Paddle automatically creates a related subscription.
- Subscriptions automatically create transactions for renewals, subscription lifecycle changes, and one-time charges.
Where a transaction and a subscription are related, the subscription_id is included against the transaction for your reference. You can filter to see a transactions for particular subscriptions using the subscription_id query parameter when listing transactions.
You can also use Paddle to sell single purchases that don't create new subscriptions or relate to an existing subscription. This might include ebooks, software downloads, or other digital goods. Where transactions are for single purchases, the subscription_id is null.
Previously, there was no way to filter to see single purchases in Paddle.
Now, you can pass null as a value when using the subscription_id query parameter when listing transactions to see them. Paddle returns transactions that aren't related to a subscription. Combine with the status parameter with the value completed to see transactions for single purchases.
/transactions?status=completed&subscription_id=null Return entities that match the specified status. Use a comma-separated list to specify multiple status values
Return entities related to the specified subscription. Use a comma-separated list to specify multiple subscription IDs. Pass null to return entities that aren't related to any subscription
As well as single purchase transactions, transactions for incomplete checkouts and draft invoices have null as a value for subscription_id — even if the transaction is for recurring items. Paddle creates a subscription for recurring items when a checkout completes or when an invoice is issued.
Next steps
This change is available in version 1 of the Paddle API.
It's a non-breaking change, meaning it doesn't impact existing integrations.
You can list transactions using the API to start using the new accepted query parameter value.
Summary of changes
| Entity | Field | Change | Type |
|---|---|---|---|
| List transactions | subscription_id | ~ Updated | Field |
| Accepts null to filter for non-subscription transactions. | |||