Create a subscription with a trial

Learn how to create a subscription with a discount in the trial period. We assume that you are familiar with the BillPro UI and you have completed the basic tutorials to get started and create an order with the BillPro API.

In BillPro, you can create a subscription with a trial with a duration of exactly one subscription period. However, if you want to adjust the length of the subscription period to a non-standard length, or change the pricing, then you should use the API to adjust the future scheduled payment. These changes will apply to future payments until you make more changes.

An example use case is a pharmacy product. The user has an initial trial prescription for 3 weeks. Then after the trial period, the standard prescription is for 4 weeks. In this case, you can create an initial monthly subscription with the UI. Modify the first scheduled payment to be due after 3 weeks and adjust the amount for the trial. Then modify the subscription period to four weeks and adjust the amount.

All merchants can Integrate with payment links or if you are a CardCorp merchant you can also Integrate with custom checkout and payment iframe.

1. In the UI, create a discount to apply to your trial period. The calculation of the trial price will be trial price = regular price - discount
   See https://docs.bill.pro/docs/create-product-groups-and-pricing-elements#create-discounts
2. In the UI, create a subscription product. For the Price, enter your regular price and for the Discount, select your trial discount. Select the option to Apply discount to the initial payment only.
   See https://docs.bill.pro/docs/create-a-subscription-product
3. Create a customer with the UI, or API, or use the CSV upload.
   For the UI, see https://docs.bill.pro/docs/create-customers
   For the API, see https://docs.bill.pro/reference/create-customer
4. Create a subscription order in the API. Set the start_date with the date format DD/MM/YYYY HH:MM.
   • See https://docs.bill.pro/reference/create-subscription-order
     Create a subscription order

     curl --request POST \  
          --url 'https://staging.bill.pro/api/v1/orders/create_subscription_order' \
          --header 'Authorization: Bearer {apiKey}' \
          --header 'accept: application/json' \
          --header 'content-type: application/json' \
          --data '
     {
       "order": {
         "currency": "EUR",
         "customer_id": 307,
         "invoice_id": "MyInvoiceID",
         "recurring_collection_interval": "MONTH",
         "start_date": "17/07/2024 14:00",
         "start_date_unix": "",
         "redirect_url": "https://success.example.com/",
         "failed_redirect_url": "https://failed.example.com/",
         "note": "Test subscription",
         "create_checkout": true,
         "order_product": {
           "product_id": 156
         }
       }
     }'

5. Accept the initial payment via payment link or custom checkout (CardCorp merchants only). If you are integrating with payment links, then you need to display or send the payment link to the customer.
   • See https://docs.bill.pro/reference/integrate-with-payment-links
   • See https://docs.bill.pro/reference/integrate-with-custom-checkout-and-payment-iframe

6. Get the billing events of the order from the scheduled payments endpoint for the order.
   • See https://docs.bill.pro/reference/list-scheduled-payments
     • In a subscription there is one event that is scheduled at the end of the first billing cycle. You will need the ID of the scheduled payment for the next step.
       List scheduled payments

       curl --request GET \  
            --url 'https://staging.bill.pro/api/v1/orders/{order_id}/scheduled_payments' \
            --header 'Authorization: Bearer {apiKey}' \
            --header 'accept: application/json' \
            --header 'content-type: application/json'

7. Modify the scheduled payment to adjust the date of the next billing event to the end of the trial period. This will be the new billing date for future payments. Set the date using UTC time in ISO 8601 format.
   • See https://docs.bill.pro/reference/update-scheduled-payment
     Update scheduled payment

     curl --request PUT \  
          --url 'https://staging.bill.pro/api/v1/orders/{order_id}/scheduled_payments/{spid}' \
          --header 'Authorization: Bearer {apiKey}' \
          --header 'accept: application/json' \
          --header 'content-type: application/json' \
          --data '
     {
       "scheduled_payment": {
         "scheduled_at": "2024-07-19T14:00:00.000Z",
         "status": "scheduled"
       }
     }
     '