Create invoice

curl --request POST \ --url https://staging-api.usetyms.com/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" } ] }

Authorizations

X-API-Key

string

header

default:your_tyms_sk_or_partner_key

required

Business secret tyms_sk_... for business-scoped routes. Partner secret for register-business and referred-business distributor routes.

Body

application/json

date

string<date>

required

Invoice date.

document_due

string<date>

required

Due date. Alias: due_date.

currency

string

required

Currency code, e.g. NGN.

items

object[]

required

Line items. Document total is computed from here.

Minimum array length: 1

Hide child attributes

items.item_name

string

required

Line label. Alias: name.

items.quantity

number

required

Quantity sold or purchased.

items.selling_price

number

required

Unit price. On bills this is unit cost. Alias: price.

items.category

string

required

Required. Revenue, expense, or inventory account — name, uuid, or account code.

items.description

string

Optional line description.

items.tax

number

Tax rate as a percentage (e.g. 7.5 = 7.5%). Preferred over tax_uuid.

items.tax_uuid

string

Optional tax record uuid instead of tax percentage.

items.withholding_tax

number

Withholding tax (WHT) rate as a percentage.

items.withholding_tax_uuid

string

Optional WHT uuid instead of withholding_tax percentage.

items.discount

number

Line discount value.

items.discount_type

enum<string>

percent or amount / fixed.

Available options:

percent,

amount,

fixed

items.is_inventory

boolean

true if the line affects stock.

items.uuid

string

Existing inventory item uuid when linking stock.

customer

string

Contact uuid, name, or email. Aliases: contact, contact_uuid, vendor.

document_number

string

Invoice number. Auto-suggested if omitted.

narration

string

Document title. Alias: title.

memo

string

Internal note. Alias: note.

document_note

string

Note printed on the invoice.

status

string

Default pending. Use draft to save without posting.

exchange_rate

number

Default 1.

shipping_fee

number

Shipping amount added to the invoice.

receivable_account

string

Accounts receivable control account — name, uuid, or code.

amount_paid

number

Payment collected on create. 0 or omit for unpaid.

payment_category

string

Cash or bank account name when recording payment on create. Aliases: paid_through, payment_account.

Response

Invoice created

status

string

required

Example:

"success"

message

string

required

data

any

Single resource, array of resources, statement sections, or async job metadata — see each operation's example.

Overview

Authentication

OAuth

Chart of accounts

Invoices

Bills

Expenses

Income

Journals

Contacts

Banks

Bank transactions

Inventory

Fixed Assets

Quotes

Purchase Orders

Departments

Projects

Branches

Reports

Distribution Partners

Authorizations

Body

Response