First steps with the BillPro API
Before you begin using the BillPro API, we recommend these steps.
- Familiarise yourself with the BillPro platform, especially the order status flows and the management of 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 create 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. - Go to the user account icon in the top right corner and from the user account menu, select Users.
- Create another integration user with a Role of
admin_userand with Api Access selected. - From the User Details screen, obtain the Api token and the API base URL, as part of the Api Order Creation URL.
- If you need to get the API token 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!.
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, to format these objects to make them more readable, you can use a JSON formatter.
For example, here 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 in 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 some additional attributes that you can use in future requests.
When you create a customer, 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, 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 entity id.
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 #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.