Customers API

One record for every customer, shared by every module.

Module code customers · 27 actions · 6 data models · 18 events. A key or token never does more here than the person behind it can; row-level security applies exactly as in the app. Scopes: customers (everything), customers:read (read only) or customers:<capability>.

Resources

Lists take limit (up to 200), cursor, order (e.g. -created_at), fields and q; every other query parameter is a column filter: ?status=paid, ?total[gte]=100, ?id[in]=a,b, ?x=null.

Actions

customers.add_address

Add an address — Puts a delivery or billing address in this person’s book.

Needs customers:write · changes data

• REST alias: POST /api/v1/addresses
• Canonical address: POST /api/v1/actions/customers.add_address

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: customers.address_changed

What it writes: address (insert) — Writes the address; customer_address (upsert) — Links it to the person

curl -X POST https://app.getera.io/api/v1/addresses/actions/add_address \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"id":"CUSTOMER_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "customers.address_changed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.addresses.create({
  id: "CUSTOMER_ID"
})

era addresses create \
  --id "CUSTOMER_ID"

{
  "name": "era__customers__add_address",
  "arguments": {
    "id": "CUSTOMER_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold customers:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, already_merged, empty_address · 429 slow down

customers.add_identity

Add a way to recognise this person — Records another email, phone number, domain or external key for one customer.

Needs customers:write · changes data

• Canonical address: POST /api/v1/actions/customers.add_identity

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: customers.identity_changed

What it writes: customer_identity (insert) — Adds the key

curl -X POST https://app.getera.io/api/v1/customer_identities/actions/add_identity \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"id":"CUSTOMER_ID","kind":"email","value":"Value"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "customers.identity_changed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.customerIdentities.addIdentity({
  id: "CUSTOMER_ID",
  kind: "email",
  value: "Value"
})

era customer_identities add_identity \
  --id "CUSTOMER_ID" \
  --kind "email" \
  --value "Value"

{
  "name": "era__customers__add_identity",
  "arguments": {
    "id": "CUSTOMER_ID",
    "kind": "email",
    "value": "Value"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold customers:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, already_merged, empty_identity, identity_already_present, identity_taken · 429 slow down

customers.add_my_address

Add an address to my account — A signed-in customer saves a delivery or billing address to their own address book.

Needs customers:write · changes data · Also callable from a published site (customer)

• Canonical address: POST /api/v1/actions/customers.add_my_address

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: customers.address_changed

What it writes: address (insert) — The address; customer_address (insert) — In their own book

Errors: 401 no or expired credential · 403 the credential does not hold customers:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 empty_address · 429 slow down

customers.archive

Archive a customer — Takes the record out of lists and pickers without deleting anything.

Needs customers:delete · removes or cannot be undone · asks a person to confirm when Era runs it

• REST alias: DELETE /api/v1/customers/{id}
• Canonical address: POST /api/v1/actions/customers.archive

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: customers.archived

What it writes: customer (update) — Stamps archived_at

curl -X POST https://app.getera.io/api/v1/customers/CUSTOMER_ID/actions/archive \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "customers.archived"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.customers.archive("CUSTOMER_ID")

era customers archive CUSTOMER_ID

{
  "name": "era__customers__archive",
  "arguments": {
    "id": "CUSTOMER_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold customers:delete · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, already_merged, already_archived · 429 slow down

customers.capture

Add or recognise a customer — Resolves an email or phone number to one customer record, creating it only if new.

Needs customers:write · changes data

• REST alias: POST /api/v1/customers
• Canonical address: POST /api/v1/actions/customers.capture

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: customers.created, customers.recognised

What it writes: customer (upsert) — Creates the customer when the identity is new; customer_identity (upsert) — Records every way this person reaches you

curl -X POST https://app.getera.io/api/v1/customers/actions/capture \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name":"Name"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "customers.created",
    "customers.recognised"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.customers.create({
  name: "Name"
})

era customers create \
  --name "Name"

{
  "name": "era__customers__capture",
  "arguments": {
    "name": "Name"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold customers:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 no_identity, unknown_identity_kind · 429 slow down

customers.capture_site_guest

Recognise a website buyer — The checkout’s contact step: the signed-in customer, or a guest recognised by email, and the delivery address as this order’s own copy.

Needs customers:write · changes data · Also callable from a published site (visitor)

• Canonical address: POST /api/v1/actions/customers.capture_site_guest

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: customers.recognised, customers.created

What it writes: customer (insert) — A new guest, when the email is not known; address (insert) — The delivery address, as the order’s own copy

Errors: 401 no or expired credential · 403 the credential does not hold customers:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 invalid_email, name_missing · 429 slow down

customers.confirm_email_change

Confirm my new email — The code from the new inbox moves the site account and the customer record to that address.

Needs customers:write · reaches outside (sends, publishes or charges) · Also callable from a published site (customer)

• Canonical address: POST /api/v1/actions/customers.confirm_email_change

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: customers.login_changed, customers.updated

What it writes: customer_login_code (update) — Counts the attempt or uses the code up; customer_login (update) — Moves the sign-in to the new address; customer (update) — Their record gets the new address

Errors: 401 no or expired credential · 403 the credential does not hold customers:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_signed_in, login_disabled, same_email, email_taken, code_expired · 429 slow down

customers.disable_login

Switch off site account — Stops the customer signing in to your website and signs them out everywhere. Their record and history stay.

Needs customers:manage · reaches outside (sends, publishes or charges) · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/customers.disable_login

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: customers.login_changed

What it writes: customer_login (update) — Switched off, with the reason; customer_session (update) — Every open session revoked

curl -X POST https://app.getera.io/api/v1/customer_logins/actions/disable_login \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"id":"CUSTOMER_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "customers.login_changed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.customerLogins.disableLogin({
  id: "CUSTOMER_ID"
})

era customer_logins disable_login \
  --id "CUSTOMER_ID"

{
  "name": "era__customers__disable_login",
  "arguments": {
    "id": "CUSTOMER_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold customers:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, no_login, already_disabled · 429 slow down

customers.enable_login

Switch site account back on — Lets the customer sign in to your website again.

Needs customers:manage · changes data

• Canonical address: POST /api/v1/actions/customers.enable_login

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: customers.login_changed

What it writes: customer_login (update) — Switched back on

curl -X POST https://app.getera.io/api/v1/customer_logins/actions/enable_login \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"id":"CUSTOMER_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "customers.login_changed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.customerLogins.enableLogin({
  id: "CUSTOMER_ID"
})

era customer_logins enable_login \
  --id "CUSTOMER_ID"

{
  "name": "era__customers__enable_login",
  "arguments": {
    "id": "CUSTOMER_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold customers:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, no_login, not_disabled · 429 slow down

customers.export

Export customers — The customer list as filtered, as rows — the customers screen turns them into a CSV or Excel file.

Needs customers:export · reaches outside (sends, publishes or charges)

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: customers.exported

curl -X POST https://app.getera.io/api/v1/actions/customers.export \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"q":"Search"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "customers.exported"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.actions.run("customers.export", {
  q: "Search"
})

era run customers.export \
  --q "Search"

{
  "name": "era__customers__export",
  "arguments": {
    "q": "Search"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold customers:export · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 invalid_filter · 429 slow down

customers.merge

Merge two customers — Folds one record into another, moving its identities and history across.

Needs customers:manage · removes or cannot be undone · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/customers.merge

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: customers.merged

What it writes: customer (update) — Tombstones the merged record and applies the chosen values; customer_identity (update) — Moves identities to the survivor; customer_address (update) — Moves the address book to the survivor

curl -X POST https://app.getera.io/api/v1/customers/CUSTOMER_ID/actions/merge \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"mergeId":"CUSTOMER_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "customers.merged"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.customers.merge("CUSTOMER_ID", {
  mergeId: "CUSTOMER_ID"
})

era customers merge CUSTOMER_ID \
  --merge-id "CUSTOMER_ID"

{
  "name": "era__customers__merge",
  "arguments": {
    "keepId": "CUSTOMER_ID",
    "mergeId": "CUSTOMER_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold customers:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, same_record, already_merged, keep_is_merged, company_has_members · 429 slow down

customers.remove_address

Archive an address — Takes it out of the book without touching the documents that used it.

Needs customers:delete · removes or cannot be undone · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/customers.remove_address

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: customers.address_changed

What it writes: address (update) — Stamps archived_at; customer_address (update) — Clears the defaults

curl -X POST https://app.getera.io/api/v1/addresses/ADDRESSE_ID/actions/remove_address \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "customers.address_changed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.addresses.removeAddress("ADDRESSE_ID")

era addresses remove_address ADDRESSE_ID

{
  "name": "era__customers__remove_address",
  "arguments": {
    "addressId": "ADDRESSE_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold customers:delete · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 address_not_found, address_is_snapshot, already_archived · 429 slow down

customers.remove_identity

Remove a way to recognise this person — Drops one key, unless it is the only one left.

Needs customers:write · removes or cannot be undone · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/customers.remove_identity

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: customers.identity_changed

What it writes: customer_identity (delete) — Removes the key

curl -X POST https://app.getera.io/api/v1/customer_identities/actions/remove_identity \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"id":"CUSTOMER_ID","kind":"email","value":"Value"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "customers.identity_changed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.customerIdentities.removeIdentity({
  id: "CUSTOMER_ID",
  kind: "email",
  value: "Value"
})

era customer_identities remove_identity \
  --id "CUSTOMER_ID" \
  --kind "email" \
  --value "Value"

{
  "name": "era__customers__remove_identity",
  "arguments": {
    "id": "CUSTOMER_ID",
    "kind": "email",
    "value": "Value"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold customers:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, already_merged, identity_not_found, last_identity · 429 slow down

customers.remove_my_address

Remove an address from my account — A signed-in customer takes an address out of their own address book.

Needs customers:write · removes or cannot be undone · Also callable from a published site (customer)

• Canonical address: POST /api/v1/actions/customers.remove_my_address

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: customers.address_changed

What it writes: address (update) — Archived — orders that used it keep their copy; customer_address (update) — No longer a default

Errors: 401 no or expired credential · 403 the credential does not hold customers:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 address_not_on_customer · 429 slow down

customers.request_email_change

Change my sign-in email — A signed-in customer asks to sign in with another address; a code goes to that address to prove it is theirs.

Needs customers:write · reaches outside (sends, publishes or charges) · Also callable from a published site (customer)

• Canonical address: POST /api/v1/actions/customers.request_email_change

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: customers.sign_in_code_requested

What it writes: customer_login_code (insert) — Stores the hash of a ten-minute change code

Errors: 401 no or expired credential · 403 the credential does not hold customers:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_signed_in, login_disabled, same_email, email_taken, too_many_codes · 429 slow down

customers.request_sign_in_code

Send a sign-in code — Emails a six-digit code a visitor types to sign in to the site — no password needed.

Needs customers:write · changes data · Also callable from a published site (visitor)

• Canonical address: POST /api/v1/actions/customers.request_sign_in_code

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: customers.sign_in_code_requested

What it writes: customer_login_code (insert) — Stores the hash of a ten-minute code

Errors: 401 no or expired credential · 403 the credential does not hold customers:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 login_disabled, too_many_codes · 429 slow down

customers.restore

Restore a customer — Brings an archived record back.

Needs customers:delete · changes data

• Canonical address: POST /api/v1/actions/customers.restore

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: customers.restored

What it writes: customer (update) — Clears archived_at

curl -X POST https://app.getera.io/api/v1/customers/CUSTOMER_ID/actions/restore \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "customers.restored"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.customers.restore("CUSTOMER_ID")

era customers restore CUSTOMER_ID

{
  "name": "era__customers__restore",
  "arguments": {
    "id": "CUSTOMER_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold customers:delete · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, already_merged, not_archived · 429 slow down

customers.send_sign_in_link

Send a site sign-in link — Emails the customer a link to sign in to your website — the first time, or when they cannot get in. They get their own code there.

Needs customers:write · reaches outside (sends, publishes or charges)

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: customers.sign_in_link_sent

curl -X POST https://app.getera.io/api/v1/actions/customers.send_sign_in_link \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"id":"CUSTOMER_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "customers.sign_in_link_sent"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.actions.run("customers.send_sign_in_link", {
  id: "CUSTOMER_ID"
})

era run customers.send_sign_in_link \
  --id "CUSTOMER_ID"

{
  "name": "era__customers__send_sign_in_link",
  "arguments": {
    "id": "CUSTOMER_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold customers:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, already_merged, no_email, login_disabled · 429 slow down

customers.set_default_address

Set a default address — Which address is used for delivery or for billing unless told otherwise.

Needs customers:write · changes data

• Canonical address: POST /api/v1/actions/customers.set_default_address

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: customers.address_default_changed

What it writes: customer_address (update) — Moves the default

curl -X POST https://app.getera.io/api/v1/customer_addresses/actions/set_default_address \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"id":"CUSTOMER_ID","addressId":"ADDRESS_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "customers.address_default_changed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.customerAddresses.setDefaultAddress({
  id: "CUSTOMER_ID",
  addressId: "ADDRESS_ID"
})

era customer_addresses set_default_address \
  --id "CUSTOMER_ID" \
  --address-id "ADDRESS_ID"

{
  "name": "era__customers__set_default_address",
  "arguments": {
    "id": "CUSTOMER_ID",
    "addressId": "ADDRESS_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold customers:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, already_merged, address_not_on_customer, address_archived, nothing_to_set · 429 slow down

customers.set_my_password

Set my password — A signed-in customer sets or changes the password for their site account.

Needs customers:write · changes data · Also callable from a published site (customer)

• Canonical address: POST /api/v1/actions/customers.set_my_password

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: customers.login_changed

What it writes: customer_login (update) — Stores the scrypt hash of the password

Errors: 401 no or expired credential · 403 the credential does not hold customers:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_signed_in, password_too_short, wrong_password · 429 slow down

customers.set_parent

Attach to a company — Says which company this person belongs to, or detaches them.

Needs customers:write · changes data

• Canonical address: POST /api/v1/actions/customers.set_parent

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: customers.parent_changed

What it writes: customer (update) — Sets the company link

curl -X POST https://app.getera.io/api/v1/customers/CUSTOMER_ID/actions/set_parent \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"parentId":"CUSTOMER_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "customers.parent_changed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.customers.setParent("CUSTOMER_ID", {
  parentId: "CUSTOMER_ID"
})

era customers set_parent CUSTOMER_ID \
  --parent-id "CUSTOMER_ID"

{
  "name": "era__customers__set_parent",
  "arguments": {
    "id": "CUSTOMER_ID",
    "parentId": "CUSTOMER_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold customers:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, already_merged, self_parent, parent_not_a_company, parent_cycle · 429 slow down

customers.sign_in_with_password

Sign in with a password — Signs a customer in to the site with the password they set on their account.

Needs customers:write · changes data · Also callable from a published site (visitor)

• Canonical address: POST /api/v1/actions/customers.sign_in_with_password

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: customers.signed_in

What it writes: customer_session (insert) — A thirty-day site session; customer_login (update) — Last sign-in

Errors: 401 no or expired credential · 403 the credential does not hold customers:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 wrong_credentials, login_disabled · 429 slow down

customers.sign_out

Sign out — Ends the customer’s site session on this device.

Needs customers:write · changes data · Also callable from a published site (customer)

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: customers.signed_out

What it writes: customer_session (update) — Revoked

Errors: 401 no or expired credential · 403 the credential does not hold customers:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 session_not_found · 429 slow down

customers.update

Edit a customer — Changes the person’s details and tells the rest of the system.

Needs customers:write · changes data

• REST alias: PATCH /api/v1/customers/{id}
• Canonical address: POST /api/v1/actions/customers.update

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: customers.updated

What it writes: customer (update) — Updates the record

curl -X POST https://app.getera.io/api/v1/customers/CUSTOMER_ID/actions/update \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name":"Name"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "customers.updated"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.customers.update("CUSTOMER_ID", {
  name: "Name"
})

era customers update CUSTOMER_ID \
  --name "Name"

{
  "name": "era__customers__update",
  "arguments": {
    "id": "CUSTOMER_ID",
    "name": "Name"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold customers:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_found, already_merged, company_has_members · 429 slow down

customers.update_address

Edit an address — Changes a book address. The copy frozen on a document does not move.

Needs customers:write · changes data

• Canonical address: POST /api/v1/actions/customers.update_address

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: customers.address_changed

What it writes: address (update) — Updates the address; customer_address (update) — Updates its label

curl -X POST https://app.getera.io/api/v1/addresses/ADDRESSE_ID/actions/update_address \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"label":"Label"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "customers.address_changed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.addresses.updateAddress("ADDRESSE_ID", {
  label: "Label"
})

era addresses update_address ADDRESSE_ID \
  --label "Label"

{
  "name": "era__customers__update_address",
  "arguments": {
    "addressId": "ADDRESSE_ID",
    "label": "Label"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold customers:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 address_not_found, address_is_snapshot, empty_address · 429 slow down

customers.update_my_profile

Update my details — A signed-in customer corrects their own name, phone and language.

Needs customers:write · changes data · Also callable from a published site (customer)

• Canonical address: POST /api/v1/actions/customers.update_my_profile

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: customers.updated

What it writes: customer (update) — Their own record

Errors: 401 no or expired credential · 403 the credential does not hold customers:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 name_required · 429 slow down

customers.verify_sign_in_code

Sign in with a code — Checks the emailed code and signs the visitor in — making their account the first time, attached to the customer the business already knows.

Needs customers:write · changes data · Also callable from a published site (visitor)

• Canonical address: POST /api/v1/actions/customers.verify_sign_in_code

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: customers.signed_in, customers.sign_in_failed, customers.login_created, customers.created, customers.recognised

What it writes: customer_login_code (update) — Counts the attempt or uses the code up; customer_login (upsert) — Makes the login the first time; marks the email verified; customer (insert) — A new customer when nobody with this email is known; customer_identity (insert) — The email, as a way of recognising them; customer_session (insert) — A thirty-day site session

Errors: 401 no or expired credential · 403 the credential does not hold customers:write · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 code_expired, login_disabled · 429 slow down

Data models

Address

Table address · Resource addresses

• GET /api/v1/addresses
• GET /api/v1/addresses/{id}
• POST /api/v1/addresses → customers.add_address

Primary key: id

Checks:

• CHECK ((COALESCE(street_address_1, city, postal_code, raw, company_name) IS NOT NULL))
• CHECK ((NOT (is_snapshot AND (archived_at IS NOT NULL))))

CustomerAddress

Table customer_address · Resource customer_addresses

• GET /api/v1/customer_addresses
• GET /api/v1/customer_addresses/{id}

Primary key: id

Unique: customer_id, address_id

CustomerIdentity

Table customer_identity · Resource customer_identities

• GET /api/v1/customer_identities
• GET /api/v1/customer_identities/{id}

Primary key: id

Checks:

• CHECK (( CASE kind WHEN 'email'::text THEN (value = lower(value)) WHEN 'domain'::text THEN (value = lower(value)) ELSE true END AND (value = btrim(value)) AND (length(value) > 0)))

CustomerLoginCode

Table customer_login_code · Resource customer_login_codes

• GET /api/v1/customer_login_codes
• GET /api/v1/customer_login_codes/{id}

Primary key: id

CustomerLogin

Table customer_login · Resource customer_logins

• GET /api/v1/customer_logins
• GET /api/v1/customer_logins/{id}

Primary key: id

Checks:

• CHECK (((email IS NOT NULL) OR (phone IS NOT NULL)))
• CHECK (((email IS NULL) OR ((email = lower(btrim(email))) AND (POSITION(('@'::text) IN (email)) > 1))))
• CHECK (((disabled_reason IS NULL) OR (length(disabled_reason) <= 500)))

Customer

Table customer · Resource customers

• GET /api/v1/customers
• GET /api/v1/customers/{id}
• POST /api/v1/customers → customers.capture
• PATCH /api/v1/customers/{id} → customers.update
• DELETE /api/v1/customers/{id} → customers.archive

Primary key: id

Events

Workflows and webhooks react to these events.