Customers
Learn about the customer resource.
Overview
The creation of a customer is essential to the Acquired.com API; everything is linked back to the customer_id. We recommend creating a customer profile containing personal information before submitting a payment request. You can then retrieve details about a returning customer, as all payment information will be linked back to the customer_id. This process allows us to manage your customer profile for you.
Submitting customer or billing details with a payment request does not guarantee that the customer profile will be created, you must actually create a customer. Customers can be created and managed from within the API, read on to find out how.
Find out how to search for and manage all your customers in the Acquired.com Hub, in our guide here.
In the API you can:
- Create a customer
- Retrieve a customer
- Update an existing customer
- List all customers (you can also utilise pagination parameters to query specific customer records)
Note
Before you create a new customer, make sure that the customer does not already exist, as this can cause problems with further transactions etc.
Card payments process
New customer
The first step in processing a payment for a new customer is to create the customer record. Submit a request into the /customers endpoint and you will be returned a customer_id.
Example:
{
"reference": "customer_number_00001",
"first_name": "Edward",
"last_name": "Johnson",
"dob": "1988-10-03",
"ip": "127.0.0.1",
"custom_data": "L3BheW1lbnQtbGlua3MgcGF5IGN1c3RvbV9kYXRh",
"billing": {
"address": {
"line_1": "152 Aldgate Drive",
"line_2": "",
"city": "London",
"state": "",
"postcode": "E1 7RT",
"country_code": "GB"
},
"email": "[email protected]",
"phone": {
"country_code": "44",
"number": "2039826580"
}
},
"shipping": {
"address_match": true,
}
}
}
Response:
{
"customer_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
You can then include the customer_id in the payment request along with the card details. For more information on how to use the save cards feature, please refer to our card payments guide.
Existing customer
When an existing customer returns to make a payment request, either the card_id or the full card parameters (depending on whether the card has already been created) can be submitted. For more information on our card payments flows, view our card payments guide.
Guest checkout
In the event that the request does not include any customer details and the create_card parameter is set to false, the payment will be successfully processed; however, it will not be linked to a specific customer. This is essentially the /payments version of 'guest checkout'.
Note
Please refer to both our card payments guide and also our payments API reference for further detail on these processes, including code examples.
Hosted Checkout process
Much like with the payments API, customers and their customer_id are very important to the Hosted Checkout and will determine the customer's experience of using checkout as well as the merchant's ability to process recurring payments.
Creating new customers
The first step in processing a payment for a new customer is to create the customer record. Submit a request into the /customers endpoint and you will be returned a customer_id. You can then include the customer_id in the /payment-links request along with the payment details.
If the initial payment is intended for future recurring payments and the is_recurring flag is set to true, a customer_id must be provided.
Existing customers
For existing customers, providing a customer_id in the initial /payment-links request will take the saved billing details for that customer to submit payment with. If the customer completes payment with a new card, the details will be saved against the customer_id. See the Hosted Checkout saving card details guide for more details.
The below example shows all potential customer object fields, you do not have to pass all of them in your request.
Note
When passing the
customer_idit is not required that the full customer details are also passed in the request.
Example request for using an existing customer:
{
"transaction": {
"order_id": "{{$guid}}",
"amount": 15.02,
"currency": "gbp",
"capture": true
},
"customer": {
"customer_id": "cd9a5209-5eac-4744-b674-1b8af429f0d5"
},
"tds": {
"is_active": true,
"challenge_preference": "no_preference",
"contact_url": "https://yourdomain.com/contact"
},
"is_recurring": false,
"redirect_url": "https://qaacs.acquired.com/merchant_redirect/test_success",
"webhook_url": "https://yourdomain.com/webhook"
}
Customer requests
Update customer details
To update any of the customer's personal details, such as billing or shipping data, you must submit a request into PUT /customers/{customer_id}.
In the below request we are updating the billing.address.line_1 parameter:
{
"billing": {
"address": {
"line_1": "156 Aldgate Drive"
}
}
}
Retrieve a customer
To retrieve a specific customer, simply append the required customer_id to GET/customers/{customer_id}.
You can utilise query parameters to filter what is returned in your response. See the below example:
GET /customers/{customer_id}?filter=first_name,last_name,billing.address.line_1
Response:
{
"first_name": "Edward",
"last_name": "Johnson",
"billing": {
"address": {
"line_1": "152 Aldgate Drive"
}
}
}
List all customers
Simply submit a GET request into the /customers endpoint to retrieve a list of all customers. Use query parameters to filter and limit what is returned within your response. See the below example:
GET /customers?filter=customer_id,first_name,ip&limit=3
Response:
{
"meta": {
"count": 3,
"offset": 0,
"limit": 3,
"total": 22,
"links": [
{
"rel": "self",
"href": "/v1/customers?filter=customer_id%2Cfirst_name%2Cip&limit=3&offset=0"
},
{
"rel": "first",
"href": "/v1/customers?filter=customer_id%2Cfirst_name%2Cip&limit=3&offset=0",
"title": "first page"
},
{
"rel": "last",
"href": "/v1/customers?filter=customer_id%2Cfirst_name%2Cip&limit=3&offset=21",
"title": "last page"
},
{
"rel": "prev",
"href": "",
"title": "prev page"
},
{
"rel": "next",
"href": "/v1/customers?filter=customer_id%2Cfirst_name%2Cip&limit=3&offset=3",
"title": "next page"
}
]
},
"data": [
{
"customer_id": "b56af699-1abd-783c-4453-d3e7df888886",
"first_name": "Edward",
"ip": "127.0.0.1"
},
{
"customer_id": "7397a977-7984-53c5-2e89-e04f7a325270",
"first_name": "Edward",
"ip": "127.0.0.1"
},
{
"customer_id": "ad2cc336-349f-b3a6-6735-581e32ae06b1",
"first_name": "Edward",
"ip": "127.0.0.1"
}
]
}
Updated 3 months ago