To charge recurring payments to your customers at regular intervals, create subscription orders.

Before you begin

Check that your merchant account and BillPro configuration have the option to create recurring payments for subscriptions.
If you are using a Stripe or CardCorp merchant account, you can Integrate with payment links. If you are using a CardCorp merchant account, 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 lets you charge subscriptions monthly, quarterly, or yearly 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.

In BillPro, you can pause and resume subscriptions. 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.

To comply with card scheme rules, activate subscription renewal notifications in BillPro. 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. Use the update scheduled payment request to set more subscription period options. For example, pharmacy merchants can charge a customer for a prescription every four weeks.

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 as included in the 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, you can apply the discount to the initial payment or 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, you can 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, you 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 create a data object for a subscription order, follow these steps.

Create a data object for a subscription order.
1. Set a customer_id, which is the system identifier of a customer. You can get the system ID by listing the customers in the API or UI.
2. Set an invoice_id to uniquely identify your order.
3. 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.
4. If you use 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.
5. 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 send the request, use the create_subscription_order endpoint. Replace YOUR_API_TOKEN.

curl --request POST \
     --url https://staging.bill.pro/api/v1/orders/create_subscription_order \
     --header 'Authorization: Bearer YOUR_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 the response, use a utility like jq. For example, after you run the cURL command, append | jq ..

Here is an example 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. If you have a sales team, team members can log into 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. This means BillPro sends the customer a reminder email after the configured period.

BillPro sends email notifications to comply with card scheme rules. It sends notifications when a subscription is due for renewal 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 when a card will expire, after a card has expired, 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 their subscription, and download invoices, receipts, and credit notes. See Order portal overview.