Create invoice - Tyms Developer API

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

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.