Customers

Properties

Properties

Properties

Properties

Properties

Retrieve a list of customers associated with an organisation. Also allows for searching by email or phone number.

Query Parameters

Create a new customer.

Attaching addresses to the customer at the point of creation is not currently supported, and must be done with a subsequent request to the relevant endpoint.

Creating Customers with Existing Details

When creating a customer, it is possible that the primary email address or phone number that is supplied is in use by another customer. This can commonly occur in situations such as:

• A couple using a shared email address.
• A person ordering for multiple people from their account.
• The phone number provided being a landline or a switchboard, eg. a work phone number.

In situations such as these, requiring email addresses/phone numbers to be unique would require us to return an error if someone attempted to create a new customer with conflicting details. As orders will generally come from external systems where we may be unable to request that the customer provide an alternative set of details, we instead allow email addresses and phone numbers to be assigned to multiple customers, and provide no guarantees of uniqueness.

To find customers associated with an email or phone number, the Get Customers endpoint provides filters for email addresses and phone numbers, which can be used to retrieve a list of customers associated with a given identifier, and to check if a customer exists beforehand to avoid creating duplicates.

Endpoint for bulk updating customer details.

The nature of this endpoint means that the following behaviour is present here that is not present on other endpoints:

• Metadata and marketplace fields are added to those that are already present. Such fields cannot be deleted using this endpoint, and instead must use the update customer endpoint. At a later date it will be possible to delete metadata fields by passing a null value for the key that should be deleted.

• All entries must contain a customer ID. If any customer ID is missing or invalid, the request will fail.

• The endpoint will not return validation errors for individual entries in the request if present, but will instead fail with a generic validation error.

• In the event that the request contains conflicting marketplace IDs (i.e. the client attempts to assign an ID to a customer when it has already been assigned to a different customer), the request will fail, and the error message will contain a list of the existing customer IDs that are already assigned to the specified ID.

• Addresses can be created/updated for a customer using this endpoint. Addresses that are to be updated must pass the ID of the address to be updated, otherwise a new address will be created. It is the responsibility of the client to ensure updates to addresses are reflected in 3rd party platforms, as in many cases the platforms do not provide a mechanism to update addresses once created, and we do not create a new address & ID on 3rd party providers, as this has the potential to cause confusion if done automatically.

Detailed descriptions

»»»»»» confidence: A confidence score associated with the cordinates, indicating how accurately they represent the address.

For manually set coordinates, set the confidence score to 1 to indicate that the location has been manually specified/verified.

Endpoint for bulk creating customers.

The nature of this endpoint means that the following behaviour is present here that is not present on other endpoints:

• Addresses and marketplaces can be supplied as part of the request, and will be created at the same time the customer is created
• Conflicting IDs in the case of marketplaces will cause a partial failure, which will be present in the errors parameter.

In the event of the request being partially successful, a 202 Accepted status is returned, and the errors field of the response contains details of the elements that failed to create. In the event that all customers in the request are successfully created, a 201 Created status is returned.

In both cases, the data parameter of the response will contain the customers that were successfully created.

Detailed descriptions

»»»»»» confidence: A confidence score associated with the cordinates, indicating how accurately they represent the address.

For manually set coordinates, set the confidence score to 1 to indicate that the location has been manually specified/verified.

Retrieve an individual customer by the unique ID.

Path Parameters

Update the attributes of a given customer.

N.B. It is currently not possible to update the emails, phone numbers or addresses associated with the customer with this method. Such updates should be carried out using the dedicated endpoints.

Path Parameters

Deletes a customer with the specified ID.

If successful, a 204 status code is returned. If the customer has already been deleted or otherwise could not be located, a 404 error is returned.

Path Parameters

Check if the customer exists in the database. This request is functionally identical to the Get Customer endpoint, except that no response body is returned.

Path Parameters

Retrieves all the email addresses associated with a given customer.

As described in Create Customer, these email addresses are not guaranteed ot be unique to the customer.

All emails are returned in one request, there is currently no pagination implemented.

Path Parameters

Add an email address to the specified customer.

Path Parameters

Delete an email address associated with a given customer.

At any given point a customer must have either a primary phone number or a primary email attached to their profile. Attempting to delete an email address will thus fail if the customer would be left without an email address or password attached to their account.

In the event that the email being deleted is the primary email, and the customer has an alternate email attached to their profile, the alternate email will automatically be assigned as the new primary email.

It is the end user's responsibility to ensure that any required consent from the customer to receive communication at the new primary email is gathered beforehand if necessary.

Path Parameters

Retrieves all the phone numbers associated with a given customer.

As described in Create Customer, these phone numbers are not guaranteed ot be unique to the customer.

All phone numbers are returned in one request, there is currently no pagination implemented.

Path Parameters

Add a phone number to the specified customer.

Path Parameters

Delete an email address associated with a given customer.

At any given point a customer must have either a primary phone number or a primary email attached to their profile. Attempting to delete an email address will thus fail if the customer would be left without an email address or password attached to their account.

In the event that the email being deleted is the primary email, and the customer has an alternate email attached to their profile, the alternate email will automatically be assigned as the new primary email.

It is the end user's responsibility to ensure that any required consent from the customer to receive communication at the new primary email is gathered beforehand if necessary.

Path Parameters

Retrieves all the postal addresses for a given customer.

All addresses are returned in a single request, there is no pagination implemented currently.

Path Parameters

Create a new address for a customer.

Normalisation

To try and both standardise the format of addresses, and reduce the likelihood of duplicates, any address that is added is formatted using Google's i18n dataset, the same dataset that is used for address formatting in Chromium. As a result, the case and layout of the address will be normalised according to the standards of the country that the address exists in.

The strict_normalisation parameter is currently disabled due to in progress changes to the underlying logic which may or may not render it obsolete. The documentation is left here for reference which the changes are pending.

If the strict_normalisation parameter is passed in the request, all fields of the address will be uppercased before storing. The decision to uppercase instead of lowercase was made on the basis of Microsoft CA1308, which points out that in some languages a letter can be converted from lowercase to uppercase, but not vice versa (an example of this is the Turkish 'i' problem, described here).

Address Expansion & Correction

It is also possible to pass the expand_address parameter. This parameter will attempt to expand abbreviations, convert written numbers to actual numbers, and so on, using unclean, but it should be used with care, as some expansions may be inaccurate (eg: 'St' may be expanded to 'Saint' instead of 'Street'). Expansion is currently only applied to the line_1, line_2 & line_3 parameters - the other parameters are only subject to normalisation as described in the previous paragraph.

Metadata

It is possible to attach metadata to each address. This is useful for when additional information relating to the address should be stored with it, such as safeplace locations, gate access codes, delivery contact information, etc.

The metadata object takes key/value pairs, both of which must be strings. Additionally, the keys may only contain alphanumeric characters and underscores, and can be up to 50 characters in length. The values may be up to 500 characters in length, and must be UTF-8 compliant strings.

The following keys are special property keys, with the following caveats:

• contact_phone_number: The value must be an E.164 formatted number. The value is checked to ensure that it is formatted correctly, but further validation to check whether the number is in service is not performed.

• contact_email: The value must be a syntactically valid email address. The usage of special use domain names is not permitted.
  Checks for the deliverability of emails to the provided address are not carried outcurrently, though this may change at a later date without notice.

Path Parameters

Query Parameters

Enumerated Values

Retrieve an address belonging to a customer by ID.

Path Parameters

Update a customer address by it's unique ID.

No fields are explicity required as part of the update - either the full record or a partial record can be submitted.

It is currently not possible to depopulate a field once it has been populated (eg. line_2 contains Smith Street, we want to set it to null) due to possible interdependency issues. This will be resolved imminently alongside the addition of support for PATCH requests, which will be responsible for the partial updates currently supported by the PUT method.

Once support for depopulating fields is added, any attempts to depopulate required fields will result in a 400 error being thrown.

Path Parameters

Delete an address belonging to a customer by it's unique ID.

Path Parameters