Create an invoice

POST/v1/invoicesRun

Requires invoices:write permission.

Headers

Idempotency-Keystringrequired

Example: order-1001-attempt-1

Required. A unique string for this request. See Idempotency.

Request body

project_idstringoptional

The project the invoice belongs to. Needed with a merchant key; a project key already names its project.

Example: prj_01k7q3m8x2v5t9n4b6c1d0e7fa

Prefixed with prj_.

customer_namestringrequired

The name of the customer you bill.

Example: Budi Santoso

Min length: 1

Max length: 120

customer_emailstringrequired

Where the pay link is mailed when you issue the invoice in live.

Example: budi@example.com

Min length: 3

Max length: 254

customer_phonestring | nulloptional

The customer's phone number; optional.

Example: +628123456789

Max length: 30

notestring | nulloptional

A note printed on the invoice, up to 500 characters.

Example: Terima kasih atas kepercayaannya.

Max length: 500

itemsarray of objectrequired

The lines of the bill, from 1 to 50.

Max items: 50

descriptionstringrequired

Name the product or service being billed on this invoice line.

Example: Desain logo

Min length: 1

Max length: 200

quantityintegerrequired

Number of units on this line; multiplied by unit_amount to calculate amount.

Example: 2

Minimum: 1

Maximum: 1000000

unit_amountintegerrequired

The price of one unit, a whole rupiah, in the smallest unit of currency (Rp125.000 is 12500000).

Example: 30000000

Minimum: 100

Maximum: 100000000000

tax_rate_bpintegeroptional

One tax rate for the whole invoice in basis points: 1100 is 11%. No tax when left out.

Example: 1100

Minimum: 0

Maximum: 10000

due_atstringrequired

When the invoice is due (RFC 3339). After that the pay link no longer takes payments.

Example: 2026-11-15T16:59:59Z

Format: date-time

fee_bearerstringoptional

Who bears Baiyar's fee: merchant takes it out of what you receive, customer adds it to what the payer pays.

Example: merchant

Possible values: merchant, customer

Response (201)

dataobjectrequired

The returned object, or an array of objects for a list.

idstringrequired

The id of the invoice (inv_…).

Example: inv_01k7q3m8x2v5t9n4b6c1d0e7fa

Prefixed with inv_.

livemodebooleanrequired

true means this object belongs to live and can involve real payments; false means it belongs to the sandbox.

project_idstringrequired

The project this object belongs to. Its settings determine which payment methods and limits apply.

Example: prj_01k7q3m8x2v5t9n4b6c1d0e7fa

Prefixed with prj_.

numberstringrequired

The running number of your invoices, by month: INV/2026/10/0001. A number is never used twice.

Example: INV/2026/10/0001

statusstringrequired

draft (editable), open (waiting for payment), paying (a payment is under way), paid, expired (past its due date) or void.

Example: open

Possible values: draft, open, paying, paid, expired, void

customer_namestringrequired

The name of the customer you bill.

Example: Budi Santoso

customer_emailstringrequired

Where the pay link is mailed when you issue the invoice in live.

Example: budi@example.com

customer_phonestring | nullrequired

The customer's phone number; optional.

Example: +628123456789

notestring | nullrequired

A note printed on the invoice, up to 500 characters.

Example: Terima kasih atas kepercayaannya.

itemsarray of objectrequired

The lines of the bill, from 1 to 50.

descriptionstringrequired

Name the product or service being billed on this invoice line.

Example: Desain logo

quantityintegerrequired

Number of units on this line; multiplied by unit_amount to calculate amount.

Example: 2

unit_amountintegerrequired

The price of one unit, a whole rupiah, in the smallest unit of currency (Rp125.000 is 12500000).

Example: 30000000

amountintegerrequired

The line total: quantity times the unit price, in the smallest unit of currency (Rp125.000 is 12500000).

Example: 60000000

currencystringrequired

The currency, an ISO 4217 code. Only IDR today.

Example: IDR

Value: IDR

subtotalintegerrequired

The sum of the lines, before tax, in the smallest unit of currency (Rp125.000 is 12500000).

Example: 60000000

tax_rate_bpintegerrequired

One tax rate for the whole invoice in basis points: 1100 is 11%. No tax when left out.

Example: 1100

tax_amountintegerrequired

The tax, in the smallest unit of currency (Rp125.000 is 12500000).

Example: 6600000

totalintegerrequired

What the customer pays: the subtotal plus the tax, in the smallest unit of currency (Rp125.000 is 12500000).

Example: 66600000

fee_bearerstringrequired

Who bears Baiyar's fee: merchant takes it out of what you receive, customer adds it to what the payer pays.

Example: merchant

Possible values: merchant, customer

due_atstringrequired

When the invoice is due (RFC 3339). After that the pay link no longer takes payments.

Example: 2026-11-15T16:59:59Z

Format: date-time

urlstring | nullrequired

The address to send to the customer, where they pay. Null until the invoice is issued.

Example: https://pay.baiyar.com/p/lt_live_…

payment_link_idstring | nullrequired

The single-use payment link made when the invoice was issued; null for a draft.

Example: lnk_01k7q3m8x2v5t9n4b6c1d0e7fa

Prefixed with lnk_.

issued_atstring | nullrequired

When it was issued; null for a draft.

Example: 2026-10-26T03:04:05.000Z

Format: date-time

paid_atstring | nullrequired

When the payment was confirmed as paid (RFC 3339, UTC); null until then.

Example: 2026-10-26T03:04:05.000Z

Format: date-time

voided_atstring | nullrequired

When it was voided; null otherwise.

Example: 2026-10-26T03:04:05.000Z

Format: date-time

versionintegerrequired

Send it back when you rewrite a draft, so a save by somebody else in between is noticed.

Example: 1

created_atstringrequired

When this object was created (RFC 3339, UTC). Use it to sort objects by creation time.

Example: 2026-10-26T03:04:05.000Z

Format: date-time

metaobjectrequired

Request details such as its id and pagination cursor.

request_idstringrequired

The id of this request. Quote it when you ask support about it.

Example: req_Hy3k9QzT2LmN8vXa

A failed request answers with the common error shape; see Errors.

Request

curl -X POST "https://api.baiyar.com/v1/invoices" \
  -H "Authorization: Bearer $BAIYAR_KEY" \
  -H "Idempotency-Key: order-1001-attempt-1" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_name": "Budi Santoso",
    "customer_email": "budi@example.com",
    "items": [
      {
        "description": "Desain logo",
        "quantity": 2,
        "unit_amount": 30000000
      }
    ],
    "due_at": "2026-11-15T16:59:59Z"
  }'

Response

{
  "data": {
    "id": "inv_01k7q3m8x2v5t9n4b6c1d0e7fa",
    "livemode": false,
    "project_id": "prj_01k7q3m8x2v5t9n4b6c1d0e7fa",
    "number": "INV/2026/10/0001",
    "status": "open",
    "customer_name": "Budi Santoso",
    "customer_email": "budi@example.com",
    "customer_phone": "+628123456789",
    "note": "Terima kasih atas kepercayaannya.",
    "items": [
      {
        "description": "Desain logo",
        "quantity": 2,
        "unit_amount": 30000000,
        "amount": 60000000
      }
    ],
    "currency": "IDR",
    "subtotal": 60000000,
    "tax_rate_bp": 1100,
    "tax_amount": 6600000,
    "total": 66600000,
    "fee_bearer": "merchant",
    "due_at": "2026-11-15T16:59:59Z",
    "url": "https://pay.baiyar.com/p/lt_live_…",
    "payment_link_id": "lnk_01k7q3m8x2v5t9n4b6c1d0e7fa",
    "issued_at": "2026-10-26T03:04:05.000Z",
    "paid_at": "2026-10-26T03:04:05.000Z",
    "voided_at": "2026-10-26T03:04:05.000Z",
    "version": 1,
    "created_at": "2026-10-26T03:04:05.000Z"
  },
  "meta": {
    "request_id": "req_Hy3k9QzT2LmN8vXa"
  }
}