Reference
BillPro Website
Start typing to search…

Get started with the BillPro API

First steps 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 BillPro's 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.

  1. Familiarise yourself with the BillPro platform, especially how an order's status changes during the order lifecycle and how to manage cards, payments, and billing events.
  2. Create your products using the UI because you cannot create products with the API, and you will need a product to place an order.

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

How to get API token

  1. Log in to BillPro UI as an admin_user.
  2. Select your merchant profile.
  3. Go to the user account icon in the top right corner, and from the user account menu, select Users.
  4. 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 the user can access multiple profiles, you must specify the profile_id as a query parameter in every request.
  5. From the User Details screen, obtain the Api Token, which is a long string in the format abcd12341234123412341234abcd1234123412341234abcd12342342134
  6. 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.billing.gg/api/v1/.
  7. 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, in the Authorization header, add Bearer, and then add your API credential. In the example requests, replace {api_token} with your API token, as shown in the example in Your first API call.

     --header 'Authorization: Bearer {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.

  1. Copy the request to your terminal or import it to an API browser such as Postman.
  2. Replace {api_token} with your API token.
  3. Send the request.
curl --request GET \
     --url 'https://test.billing.gg/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.billing.gg/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!.

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 request to list the products of the merchant with a profile ID of 5.

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

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.billing.gg/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 in this example, the phone number is invalid for the country code). For full details of the data objects, please see the API reference documentation.

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

You can use the interactive requests in the API reference documentation to test requests to the BillPro API. Just paste your API token in the Authorization field, enter or select the required values, and click Try it!.

Each merchant has its own customers, products, and orders, and the identifiers for these entities are unique across the whole platform, so you will need to get values for your merchant.

First, you should use GET requests to list entities in your merchant so that you can then try specific GET requests using a valid entityid.

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.

If you are planning to integrate with payment links or custom checkouts (for CardCorp merchants) or the payment gateway webhook, please also read the separate documentation in the integration section.