Get started with the BillPro API

Welcome to the BillPro API, where you can automate your billing operations for card payments.

With the BillPro API, you can create customers and you can create orders for them with the products and services you sell. You can then render a custom checkout or use the BillPro payment links to accept a payment from your customers. You can also manage orders and scheduled payments.

Diagram of typical API workflows.

flowchart TB

  CreateCustomer["Create Customer"]
  GetCustomer["Get Customer"]
	CustomerID["Customer ID"]
  GetProduct["Get Product"]
	ProductID["Product ID"]
  CreateOrder["Create Order"]
  GetOrder["Get Order"]
  OrderID["Order ID"]
  GetScheduledPayments["Get Scheduled
  Payments"]
  ManageOrder["Manage Order"]
  ScheduledPaymentID["Scheduled Payment ID"]
  ManageScheduledPayment["Manage Scheduled
  Payment"]

  CreateCustomer --> Customer
  GetCustomer --> CustomerID
  GetProduct --> ProductID
  CustomerID --> CreateOrder
  ProductID --> CreateOrder
  GetOrder --> OrderID --> GetScheduledPayments
  OrderID --> ManageOrder
  OrderID --> ManageScheduledPayment
  ScheduledPaymentID --> ManageScheduledPayment

📘
BillPro test system
This API documentation uses the BillPro test environment. If you are using Stripe and you would like to build an integration with the BillPro API, please contact BillPro to obtain access to the test environment.

Before you begin using the BillPro API, we recommend these steps.

Familiarise yourself with the BillPro platform. Learn how to create products, customers, and orders, then how to manage cards, payments, and billing events, and how the order status changes during the order lifecycle (see Order status and Order flow) .
Create your products using the UI because you cannot do this with the API, and you will need a product to create an order. See Create your product catalogue

Then, to start using the BillPro API, follow this guide.

How to get API token

Sign up for BillPro at https://app.bill.pro and select and configure a payment processor.
Log in to BillPro UI with your user, which should be an admin_user account.
If you have more than one merchant profile, select one.
Go to the user account icon in the top right corner, and from the menu, select Users.
Create a separate integration user with a Role of admin_user and with Api Access selected.
1. We recommend that you create a separate integration user for each merchant profile, but it is possible to select more profiles for a user. If your integration user can access multiple profiles, you must specify the profile_id in every API request.
From the User Details screen, obtain the Api Token, which is a long string in alphanumeric format, for example abcd12341234123412341234abcd1234123412341234abcd12342342134
Get the API base URL, which is the first part of the Api Order Creation URL. For example, for the test environment this is https://test.bill.pro/api/v1/.
Also, if you have multiple merchant profiles, obtain the profile ID number for each of the Merchants.

Display the user details with the merchants list — Display the user details, including the merchants list

If you need to get the API token or profile ID again from the Users list, click the eye icon to display the User Details.

How to use the API token

The BillPro API is a REST API, so you should send your requests using the HTTPS protocol. To authorise your requests, send the Authorization header with Bearer, and then add your API credential.

     --header 'Authorization: Bearer {api_token}' \

In the example requests, replace {api_token} with your API token.

Your first API call

In this example, we will make a GET request to the products endpoint to list the first page of products.

Copy the request to your terminal or import it to an API browser such as Postman.
Replace {api_token} with your API token.
Send the request.

curl --request GET \
     --url 'https://test.bill.pro/api/v1/products?page=1' \
     --header 'Authorization: Bearer {api_token}' \
     --header 'accept: application/json'

So, for example, if your API token was abcd12341234123412341234abcd1234123412341234abcd12342342134, you would send the following request.

curl --request GET \
     --url 'https://test.bill.pro/api/v1/products?page=1' \
     --header 'Authorization: Bearer abcd12341234123412341234abcd1234123412341234abcd12342342134' \
     --header 'accept: application/json'

In the API reference documentation, you can paste your API key in the Authorization field, and click Try it!.

Get the API response

The data objects returned by the API are in JSON format. The response body of a successful GET request could look something like the following.

[{"id":1,"product_id":"E2824181D8","currency":"GBP","price":"44.99","product_type":"subscription","product_status":"active","lock_price":true,"lock_payment_config":false,"product_group":"Memberships","scheduled_interval":"1","scheduled_unit":"MONTH","fee_for_initial_payment_only":true,"discount_for_initial_payment_only":true,"deposit_amount":"42.74","created_at":"2024-02-12T15:12:37.314Z","discount":{"name":"Discount 5%","percentage":"5.00","description":"Five Percent New Customer Discount","created_at":"2022-05-05T15:23:16.666Z","updated_at":"2022-06-14T10:45:13.933Z"},"tax":{"name":"VAT Spain","percentage":"21.00","description":"Spain Value Added Tax 21%","created_at":"2022-05-05T15:18:09.958Z","updated_at":"2022-05-08T16:06:29.185Z"}}]

When testing in the terminal, you can use a JSON formatter to format JSON objects and make them more readable.

In this example, we have used JQ.

curl --request GET \
     --url 'https://test.bill.pro/api/v1/products?page=1' \
     --header 'Authorization: Bearer abcd12341234123412341234abcd1234123412341234abcd12342342134' \
     --header 'accept: application/json' | jq .

The formatted data object for the same product shown above would be as follows.

[
  {
    "id": 1,
    "product_id": "E2824181D8",
    "currency": "GBP",
    "price": "44.99",
    "product_type": "subscription",
    "product_status": "active",
    "lock_price": true,
    "lock_payment_config": false,
    "product_group": "Memberships",
    "scheduled_interval": "1",
    "scheduled_unit": "MONTH",
    "fee_for_initial_payment_only": true,
    "discount_for_initial_payment_only": true,
    "deposit_amount": "42.74",
    "created_at": "2024-02-12T15:12:37.314Z",
    "discount": {
      "name": "Discount 5%",
      "percentage": "5.00",
      "description": "Five Percent New Customer Discount",
      "created_at": "2022-05-05T15:23:16.666Z",
      "updated_at": "2022-06-14T10:45:13.933Z"
    },
    "tax": {
      "name": "VAT Spain",
      "percentage": "21.00",
      "description": "Spain Value Added Tax 21%",
      "created_at": "2022-05-05T15:18:09.958Z",
      "updated_at": "2022-05-08T16:06:29.185Z"
    }
  }
]

For information about error responses, see below.

Create data objects

When you make a request to create or update an entity, using aPUT or POST command, you can send data as FormData or JSON object format.

For example, to create a customer, you could send an object such as this one, but note that this example has an invalid phone number for the country code!

{
    "customer": {
        "first_name":       "Dana",
        "last_name":        "Borys",
        "date_of_birth":    "12/05/1995",
        "email":            "[email protected]",
        "phone":            "+44770000000000",
        "organisation": {
            "name":                 "TEST1",
            "registration_number":  "081234567",
            "web_url":              "https://staging.billing.gg",
            "vat":                  "GB0123456789",
            "description":          "Mutual society"
        },
        "addresses": {
            "billing_address": {
                "street":       "28 Milsom St",
                "city":         "Bath",
                "state":        "Avon",
                "country":      "GB",
                "postal_code":  "BA1 1DG"
            },
            "shipping_address": {
                "street":       "28 Milsom St",
                "city":         "Bath",
                "state":        "Avon",
                "country":      "GB",
                "postal_code":  "BA1 1DG"
            }
        }
    }
}

When a POST or PUT request is successful, BillPro returns the new data object in the response body. The response can include additional attributes that you can use in future requests.

For example, when you create a customer in BillPro, the response includes the id, which is the unique system identifier, and the merchant customer_id. It also includes the time stamps of when the customer account, the customer's addresses, and the customer's organisation were created and updated.

Get API response codes

The BillPro API returns standard HTTP status codes. For example, for successful requests, the code is 200 OK and for bad requests, the code is 400 Bad Request.

As an example of an error code with a message, if you send a POST request to create a customer and the customer data object has an invalid attribute, such as the phone number is not valid for the country code (as in the example above), then the API returns a status code of 422 - Unprocessable Content and the response body contains the error message, such as {"phone":["is invalid"]}.

Try requests with the API documentation

The API documentation references the BillPro test environment by default. You can request access to the test environment from BillPro Merchant Support.

To use the interactive environment, just paste your API token in the Authorization field, and enter or select the required values for parameters and data, then click Try it!.

All entities, such as products and orders, have unique identifiers across the whole platform, so you will need to get values for your merchant. So we suggest that you first create some entities in the UI and then use GET requests to list them with the API.

To test creating an order, create a product in the UI, and use the id of the product in the product_id in the order request body, as well as the id of the customer in the customer_id. For full details, see How to create an order with the BillPro API and the Orders API documentation.

If you are planning to integrate with payment links or custom checkouts (for CardCorp merchants) or the payment gateway webhook, please also follow Integrate with payment links and Integrate with custom checkout and payment iframe.

API request with multiple merchant profiles

This example applies to API users with access to multiple merchant profiles only.

We recommend creating a separate API user for each merchant profile. But if your API user can access more than one merchant, you must send the profile_id parameter with all API requests.

Here is an example of the GET request to list the products of the merchant with a profile ID of 5.

curl --request GET \
     --url 'https://test.bill.pro/api/v1/products?page=1&profile_id=5' \
     --header 'Authorization: Bearer abcd12341234123412341234abcd1234123412341234abcd12342342134' \
     --header 'accept: application/json'