Create subscription orders to charge your customers recurring payments at regular intervals. This tutorial assumes that you have completed Get started with the BillPro API.

Before you begin

Check that your merchant account and BillPro configuration have the option to create recurring payments for subscriptions.
For Stripe or CardCorp merchant accounts, you can Integrate with payment links. For CardCorp merchant accounts, you can also Integrate with custom checkout and payment iframe.
Log in to the BillPro UI, create an API user, and get an API key. See Get started with the BillPro API.

Subscription billing with the BillPro API

BillPro supports monthly, quarterly, and yearly subscription billing as predefined options. Use monthly or quarterly subscriptions when possible, because yearly subscriptions have a higher risk rating with acquirers.

In BillPro, a subscription has an initial payment and recurring payments. The customer provides their card details to make the initial payment. By default, the initial payment covers one subscription period. You can also configure a subscription product with a fee and a discount that apply to the initial payment only.

When you create a subscription order, you can change the default start date. This is the date of the first recurring payment. BillPro charges recurring payments on the same day of each month. If you set the start date to the last day of a month, BillPro charges on the last day of each month.

You can pause and resume subscriptions in BillPro. In the UI, you can resume a subscription manually or schedule a restart date. With the API, use the resume request to restart the subscription immediately and continue charging the customer on the same billing cycle. You cannot charge a payment that was due while the subscription was paused.

To comply with card scheme rules, you can activate subscription renewal notifications in BillPro, and customers can cancel their subscriptions at any time in the order portal.

The BillPro API lets you reschedule subscription payments and change the payment amount. To change the billing cycle and the amount of future payments, use the update scheduled payment request. With this request, you have more flexible subscription options. For example, pharmacy merchants can charge a customer for a prescription every four weeks, instead of monthly. See Update scheduled payment.

Tutorial steps

In the BillPro UI, create a tax to include in the product price.
(Optional) Create a discount.
Create a subscription product.
Create a subscription order with the BillPro API.

Create a tax in the BillPro UI

To create a tax in the BillPro UI, follow these steps.

In the navigation menu, go to Products > Taxes.
Click (+). The New Tax section opens.
Enter a Tax Name.
Enter the Tax Percentage.
(Optional) Enter a Description.
To save the tax, click Save Tax.

BillPro calculates taxes to include in the product price after it applies fees and discounts.

When you create an order with the BillPro API, you can calculate the tax and apply the amount to the order if you did not lock the product pricing.

Optional: Create a discount in the UI

To create an introductory offer or trial period, create a discount in the UI. When you create your product, apply the discount to the initial payment. You can also apply it to all subscription payments.

You can also create fees in the UI to apply to your subscription products.

To create a discount, follow these steps.

In the navigation menu, go to Products > Discounts.
Click (+). The New Discount section opens.
Enter a Discount Name.
To calculate the discount as a percentage, select Calculate Percentage.
Enter the Discount Amount.
(Optional) Enter a Discount Description.
To save the discount, click Save Discount.

You can also apply a discount amount directly in the API, but the discount applies to all payments, not just the initial payment.

Create a subscription product in the UI

Next, create a subscription product and select your tax, discounts, or fees.

To create a subscription product, follow these steps.

In the navigation menu, click (+) and select Add Product. The New Product section opens.
For Product Information, enter a Product Name.
For the Product ID, enter your own identifier to help you find the product when searching. If you don't create one, BillPro creates a Product ID for you.
Enter the Product Description.
For the Price, enter the amount of each scheduled payment with tax.
(Optional) In Select Discount, enter search text in the discount name and select the discount.
In Select Tax, enter search text in the tax name and select the tax.
For the Product type, select Subscription.
(Optional) In Payment, select Apply discount to initial payment only.
Click Save.

In this tutorial, do not lock the product pricing or payment configuration. If you lock product pricing, you cannot adjust it when you create an order.

Create a subscription order data object

To build a data object for a subscription order:

You must set a currency.
Set a customer_id, which is the system identifier of a customer. Get the system ID by listing the customers in the API or UI.
Set an invoice_id to uniquely identify your order.
Set a start_date for when BillPro collects the first scheduled payment. If you use a past date, the first scheduled payment and the initial payment are due when you create the order.
For a custom checkout:
1. Set create_checkout to true.
2. Set the redirect_uri and failed_redirect_uri. You can get the status of the initial payment from the payment gateway redirect action.
Enter the product_id, which is the system identifier of a subscription product. You can get the product ID by listing products with the API or displaying them in the UI.
1. (Optional) To change the product price, set an amount if product pricing is not locked.
2. (Optional) To apply a discount to all payments, set the discount in this product section. To apply a percentage discount, calculate it and apply it as an amount.

Here is an example subscription order data object.

{
  "order": {
    "currency": "EUR",
    "customer_id": 225,
    "recurring_collection_interval": "MONTH",
    "start_date": "01/06/2026 09:24",
    "start_date_unix": "",
    "redirect_url": "",
    "failed_redirect_url": "",
    "note": "Film club subscription",
    "create_checkout": true,
    "order_product": {
      "product_id": 4,
      "qty": 1,
      "amount": "20.00",
      "discount_amount": "0",
      "fee_amount": 0
    }
  }
}

Send the request to create a subscription order

Send your request with your create subscription order data object to the create_subscription_order endpoint. Replace {api_token} with your API Token

If your API user has access to more than one merchant profile, send the profile_id as a query parameter. See Get started with the BillPro API.

curl --request POST \
     --url https://staging.bill.pro/api/v1/orders/create_subscription_order \
     --header 'Authorization: Bearer {api_token}' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "order": {
    "currency": "EUR",
    "customer_id": 225,
    "recurring_collection_interval": "MONTH",
    "start_date": "01/06/2026 09:24",
    "start_date_unix": "",
    "redirect_url": "",
    "failed_redirect_url": "",
    "note": "Film club subscription",
    "create_checkout": true,
    "order_product": {
      "product_id": 4,
      "qty": 1,
      "amount": "20.00",
      "discount_amount": "0",
      "fee_amount": 0
    }
  }
}
'

The response is a JSON object. To format it, use a utility like jq. For example, after you run the cURL command, append | jq ..

Here is an example formatted JSON response.

{
  "payload": {
    "order": {
      "id": 3723,
      "profile_id": 1,
      "invoice_id": "F6C834EF7C",
      "customer_id": "81DB6C85B7",
      "initial_amount": "20.0",
      "description": null,
      "note": null,
      "total_discount_amount": "0.0",
      "total_fee_amount": "0.0",
      "total_tax_amount": "3.33"
    },
    "customer": {
      "id": 225,
      "first_name": "Mari",
      "last_name": "Smith",
      "email": "marismith@example.com",
      "date_of_birth": "2000-03-05",
      "phone": "34666777666",
      "billing_address": {
        "street": "Via Augusta 29",
        "city": "Barcelona",
        "postal_code": "08012",
        "state": "Barcelona",
        "country": "ES"
      }
    },
    "product": [
      {
        "id": 4085,
        "order_id": 3723,
        "product_id": 4,
        "name": "VideoFlix",
        "description": null,
        "qty": 1,
        "amount": "20.0",
        "created_at": "2026-05-02T10:14:39.209Z",
        "updated_at": "2026-05-02T10:14:39.209Z",
        "product_discount_id": null,
        "product_fee_id": null,
        "product_tax_id": 2,
        "discount_amount": "0.0",
        "fee_amount": "0.0",
        "tax_amount": "3.33",
        "subtotal_amount": "20.0",
        "product_config": {
          "tax": {
            "id": 2,
            "name": "VAT UK",
            "type": "percentage",
            "percentage": 20.0
          },
          "price": 20.0,
          "currency": "EUR",
          "product_type": "subscription",
          "subscription": {
            "scheduled_interval": 1,
            "initial_payment_amount": 20.0,
            "scheduled_duration_unit": "MONTH"
          },
          "payment_configuration": {
            "payment_note": "",
            "product_note": "Cancel anytime.",
            "product_initial": "",
            "product_subtotal": "",
            "product_recurring": "",
            "product_tax_amount": "",
            "scheduled_interval": "1",
            "collection_interval": "MONTH",
            "product_total_to_pay": "",
            "product_taxable_amount": "",
            "scheduled_duration_unit": "MONTH",
            "scheduled_duration_number": "",
            "fee_for_initial_payment_only": "1",
            "discount_for_initial_payment_only": "1"
          }
        }
      }
    ],
    "checkout": {
      "result": {
        "code": "000.200.100",
        "description": "successfully created checkout"
      },
      "buildNumber": "cccc12347609801667616bd3e6e26cb2617852e@2026-05-01 00:42:32 +0000",
      "timestamp": "2026-05-02 10:14:39+0000",
      "ndc": "F1593546ABCD846671FD081C458A1B.uat01-vm-tx04",
      "id": "F1593546ABCDD427846671FD081C458A1B.uat01-vm-tx04",
      "integrity": "sha123456578285925852HXLATUT+CDNoqGVhffRdEgwymsiQp7yyKTMuhdNyTl2ju",
      "form_action": "https://staging.bill.pro/checkout/3723/1234X1234AsRns7SGhe8HCgij"
    },
    "payment_link": "https://staging.bill.pro/checkout/3723/12341234AsRns7SGhe8HCgij",
    "redirect_url": null,
    "start_date": "2026-06-01T09:24:00.000Z",
    "repeated_amount": "20.0",
    "scheduled_duration": null,
    "scheduled_unit": "MONTH",
    "scheduled_interval": 1
  },
  "status": 201
}

Collect the initial payment

The BillPro API creates the order in a Pending state. This means the customer has not paid the initial amount. After the initial payment, BillPro sets the subscription status to Active and creates one billing event for the next billing cycle.

Custom checkout integration

When you set create_checkout to true, the request returns a checkout ID. Use this ID to display the checkout on your website and collect the initial payment.

Payment link integration

If you integrate with payment links and your BillPro user has the appropriate permissions, the request returns a payment link. Display the payment link or send it to the customer. Also, sales team members can log in to BillPro and collect phone payments.

Initial payment reminder and email notifications

You can configure BillPro to send email notifications to your customers about their subscriptions. See Activate email notifications.

When you create orders with the API, the orders are in a Pending state. After the configured period, BillPro sends the customer a reminder email about their pending order.

BillPro sends email notifications to comply with card scheme rules. It sends emails when a subscription will renew soon and when you pause or resume a subscription. BillPro email notifications contain payment links that open the order portal. See Order portal overview.

BillPro also sends email notifications before a card expires, after a card expires, and when a payment is soft declined (for temporary issues such as lack of funds) or hard declined (for permanent issues such as a stolen card).

Order portal for subscriptions

In the order portal, customers can view their order details and billing history. They can also manage cards, cancel subscriptions, and download invoices, receipts, and credit notes. See Order portal overview.