Purchase invoice

This module handles purchase invoice operations which are also referred to as the LPO by the client

Purchase Invoice Taxes

Taxes in a Purchase Invoice can be computed in two ways:

Apply a global tax rate

Apply item-specific tax rate

Note

1. Apply a global tax rate

In this scenario, the taxes will be computed on the invoice total amount. To determine the tax rate to apply, a Purchase Taxes and Charges Template must be attached to the invoice.

2. Apply item-specific tax rate

In this scenario, specific tax computation is done on items that have a value of item_tax_template specified as the invoice is being created. If no item has a item_tax_template specified, the taxes will be computed based on the value of taxes_and_charges template specified. See Item Tax Template

Create a Purchase Invoice

Endpoint: {SERVER_URL}/api/method/eclectics.api.purchase_invoice.create
Method: POST
Payload:

{
    "transaction_date": "2025-04-10",
    "created_by": "Nyaga",
    "created_on": "2025-04-16",
    "approved_by": "Steve",
    "approved_on": "2025-04-20",
    "company_code": "001",
    "branch_code": "Branch 2",
    "branch_dim_code": "Branch Dim 2",
    "document_type": "Contractual",
    "document_no": "333/45",
    "contract_no": "333/45/2025",
    "customer_no": "CUST-1",
    "customer_name": "XYZ Customer",
    "reversed": false,
    "document_date": "2025-01-02",
    "enquiry_no": "INQ/1/2025",
    "title": "First Purchase Invoice",
    "supplier": "Summit Traders Ltd.",
    "posting_date": "2025-02-01",
    "due_date": "2025-02-27",
    "supplier_invoice_no": "PNT/233/3000",
    "supplier_invoice_date": "2025-02-27",
    "cost_center": "Main - EFTA",
    "taxes_and_charges": "Tanzania VAT Exclusive - EFTA",
    "tax_withholding_category": "Withholding Tax (5%)",
    "items": [
        {
            "item": "Tractor",
            "qty": 2,
            "rate": 100,
            "expense_account": "999901",
        },
        {
            "item": "15Ltr Drinking Water",
            "qty": 2,
            "rate": 1000,
            "expense_account": "999901",
            "item_tax_template": "Tanzania Zero Rated - EFTA",
            "asset_type": "Motor Vehicle"
        },
    ]
}

Headers:

{
    "Authorization": "token <YOUR_TOKEN>"
}

These fields may not be exhaustive. Check the general guidance section on how to check all the parameters that an endpoint can accept

Create a Multi-currency Purchase Invoice

Notes:

Warning

To create an Purchase Invoice that has been denominated in a currency that is different from the base currency (TZS), you will need to provide the following additional parameters in the payload:
- currency. This is the ISO code for the transacting currency
- exchange_rate. The exchange rate based on the transacting currency. This will be the equivalent of base currency units to 1 unit of the transacting currency, e.g if the currency is USD, the exchange rate may be something like 2598.4401

Endpoint: {SERVER_URL}/api/method/eclectics.api.purchase_invoice.create
Method: POST
Payload:

{
    "transaction_date": "2025-04-10",
    "created_by": "Nyaga",
    "created_on": "2025-04-16",
    "approved_by": "Steve",
    "approved_on": "2025-04-20",
    "company_code": "001",
    "branch_code": "Branch 2",
    "branch_dim_code": "Branch Dim 2",
    "document_type": "Contractual",
    "document_no": "333/45",
    "contract_no": "333/45/2025",
    "customer_no": "CUST-1",
    "customer_name": "XYZ Customer",
    "reversed": false,
    "document_date": "2025-01-02",
    "enquiry_no": "INQ/1/2025",
    "title": "First Purchase Invoice",
    "supplier": "Summit Traders Ltd.",
    "posting_date": "2025-02-01",
    "due_date": "2025-02-27",
    "supplier_invoice_no": "PNT/233/3000",
    "supplier_invoice_date": "2025-02-27",
    "currency": "USD",
    "exchange_rate": 2598.4401,
    "payable_account": "21990",
    "tax_withholding_category": "Withholding Tax (5%)",
    "items": [
        {
            "item": "Tractor",
            "qty": 2,
            "rate": 100
        }
    ]
}

Headers:

{
    "Authorization": "token <YOUR_TOKEN>"
}

These fields may not be exhaustive. Check the general guidance section on how to check all the parameters that an endpoint can accept

Note

The payable_account must be passed in the payload when the transaction currency is a foreign currency.

Create a Purchase Invoice specifying the transaction code

Notes:

Note

There are instances where you want to specify the account which will be affected when the Purchase Invoice is posted. If this account is not specified, the system will use the default accounts

Endpoint: {SERVER_URL}/api/method/eclectics.api.purchase_invoice.create
Method: POST
Payload:

{
    "transaction_date": "2025-04-10",
    "created_by": "Nyaga",
    "created_on": "2025-04-16",
    "approved_by": "Steve",
    "approved_on": "2025-04-20",
    "company_code": "001",
    "branch_code": "Branch 2",
    "branch_dim_code": "Branch Dim 2",
    "document_type": "Contractual",
    "document_no": "333/45",
    "contract_no": "333/45/2025",
    "customer_no": "CUST-1",
    "customer_name": "XYZ Customer",
    "reversed": false,
    "document_date": "2025-01-02",
    "enquiry_no": "INQ/1/2025",
    "title": "First Purchase Invoice",
    "supplier": "Summit Traders Ltd.",
    "posting_date": "2025-02-01",
    "due_date": "2025-02-27",
    "supplier_invoice_no": "PNT/233/3000",
    "supplier_invoice_date": "2025-02-27",
    "tax_withholding_category": "Withholding Tax (5%)",
    "items": [
        {
            "item": "Fork list",
            "expense_account_number": "5204",
            "qty": 2,
            "rate": 100
        }
    ]
}

Headers:

{
    "Authorization": "token <YOUR_TOKEN>"
}

Get a list of Purchase Invoices

Endpoint: {SERVER_URL}/api/method/eclectics.api.purchase_invoice.list
Method: GET
Payload:

{
    "fields": ["name", "title", "posting_date", "supplier", "total"],
    "filters": [["posting_date", "<", "2035-02-24"]],
    "start": 0,
    "page_length": 0,
    "order_by": "creation desc"
}

Headers:

{
    "Authorization": "token <YOUR_TOKEN>"
}

Refer to Document List API Parameters for guidance on the payload

Get a single Purchase Invoice

Endpoint: {SERVER_URL}/api/method/eclectics.api.purchase_invoice.get
Method: GET
Payload:

{
    "doc_id_": "ACC-PINV-2025-00010"
}

Headers:

{
    "Authorization": "token <YOUR_TOKEN>"
}

Delete a Purchase Invoice

Endpoint: {SERVER_URL}/api/method/eclectics.api.purchase_invoice.delete
Method: DELETE
Payload:

{
    "doc_id_": "ACC-PINV-2025-00010"
}

Cancel a Purchase Invoice

Endpoint: {SERVER_URL}/api/method/eclectics.api.purchase_invoice.cancel
Method: DELETE
Payload:

{
    "doc_id_": "ACC-PINV-2025-00010"
}