Paddle Billing
Search

Subscription creation

Paddle creates a new subscription for recurring items when payment for a checkout completes or when you issue an invoice.

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

How to create a subscription

Events

This guide is overview of events that typically occur. Depending on your customer journey and how you build your workflows, not all events listed may occur, or additional events may occur.

We can't guarantee the order of delivery for webhooks. Store and check the occurred_at date against a webhook before making changes.

  1. Customer opens checkout

    transaction.createdPaddle 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.createdWhen a customer enters their email address, Paddle creates a customer if one can't be found that matches the email address.
    address.createdWhen a customer enters their country and ZIP/postal code, Paddle creates an address related to this customer.
    transaction.updatedPaddle 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.readyOccurs because the transaction status changes to ready.
  3. Customer enters business information (optional)

    business.createdIf a customer chooses to enter a tax/VAT number, Paddle creates a business.
    address.updatedWhen collecting business information, checkout collects a complete address. Paddle updates the address entity with the new information.
    transaction.updatedPaddle 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.updatedWhen a customer adds a discount or makes changes to items or quantities, Paddle updates the transaction.
  5. Customer completes checkout successfully

    transaction.updatedThe transaction status changes to paid now that the customer has paid successfully. The transaction is updated with information about the successful payment.
    transaction.paidOccurs because the transaction status changes to paid.
    subscription.createdPaddle 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.trialingIf items on a subscription have a trial period, this event occurs because the subscription status is trialing.
    subscription.activatedIf items on a subscription have no trial period, this event occurs because the subscription status is active.
    transaction.updatedThe transaction is updated with the ID of the new subscription and information about fees, payouts, and earnings.
    transaction.updatedAn invoice number is assigned to the transaction. Its status changes to completed as Paddle has finished processing it.
    transaction.completedOccurs 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:

Screenshot showing a receipt email. It includes a list of items, total, and billing date.

Receipt

Your receipt from [company]

List of items purchased, along with totals and purchase date. Includes a PDF invoice for their records.

Screenshot showing a subscription confirmation email. It includes a list of items, total, and renewal dates. There are links to cancel and update payment method.

Subscription confirmation

Welcome to [company]

Information about any recurring items purchased. Includes renewal dates and totals, and links to update payment method and cancel subscription.

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 addressEmail address for your customer. You might capture this for creating a user account for your app.
    CountryCountry 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.createdGet notified when a new subscription is created. Transactions with the origin of web are created by Paddle.js for checkouts.
    transaction.paidGet notified that a customer paid successfully.
    transaction.completedGet 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:

    DescriptionField nameReason to store
    Customer and business detailscustomer.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 IDsubscription.idUsed to identify this subscription in webhook responses and work with this subscription using the API.
    Subscription statussubscription.statusUsed to limit or stop access when paused or canceled, and determine if a subscription is past due or trialing.
    Subscription itemssubscription.items[].price.id, subscription.items[].quantityUsed to change items on a subscription as part of an upgrade or downgrade workflow.
    Subscription productssubscription.items[].price.product_idUsed to determine which plan your customer is on, which may determine the features in your app that they should have access to.
    Collection modesubscription.collection_modeUsed to determine whether a subscription bills automatically or whether Paddle sends an invoice for charges that customers must pay manually.
    Next billing datesubscription.next_billed_atUsed to determine when a subscription renews if active, or when it's scheduled to resume if paused.
    Pause datesubscription.paused_atUsed to determine if a subscription is paused.
    Cancellation datesubscription.canceled_atUsed to determine if a subscription is canceled.
    Scheduled changesubscription.scheduled_changeUsed 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