Customers API

Manage customer (buyer) records used in managed invoices. When creating a managed invoice, you reference a customer by ID to populate the buyer details.

Create Customer

POST /api/v1/customers

Request:

{
  "name": "Jane Smith",
  "email": "jane@example.com",
  "phone": "+1-555-987-6543",
  "tax_id": "US-EIN-98-7654321",
  "billing_address": {
    "line1": "42 Oak Ave",
    "city": "Portland",
    "state": "OR",
    "postal_code": "97201",
    "country": "US"
  },
  "shipping_address": {
    "line1": "99 Dock Rd",
    "city": "Portland",
    "state": "OR",
    "postal_code": "97201",
    "country": "US"
  },
  "metadata": {
    "internal_id": "CRM-12345",
    "segment": "enterprise"
  }
}

Field	Required	Description
name	Yes	Customer display name
email	No	Contact email
phone	No	Contact phone number
tax_id	No	Tax identification number
billing_address	No	Primary billing address
shipping_address	No	Shipping address (if different from billing)
metadata	No	Arbitrary key-value pairs for your use

Response:

{
  "data": {
    "id": "cus_01XYZ",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "phone": "+1-555-987-6543",
    "tax_id": "US-EIN-98-7654321",
    "billing_address": {
      "line1": "42 Oak Ave",
      "city": "Portland",
      "state": "OR",
      "postal_code": "97201",
      "country": "US"
    },
    "shipping_address": {
      "line1": "99 Dock Rd",
      "city": "Portland",
      "state": "OR",
      "postal_code": "97201",
      "country": "US"
    },
    "metadata": {
      "internal_id": "CRM-12345",
      "segment": "enterprise"
    },
    "created_at": "2026-07-20T10:00:00Z",
    "updated_at": "2026-07-20T10:00:00Z"
  }
}

Try it

List Customers

GET /api/v1/customers?limit=25

Response:

{
  "data": [
    {
      "id": "cus_01XYZ",
      "name": "Jane Smith",
      "email": "jane@example.com",
      "created_at": "2026-07-20T10:00:00Z",
      "updated_at": "2026-07-20T10:00:00Z"
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null
  }
}

Try it

Get Customer

GET /api/v1/customers/{id}

Fetch a single customer by ID, including full billing/shipping addresses and metadata. Returns 404 not_found if the customer doesn't exist.

Response:

{
  "data": {
    "id": "cus_01XYZ",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "phone": "+1-555-987-6543",
    "tax_id": "US-EIN-98-7654321",
    "billing_address": {
      "line1": "42 Oak Ave", "city": "Portland", "state": "OR",
      "postal_code": "97201", "country": "US"
    },
    "shipping_address": {
      "line1": "99 Dock Rd", "city": "Portland", "state": "OR",
      "postal_code": "97201", "country": "US"
    },
    "metadata": { "internal_id": "CRM-12345", "segment": "enterprise" },
    "created_at": "2026-07-20T10:00:00Z",
    "updated_at": "2026-07-20T10:00:00Z"
  }
}

Try it

Update Customer

PATCH /api/v1/customers/{id}

Only include the fields you want to change:

{
  "email": "jane.smith@newdomain.com",
  "metadata": {
    "internal_id": "CRM-12345",
    "segment": "enterprise",
    "tier": "gold"
  }
}

Note

metadata is replaced entirely on update, not merged. Include all key-value pairs you want to keep.

Try it

Delete Customer

DELETE /api/v1/customers/{id}

Response:

{
  "data": {
    "deleted": true
  }
}

Try it