Customers
Manage customer records for invoicing and receipt generation.
Customers represent the businesses or individuals you invoice. Store customer details including tax identification numbers (TIN) for ZIMRA compliance.
The Customer Object
The customer object contains contact information, tax identifiers, and billing address details.
{
"id": "cust_xyz789",
"name": "Acme Corporation",
"email": "billing@acme.com",
"phone": "+263771234567",
"tin": "123456789",
"vat_number": "VAT123456",
"address": {
"line1": "123 Main Street",
"line2": "Suite 100",
"city": "Harare",
"state": "Harare",
"postal_code": "00263",
"country": "ZW"
},
"metadata": {
"industry": "technology",
"account_manager": "john.doe"
},
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-15T10:30:00Z"
}
Required Fields for ZIMRA
For invoices submitted to ZIMRA, the following customer fields are required:
- name - The customer's legal business name
- tin - Tax Identification Number for B2B transactions
- address - At least city and country are required
Create a Customer
Create a new customer record. The customer can then be referenced when creating invoices and receipts.
/v1/customersCreates a new customer.
Request Body
namestring required The customer's name or business name.
Example: Acme Corporation
emailstringPrimary email address for invoices.
Example: billing@acme.com
phonestringContact phone number.
Example: +263771234567
tinstringTax Identification Number. Required for B2B invoices.
Example: 123456789
vat_numberstringVAT registration number if different from TIN.
addressobjectCustomer's billing address.
metadataobjectCustom key-value pairs for additional data.
Example Request
{
"name": "Acme Corporation",
"email": "billing@acme.com",
"phone": "+263771234567",
"tin": "123456789",
"vat_number": "VAT123456",
"address": {
"line1": "123 Main Street",
"line2": "Suite 100",
"city": "Harare",
"state": "Harare",
"postal_code": "00263",
"country": "ZW"
}
}
Response
{
"id": "cust_xyz789",
"name": "Acme Corporation",
"email": "billing@acme.com",
"phone": "+263771234567",
"tin": "123456789",
"vat_number": "VAT123456",
"address": {
"line1": "123 Main Street",
"line2": "Suite 100",
"city": "Harare",
"state": "Harare",
"postal_code": "00263",
"country": "ZW"
},
"metadata": {
"industry": "technology",
"account_manager": "john.doe"
},
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-15T10:30:00Z"
}
List Customers
Retrieve a paginated list of customers. Search by name, email, or TIN.
/v1/customersReturns a paginated list of customers.
Query Parameters
searchstringSearch by name, email, or TIN.
pageinteger default: 1Page number for pagination.
per_pageinteger default: 20Number of items per page (max 100).
Response
{
"data": [
{
"id": "cust_xyz789",
"name": "Acme Corporation",
"email": "billing@acme.com",
"tin": "123456789"
},
{
"id": "cust_abc123",
"name": "TechStart Inc",
"email": "accounts@techstart.co.zw",
"tin": "987654321"
}
],
"meta": {
"current_page": 1,
"per_page": 20,
"total": 234
}
}
Update a Customer
Update an existing customer. Only the fields you include will be updated. Nested objects like address are merged with existing data.
/v1/customers/{customer_id}Updates the specified customer.
Path Parameters
customer_idstring required The unique identifier of the customer.
Example: cust_xyz789
Example Request
{
"email": "finance@acme.com",
"address": {
"line1": "456 Business Park",
"city": "Harare"
}
}
Response
{
"id": "cust_xyz789",
"name": "Acme Corporation",
"email": "billing@acme.com",
"phone": "+263771234567",
"tin": "123456789",
"vat_number": "VAT123456",
"address": {
"line1": "123 Main Street",
"line2": "Suite 100",
"city": "Harare",
"state": "Harare",
"postal_code": "00263",
"country": "ZW"
},
"metadata": {
"industry": "technology",
"account_manager": "john.doe"
},
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-15T10:30:00Z"
}