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 customers have 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 dashboard, or marked as billed using the API, Paddle creates a subscription for any recurring items.

How to create a subscription

Events

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 a customer. You might capture this for creating a user account for your app.
   Country	Country where a 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's fully paid and Paddle has completed processing.

   In most cases, listening for subscription.created and transaction.completed should be enough 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 a 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 want to build a more comprehensive billing and subscription management experience. To learn more, see Handle provisioning and fulfillment

4. Provision

   Provision your app so a 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 a customer has paid for.

Related pages