Customers

GET `/customers`

List the organization's customers, newest first by default. Supports search, filtering and cursor pagination.

Requires the customers:read permission.

Query Parameters

limitnumber

The number of records to return.

cursorstring

A pagination cursor. Fetch the next page by passing the nextCursor value from the previous response.

sortemail | -email | createdAt | -createdAt

The sort order. Prefix a field with - to sort descending. Defaults to -createdAt.

searchstring

A free-text search term, matched case-insensitively against the record's most identifying fields. Combined with filter using AND.

filterstring

A JSON-encoded filter document, for example {"createdAt":{"$gte":"2025-01-01T00:00:00Z"}}. Filterable fields: id, email, firstName, lastName, metadata, emailOptOut, emailOptOutSource, createdAt, tags.name. See Filtering for the syntax.

includestring

A comma-separated list of extra fields to compute and return. Each one costs an additional query, so ask only for what you need. Available: importJob, ordersCount, reviewsCount, wishlistsCount, loyaltyPointsBalance, tags.

Request

curl \
  "https://api.cascade.dev/customers" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY"

Request

import { client } from "@cascade-commerce/api/admin/client"
import { getCustomers } from "@cascade-commerce/api/admin"

client.setConfig({
  baseUrl: "https://api.cascade.dev",
  headers: { Authorization: "Bearer sk_YOUR_SECRET_KEY" },
})

const { data, error } = await getCustomers()

Request

require "net/http"

uri = URI("https://api.cascade.dev/customers")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer sk_YOUR_SECRET_KEY"

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body

Request

import json
from urllib.request import Request, urlopen

req = Request(
    "https://api.cascade.dev/customers",
    headers={"Authorization": "Bearer sk_YOUR_SECRET_KEY"},
)
with urlopen(req) as res:
    print(json.load(res))

Response

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "[email protected]",
      "phone": "string",
      "firstName": "string",
      "lastName": "string",
      "country": "string",
      "birthday": "string",
      "metadata": "...",
      "notes": "string",
      "emailOptOut": true,
      "emailOptOutAt": "2025-01-15T09:30:00Z",
      "emailOptOutSource": "customer",
      "createdAt": "2025-01-15T09:30:00Z",
      "updatedAt": "2025-01-15T09:30:00Z",
      "importJob": {
        "id": "...",
        "type": "...",
        "action": "...",
        "row": "...",
        "createdAt": "..."
      },
      "ordersCount": 0,
      "reviewsCount": 0,
      "wishlistsCount": 0,
      "loyaltyPointsBalance": 0,
      "tags": ["..."]
    }
  ],
  "nextCursor": "string"
}

Response schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
            "description": "Unique identifier for the customer."
          },
          "email": {
            "type": "string",
            "format": "email",
            "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
            "description": "The customer's email address, unique within the organization."
          },
          "phone": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "The customer's phone number in E.164 format."
          },
          "firstName": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "The customer's first name."
          },
          "lastName": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "The customer's last name."
          },
          "country": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "The customer's country, as an ISO 3166-1 code."
          },
          "birthday": {
            "anyOf": [
              {
                "type": "string",
                "pattern": "^(?:(?:0[13578]|1[02])-(?:0[1-9]|[12][0-9]|3[01])|(?:0[469]|11)-(?:0[1-9]|[12][0-9]|30)|02-(?:0[1-9]|1[0-9]|2[0-9]))$",
                "description": "The customer's birthday as `MM-DD`. Month and day only: no year is collected or stored. February 29 is allowed, and in a year that has no February 29 it is treated as February 28."
              },
              {
                "type": "null"
              }
            ],
            "description": "The customer's birthday as `MM-DD`, or null when they have not given one. Month and day only: no year is collected or stored."
          },
          "metadata": {
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {
              "type": "string"
            },
            "description": "Free-form string key/value pairs for your own data. Individual keys are filterable with a dot path, for example `metadata.category`."
          },
          "notes": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Internal notes about the customer. Never shown to them."
          },
          "emailOptOut": {
            "type": "boolean",
            "description": "Whether the customer has opted out of marketing email. They still receive mail they asked for, such as a wishlist they shared themselves."
          },
          "emailOptOutAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
              },
              {
                "type": "null"
              }
            ],
            "description": "When the opt-out was recorded. Null while the customer is still subscribed."
          },
          "emailOptOutSource": {
            "anyOf": [
              {
                "type": "string",
                "enum": ["customer", "merchant", "import", "shopify"],
                "description": "Where the opt-out came from."
              },
              {
                "type": "null"
              }
            ],
            "description": "Where the opt-out came from: `customer` (they opted out themselves, through an unsubscribe link or your integration), `merchant`, `import` or `shopify`. Null while the customer is still subscribed."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
            "description": "When the customer was first created in Cascade."
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
            "description": "When the customer was last changed."
          },
          "importJob": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid",
                    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
                    "description": "The import job that wrote the record."
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "customers",
                      "products",
                      "orders",
                      "wishlists",
                      "reviews",
                      "loyalty-members"
                    ],
                    "description": "What that import's file contained."
                  },
                  "action": {
                    "type": "string",
                    "enum": ["created", "updated"],
                    "description": "Whether the import created this record or updated one that was already there."
                  },
                  "row": {
                    "anyOf": [
                      {
                        "type": "integer",
                        "minimum": -9007199254740991,
                        "maximum": 9007199254740991
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "The 1-based row in the import's CSV that became this record, where it is known."
                  },
                  "createdAt": {
                    "type": "string",
                    "format": "date-time",
                    "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
                    "description": "When that import was started."
                  }
                },
                "required": ["id", "type", "action", "row", "createdAt"],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ],
            "description": "The import that last wrote this record, or null when no import did."
          },
          "ordersCount": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "How many orders the customer has placed."
          },
          "reviewsCount": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "How many reviews the customer has written."
          },
          "wishlistsCount": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "How many wishlists the customer has."
          },
          "loyaltyPointsBalance": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "The customer's current loyalty points balance, or zero when they hold none."
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Names of the tags applied to the customer."
          }
        },
        "required": [
          "id",
          "email",
          "phone",
          "firstName",
          "lastName",
          "country",
          "birthday",
          "metadata",
          "notes",
          "emailOptOut",
          "emailOptOutAt",
          "emailOptOutSource",
          "createdAt",
          "updatedAt"
        ],
        "additionalProperties": false
      },
      "description": "The page of records, in the requested sort order."
    },
    "nextCursor": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Pass this back as `cursor` to fetch the next page. Null once the last page has been returned."
    }
  },
  "required": ["data", "nextCursor"],
  "additionalProperties": false
}

PATCH `/customers/bulk-update`

Add or remove tags and metadata, or set the marketing email opt-out, across every customer matching a filter in one request. Sending no filter applies the changes to every customer in the organization. At least one change is required.

Requires the customers:write permission.

Costs 5 rate limit tokens instead of the usual one. See Rate limits.

Query Parameters

filterstring

A JSON-encoded filter document selecting the customers to update. Omit it and every customer in the organization is updated. See Filtering for the syntax.

searchstring

A free-text search term, matched case-insensitively against the record's most identifying fields. Combined with filter using AND.

Body Parameters

addTagsstring[]

Tag names to add. Tags that do not exist yet are created.

removeTagsstring[]

Tag names to remove.

addMetadataobject

Metadata keys to set, merged onto whatever each customer already has.

removeMetadataKeysstring[]

Metadata keys to delete.

emailOptOutboolean

Set to true to stop sending every matching customer marketing email, false to opt them all back in. Omit to leave it alone.

emailOptOutSourcecustomer | merchant | import | shopify

Where the opt-out came from. Defaults to merchant.

Request

curl \
  -X PATCH \
  "https://api.cascade.dev/customers/bulk-update" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "addTags": [
    "string"
  ],
  "removeTags": [
    "string"
  ],
  "addMetadata": "...",
  "removeMetadataKeys": [
    "string"
  ],
  "emailOptOut": true,
  "emailOptOutSource": "customer"
}'

Request

import { client } from "@cascade-commerce/api/admin/client"
import { patchCustomersBulkUpdate } from "@cascade-commerce/api/admin"

client.setConfig({
  baseUrl: "https://api.cascade.dev",
  headers: { Authorization: "Bearer sk_YOUR_SECRET_KEY" },
})

const { data, error } = await patchCustomersBulkUpdate({
  body: {
    addTags: ["string"],
    removeTags: ["string"],
    addMetadata: "...",
    removeMetadataKeys: ["string"],
    emailOptOut: true,
    emailOptOutSource: "customer",
  },
})

Request

require "net/http"

uri = URI("https://api.cascade.dev/customers/bulk-update")
req = Net::HTTP::Patch.new(uri)
req["Authorization"] = "Bearer sk_YOUR_SECRET_KEY"
req["Content-Type"] = "application/json"
req.body = <<~JSON
  {
    "addTags": [
      "string"
    ],
    "removeTags": [
      "string"
    ],
    "addMetadata": "...",
    "removeMetadataKeys": [
      "string"
    ],
    "emailOptOut": true,
    "emailOptOutSource": "customer"
  }
JSON

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body

Request

import json
from urllib.request import Request, urlopen

body = """{
  "addTags": [
    "string"
  ],
  "removeTags": [
    "string"
  ],
  "addMetadata": "...",
  "removeMetadataKeys": [
    "string"
  ],
  "emailOptOut": true,
  "emailOptOutSource": "customer"
}"""

req = Request(
    "https://api.cascade.dev/customers/bulk-update",
    data=body.encode(),
    method="PATCH",
    headers={
        "Authorization": "Bearer sk_YOUR_SECRET_KEY",
        "Content-Type": "application/json",
    },
)
with urlopen(req) as res:
    print(json.load(res))

Response

{
  "count": 0
}

Response schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "count": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "How many customers the filter matched."
    }
  },
  "required": ["count"],
  "additionalProperties": false
}

POST `/customers/import`

Create or update customers in bulk, matching on email. Every column you send overwrites what is already stored, so send complete records rather than partial ones.

Requires the customers:write permission.

Costs 10 rate limit tokens instead of the usual one. See Rate limits.

Body Parameters

dataobject[]required

The customers to create or update.

Request

curl \
  -X POST \
  "https://api.cascade.dev/customers/import" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "data": [
    {
      "email": "[email protected]",
      "phone": "string",
      "firstName": "string",
      "lastName": "string",
      "birthday": "string",
      "metadata": "...",
      "tags": [
        "..."
      ],
      "emailOptOut": true,
      "emailOptOutSource": "customer"
    }
  ]
}'

Request

import { client } from "@cascade-commerce/api/admin/client"
import { postCustomersImport } from "@cascade-commerce/api/admin"

client.setConfig({
  baseUrl: "https://api.cascade.dev",
  headers: { Authorization: "Bearer sk_YOUR_SECRET_KEY" },
})

const { data, error } = await postCustomersImport({
  body: {
    data: [
      {
        email: "[email protected]",
        phone: "string",
        firstName: "string",
        lastName: "string",
        birthday: "string",
        metadata: "...",
        tags: ["..."],
        emailOptOut: true,
        emailOptOutSource: "customer",
      },
    ],
  },
})

Request

require "net/http"

uri = URI("https://api.cascade.dev/customers/import")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer sk_YOUR_SECRET_KEY"
req["Content-Type"] = "application/json"
req.body = <<~JSON
  {
    "data": [
      {
        "email": "[email protected]",
        "phone": "string",
        "firstName": "string",
        "lastName": "string",
        "birthday": "string",
        "metadata": "...",
        "tags": [
          "..."
        ],
        "emailOptOut": true,
        "emailOptOutSource": "customer"
      }
    ]
  }
JSON

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body

Request

import json
from urllib.request import Request, urlopen

body = """{
  "data": [
    {
      "email": "[email protected]",
      "phone": "string",
      "firstName": "string",
      "lastName": "string",
      "birthday": "string",
      "metadata": "...",
      "tags": [
        "..."
      ],
      "emailOptOut": true,
      "emailOptOutSource": "customer"
    }
  ]
}"""

req = Request(
    "https://api.cascade.dev/customers/import",
    data=body.encode(),
    headers={
        "Authorization": "Bearer sk_YOUR_SECRET_KEY",
        "Content-Type": "application/json",
    },
)
with urlopen(req) as res:
    print(json.load(res))

Response

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "[email protected]",
      "phone": "string",
      "firstName": "string",
      "lastName": "string",
      "country": "string",
      "birthday": "string",
      "metadata": "...",
      "notes": "string",
      "emailOptOut": true,
      "emailOptOutAt": "2025-01-15T09:30:00Z",
      "emailOptOutSource": "customer",
      "createdAt": "2025-01-15T09:30:00Z",
      "updatedAt": "2025-01-15T09:30:00Z",
      "importJob": {
        "id": "...",
        "type": "...",
        "action": "...",
        "row": "...",
        "createdAt": "..."
      },
      "ordersCount": 0,
      "reviewsCount": 0,
      "wishlistsCount": 0,
      "loyaltyPointsBalance": 0,
      "tags": ["..."]
    }
  ],
  "skipped": [
    {
      "index": 0,
      "message": "string"
    }
  ]
}

Response schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
            "description": "Unique identifier for the customer."
          },
          "email": {
            "type": "string",
            "format": "email",
            "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
            "description": "The customer's email address, unique within the organization."
          },
          "phone": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "The customer's phone number in E.164 format."
          },
          "firstName": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "The customer's first name."
          },
          "lastName": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "The customer's last name."
          },
          "country": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "The customer's country, as an ISO 3166-1 code."
          },
          "birthday": {
            "anyOf": [
              {
                "type": "string",
                "pattern": "^(?:(?:0[13578]|1[02])-(?:0[1-9]|[12][0-9]|3[01])|(?:0[469]|11)-(?:0[1-9]|[12][0-9]|30)|02-(?:0[1-9]|1[0-9]|2[0-9]))$",
                "description": "The customer's birthday as `MM-DD`. Month and day only: no year is collected or stored. February 29 is allowed, and in a year that has no February 29 it is treated as February 28."
              },
              {
                "type": "null"
              }
            ],
            "description": "The customer's birthday as `MM-DD`, or null when they have not given one. Month and day only: no year is collected or stored."
          },
          "metadata": {
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {
              "type": "string"
            },
            "description": "Free-form string key/value pairs for your own data. Individual keys are filterable with a dot path, for example `metadata.category`."
          },
          "notes": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Internal notes about the customer. Never shown to them."
          },
          "emailOptOut": {
            "type": "boolean",
            "description": "Whether the customer has opted out of marketing email. They still receive mail they asked for, such as a wishlist they shared themselves."
          },
          "emailOptOutAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
              },
              {
                "type": "null"
              }
            ],
            "description": "When the opt-out was recorded. Null while the customer is still subscribed."
          },
          "emailOptOutSource": {
            "anyOf": [
              {
                "type": "string",
                "enum": ["customer", "merchant", "import", "shopify"],
                "description": "Where the opt-out came from."
              },
              {
                "type": "null"
              }
            ],
            "description": "Where the opt-out came from: `customer` (they opted out themselves, through an unsubscribe link or your integration), `merchant`, `import` or `shopify`. Null while the customer is still subscribed."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
            "description": "When the customer was first created in Cascade."
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
            "description": "When the customer was last changed."
          },
          "importJob": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid",
                    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
                    "description": "The import job that wrote the record."
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "customers",
                      "products",
                      "orders",
                      "wishlists",
                      "reviews",
                      "loyalty-members"
                    ],
                    "description": "What that import's file contained."
                  },
                  "action": {
                    "type": "string",
                    "enum": ["created", "updated"],
                    "description": "Whether the import created this record or updated one that was already there."
                  },
                  "row": {
                    "anyOf": [
                      {
                        "type": "integer",
                        "minimum": -9007199254740991,
                        "maximum": 9007199254740991
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "The 1-based row in the import's CSV that became this record, where it is known."
                  },
                  "createdAt": {
                    "type": "string",
                    "format": "date-time",
                    "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
                    "description": "When that import was started."
                  }
                },
                "required": ["id", "type", "action", "row", "createdAt"],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ],
            "description": "The import that last wrote this record, or null when no import did."
          },
          "ordersCount": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "How many orders the customer has placed."
          },
          "reviewsCount": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "How many reviews the customer has written."
          },
          "wishlistsCount": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "How many wishlists the customer has."
          },
          "loyaltyPointsBalance": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "The customer's current loyalty points balance, or zero when they hold none."
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Names of the tags applied to the customer."
          }
        },
        "required": [
          "id",
          "email",
          "phone",
          "firstName",
          "lastName",
          "country",
          "birthday",
          "metadata",
          "notes",
          "emailOptOut",
          "emailOptOutAt",
          "emailOptOutSource",
          "createdAt",
          "updatedAt"
        ],
        "additionalProperties": false
      },
      "description": "The imported customers, as they now stand."
    },
    "skipped": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "index": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "Position of the row in the batch you sent."
          },
          "message": {
            "type": "string",
            "description": "Why the row could not be imported."
          }
        },
        "required": ["index", "message"],
        "additionalProperties": false
      },
      "description": "The rows that could not be imported, and why. A customer row references nothing, so this is always empty."
    }
  },
  "required": ["data", "skipped"],
  "additionalProperties": false
}

GET `/customers/{id}`

Get a single customer by ID.

Requires the customers:read permission.

Path Parameters

idstring (uuid)required

The ID of the customer.

Query Parameters

includestring

Request

curl \
  "https://api.cascade.dev/customers/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY"

Request

import { client } from "@cascade-commerce/api/admin/client"
import { getCustomersById } from "@cascade-commerce/api/admin"

client.setConfig({
  baseUrl: "https://api.cascade.dev",
  headers: { Authorization: "Bearer sk_YOUR_SECRET_KEY" },
})

const { data, error } = await getCustomersById({
  path: { id: "550e8400-e29b-41d4-a716-446655440000" },
})

Request

require "net/http"

uri = URI("https://api.cascade.dev/customers/550e8400-e29b-41d4-a716-446655440000")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer sk_YOUR_SECRET_KEY"

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body

Request

import json
from urllib.request import Request, urlopen

req = Request(
    "https://api.cascade.dev/customers/550e8400-e29b-41d4-a716-446655440000",
    headers={"Authorization": "Bearer sk_YOUR_SECRET_KEY"},
)
with urlopen(req) as res:
    print(json.load(res))

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "[email protected]",
  "phone": "string",
  "firstName": "string",
  "lastName": "string",
  "country": "string",
  "birthday": "string",
  "metadata": "...",
  "notes": "string",
  "emailOptOut": true,
  "emailOptOutAt": "2025-01-15T09:30:00Z",
  "emailOptOutSource": "customer",
  "createdAt": "2025-01-15T09:30:00Z",
  "updatedAt": "2025-01-15T09:30:00Z",
  "importJob": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "customers",
    "action": "created",
    "row": 0,
    "createdAt": "2025-01-15T09:30:00Z"
  },
  "ordersCount": 0,
  "reviewsCount": 0,
  "wishlistsCount": 0,
  "loyaltyPointsBalance": 0,
  "tags": ["string"]
}

Response schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "Unique identifier for the customer."
    },
    "email": {
      "type": "string",
      "format": "email",
      "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
      "description": "The customer's email address, unique within the organization."
    },
    "phone": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "The customer's phone number in E.164 format."
    },
    "firstName": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "The customer's first name."
    },
    "lastName": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "The customer's last name."
    },
    "country": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "The customer's country, as an ISO 3166-1 code."
    },
    "birthday": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^(?:(?:0[13578]|1[02])-(?:0[1-9]|[12][0-9]|3[01])|(?:0[469]|11)-(?:0[1-9]|[12][0-9]|30)|02-(?:0[1-9]|1[0-9]|2[0-9]))$",
          "description": "The customer's birthday as `MM-DD`. Month and day only: no year is collected or stored. February 29 is allowed, and in a year that has no February 29 it is treated as February 28."
        },
        {
          "type": "null"
        }
      ],
      "description": "The customer's birthday as `MM-DD`, or null when they have not given one. Month and day only: no year is collected or stored."
    },
    "metadata": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "string"
      },
      "description": "Free-form string key/value pairs for your own data. Individual keys are filterable with a dot path, for example `metadata.category`."
    },
    "notes": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Internal notes about the customer. Never shown to them."
    },
    "emailOptOut": {
      "type": "boolean",
      "description": "Whether the customer has opted out of marketing email. They still receive mail they asked for, such as a wishlist they shared themselves."
    },
    "emailOptOutAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
        },
        {
          "type": "null"
        }
      ],
      "description": "When the opt-out was recorded. Null while the customer is still subscribed."
    },
    "emailOptOutSource": {
      "anyOf": [
        {
          "type": "string",
          "enum": ["customer", "merchant", "import", "shopify"],
          "description": "Where the opt-out came from."
        },
        {
          "type": "null"
        }
      ],
      "description": "Where the opt-out came from: `customer` (they opted out themselves, through an unsubscribe link or your integration), `merchant`, `import` or `shopify`. Null while the customer is still subscribed."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the customer was first created in Cascade."
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the customer was last changed."
    },
    "importJob": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "format": "uuid",
              "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
              "description": "The import job that wrote the record."
            },
            "type": {
              "type": "string",
              "enum": [
                "customers",
                "products",
                "orders",
                "wishlists",
                "reviews",
                "loyalty-members"
              ],
              "description": "What that import's file contained."
            },
            "action": {
              "type": "string",
              "enum": ["created", "updated"],
              "description": "Whether the import created this record or updated one that was already there."
            },
            "row": {
              "anyOf": [
                {
                  "type": "integer",
                  "minimum": -9007199254740991,
                  "maximum": 9007199254740991
                },
                {
                  "type": "null"
                }
              ],
              "description": "The 1-based row in the import's CSV that became this record, where it is known."
            },
            "createdAt": {
              "type": "string",
              "format": "date-time",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
              "description": "When that import was started."
            }
          },
          "required": ["id", "type", "action", "row", "createdAt"],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ],
      "description": "The import that last wrote this record, or null when no import did."
    },
    "ordersCount": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "How many orders the customer has placed."
    },
    "reviewsCount": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "How many reviews the customer has written."
    },
    "wishlistsCount": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "How many wishlists the customer has."
    },
    "loyaltyPointsBalance": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "The customer's current loyalty points balance, or zero when they hold none."
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Names of the tags applied to the customer."
    }
  },
  "required": [
    "id",
    "email",
    "phone",
    "firstName",
    "lastName",
    "country",
    "birthday",
    "metadata",
    "notes",
    "emailOptOut",
    "emailOptOutAt",
    "emailOptOutSource",
    "createdAt",
    "updatedAt"
  ],
  "additionalProperties": false,
  "description": "The requested customer."
}

PATCH `/customers/{id}`

Update a customer's metadata, notes, tags, birthday or marketing email opt-out. Profile fields such as the email and name come from the store and cannot be edited here. Triggers the customer.updated webhook.

Requires the customers:write permission.

Path Parameters

idstring (uuid)required

The ID of the customer to update.

Body Parameters

metadataobject

Replaces the customer's metadata wholesale. Omit to leave it alone.

notesstring

Internal notes about the customer.

tagsstring[]

The customer's full set of tag names. Omit to leave the tags alone.

emailOptOutboolean

Set to true to stop sending the customer marketing email, false to opt them back in. Omit to leave it alone.

emailOptOutSourcecustomer | merchant | import | shopify

Where the opt-out came from. Defaults to merchant.

birthdaystring | null

The customer's birthday as MM-DD, such as 03-14. Send null to clear it, and omit it to leave it alone.

Request

curl \
  -X PATCH \
  "https://api.cascade.dev/customers/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "metadata": "...",
  "notes": "string",
  "tags": [
    "string"
  ],
  "emailOptOut": true,
  "emailOptOutSource": "customer",
  "birthday": "string"
}'

Request

import { client } from "@cascade-commerce/api/admin/client"
import { patchCustomersById } from "@cascade-commerce/api/admin"

client.setConfig({
  baseUrl: "https://api.cascade.dev",
  headers: { Authorization: "Bearer sk_YOUR_SECRET_KEY" },
})

const { data, error } = await patchCustomersById({
  path: { id: "550e8400-e29b-41d4-a716-446655440000" },
  body: {
    metadata: "...",
    notes: "string",
    tags: ["string"],
    emailOptOut: true,
    emailOptOutSource: "customer",
    birthday: "string",
  },
})

Request

require "net/http"

uri = URI("https://api.cascade.dev/customers/550e8400-e29b-41d4-a716-446655440000")
req = Net::HTTP::Patch.new(uri)
req["Authorization"] = "Bearer sk_YOUR_SECRET_KEY"
req["Content-Type"] = "application/json"
req.body = <<~JSON
  {
    "metadata": "...",
    "notes": "string",
    "tags": [
      "string"
    ],
    "emailOptOut": true,
    "emailOptOutSource": "customer",
    "birthday": "string"
  }
JSON

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body

Request

import json
from urllib.request import Request, urlopen

body = """{
  "metadata": "...",
  "notes": "string",
  "tags": [
    "string"
  ],
  "emailOptOut": true,
  "emailOptOutSource": "customer",
  "birthday": "string"
}"""

req = Request(
    "https://api.cascade.dev/customers/550e8400-e29b-41d4-a716-446655440000",
    data=body.encode(),
    method="PATCH",
    headers={
        "Authorization": "Bearer sk_YOUR_SECRET_KEY",
        "Content-Type": "application/json",
    },
)
with urlopen(req) as res:
    print(json.load(res))

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "[email protected]",
  "phone": "string",
  "firstName": "string",
  "lastName": "string",
  "country": "string",
  "birthday": "string",
  "metadata": "...",
  "notes": "string",
  "emailOptOut": true,
  "emailOptOutAt": "2025-01-15T09:30:00Z",
  "emailOptOutSource": "customer",
  "createdAt": "2025-01-15T09:30:00Z",
  "updatedAt": "2025-01-15T09:30:00Z",
  "importJob": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "customers",
    "action": "created",
    "row": 0,
    "createdAt": "2025-01-15T09:30:00Z"
  },
  "ordersCount": 0,
  "reviewsCount": 0,
  "wishlistsCount": 0,
  "loyaltyPointsBalance": 0,
  "tags": ["string"]
}

Response schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "Unique identifier for the customer."
    },
    "email": {
      "type": "string",
      "format": "email",
      "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
      "description": "The customer's email address, unique within the organization."
    },
    "phone": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "The customer's phone number in E.164 format."
    },
    "firstName": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "The customer's first name."
    },
    "lastName": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "The customer's last name."
    },
    "country": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "The customer's country, as an ISO 3166-1 code."
    },
    "birthday": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^(?:(?:0[13578]|1[02])-(?:0[1-9]|[12][0-9]|3[01])|(?:0[469]|11)-(?:0[1-9]|[12][0-9]|30)|02-(?:0[1-9]|1[0-9]|2[0-9]))$",
          "description": "The customer's birthday as `MM-DD`. Month and day only: no year is collected or stored. February 29 is allowed, and in a year that has no February 29 it is treated as February 28."
        },
        {
          "type": "null"
        }
      ],
      "description": "The customer's birthday as `MM-DD`, or null when they have not given one. Month and day only: no year is collected or stored."
    },
    "metadata": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "string"
      },
      "description": "Free-form string key/value pairs for your own data. Individual keys are filterable with a dot path, for example `metadata.category`."
    },
    "notes": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Internal notes about the customer. Never shown to them."
    },
    "emailOptOut": {
      "type": "boolean",
      "description": "Whether the customer has opted out of marketing email. They still receive mail they asked for, such as a wishlist they shared themselves."
    },
    "emailOptOutAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
        },
        {
          "type": "null"
        }
      ],
      "description": "When the opt-out was recorded. Null while the customer is still subscribed."
    },
    "emailOptOutSource": {
      "anyOf": [
        {
          "type": "string",
          "enum": ["customer", "merchant", "import", "shopify"],
          "description": "Where the opt-out came from."
        },
        {
          "type": "null"
        }
      ],
      "description": "Where the opt-out came from: `customer` (they opted out themselves, through an unsubscribe link or your integration), `merchant`, `import` or `shopify`. Null while the customer is still subscribed."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the customer was first created in Cascade."
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the customer was last changed."
    },
    "importJob": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "format": "uuid",
              "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
              "description": "The import job that wrote the record."
            },
            "type": {
              "type": "string",
              "enum": [
                "customers",
                "products",
                "orders",
                "wishlists",
                "reviews",
                "loyalty-members"
              ],
              "description": "What that import's file contained."
            },
            "action": {
              "type": "string",
              "enum": ["created", "updated"],
              "description": "Whether the import created this record or updated one that was already there."
            },
            "row": {
              "anyOf": [
                {
                  "type": "integer",
                  "minimum": -9007199254740991,
                  "maximum": 9007199254740991
                },
                {
                  "type": "null"
                }
              ],
              "description": "The 1-based row in the import's CSV that became this record, where it is known."
            },
            "createdAt": {
              "type": "string",
              "format": "date-time",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
              "description": "When that import was started."
            }
          },
          "required": ["id", "type", "action", "row", "createdAt"],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ],
      "description": "The import that last wrote this record, or null when no import did."
    },
    "ordersCount": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "How many orders the customer has placed."
    },
    "reviewsCount": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "How many reviews the customer has written."
    },
    "wishlistsCount": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "How many wishlists the customer has."
    },
    "loyaltyPointsBalance": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "The customer's current loyalty points balance, or zero when they hold none."
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Names of the tags applied to the customer."
    }
  },
  "required": [
    "id",
    "email",
    "phone",
    "firstName",
    "lastName",
    "country",
    "birthday",
    "metadata",
    "notes",
    "emailOptOut",
    "emailOptOutAt",
    "emailOptOutSource",
    "createdAt",
    "updatedAt"
  ],
  "additionalProperties": false,
  "description": "The updated customer."
}

DELETE `/customers/{id}`

Delete a customer along with their orders, loyalty memberships, referrals and tags. Their reviews are kept but unlinked and unpublished, unless the organization has cascadeDeleteReviews turned on. Triggers the customer.deleted webhook.

Requires the customers:write permission.

Path Parameters

idstring (uuid)required

The ID of the customer to delete.

Request

curl \
  -X DELETE \
  "https://api.cascade.dev/customers/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY"

Request

import { client } from "@cascade-commerce/api/admin/client"
import { deleteCustomersById } from "@cascade-commerce/api/admin"

client.setConfig({
  baseUrl: "https://api.cascade.dev",
  headers: { Authorization: "Bearer sk_YOUR_SECRET_KEY" },
})

const { data, error } = await deleteCustomersById({
  path: { id: "550e8400-e29b-41d4-a716-446655440000" },
})

Request

require "net/http"

uri = URI("https://api.cascade.dev/customers/550e8400-e29b-41d4-a716-446655440000")
req = Net::HTTP::Delete.new(uri)
req["Authorization"] = "Bearer sk_YOUR_SECRET_KEY"

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body

Request

import json
from urllib.request import Request, urlopen

req = Request(
    "https://api.cascade.dev/customers/550e8400-e29b-41d4-a716-446655440000",
    method="DELETE",
    headers={"Authorization": "Bearer sk_YOUR_SECRET_KEY"},
)
with urlopen(req) as res:
    print(json.load(res))

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "[email protected]",
  "phone": "string",
  "firstName": "string",
  "lastName": "string",
  "country": "string",
  "birthday": "string",
  "metadata": "...",
  "notes": "string",
  "emailOptOut": true,
  "emailOptOutAt": "2025-01-15T09:30:00Z",
  "emailOptOutSource": "customer",
  "createdAt": "2025-01-15T09:30:00Z",
  "updatedAt": "2025-01-15T09:30:00Z",
  "importJob": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "customers",
    "action": "created",
    "row": 0,
    "createdAt": "2025-01-15T09:30:00Z"
  },
  "ordersCount": 0,
  "reviewsCount": 0,
  "wishlistsCount": 0,
  "loyaltyPointsBalance": 0,
  "tags": ["string"]
}

Response schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "Unique identifier for the customer."
    },
    "email": {
      "type": "string",
      "format": "email",
      "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
      "description": "The customer's email address, unique within the organization."
    },
    "phone": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "The customer's phone number in E.164 format."
    },
    "firstName": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "The customer's first name."
    },
    "lastName": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "The customer's last name."
    },
    "country": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "The customer's country, as an ISO 3166-1 code."
    },
    "birthday": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^(?:(?:0[13578]|1[02])-(?:0[1-9]|[12][0-9]|3[01])|(?:0[469]|11)-(?:0[1-9]|[12][0-9]|30)|02-(?:0[1-9]|1[0-9]|2[0-9]))$",
          "description": "The customer's birthday as `MM-DD`. Month and day only: no year is collected or stored. February 29 is allowed, and in a year that has no February 29 it is treated as February 28."
        },
        {
          "type": "null"
        }
      ],
      "description": "The customer's birthday as `MM-DD`, or null when they have not given one. Month and day only: no year is collected or stored."
    },
    "metadata": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "string"
      },
      "description": "Free-form string key/value pairs for your own data. Individual keys are filterable with a dot path, for example `metadata.category`."
    },
    "notes": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Internal notes about the customer. Never shown to them."
    },
    "emailOptOut": {
      "type": "boolean",
      "description": "Whether the customer has opted out of marketing email. They still receive mail they asked for, such as a wishlist they shared themselves."
    },
    "emailOptOutAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
        },
        {
          "type": "null"
        }
      ],
      "description": "When the opt-out was recorded. Null while the customer is still subscribed."
    },
    "emailOptOutSource": {
      "anyOf": [
        {
          "type": "string",
          "enum": ["customer", "merchant", "import", "shopify"],
          "description": "Where the opt-out came from."
        },
        {
          "type": "null"
        }
      ],
      "description": "Where the opt-out came from: `customer` (they opted out themselves, through an unsubscribe link or your integration), `merchant`, `import` or `shopify`. Null while the customer is still subscribed."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the customer was first created in Cascade."
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the customer was last changed."
    },
    "importJob": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "format": "uuid",
              "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
              "description": "The import job that wrote the record."
            },
            "type": {
              "type": "string",
              "enum": [
                "customers",
                "products",
                "orders",
                "wishlists",
                "reviews",
                "loyalty-members"
              ],
              "description": "What that import's file contained."
            },
            "action": {
              "type": "string",
              "enum": ["created", "updated"],
              "description": "Whether the import created this record or updated one that was already there."
            },
            "row": {
              "anyOf": [
                {
                  "type": "integer",
                  "minimum": -9007199254740991,
                  "maximum": 9007199254740991
                },
                {
                  "type": "null"
                }
              ],
              "description": "The 1-based row in the import's CSV that became this record, where it is known."
            },
            "createdAt": {
              "type": "string",
              "format": "date-time",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
              "description": "When that import was started."
            }
          },
          "required": ["id", "type", "action", "row", "createdAt"],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ],
      "description": "The import that last wrote this record, or null when no import did."
    },
    "ordersCount": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "How many orders the customer has placed."
    },
    "reviewsCount": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "How many reviews the customer has written."
    },
    "wishlistsCount": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "How many wishlists the customer has."
    },
    "loyaltyPointsBalance": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "The customer's current loyalty points balance, or zero when they hold none."
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Names of the tags applied to the customer."
    }
  },
  "required": [
    "id",
    "email",
    "phone",
    "firstName",
    "lastName",
    "country",
    "birthday",
    "metadata",
    "notes",
    "emailOptOut",
    "emailOptOutAt",
    "emailOptOutSource",
    "createdAt",
    "updatedAt"
  ],
  "additionalProperties": false,
  "description": "The deleted customer."
}

#Customers

GET /customers

Query Parameters

PATCH /customers/bulk-update

Query Parameters

Body Parameters

POST /customers/import

Body Parameters

GET /customers/{id}

Path Parameters

Query Parameters

PATCH /customers/{id}

Path Parameters

Body Parameters

DELETE /customers/{id}

Path Parameters

Customers

GET `/customers`

PATCH `/customers/bulk-update`

POST `/customers/import`

GET `/customers/{id}`

PATCH `/customers/{id}`

DELETE `/customers/{id}`