Customers

List customersCopy Anchor Link

GET /api/v1/stores/{storeId}/customers

A page of customers, newest first unless sort says otherwise, each with what they have bought. Archived customers are left out unless archived asks for them. Each narrowing takes some away, and a value that cannot be read is ignored. meta.breakdown counts every customer not archived; send breakdown=0 to leave it out.

Needs customers:read.

Parameters

Answers 200

curl "https://api.storeware.ai/api/v1/stores/$STORE_ID/customers" \
  -H "Authorization: Bearer $TOKEN"

Create a customerCopy Anchor Link

POST /api/v1/stores/{storeId}/customers

Adds somebody who has not been through the checkout, as a guest. Marketing consent cannot be set here: a customer added this way starts without it. An email another customer of the shop holds, an archived one included, is a 409. Send an Idempotency-Key header to make a retry safe.

Needs customers:write.

Parameters

Body

Answers 201

curl -X POST "https://api.storeware.ai/api/v1/stores/$STORE_ID/customers" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json

List the tags and countries customers haveCopy Anchor Link

GET /api/v1/stores/{storeId}/customers/facets

The tags the shop’s customers carry and the countries they live in or have had orders sent to, the commonest first, counted over customers not archived. For offering the values tags and country can narrow listCustomers by.

Needs customers:read.

Parameters

Answers 200

curl "https://api.storeware.ai/api/v1/stores/$STORE_ID/customers/facets" \
  -H "Authorization: Bearer $TOKEN"

Get a customerCopy Anchor Link

GET /api/v1/stores/{storeId}/customers/{customerId}

The customer, with their 100 most recent orders in meta.orders.

Needs customers:read.

Parameters

Answers 200

curl "https://api.storeware.ai/api/v1/stores/$STORE_ID/customers/$CUSTOMER_ID" \
  -H "Authorization: Bearer $TOKEN"

Update a customerCopy Anchor Link

PATCH /api/v1/stores/{storeId}/customers/{customerId}

Changes only the fields sent; a null empties one, and an address is replaced whole. Marketing consent cannot be set here. Changing the email to one another customer holds is a 409, and any new email counts as unverified until the customer signs in with it. note is the merchant’s own and is never shown to the customer. Send an Idempotency-Key header to make a retry safe.

Needs customers:write.

Parameters

Body

Answers 200

curl -X PATCH "https://api.storeware.ai/api/v1/stores/$STORE_ID/customers/$CUSTOMER_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json

List a customer’s saved addressesCopy Anchor Link

GET /api/v1/stores/{storeId}/customers/{customerId}/addresses

The addresses a customer has besides their default, oldest first, up to 50. The default is defaultAddress on the customer and is not repeated here.

Needs customers:read.

Parameters

Answers 200

curl "https://api.storeware.ai/api/v1/stores/$STORE_ID/customers/$CUSTOMER_ID/addresses" \
  -H "Authorization: Bearer $TOKEN"

Save an address for a customerCopy Anchor Link

POST /api/v1/stores/{storeId}/customers/{customerId}/addresses

Saves another address, whole. One the customer already has, their default included, is a 409, and so is one past the 50 a customer can keep. Send an Idempotency-Key header to make a retry safe.

Needs customers:write.

Parameters

Body

Answers 201

curl -X POST "https://api.storeware.ai/api/v1/stores/$STORE_ID/customers/$CUSTOMER_ID/addresses" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json

Correct a customer’s saved addressCopy Anchor Link

PATCH /api/v1/stores/{storeId}/customers/{customerId}/addresses/{addressId}

Replaces the address whole. Sending what is already there changes nothing. Lines that match another address the customer has are a 409. Send an Idempotency-Key header to make a retry safe.

Needs customers:write.

Parameters

Body

Answers 200

curl -X PATCH "https://api.storeware.ai/api/v1/stores/$STORE_ID/customers/$CUSTOMER_ID/addresses/$ADDRESS_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json

Remove a customer’s saved addressCopy Anchor Link

DELETE /api/v1/stores/{storeId}/customers/{customerId}/addresses/{addressId}

Removes one saved address. The default is not one and stays. Send an Idempotency-Key header to make a retry safe.

Needs customers:write.

Parameters

Answers 200

curl -X DELETE "https://api.storeware.ai/api/v1/stores/$STORE_ID/customers/$CUSTOMER_ID/addresses/$ADDRESS_ID" \
  -H "Authorization: Bearer $TOKEN"

Make a saved address the defaultCopy Anchor Link

POST /api/v1/stores/{storeId}/customers/{customerId}/addresses/{addressId}/default

Puts this address on the customer as defaultAddress, and saves the old default in its place, so no address is lost. Send an Idempotency-Key header to make a retry safe.

Needs customers:write.

Parameters

Answers 200

curl -X POST "https://api.storeware.ai/api/v1/stores/$STORE_ID/customers/$CUSTOMER_ID/addresses/$ADDRESS_ID/default" \
  -H "Authorization: Bearer $TOKEN"

Archive a customerCopy Anchor Link

POST /api/v1/stores/{storeId}/customers/{customerId}/archive

Puts the customer away without deleting anything: their orders, credit and email stay theirs. They leave the lists and totals, and are signed out of their account on the shop until unarchived. Archiving one already archived changes nothing.

Needs customers:write.

Parameters

Answers 200

curl -X POST "https://api.storeware.ai/api/v1/stores/$STORE_ID/customers/$CUSTOMER_ID/archive" \
  -H "Authorization: Bearer $TOKEN"

Unarchive a customerCopy Anchor Link

POST /api/v1/stores/{storeId}/customers/{customerId}/unarchive

Brings the customer back as they were. One not archived is answered as it is.

Needs customers:write.

Parameters

Answers 200

curl -X POST "https://api.storeware.ai/api/v1/stores/$STORE_ID/customers/$CUSTOMER_ID/unarchive" \
  -H "Authorization: Bearer $TOKEN"

Withdraw a customer’s marketing consentCopy Anchor Link

DELETE /api/v1/stores/{storeId}/customers/{customerId}/marketing-consent

Records that the customer asked not to be emailed, and sends customer.consent_withdrawn.v1 with their email. Consent can only be withdrawn here, never given. A customer already off the list is answered as they are.

Needs customers:write.

Parameters

Answers 200

curl -X DELETE "https://api.storeware.ai/api/v1/stores/$STORE_ID/customers/$CUSTOMER_ID/marketing-consent" \
  -H "Authorization: Bearer $TOKEN"

List a customer’s metafieldsCopy Anchor Link

GET /api/v1/stores/{storeId}/customers/{customerId}/metafields

Every metafield value set on a customer, each with its definition.

Needs customers:read.

Parameters

Answers 200

curl "https://api.storeware.ai/api/v1/stores/$STORE_ID/customers/$CUSTOMER_ID/metafields" \
  -H "Authorization: Bearer $TOKEN"

Set a customer’s metafieldsCopy Anchor Link

PUT /api/v1/stores/{storeId}/customers/{customerId}/metafields

Sets up to 25 values in one call. A null value clears its field; keys not named are left alone. An app may set only the fields its manifest declares.

Needs customers:write.

Parameters

Body

Answers 200

curl -X PUT "https://api.storeware.ai/api/v1/stores/$STORE_ID/customers/$CUSTOMER_ID/metafields" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json

List the trade accounts a customer buys forCopy Anchor Link

GET /api/v1/stores/{storeId}/customers/{customerId}/companies

The companies the customer buys on behalf of, by name. At most one today.

Needs companies:read.

Parameters

Answers 200

curl "https://api.storeware.ai/api/v1/stores/$STORE_ID/customers/$CUSTOMER_ID/companies" \
  -H "Authorization: Bearer $TOKEN"

Get a customer’s store creditCopy Anchor Link

GET /api/v1/stores/{storeId}/customers/{customerId}/store-credit

What the customer holds in each currency, and the entries behind it, newest first. orders:read will do in place of customers:read.

Needs customers:read.

Parameters

Answers 200

curl "https://api.storeware.ai/api/v1/stores/$STORE_ID/customers/$CUSTOMER_ID/store-credit" \
  -H "Authorization: Bearer $TOKEN"

Give a customer store creditCopy Anchor Link

POST /api/v1/stores/{storeId}/customers/{customerId}/store-credit

Puts credit on the customer’s account in one currency, for them to spend at checkout. amount is in minor units. It needs orders:write, as a refund does. An idempotencyKey already used is refused, so a retry cannot credit twice.

Needs orders:write.

Parameters

Body

Answers 201

curl -X POST "https://api.storeware.ai/api/v1/stores/$STORE_ID/customers/$CUSTOMER_ID/store-credit" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json

Get what the shop remembers about a customerCopy Anchor Link

GET /api/v1/stores/{storeId}/customers/{customerId}/memory

What the customer told the shop they want while shopping signed in (a budget, requirements, context), which the shop keeps to narrow and rank what it shows them.

Needs customers:read.

Parameters

Answers 200

curl "https://api.storeware.ai/api/v1/stores/$STORE_ID/customers/$CUSTOMER_ID/memory" \
  -H "Authorization: Bearer $TOKEN"

Make the shop forget what a customer told itCopy Anchor Link

POST /api/v1/stores/{storeId}/customers/{customerId}/memory

Removes all of it, or one part. There is no default: a body that names nothing is a 400. Answers with what remains.

Needs customers:write.

Parameters

Body

Answers 200

curl -X POST "https://api.storeware.ai/api/v1/stores/$STORE_ID/customers/$CUSTOMER_ID/memory" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json