Reference
BillPro Website

Tutorial - Create a subscription with the BillPro API

Learn how to create a subscription order with the BillPro API

Create a subscription order to charge your customer a recurring payment at a regular interval. Before you start, complete Get started 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.

Before you begin

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

Create a subscription order with the API

  1. Create a tax in the BillPro UI, to include in the product price after applying fees and discounts.
    1. See Create product groups and pricing elements.
  2. Optional: Create a discount in the UI for an introductory offer or trial period. When you create your product, apply the discount to the initial payment. You can also create fees.
  3. Create a subscription product in the UI and select your tax, discount, and fee.
    1. See Create a subscription product.
    2. By default, the initial payment is due immediately and covers one subscription cycle.
    3. Select whether the fee and discount apply to the initial payment only. Get the product id to set as the product_id in the order.
  4. Create a subscription order data object. Use the data object below as a template.
    1. Set a currency.
    2. 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.
    3. Set an invoice_id to uniquely identify your order.
    4. 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. 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 (e.g. 30 April, 31 May).
    5. 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.
    6. The order_product data object contains a single subscription product. 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.
  5. Create the subscription order using the create_subscription_order endpoint.
    1. Replace {api_token} with your API token.
    2. If your API user has access to more than one merchant profile, send the profile_id as a query parameter.

If the request is successful, the response code is 201. If there is an error, such as an invalid product or customer ID, the response code is 422.

Create subscription order request

Use this cURL request to create a subscription order.

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 '
{{SUBSCRIPTION-DATA-OBJECT}}
'

Subscription data object

A sample subscription order data object. The order_product data object contains a single subscription product.

{
  "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
    }
  }

For more details, see the API Reference section Create subscription order.

Create subscription order response

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

{
  "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": "[email protected]",
      "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.

If you integrate with the custom checkout and 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. See Integrate with custom checkout and payment iframe.

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

Initial payment reminder and 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. See Activate email notifications. 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 and after a card expires. It also notifies 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.

Pause and resume subscriptions

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.

Reschedule subscriptions and change amounts

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 can create 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.

Updated about 2 months ago

Did this page help you?

Updated about 2 months ago

Did this page help you?