POS Customers

Aggregate and indexed customer information from your POS system. Customer records include emails, phone numbers, and addresses.

Overview

The POS Customer API provides access to customer data stored in your POS system. Customer records are structured with the main customer entity containing related email addresses, phone numbers, and physical addresses.

Customer Dependencies

The customer data structure includes the following relationships:

Customer contains multiple:
- CustomerEmail (0 or more)
- CustomerPhone (0 or more)
- CustomerAddress (0 or more)

API Endpoints

Retrieve Customers

Returns customer records for a specific location.

Method: GET

Endpoint: /pos/v2/{locationId}/customers

Authentication: Bearer token required

Retrieve all customers associated with a location. The endpoint supports pagination and filtering to help you manage large customer databases.

Path Parameters

Name	Type	Description
`locationId` *	integer	The unique identifier for the location

Query Parameters

Name	Type	Description
`page`	integer	Page number for pagination (default: 1)
`pageSize`	integer	Number of results per page (default: 50, max: 100)
`search`	string	Search customers by name, email, or phone
`updatedAfter`	datetime	Filter customers updated after this timestamp

Request

GET

/pos/v2/{locationId}/customers

curl -X GET https://conecto-api.shift4payments.com/pos/v2/12345/customers \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

{
  "results": [
    {
      "posRef": "CUST-12345",
      "firstName": "John",
      "lastName": "Doe",
      "companyName": null,
      "locationId": 12345,
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z",
      "customerEmails": [
        {
          "email": "john.doe@example.com",
          "isPrimary": true
        }
      ],
      "customerPhones": [
        {
          "phone": "+1234567890",
          "isPrimary": true,
          "type": "MOBILE"
        }
      ],
      "customerAddresses": [
        {
          "street": "123 Main St",
          "city": "New York",
          "state": "NY",
          "zipCode": "10001",
          "country": "US",
          "isPrimary": true,
          "type": "HOME"
        }
      ]
    }
  ],
  "meta": {
    "page": 1,
    "pageSize": 50,
    "totalCount": 150
  }
}

Models

Customer

The main customer record containing personal information and references to related data.

Name
posRef
Type
string
Description
Unique POS system reference ID for the customer
Name
firstName
Type
string
Description
Customer's first name
Name
lastName
Type
string
Description
Customer's last name
Name
companyName
Type
string
Description
Company name, if the customer represents a business
Name
locationId
Type
integer
Description
Location ID where the customer record exists
Name
createdAt
Type
datetime
Description
When the customer record was created
Name
updatedAt
Type
datetime
Description
When the customer record was last updated
Name
customerEmails
Type
array
Description
Array of CustomerEmail objects
Name
customerPhones
Type
array
Description
Array of CustomerPhone objects
Name
customerAddresses
Type
array
Description
Array of CustomerAddress objects

CustomerEmail

Email addresses associated with a customer.

Name
email
Type
string
Description
Email address
Name
isPrimary
Type
boolean
Description
Whether this is the primary email address for the customer
Name
isVerified
Type
boolean
Description
Whether the email address has been verified
Name
createdAt
Type
datetime
Description
When the email was added

CustomerPhone

Phone numbers associated with a customer.

Name
phone
Type
string
Description
Phone number in E.164 format (e.g., +1234567890)
Name
type
Type
string
Description
Phone type: MOBILE, HOME, WORK, or OTHER
Name
isPrimary
Type
boolean
Description
Whether this is the primary phone number for the customer
Name
isVerified
Type
boolean
Description
Whether the phone number has been verified
Name
extension
Type
string
Description
Phone extension, if applicable
Name
createdAt
Type
datetime
Description
When the phone number was added

CustomerAddress

Physical addresses associated with a customer.

Name
street
Type
string
Description
Street address (line 1)
Name
street2
Type
string
Description
Additional street address information (line 2)
Name
city
Type
string
Description
City name
Name
state
Type
string
Description
State or province code (e.g., "NY", "CA")
Name
zipCode
Type
string
Description
Postal/ZIP code
Name
country
Type
string
Description
ISO 3166-1 alpha-2 country code (e.g., "US", "CA")
Name
type
Type
string
Description
Address type: HOME, WORK, BILLING, or OTHER
Name
isPrimary
Type
boolean
Description
Whether this is the primary address for the customer
Name
latitude
Type
number
Description
Geographic latitude coordinate
Name
longitude
Type
number
Description
Geographic longitude coordinate
Name
createdAt
Type
datetime
Description
When the address was added

Best Practices

Name
Data Privacy
Description
Handle customer data in compliance with privacy regulations (GDPR, CCPA, etc.). Store customer information securely and only request the data you need.
Name
Pagination
Description
Use pagination when retrieving large customer lists to optimize performance and reduce API load.
Name
Search Optimization
Description
Use the search parameter to filter customers instead of retrieving all records and filtering client-side.
Name
Incremental Updates
Description
Use the updatedAfter parameter to fetch only customers that have been updated since your last sync, reducing data transfer and processing time.
Name
Error Handling
Description
Implement proper error handling for cases where customer data may be incomplete or malformed.