TagPayTagPay

API Reference

Customers

A Customer is a long-lived record of someone who buys from you. You don't need to create one to take a charge — TagPay can match by email — but explicit customer records unlock subscriptions, loyalty workflows, and richer reconciliation in the dashboard.

Create a customer

POST/v1/customers

Email is the only required field — every customer is uniquely identified by email per merchant. Re-creating with the same email returns the existing record.

Body parameters

emailstringrequired

Customer email. Must be unique within your merchant account.

first_namestringoptional

Given name.

last_namestringoptional

Family name.

phonestringoptional

Phone in E.164 format, e.g. +2348012345678.

metadataobjectoptional

Arbitrary key/value pairs (max 20 keys, values up to 500 chars).

Response

200
idstring

TagPay-assigned customer ID, prefixed with `cus_`.

emailstring

Customer email.

first_namestring | null

Given name, or null.

last_namestring | null

Family name, or null.

phonestring | null

Phone number, or null.

created_atstring

ISO-8601 creation timestamp.

total_chargesinteger

Lifetime count of successful charges by this customer.

total_spendinteger

Lifetime sum of successful charge amounts in kobo.

Errors

INVALID_EMAIL400Email is required and must be valid.
EMAIL_EXISTS409A customer with this email already exists. Use retrieve or update instead.
UNAUTHORIZED401API key missing or invalid.

List customers

GET/v1/customers

Returns customers in reverse-chronological order of creation.

Query parameters

emailstringoptional

Filter to a specific email. Returns 0 or 1 results.

pageintegeroptional

Page number, 1-indexed.

per_pageintegeroptional

Results per page, max 100. Default 20.

Response

200
dataarray<Customer>

Array of customer objects.

metaobject

Pagination metadata.

totalinteger

Total matching records.

pageinteger

Current page.

per_pageinteger

Per-page count.

Retrieve a customer

GET/v1/customers/:id

Returns the full customer resource including aggregate totals.

Path parameters

idstringrequired

Customer ID, prefixed with cus_.

Response

200
idstring

Customer ID.

emailstring

Email.

first_namestring | null

Given name.

last_namestring | null

Family name.

phonestring | null

Phone.

created_atstring

ISO-8601 timestamp.

total_chargesinteger

Lifetime successful charge count.

total_spendinteger

Lifetime spend in kobo.

Errors

NOT_FOUND404No customer with that ID.

Update a customer

PUT/v1/customers/:id

Send only the fields you want to change. Email can be updated but must remain unique within your merchant account.

Path parameters

idstringrequired

Customer ID.

Body parameters

emailstringoptional

New email. Must be unique.

first_namestringoptional

New given name.

last_namestringoptional

New family name.

phonestringoptional

New phone in E.164 format.

metadataobjectoptional

Replaces stored metadata entirely.

Response

200
idstring

Customer ID.

emailstring

Updated email.

first_namestring | null

Updated given name.

last_namestring | null

Updated family name.

phonestring | null

Updated phone.

Errors

NOT_FOUND404No customer with that ID.
EMAIL_EXISTS409Another customer already uses that email.