TallyPip
Start free

API reference

Customer

Someone the business sells to. Invoices and payments belong to a customer.

The customer object

object string
Always "customer".
id id
The customer's id (a UUID). Use it to fetch it, or to refer to it from other things.
name string
The display name: what invoices, bills and lists show.
company_name string or null
The company's name, when different.
title string or null
Mr., Ms., Dr.…
first_name string or null
First name of the person to deal with.
middle_name string or null
Middle name.
last_name string or null
Last name.
suffix string or null
Jr., Sr.…
email string or null
Email address (where invoices or remittances go).
cc string or null
More addresses copied on emails, separated by commas.
bcc string or null
Addresses blind-copied on emails.
phone string or null
Phone.
mobile string or null
Mobile.
fax string or null
Fax.
website string or null
Website.
address string or null
Billing address; lines separated by \n.
terms string or null
Usual payment terms: due_on_receipt, net_7, net_15, net_30 or net_60.
notes string or null
Private notes.
active boolean
False once it's made inactive in TallyPip (it's kept, with its history, but left out of pickers).
created_at timestamp
When it was added, in UTC.
currency string or null
Their currency when it isn't the business's (Multicurrency, like EUR): their invoices and open balance are in it. Null otherwise.
shipping_address string or null
Where goods go, if different from the address.
payment_method string or null
How they usually pay.
delivery_method string or null
How they like invoices: print or email.
tax_exempt boolean
True if they don't pay sales tax.
tax_exempt_reason string or null
Why they're exempt.
parent_id string or null
A sub-customer's parent customer (a job, location or department under it). Null at the top.
bill_with_parent boolean
True when the parent pays this sub-customer's invoices (its statement and payments include them).
open_balance_cents integer
What they owe on sent invoices now, in cents.

Example

{
  "object": "customer",
  "id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708101",
  "name": "Oak Street Dental",
  "company_name": "Oak Street Dental LLC",
  "title": null,
  "first_name": "Robin",
  "middle_name": null,
  "last_name": "Shah",
  "suffix": null,
  "email": "accounts@oakstreetdental.example",
  "cc": null,
  "bcc": null,
  "phone": "(555) 010-2299",
  "mobile": null,
  "fax": null,
  "website": null,
  "address": "12 Oak Street\nSpringfield, IL 62701",
  "terms": "net_30",
  "notes": null,
  "active": true,
  "created_at": "2026-10-06T14:30:00.000Z",
  "currency": null,
  "shipping_address": null,
  "payment_method": null,
  "delivery_method": "email",
  "tax_exempt": false,
  "tax_exempt_reason": null,
  "parent_id": null,
  "bill_with_parent": false,
  "open_balance_cents": 24000
}

List customers

GET /api/v1/customers

Customers, newest first, with what each owes on sent invoices.

Key: any (Read only works).

Query

limit integer
How many, 1 to 100 (default 25).
starting_after id
The last id of the page before, for the next page (when has_more is true).
filters
email, name (exact, ignoring capitals: to find one before adding it)

Newest first. Answers a list: { object: "list", url, has_more, data }.

Request

curl https://tallypip.com/api/v1/customers?limit=3 \
  -H "Authorization: Bearer tpk_your_key"

Answer: 200

{
  "object": "list",
  "url": "/api/v1/customers",
  "has_more": false,
  "data": [
    {
      "object": "customer",
      "id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708101",
      "name": "Oak Street Dental",
      "company_name": "Oak Street Dental LLC",
      "title": null,
      "first_name": "Robin",
      "middle_name": null,
      "last_name": "Shah",
      "suffix": null,
      "email": "accounts@oakstreetdental.example",
      "cc": null,
      "bcc": null,
      "phone": "(555) 010-2299",
      "mobile": null,
      "fax": null,
      "website": null,
      "address": "12 Oak Street\nSpringfield, IL 62701",
      "terms": "net_30",
      "notes": null,
      "active": true,
      "created_at": "2026-10-06T14:30:00.000Z",
      "currency": null,
      "shipping_address": null,
      "payment_method": null,
      "delivery_method": "email",
      "tax_exempt": false,
      "tax_exempt_reason": null,
      "parent_id": null,
      "bill_with_parent": false,
      "open_balance_cents": 24000
    }
  ]
}

Try it

With your own key (Settings › Connected apps). It stays in this page only, and reading can't change anything.

Create a customer

POST /api/v1/customers

Add a customer.

Key: Read and change.

Body (JSON)

name string
Required. The name shown on invoices.
email, phone, mobile, fax, website string
Optional contact details.
company_name, title, first_name, middle_name, last_name, suffix string
Optional.
cc, bcc string
Extra addresses for emailed invoices.
address, shipping_address string
Optional. Lines separated by \n.
terms string
due_on_receipt, net_7, net_15, net_30 or net_60.
payment_method, delivery_method, notes string
Optional.
tax_exempt, tax_exempt_reason boolean, string
Optional.
parent_id, bill_with_parent string, boolean
Optional. Makes it a sub-customer of that customer (same currency, up to 5 levels); bill_with_parent: the parent pays its invoices.

Answers 201 with the new customer. Refused with 400 and the reason (nothing is saved); send an Idempotency-Key so a retry can't make it twice.

Request

curl https://tallypip.com/api/v1/customers \
  -H "Authorization: Bearer tpk_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <a new id for each change>" \
  -d '{
    "name": "Oak Street Dental",
    "email": "accounts@oakstreetdental.example",
    "phone": "(555) 010-2299",
    "terms": "net_30"
  }'

Answer: 201

{
  "object": "customer",
  "id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708101",
  "name": "Oak Street Dental",
  "company_name": "Oak Street Dental LLC",
  "title": null,
  "first_name": "Robin",
  "middle_name": null,
  "last_name": "Shah",
  "suffix": null,
  "email": "accounts@oakstreetdental.example",
  "cc": null,
  "bcc": null,
  "phone": "(555) 010-2299",
  "mobile": null,
  "fax": null,
  "website": null,
  "address": "12 Oak Street\nSpringfield, IL 62701",
  "terms": "net_30",
  "notes": null,
  "active": true,
  "created_at": "2026-10-06T14:30:00.000Z",
  "currency": null,
  "shipping_address": null,
  "payment_method": null,
  "delivery_method": "email",
  "tax_exempt": false,
  "tax_exempt_reason": null,
  "parent_id": null,
  "bill_with_parent": false,
  "open_balance_cents": 24000
}

Retrieve a customer

GET /api/v1/customers/{id}

One customer.

Key: any (Read only works).

Request

curl https://tallypip.com/api/v1/customers/3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708101 \
  -H "Authorization: Bearer tpk_your_key"

Answer: 200

{
  "object": "customer",
  "id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708101",
  "name": "Oak Street Dental",
  "company_name": "Oak Street Dental LLC",
  "title": null,
  "first_name": "Robin",
  "middle_name": null,
  "last_name": "Shah",
  "suffix": null,
  "email": "accounts@oakstreetdental.example",
  "cc": null,
  "bcc": null,
  "phone": "(555) 010-2299",
  "mobile": null,
  "fax": null,
  "website": null,
  "address": "12 Oak Street\nSpringfield, IL 62701",
  "terms": "net_30",
  "notes": null,
  "active": true,
  "created_at": "2026-10-06T14:30:00.000Z",
  "currency": null,
  "shipping_address": null,
  "payment_method": null,
  "delivery_method": "email",
  "tax_exempt": false,
  "tax_exempt_reason": null,
  "parent_id": null,
  "bill_with_parent": false,
  "open_balance_cents": 24000
}

Try it

With your own key (Settings › Connected apps). It stays in this page only, and reading can't change anything.