Tutorial - Create a customer with the BillPro API

This tutorial describes the process to create a customer with the BillPro API. We assume you have already worked through Get started with the BillPro API.

1. In the BillPro UI, create a user for the integration and get the Api Token.

2. Get the minimal data object for the customer from the documentation. This is the minimum customer data that you can send to create a payment. We recommend that you always send as much data as possible to get the highest possible transaction approval ratio.

   Minimal customer data object

   {
     "customer": {
       "first_name": "Jane",
       "last_name": "Smith",
       "email": "[email protected]"
     }
   }

3. This is an example of a full create customer object. Note that the create customer object is different to the get customer object.

   Create customer full example

    {
     "customer": {
       "first_name": "Jane",
       "last_name": "Smith",
       "date_of_birth": "20/05/1972",
       "email": "[email protected]",
       "phone": "+447700181908",
       "organisation": {
         "name": "TEST2",
         "registration_number": "01234567",
         "web_url": "https://test.example.com",
         "vat": "GB123456789",
         "description": "Testing company"
       },
       "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"
         }
       }
     }
   }

4. Modify the example data object with your data.

5. You must enter a first_name.

6. You must enter a last_name.

7. You must enter an email.

8. Optional: for the phone, enter the + sign, the country code and the phone number with no spaces. You can send SMS payment links to this number.

9. Optional: To display the customer's VAT or tax number on their order summaries, invoices, receipts, and credit notes, enter an organisation and set vat to the VAT or tax number.

10. Optional: enter a billing_address and/or shipping_address for the customer. This is recommended for ecommerce payments.

11. Here is an example of a minimal request to create a customer.

    Minimal request to create a single payment order

    curl --request POST \
         --url https://staging.bill.pro/api/v1/customers \
         --header 'Authorization: Bearer {api_token}' \
         --header 'accept: application/json' \
         --header 'content-type: application/json' \
         --data '
    {
      "customer": {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "[email protected]"
      }
    }
    '

12. Replace {api_token} with your API Token

13. Send your request to the endpoint URL for customers at https://staging.bill.pro/api/v1/customers

14. Check the response code, which should be 201 for a successful request. Here is an example of the response data from a successful request. If there is an error in the body object, the response code will be 422.

{
  "id": 742,
  "first_name": "Jane",
  "last_name": "Smith",
  "customer_id": "62A763AC53",
  "date_of_birth": null,
  "email": "[email protected]",
  "phone": null,
  "status": "active",
  "created_at": "2026-05-04T10:17:23.921Z",
  "updated_at": "2026-05-04T10:17:23.921Z",
  "addresses": []
}