Create purchase order (manual or AI)

curl --request POST \
  --url https://staging-api.usetyms.com/v1/adam/purchase-orders \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "date": "2026-04-05",
  "delivery_date": "2026-04-20",
  "currency": "NGN",
  "document_number": "PO-0042",
  "narration": "Q2 stock replenishment",
  "customer": "v8e7d6c5b4a3418290f0e9d8c7b6a5947",
  "items": [
    {
      "item_name": "Wireless Mouse",
      "quantity": 50,
      "selling_price": 9000,
      "category": "Inventory"
    }
  ]
}
'

import requests

url = "https://staging-api.usetyms.com/v1/adam/purchase-orders"

payload = {
    "date": "2026-04-05",
    "delivery_date": "2026-04-20",
    "currency": "NGN",
    "document_number": "PO-0042",
    "narration": "Q2 stock replenishment",
    "customer": "v8e7d6c5b4a3418290f0e9d8c7b6a5947",
    "items": [
        {
            "item_name": "Wireless Mouse",
            "quantity": 50,
            "selling_price": 9000,
            "category": "Inventory"
        }
    ]
}
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-04-05',
    delivery_date: '2026-04-20',
    currency: 'NGN',
    document_number: 'PO-0042',
    narration: 'Q2 stock replenishment',
    customer: 'v8e7d6c5b4a3418290f0e9d8c7b6a5947',
    items: [
      {
        item_name: 'Wireless Mouse',
        quantity: 50,
        selling_price: 9000,
        category: 'Inventory'
      }
    ]
  })
};

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

{
  "status": "success",
  "message": "Purchase order created successfully",
  "data": {
    "uuid": "po-uuid-1",
    "transaction_type": "purchase_order",
    "status": "draft",
    "document_number": "PO-0042",
    "narration": "Q2 stock replenishment",
    "amount": 450000,
    "currency": "NGN"
  }
}

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

POST

purchase-orders

Create purchase order (manual or AI)

curl --request POST \
  --url https://staging-api.usetyms.com/v1/adam/purchase-orders \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "date": "2026-04-05",
  "delivery_date": "2026-04-20",
  "currency": "NGN",
  "document_number": "PO-0042",
  "narration": "Q2 stock replenishment",
  "customer": "v8e7d6c5b4a3418290f0e9d8c7b6a5947",
  "items": [
    {
      "item_name": "Wireless Mouse",
      "quantity": 50,
      "selling_price": 9000,
      "category": "Inventory"
    }
  ]
}
'

import requests

url = "https://staging-api.usetyms.com/v1/adam/purchase-orders"

payload = {
    "date": "2026-04-05",
    "delivery_date": "2026-04-20",
    "currency": "NGN",
    "document_number": "PO-0042",
    "narration": "Q2 stock replenishment",
    "customer": "v8e7d6c5b4a3418290f0e9d8c7b6a5947",
    "items": [
        {
            "item_name": "Wireless Mouse",
            "quantity": 50,
            "selling_price": 9000,
            "category": "Inventory"
        }
    ]
}
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-04-05',
    delivery_date: '2026-04-20',
    currency: 'NGN',
    document_number: 'PO-0042',
    narration: 'Q2 stock replenishment',
    customer: 'v8e7d6c5b4a3418290f0e9d8c7b6a5947',
    items: [
      {
        item_name: 'Wireless Mouse',
        quantity: 50,
        selling_price: 9000,
        category: 'Inventory'
      }
    ]
  })
};

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

{
  "status": "success",
  "message": "Purchase order created successfully",
  "data": {
    "uuid": "po-uuid-1",
    "transaction_type": "purchase_order",
    "status": "draft",
    "document_number": "PO-0042",
    "narration": "Q2 stock replenishment",
    "amount": 450000,
    "currency": "NGN"
  }
}

{
  "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

Purchase order date.

items

object[]

required

Line items.

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.

delivery_date

string<date>

Expected delivery date.

currency

string

Currency code.

document_number

string

PO number; auto-assigned if omitted.

narration

string

PO title / description.

memo

string

Internal note.

customer

string

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

exchange_rate

number

Default 1.

status

string

Default draft.

branch_uuid

string | null

department_uuid

string | null

project_uuid

string | null

Response

Purchase order 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

Create purchase order (manual or AI)

Authorizations

Body

Response