First steps with the BillPro API
Before you begin using the BillPro API, we recommend these steps.
- 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.
- Create a product using the UI because you cannot create a product with the API, and you will need a product to place an order.
Then, to start using the BillPro API, follow this guide.
Create an integration user and get the API Token
- Log in to BillPro UI as an
admin_user. Select the merchant profile that you want to work with. - Go to the user account icon in the top right corner, and from the user account menu, select Users.
- Create an integration user with a Role of
admin_userand with Api Access selected.- We recommend that each integration user have access to one merchant profile only, but you can select more profiles for a user. If the user can access multiple profiles, you must specify the
profile_idas a query parameter in every request.
- We recommend that each integration user have access to one merchant profile only, but you can select more profiles for a user. If the user can access multiple profiles, you must specify the
- From the User Details screen, obtain the Api token and the API base URL, as part of the Api Order Creation URL.
- Also, if you have multiple merchant profiles, obtain the profile ID number for each of the Merchants.
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.
Authorise your requests to the API
To authorise your HTTPS requests to the API, use the Authorization header with Bearer and replace {api_token} with your API token.
For example, to list the first page of products, you could use this cURL 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.
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 order request body, as well as the id of the customer who is making the order.
You may notice that some endpoint URLs have a text extension in the format of #text. This is to distinguish the endpoints in the API documentation. Computer systems ignore this extension, and you can too!
If you are planning to integrate with payment links and custom checkouts or the payment gateway webhook, please also read the separate documentation in the integration section.