Subscription creation

A new subscription is the first stage of the subscription lifecycle. You might call this a new signup, new trial, or new customer.

When a subscription is created, you should provision so that your customer has access to your app.

How it works

Paddle automatically creates a subscription when:

• A customer pays for recurring items using Paddle Checkout

  Paddle creates a transaction when a checkout is opened to calculate and collect the amount due. When the checkout and related transaction are paid, Paddle creates a subscription for any recurring items.

• You created and issued an invoice for a customer that included recurring items

  Invoices are manually-collected transactions in Paddle. When a manually-collected transaction is issued using the Paddle web app, or marked as billed using the API, Paddle creates a subscription for any recurring items.

How to create a subscription

Events

1. Customer opens checkout

   transaction.created	Paddle creates a transaction for the items on the checkout. Its status is draft while it's missing customer and address information. Its origin is web.

2. Customer enters their information

   customer.created	When a customer enters their email address, Paddle creates a customer if one can't be found that matches the email address.
   address.created	When a customer enters their country and ZIP/postal code, Paddle creates an address related to this customer.
   transaction.updated	Paddle updates the transaction with the new customer and address that was just created. The transaction status is ready because the transaction has customer and address information.
   transaction.ready	Occurs because the transaction status changes to ready.

3. Customer enters business information (optional)

   business.created	If a customer chooses to enter a tax/VAT number, Paddle creates a business.
   address.updated	When collecting business information, checkout collects a complete address. Paddle updates the address entity with the new information.
   transaction.updated	Paddle updates the transaction with the new business that was just created. Totals on the transaction may be updated to reflect changes in tax.

4. Customer adds a discount or makes other changes (optional)

   transaction.updated	When a customer adds a discount or makes changes to items or quantities, Paddle updates the transaction.

5. Customer completes checkout successfully

   transaction.updated	The transaction status changes to paid now that the customer has paid successfully. The transaction is updated with information about the successful payment.
   transaction.paid	Occurs because the transaction status changes to paid.
   subscription.created	Paddle creates a subscription for the customer, address, and business against the transaction. Its status is active or trialing, depending on the items on the subscription. Includes a transaction_id field so you can match with the completed transaction.
   subscription.trialing	If items on a subscription have a trial period, this event occurs because the subscription status is trialing.
   subscription.activated	If items on a subscription have no trial period, this event occurs because the subscription status is active.
   transaction.updated	The transaction is updated with the ID of the new subscription and information about fees, payouts, and earnings.
   transaction.updated	An invoice number is assigned to the transaction. Its status changes to completed as Paddle has finished processing it.
   transaction.completed	Occurs because the transaction status changes to completed.

Emails

For compliance reasons, Paddle sends emails for subscription lifecycle events.

When a subscription is created, Paddle sends:

Recommended workflow

1. Collect customer information

   As part of your sign-up workflow, we recommend that you capture customer information. The exact information that you capture depends on your app, but we recommend capturing at least:

   Email address	Email address for your customer. You might capture this for creating a user account for your app.
   Country	Country where your customer is located. You might use geolocation to get this.

   You can pass customer, address, and business information to Paddle Checkout using Paddle.js. While only email address, country, and (in some countries) ZIP/postal code are required to complete a purchase, any information passed to Paddle.js is stored against the related entities in Paddle.

   We don't recommend using the cardholder name captured by Paddle Checkout for user account names in your app. Cardholders may be contacts at a business or the business name itself. If you need it, collect a name as part of signup and store in your database.

2. Listen for events

   We recommend that you listen for:

   subscription.created	Get notified when a new subscription is created. Transactions with the origin of web are created by Paddle.js for checkouts.
   transaction.paid	Get notified that a customer paid successfully.
   transaction.completed	Get notified when a transaction is completed. This means it is fully paid and Paddle has completed processing.

   In most cases, listening for subscription.created and transaction.completed should be sufficient for provisioning. You can match the transaction_id against the subscription.created event with the id against transaction.completed events to get the related transaction for a subscription.

    

   It may take a few seconds after a transaction is paid for Paddle to create a subscription. This shouldn't be a problem in most workflows, but you may prefer to listen for transaction.paid events as well. When this event occurs, you can be confident that a customer paid successfully, create a record for the subscription in your database when received, and provision. You can enrich your subscription record with the subscription ID and any information from the subscription that Paddle created when transaction.completed occurs.

3. Store information in your database

   Create a record in your database for the new subscription. As well as checking and storing the occurred_at date against notifications, we recommend storing:

   Description	Field name	Reason to store
   Customer and business details	customer.email and any other information captured in your frontend as part of signup.	You might use this to create user accounts for customers so they may access your app.
   Subscription ID	subscription.id	Used to identify this subscription in webhook responses and work with this subscription using the API.
   Subscription status	subscription.status	Used to limit or stop access when paused or canceled, and determine if a subscription is past due or trialing.
   Subscription items	subscription.items[].price.id, subscription.items[].quantity	Used to change items on a subscription as part of an upgrade or downgrade workflow.
   Subscription products	subscription.items[].price.product_id	Used to determine which plan your customer is on, which may determine the features in your app that they should have access to.
   Collection mode	subscription.collection_mode	Used to determine whether a subscription bills automatically or whether Paddle sends an invoice for charges that customers must pay manually.
   Next billing date	subscription.next_billed_at	Used to determine when a subscription renews if active, or when it's scheduled to resume if paused.
   Pause date	subscription.paused_at	Used to determine if a subscription is paused.
   Cancellation date	subscription.canceled_at	Used to determine if a subscription is canceled.
   Scheduled change	subscription.scheduled_change	Used to determine if a subscription has a scheduled change to pause, cancel, or resume. Some actions are restricted on subscriptions with a scheduled change.

   You may like to store and update other fields if you'd like to build a more complete billing page, see: Handle provisioning and fulfillment

4. Provision

   Provision your app so your customer has access.

    

   Use the subscription.status to determine whether a subscription should have access to your app. Where status is trialing, active, or past_due, customers should have full access to your app.

    

   Depending on your pricing model, you may need to give customers access to a specific set of features based on the products they bought. Check subscription.items[].price.product_id to check the products that your customer has paid for.

Related pages