Creating clients with the API

What a client is

A client is the person or business you send an order to: your buyer. Every order you create through the API belongs to a client, so your system creates the client first, then creates orders for it. Clients created through the API appear in Clients under your channel, the same as the ones you add by hand.

You need an API token first. See The Manual/API channel for how to get one. The token decides the channel: clients are created in the channel the token belongs to. The token must not be read only.

The request

Method	POST
Address (live)	https://api.aiku.io/dropshipping/clients
Address (staging)	https://api.aiku-sandbox.uk/dropshipping/clients
Headers	Authorization: Bearer followed by your token Content-Type: application/json

The answer is always JSON. You do not need to send an Accept header.

A complete example

curl -X POST https://api.aiku.io/dropshipping/clients \
  -H "Authorization: Bearer 123|AbCdEf..." \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "WEB-10045",
    "contact_name": "Jane Smith",
    "company_name": "Smith Gifts Ltd",
    "email": "jane@example.com",
    "phone": "+44 7700 900123",
    "address": {
      "address_line_1": "12 High Street",
      "address_line_2": "Flat 3",
      "locality": "Sheffield",
      "administrative_area": "South Yorkshire",
      "postal_code": "S1 2AB",
      "country_code": "GB"
    }
  }'

The smallest request we accept is just the country:

{
  "address": { "country_code": "GB" }
}

A client like that cannot receive parcels, so always send the full delivery address when you have it.

The fields

Field	Required	What to send
address	Yes	The delivery address, as an object with the fields below.
address.country_code	Yes	The country as an ISO code: two letters (GB, ES, DE) or three letters (GBR, ESP, DEU). Upper or lower case.
address.address_line_1	For delivery	Street and number.
address.address_line_2	No	Flat, floor, building.
address.locality	For delivery	Town or city.
address.administrative_area	Depends on the country	County, state or province, where the country uses one.
address.postal_code	For delivery	Postcode or ZIP.
address.dependent_locality	No	District or neighbourhood, where the country uses one.
address.sorting_code	No	Only for countries that use a sorting code.
reference	No	Your own code for the client, for example the customer number in your shop. It must be unique in your channel.
contact_name	No	The person's name.
company_name	No	The company name.
email	No	A valid email address.
phone	No	At least 6 characters. Use the international format, for example +44 7700 900123, so the courier can call.

Address fields that are not in this list, such as city, state, county or country, are ignored. Use the names above. There are no first_name or last_name fields: send the full name in contact_name.

Older integrations may send address.country_id, our own number for the country. It still works, but use country_code: if you send both, country_code wins.

The answer when it works

We answer 201 Created with the new client:

{
  "data": {
    "id": 52817,
    "ulid": "01M4639WS5Z7QT08CNW0M0DEJQ",
    "reference": "WEB-10045",
    "active": null,
    "name": "Smith Gifts Ltd",
    "contact_name": "Jane Smith",
    "company_name": "Smith Gifts Ltd",
    "location": ["GB", "United Kingdom", "Sheffield"],
    "email": "jane@example.com",
    "phone": "+44 7700 900123",
    "created_at": "2026-10-05T13:15:59.000000Z",
    "updated_at": "2026-10-05T13:15:59.000000Z",
    "address": {
      "id": 9123456,
      "address_line_1": "12 High Street",
      "address_line_2": "Flat 3",
      "sorting_code": null,
      "postal_code": "S1 2AB",
      "locality": "Sheffield",
      "dependent_locality": null,
      "administrative_area": "South Yorkshire",
      "country_code": "GB",
      "country_id": 48,
      "checksum": "74d55290109e98f64b7d908a3e66b9d8",
      "created_at": "2026-10-05T13:15:59.000000Z",
      "updated_at": "2026-10-05T13:15:59.000000Z",
      "country": { "code": "GB", "iso3": "GBR", "name": "United Kingdom" },
      "formatted_address": "<p translate=\"no\">...12 High Street<br>Flat 3<br>Sheffield<br>S1 2AB<br>United Kingdom</p>",
      "can_edit": null,
      "can_delete": null
    }
  },
  "message": "Client created successfully"
}

name is the company name when you send one, otherwise the contact name. formatted_address is the address as HTML, ready to show.

Keep data.id. You need it to create orders for this client: POST /dropshipping/order/client/{id}/store.

Change a client

Send PATCH to /dropshipping/clients/{id} with only the fields you want to change. When you change the address, send the whole address including country_code.

curl -X PATCH https://api.aiku.io/dropshipping/clients/52817 \
  -H "Authorization: Bearer 123|AbCdEf..." \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+44 7700 900999" }'

We answer 200 with the client, in the same shape as above, and "message": "Client updated successfully".

Find your clients

• GET /dropshipping/clients lists the clients of your channel, page by page.
• GET /dropshipping/clients/{id} shows one client.
• DELETE /dropshipping/clients/{id} deactivates a client. Its past orders are kept.

To avoid creating the same buyer twice, send your own customer number as reference. A second client with the same reference in the same channel is refused.

When something goes wrong

When we refuse a request because of the data, we answer 422 with a message and the field that is wrong under errors:

{
  "message": "Unknown country code \"UK\". Send the ISO code of the country, two letters (GB) or three letters (GBR).",
  "errors": {
    "address.country_code": [
      "Unknown country code \"UK\". Send the ISO code of the country, two letters (GB) or three letters (GBR)."
    ]
  }
}

• "The client's delivery address is required". The body has no address object. The address fields must be inside address, not at the top level of the body.
• "The country is required". The address has no country_code. Add it.
• "Unknown country code". The code is not an ISO country code. The United Kingdom is GB or GBR, not UK.
• "The reference has already been taken". Another client in this channel has that reference. Use a different one, or change the existing client with PATCH.
• "The phone must be at least 6 characters". Send the full phone number, or leave phone out.
• 401 with a message about the Authorization header. The token is missing, incomplete or deleted. Copy the whole token, including the number and | at the start. Staging needs its own token.
• 403 "This API token is read only.". Generate a token without Read only ticked.
• 429. Each token can make up to 120 requests a minute. Slow down and try again after a minute.

Every request your system makes is listed in the API calls tab of your channel's API page, with the answer we gave. Look there first when a request does not do what you expect.