Export customers as CSV

GET

/customers/export

const url = 'https://example.com/customers/export?includeArchived=true&owing=true&kind=commercial&marketing=email&surcharge=add&ordering=stopped&shop=confirmed&activity=returning&channel=email&purpose=all&tenantId=019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f';
const options = {
  method: 'GET',
  headers: {cookie: '__Host-bottle.session_token=<__Host-bottle.session_token>'}
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://example.com/customers/export?includeArchived=true&owing=true&kind=commercial&marketing=email&surcharge=add&ordering=stopped&shop=confirmed&activity=returning&channel=email&purpose=all&tenantId=019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f' \
  --cookie __Host-bottle.session_token=<__Host-bottle.session_token>

The customers matching the same search and filters as GET /customers (all of them when none are given), as a CSV file streamed a page at a time.

purpose=all has every detail: name, legal name, email, phone, first delivery address, trade or consumer, payment terms, owed and overdue in pounds and pence, consent on each channel (Agreed, Withdrawn or Not asked), the date they became a customer, their last order and how many orders. purpose=marketing has only customers whose consent on channel is granted and who can be reached that way (an email that has not bounced, a phone number, a postal address), with only that contact, when and how they agreed, and their order dates.

UTF-8 with a byte order mark, so Excel opens it correctly, and CRLF line ends. Any text cell starting with =, +, -, @, a tab or a carriage return has a ' put in front so a spreadsheet does not run it. Erased and merged customers are left out.

Counted against the heavy allowance, and no more than 5 exports a minute per business (429 with Retry-After). The last line is End of file with the number of customers; a file that stops part way ends with a line saying it is not complete instead. Every export is recorded with who made it, the filters (a search only as having been used, never its words), the number of rows and how it ended: finished, failed or cancelled. Refused to Bottle staff in a support session.

Authorizations

sessionCookie
customers:read
apiKey
customers:read

Parameters

Query Parameters

Search trading name

string

<= 100 characters

Search trading name

includeArchived

string

default: false

Allowed values: true false

owing

string

default: false

Allowed values: true false

kind

string

Allowed values: commercial domestic

rateSet

Any of:

string
string

UUID v7

string format: uuid

Example

019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f

marketing

Only customers whose consent on this channel is granted.

string

Allowed values: email sms phone post

Only customers whose consent on this channel is granted.

surcharge

Add: on the chosen list for the business surcharge. exclude: on the excluded list.

string

Allowed values: add exclude

Add: on the chosen list for the business surcharge. exclude: on the excluded list.

ordering

Stopped: orders or deliveries are stopped now, for money owed. rule: set to stop while unpaid, owing or not.

string

Allowed values: stopped rule

Stopped: orders or deliveries are stopped now, for money owed. rule: set to stop while unpaid, owing or not.

shop

Confirmed: at least one shop sign-in for this customer has a confirmed email. unconfirmed: has a shop sign-in, none confirmed. none: no shop sign-in.

string

Allowed values: confirmed unconfirmed none

Confirmed: at least one shop sign-in for this customer has a confirmed email. unconfirmed: has a shop sign-in, none confirmed. none: no shop sign-in.

createdFrom

string format: date

createdTo

string format: date

activity

string

Allowed values: returning inactive

activityFrom

string format: date

activityTo

string format: date

channel

For purpose=marketing: the channel the list is for. Only customers who granted it are included, with the contact details that channel needs.

string

default: email

Allowed values: email sms phone post

For purpose=marketing: the channel the list is for. Only customers who granted it are included, with the contact details that channel needs.

purpose

all: every customer matching the filters, with every detail and their consent on each channel. marketing: only those who granted consent on channel, with only what that channel needs and when they agreed.

string

default: all

Allowed values: all marketing

tenantId

The business, for a plain link that cannot send X-Tenant-Id (a browser download). The header wins when both are given; membership is checked either way.

string format: uuid

Example

019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f

The business, for a plain link that cannot send X-Tenant-Id (a browser download). The header wins when both are given; membership is checked either way.

Responses

200

The CSV file

text/csv

string

401

Not signed in

application/json

object

error

required

string

message

required

string

Example

{
  "error": "not_found",
  "message": "Customer not found"
}

403

Not a member, missing the scope, or a support session

application/json

object

error

required

string

message

required

string

Example

{
  "error": "not_found",
  "message": "Customer not found"
}

422

Validation failed

application/json

object

error

required

string

Allowed values: validation

message

required

string

issues

required

Array<object>

object

path

required

string

message

required

string

Example

{
  "error": "validation",
  "issues": [
    {
      "path": "email",
      "message": "Invalid email"
    }
  ]
}

429

Too many exports or heavy requests this minute

application/json

object

error

required

string

message

required

string

Example

{
  "error": "not_found",
  "message": "Customer not found"
}