Create an Invoice

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.

Header

{
    "Accept": "application/json",
    "Content-Type": "application/json"
}

Body

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"
        ]
    }
}

Line items and the amount

Alaaqat works out each line's net_price and the invoice's amount itself:

  1. A line is worth its unit price less its unit discount, times its quantity, plus its own tax rate.
  2. The lines are added up, then the invoice's discount_rate and fixed_discount come off.
  3. The invoice's 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.

Linking records on creation

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.

Response

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."
}

Errors

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.