POST https://app.alaaqat.com/api/invoices
Creates an invoice. Your API key needs the invoice-create ability, and the team member who created the key needs Create Invoices.
{
"Accept": "application/json",
"Content-Type": "application/json"
}
The body is a flat object of property values. Each key is the internal_name of an invoice property, built in or yours, and each value must match that property's type. Read Properties for the types, and List Invoice Properties for the properties your account has.
{
title: string,
items: [
{
name: string,
description?: string | null,
unit_price: number,
quantity: number,
unit_discount?: number,
tax_rate?: number
}
],
currency?: string,
status?: string,
due_date?: string,
discount_rate?: number,
fixed_discount?: number,
tax_rate?: number,
fixed_tax?: number,
fees_rate?: number,
fixed_fees?: number,
description?: string,
comments?: string,
owner?: number,
communication_team?: number,
association_ids?: {
[object_type: string]: string[]
},
[internal_name: string]: any
}
| Field | Required | Validation | Description |
|---|---|---|---|
| title | Required | Text | The invoice's title. |
| items | Required | An array of one or more line items | The lines of the invoice. See Line items and the amount. |
| items.*.name | Required | Text, up to 100 characters | What is sold on this line. |
| items.*.description | Optional | Text, up to 1,024 characters, or null |
More detail on the line. |
| items.*.unit_price | Required | A number | The price of one unit. |
| items.*.quantity | Required | A whole number | How many units. |
| items.*.unit_discount | Optional | A number | An amount taken off each unit. |
| items.*.tax_rate | Optional | A number, as a percentage | Tax on this line, for example 16 for 16%. |
| currency | Optional | A currency code, such as JOD, SAR or USD |
The options of the Currency property. List them with List Invoice Properties. |
| status | Optional | draft, open, paid, partially_paid or voided |
The invoice's status. |
| due_date | Optional | A date, such as 2026-11-30 |
When the invoice is due. |
| discount_rate | Optional | A number, as a percentage | A discount on the whole invoice. |
| fixed_discount | Optional | A number | A fixed amount taken off the whole invoice. |
| tax_rate | Optional | A number, as a percentage | Tax on the whole invoice. |
| fixed_tax | Optional | A number | A fixed tax amount added to the invoice. |
| fees_rate | Optional | A number, as a percentage | Fees on the whole invoice. |
| fixed_fees | Optional | A number | A fixed fee added to the invoice. |
| description, comments | Optional | Text | Free text shown on the invoice. |
| owner | Optional | The ID of a team member | The team member who owns the invoice. |
| communication_team | Optional | The ID of a team | The team the invoice belongs to. |
| association_ids | Optional | An object of record types, each with an array of IDs | Links the new invoice to existing records. See Linking records on creation. |
| Any other property | Optional | Must match the property's type | Use the property's internal_name as the key. |
Alaaqat sets _id, invoice_number and amount itself. A request that sends any of them is rejected, and so is one that sends a property with "system_only": true.
{
"title": "Office chairs, October order",
"currency": "JOD",
"status": "open",
"due_date": "2026-11-30",
"discount_rate": 5,
"tax_rate": 16,
"items": [
{
"name": "Ergonomic office chair",
"description": "Black mesh back",
"unit_price": 120,
"quantity": 4,
"unit_discount": 10
},
{
"name": "Delivery and assembly",
"unit_price": 35,
"quantity": 1
}
],
"association_ids": {
"contact": [
"6650f1a2b3c4d5e6f7a8b901"
],
"product": [
"6656b1c2d3e4f5a6b7c8d901"
]
}
}
Alaaqat works out each line's net_price and the invoice's amount itself:
discount_rate and fixed_discount come off.tax_rate and fixed_tax are added, then its fees_rate and fixed_fees.In the example above, the chairs are worth (120 − 10) × 4 = 440 and the delivery 35. The total of 475, less 5%, is 451.25, and 16% tax brings the amount to 523.45.
A line's tax_rate and the invoice's tax_rate both apply. Use one of them, or the tax is counted twice.
Alaaqat also gives each invoice the next number in your sequence, such as INV-1001, under invoice_number.
association_ids links the new invoice to records you already have, in the same request. Each key is a record type, contact, company, deal, ticket, product or invoice, other than invoice, and each value is an array of _ids of that type. An ID that isn't a record of your account is skipped.
To link records later, see Associations.
201 Created, with the new invoice under data and its line items under data.items.
{
"data": {
"properties": {
"_id": "6657c1d2e3f4a5b6c7d8e901",
"title": "Office chairs, October order",
"status": "open",
"currency": "JOD",
"discount_rate": 5,
"tax_rate": 16,
"invoice_number": "INV-1001",
"amount": 523.45,
"created_by": 12,
"updated_at": "2026-10-20T09:30:00.000000Z",
"created_at": "2026-10-20T09:30:00.000000Z"
},
"account_id": 1024,
"items": [
{
"net_price": 440,
"name": "Ergonomic office chair",
"unit_price": 120,
"quantity": 4,
"description": "Black mesh back",
"unit_discount": 10,
"tax_rate": 0
},
{
"net_price": 35,
"name": "Delivery and assembly",
"unit_price": 35,
"quantity": 1,
"description": null,
"unit_discount": 0,
"tax_rate": 0
}
]
},
"message": "Entity was created successfully."
}
| Status | Meaning |
|---|---|
| 422 | title or items is missing, a line item is incomplete, a value does not match its property's type, or a field that Alaaqat sets was sent. |