API Reference

Invoices

Sending invoices in large volumes?

If you plan to create or send more than 2000 invoices per month, it's recommended to use the Invoices (Bulk) API.

Endpoints

GET /v1/invoices/
GET /v1/invoices/:id/
POST /v1/invoices/
PATCH /v1/invoices/:id/
DELETE /v1/invoices/:id/
GET /v1/invoices/:id/download/
GET /v1/invoices/:id/line-items/
POST /v1/invoices/:id/line-items/:line_item_id/
PATCH /v1/invoices/:id/line-items/:line_item_id/
DELETE /v1/invoices/:id/line-items/:line_item_id/

Invoice object

AttributesTypeDescription
idstringThe id of the object.
amountnumberThe invoice amount.
contactstringThe id of the contact.
currencystringThe currency used in the invoice.
invoice_numberstringThe invoice number.
invoice_datestringThe date of the invoice.
languagestringThe language used in the invoice.
line_itemsarrayThe line items of the invoice.
referencestringThe reference of the invoice.
statusstringThe status of the invoice. Either DRAFT or SENT
tax_amountnumberThe tax amount.
tax_amount_typestringEither TAX_INCLUSIVE or TAX_EXCLUSIVE.

Example

{
    "amount": 115.0,
    "contact": "co_HS9cspuVZJUHdqVsS9CFfY",
    "currency": "AED",
    "id": "inv_YEdmVKecVi45RYWcrt2rJe",
    "invoice_date": "2022-10-05",
    "invoice_number": "INV-000100",
    "language": "en",
    "line_items": [
        {
            "account": "acc_7jpGSFEGGF9cK39vwoDPBt",
            "description": "Line item",
            "id": "invli_Zhf8cUxzjiRRs8Ga7MCgWE",
            "line_amount": 115.0,
            "quantity": 1.0,
            "tax_amount": 15.0,
            "tax_rate": "tax_c8TkJLeXZYJmWuSjqGzGzj",
            "unit_amount": 100.0
        }
    ],
    "reference": "",
    "status": "DRAFT",
    "tax_amount": 15.0,
    "tax_amount_type": "TAX_EXCLUSIVE"
}

Get invoice

Endpoint

GET /v1/invoices/:id/

Response sample

{
    "amount": 115.0,
    "contact": "co_HS9cspuVZJUHdqVsS9CFfY",
    "currency": "AED",
    "id": "inv_YEdmVKecVi45RYWcrt2rJe",
    "invoice_date": "2022-10-05",
    "invoice_number": "INV-000100",
    "language": "en",
    "line_items": [
        {
            "account": "acc_7jpGSFEGGF9cK39vwoDPBt",
            "description": "Line item",
            "id": "invli_Zhf8cUxzjiRRs8Ga7MCgWE",
            "line_amount": 115.0,
            "quantity": 1.0,
            "tax_amount": 15.0,
            "tax_rate": "tax_c8TkJLeXZYJmWuSjqGzGzj",
            "unit_amount": 100.0
        }
    ],
    "reference": "",
    "status": "DRAFT",
    "tax_amount": 15.0,
    "tax_amount_type": "TAX_EXCLUSIVE"
}

List invoices

Endpoint

GET /v1/invoices/

Filters

Query paramTypeDescription
contactstringThe id of the contact.
invoice_datestringThe invoice date in YYYY-MM-DD e.g. 2021-01-01.

Request

curl --location \
    --request GET 'https://api.wafeq.com/v1/invoices/' \
    --header 'Authorization: Api-Key <api_key>' \
    --header 'Content-Type: application/json'

Create invoice

Endpoint

POST /v1/invoices/

Request body

AttributesTypeDescription
amountnumberThe invoice amount.
contactstringThe id of the contact.
currencystringThe currency used in the invoice.
invoice_numberstringThe invoice number.
invoice_datestringThe date of the invoice.
languagestringThe language used in the invoice.
line_itemsarrayThe line items of the invoice.
referencestringThe reference of the invoice.
statusstringThe status of the invoice. Either DRAFT or SENT
tax_amountnumberThe tax amount.
tax_amount_typestringEither TAX_INCLUSIVE or TAX_EXCLUSIVE.

Request

curl --location \
    --request POST 'https://api.wafeq.com/v1/invoices/' \
    --header 'Authorization: Api-Key <api_key>' \
    --header 'Content-Type: application/json' \
      --data-raw '{
	"contact": "<contact>",
	"currency": "SAR",
	"invoice_number": "INV-0001",
	"invoice_date": "2022-07-19",
	"language": "en",
	"line_items": [
		{
			"account": "<account>",
			"description": "Line Item",
			"quantity": 1,
			"tax_rate": "<tax_rate>",
			"unit_amount": 100
		}
	],
	"reference": "A reference to be reused",
	"tax_amount_type": "TAX_EXCLUSIVE"
}'

Update invoice

PATCH /v1/invoices/:id/

Request body

AttributesTypeDescription
idstringThe id of the object.
amountnumberThe invoice amount.
contactstringThe id of the contact.
currencystringThe currency used in the invoice.
invoice_numberstringThe invoice number.
invoice_datestringThe date of the invoice.
languagestringThe language used in the invoice.
referencestringThe reference of the invoice.
statusstringThe status of the invoice. Either DRAFT or SENT
tax_amount_typestringEither TAX_INCLUSIVE or TAX_EXCLUSIVE.

To update the line items, you need to use the invoices line items endpoints.

Delete invoice

DELETE /v1/invoices/:id/

Download invoice

GET /v1/invoices/:id/download/

Invoice line item object

AttributeTypeDescription
accountstringThe id of the account.
descriptionstringThe description of the line item.
idstringThe id of the object.
line_amountnumberThe line amount.
quantitynumberThe quantity.
tax_amountnumberThe tax amount.
tax_ratestringThe id of the tax rate.
unit_amountnumberThe unit amount.

Example

{
    "account": "acc_7jpGSFEGGF9cK39vwoDPBt",
    "description": "Line item",
    "id": "invli_Zhf8cUxzjiRRs8Ga7MCgWE",
    "line_amount": 115.0,
    "quantity": 1.0,
    "tax_amount": 15.0,
    "tax_rate": "tax_c8TkJLeXZYJmWuSjqGzGzj",
    "unit_amount": 100.0
}

Get invoice line item

Endpoint

POST /v1/invoices/:id/line-item/

Response sample

{
    "account": "acc_7jpGSFEGGF9cK39vwoDPBt",
    "description": "Line item",
    "id": "invli_Zhf8cUxzjiRRs8Ga7MCgWE",
    "line_amount": 115.0,
    "quantity": 1.0,
    "tax_amount": 15.0,
    "tax_rate": "tax_c8TkJLeXZYJmWuSjqGzGzj",
    "unit_amount": 100.0
}

List invoice line items

Endpoint

GET /v1/invoices/:id/line-items/

Filters

Query paramTypeDescription
accountstringThe id of the account.

Create invoice line item

Endpoint

POST /v1/invoices/:id/line-items/

Request body

AttributesTypeDescription
accountstringThe id of the account.
descriptionstringThe description of the line item.
quantitynumberThe quantity.
tax_ratestringThe id of the tax rate.
unit_amountnumberThe unit amount.

Update invoice line item

PATCH /v1/invoices/:id/line-items/:line_item_id/

Request body

AttributesTypeDescription
accountstringThe id of the account.
descriptionstringThe description of the line item.
quantitynumberThe quantity.
tax_ratestringThe id of the tax rate.
unit_amountnumberThe unit amount.

Delete invoice line item

DELETE /v1/invoices/:id/line-items/:line_item_id/
Previous
Tax rates