Create bill - Tyms Developer API

Create bill

curl --request POST \
  --url https://staging-api.usetyms.com/v1/adam/create/bill \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "date": "2026-03-02",
  "document_due": "2026-03-16",
  "currency": "NGN",
  "document_number": "BILL-550",
  "narration": "Office supplies — Q1 restock",
  "customer": "v8e7d6c5b4a3418290f0e9d8c7b6a5947",
  "payment_category": "Petty Cash",
  "amount_paid": 42000,
  "items": [
    {
      "item_name": "Printer paper A4",
      "quantity": 10,
      "selling_price": 3200,
      "category": "Office Supplies",
      "tax": 0
    },
    {
      "item_name": "Toner cartridge",
      "quantity": 1,
      "selling_price": 10000,
      "category": "Office Supplies"
    }
  ]
}
'

import requests

url = "https://staging-api.usetyms.com/v1/adam/create/bill"

payload = {
    "date": "2026-03-02",
    "document_due": "2026-03-16",
    "currency": "NGN",
    "document_number": "BILL-550",
    "narration": "Office supplies — Q1 restock",
    "customer": "v8e7d6c5b4a3418290f0e9d8c7b6a5947",
    "payment_category": "Petty Cash",
    "amount_paid": 42000,
    "items": [
        {
            "item_name": "Printer paper A4",
            "quantity": 10,
            "selling_price": 3200,
            "category": "Office Supplies",
            "tax": 0
        },
        {
            "item_name": "Toner cartridge",
            "quantity": 1,
            "selling_price": 10000,
            "category": "Office Supplies"
        }
    ]
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    date: '2026-03-02',
    document_due: '2026-03-16',
    currency: 'NGN',
    document_number: 'BILL-550',
    narration: 'Office supplies — Q1 restock',
    customer: 'v8e7d6c5b4a3418290f0e9d8c7b6a5947',
    payment_category: 'Petty Cash',
    amount_paid: 42000,
    items: [
      {
        item_name: 'Printer paper A4',
        quantity: 10,
        selling_price: 3200,
        category: 'Office Supplies',
        tax: 0
      },
      {
        item_name: 'Toner cartridge',
        quantity: 1,
        selling_price: 10000,
        category: 'Office Supplies'
      }
    ]
  })
};

fetch('https://staging-api.usetyms.com/v1/adam/create/bill', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "status": "success",
  "message": "Bill imported successfully.",
  "data": [
    {
      "uuid": "b5c6d7e8f9a0418290a1b2c3d4e5f6b7",
      "transaction_type": "bills",
      "status": "pending",
      "document_number": "BILL-550"
    }
  ]
}

{
  "status": "failed",
  "message": "<string>"
}

POST

create

bill

Create bill

curl --request POST \
  --url https://staging-api.usetyms.com/v1/adam/create/bill \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "date": "2026-03-02",
  "document_due": "2026-03-16",
  "currency": "NGN",
  "document_number": "BILL-550",
  "narration": "Office supplies — Q1 restock",
  "customer": "v8e7d6c5b4a3418290f0e9d8c7b6a5947",
  "payment_category": "Petty Cash",
  "amount_paid": 42000,
  "items": [
    {
      "item_name": "Printer paper A4",
      "quantity": 10,
      "selling_price": 3200,
      "category": "Office Supplies",
      "tax": 0
    },
    {
      "item_name": "Toner cartridge",
      "quantity": 1,
      "selling_price": 10000,
      "category": "Office Supplies"
    }
  ]
}
'

import requests

url = "https://staging-api.usetyms.com/v1/adam/create/bill"

payload = {
    "date": "2026-03-02",
    "document_due": "2026-03-16",
    "currency": "NGN",
    "document_number": "BILL-550",
    "narration": "Office supplies — Q1 restock",
    "customer": "v8e7d6c5b4a3418290f0e9d8c7b6a5947",
    "payment_category": "Petty Cash",
    "amount_paid": 42000,
    "items": [
        {
            "item_name": "Printer paper A4",
            "quantity": 10,
            "selling_price": 3200,
            "category": "Office Supplies",
            "tax": 0
        },
        {
            "item_name": "Toner cartridge",
            "quantity": 1,
            "selling_price": 10000,
            "category": "Office Supplies"
        }
    ]
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    date: '2026-03-02',
    document_due: '2026-03-16',
    currency: 'NGN',
    document_number: 'BILL-550',
    narration: 'Office supplies — Q1 restock',
    customer: 'v8e7d6c5b4a3418290f0e9d8c7b6a5947',
    payment_category: 'Petty Cash',
    amount_paid: 42000,
    items: [
      {
        item_name: 'Printer paper A4',
        quantity: 10,
        selling_price: 3200,
        category: 'Office Supplies',
        tax: 0
      },
      {
        item_name: 'Toner cartridge',
        quantity: 1,
        selling_price: 10000,
        category: 'Office Supplies'
      }
    ]
  })
};

fetch('https://staging-api.usetyms.com/v1/adam/create/bill', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "status": "success",
  "message": "Bill imported successfully.",
  "data": [
    {
      "uuid": "b5c6d7e8f9a0418290a1b2c3d4e5f6b7",
      "transaction_type": "bills",
      "status": "pending",
      "document_number": "BILL-550"
    }
  ]
}

{
  "status": "failed",
  "message": "<string>"
}

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

Bill date.

document_due

string<date>

required

Payment due date. Alias: due_date.

currency

string

required

Currency code.

items

object[]

required

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

Vendor uuid, name, or email. Alias: vendor.

document_number

string

Bill reference. Alias: bill_no.

narration

string

Document title.

memo

string

Internal note.

payable_account

string

Optional accounts payable control account.

amount_paid

number

Amount paid now. Omit for an open bill.

payment_category

string

Cash or bank account name payment came from.

exchange_rate

number

Default 1.

status

string

Default pending. Use draft to save without posting.

Response

Bill 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.