curl --request POST \
--url https://staging-api.tyms.io/v1/adam/create/invoice \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"date": "2026-03-01",
"document_due": "2026-03-15",
"currency": "NGN",
"document_number": "INV-1042",
"narration": "Website design services — March",
"customer": "a1b2c3d4e5f6478990a1b2c3d4e5f678",
"status": "pending",
"amount_paid": 0,
"items": [
{
"item_name": "UI/UX design",
"quantity": 1,
"selling_price": 100000,
"category": "Design Income",
"tax": 7.5
},
{
"item_name": "Implementation support",
"quantity": 1,
"selling_price": 50000,
"category": "Service Income",
"tax": 7.5,
"discount": 5,
"discount_type": "percent"
}
]
}
'{
"status": "success",
"message": "Invoice imported successfully.",
"data": [
{
"uuid": "c4d5e6f7a8b9401a9c2d3e4f5a6b7c8d",
"transaction_type": "invoice",
"status": "pending",
"document_number": "INV-1042"
}
]
}{
"status": "failed",
"message": "<string>"
}Create invoice
curl --request POST \
--url https://staging-api.tyms.io/v1/adam/create/invoice \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"date": "2026-03-01",
"document_due": "2026-03-15",
"currency": "NGN",
"document_number": "INV-1042",
"narration": "Website design services — March",
"customer": "a1b2c3d4e5f6478990a1b2c3d4e5f678",
"status": "pending",
"amount_paid": 0,
"items": [
{
"item_name": "UI/UX design",
"quantity": 1,
"selling_price": 100000,
"category": "Design Income",
"tax": 7.5
},
{
"item_name": "Implementation support",
"quantity": 1,
"selling_price": 50000,
"category": "Service Income",
"tax": 7.5,
"discount": 5,
"discount_type": "percent"
}
]
}
'{
"status": "success",
"message": "Invoice imported successfully.",
"data": [
{
"uuid": "c4d5e6f7a8b9401a9c2d3e4f5a6b7c8d",
"transaction_type": "invoice",
"status": "pending",
"document_number": "INV-1042"
}
]
}{
"status": "failed",
"message": "<string>"
}Authorizations
Business secret tyms_sk_... for business-scoped routes. Partner secret for register-business and referred-business distributor routes.
Body
Invoice date.
Due date. Alias: due_date.
Currency code, e.g. NGN.
Line items. Document total is computed from here.
1Hide child attributes
Hide child attributes
Line label. Alias: name.
Quantity sold or purchased.
Unit price. On bills this is unit cost. Alias: price.
Required. Revenue, expense, or inventory account — name, uuid, or account code.
Optional line description.
Tax rate as a percentage (e.g. 7.5 = 7.5%). Preferred over tax_uuid.
Optional tax record uuid instead of tax percentage.
Withholding tax (WHT) rate as a percentage.
Optional WHT uuid instead of withholding_tax percentage.
Line discount value.
percent or amount / fixed.
percent, amount, fixed true if the line affects stock.
Existing inventory item uuid when linking stock.
Contact uuid, name, or email. Aliases: contact, contact_uuid, vendor.
Invoice number. Auto-suggested if omitted.
Document title. Alias: title.
Internal note. Alias: note.
Note printed on the invoice.
Default pending. Use draft to save without posting.
Default 1.
Shipping amount added to the invoice.
Accounts receivable control account — name, uuid, or code.
Payment collected on create. 0 or omit for unpaid.
Cash or bank account name when recording payment on create. Aliases: paid_through, payment_account.
Branch id. Same as branch_uuid. Leave both off to use the business default branch. A name is not accepted, and a new branch is not created. An id that is not one of your branches is still saved, but it will not show under a location in reports.
Branch id from GET /branches. Alias: branch.
Department id. Same as department_uuid. An unknown id is saved as sent and does not create a department. To add one from a name, send department_name and leave this off.
Department id from GET /departments. Alias: department.
Department name. Capitalization does not matter. If no department has that name, Tyms adds one and tags this document with it. Ignored when department or department_uuid is set.
Project id from GET /projects. An unknown id is saved as sent and does not create a project. To add one from a name, send project_name and leave this off.
Project name, matched exactly, including capital letters. If no project has that name, Tyms adds an active project that starts today and ends in one month, then tags this document with it. Ignored when project_uuid is set.
Team member id. Same as employee_uuid. An unknown id is saved as sent and does not add a person. To add one from a name, send employee_name and leave this off.
Team member id. Alias: employee.
Full name of the team member. If nobody matches, Tyms adds them. Ignored when employee or employee_uuid is set.
Response
Invoice created