Documentation

  2. Home
  4. Docs
  6. Documentation
  8. Invoicing APIs – V1
  10. API: Create Invoice

API: Create Invoice

The purpose of this API is to create new invoice.

Request

URL https://your_account.modulus.biz/api/inv/v1/Invoice?token=YOUR_TOKEN
API Name Invoice
Method POST
Source Third Party Server
Recipient modulus® Server
Content Type application/json

Query String Parameters

Parameter Required Type Description
token Yes Text Your authentication token.

Payload Parameters

Parameter Required Type Description
customer_code Yes Text Refers to customer the invoice issued to.
branch_code Yes Text The code of an active branch.
issue_date Yes Date Date format must be ISO 8601 (Example: “2020-01-10”).
due_date Yes Date Date format must be ISO 8601 (Example: “2020-01-10”) can not be before issue_date.
book_id Yes Number Refers to invoice book used for the invoice. Must be For Invoice.
status Yes Text May be STATUS_DRAFT or STATUS_SENT.
payment_term_id Yes Number Refers to the payment term used in the invoice.
exchange_rate No Decimal Number The exchange rate when the invoice is issued. Mandatory if the customer has foreign currency.
salesperson_id No Number Refers to salesperson linked to the branch of this invoice.
reference No Text Invoice reference.
description No Text Invoice description.
items Yes Array An array that contains at least one item. The structure explained here.

Item Parameter Details

Parameter Required Type Description
item_code Yes Text Item code.
unit_id Yes Number Refer to the unit of the sent quantity.
quantity Yes Decimal Number The quantity of the item can not be less than or equal to 0.
unit_price No Decimal Number The price of the item. If not sent will defined price in the customer or branch default price list.
discount No Decimal Number Discount per unit if exist but can not exceed price.

Responses

HTTP Status result title message object
Success Responses
200 OK true Success Invoice added successfully. 
{
    "invoice _id": xxx,
    "invoice_serial": "INV_xxx",
    "document_type": "Invoice",
    "creation_date_time": "yyy-mm-dd hh:MM:ss"
}
Failure Responses
400 Bad Request false Error Error message as elaborated here. 
{
    "error_code": xxx
}
500 Internal Server Error false Error Error message as elaborated here. 
{
    "error_code": xxx
}

Example 1

Request 
curl --request POST 'https://your_account.modulus.biz/api/inv/v1/Invoice?token=YOUR_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{ 
    "customer_code": "1",
    "branch_code": "2",
    "issue_date": "2024-01-01",
    "due_date": "2024-01-01",
    "book_id": 1,
    "status": "STATUS_DRAFT",
    "payment_term_id": 2,
    "items": [
        {
        "item_code": "451",
        "unit_id": 3,
        "quantity": 50,
        "unit_price": 100
        }
    ] }'
200 OK 
{
    "result": true,
    "title": "Success",
    "message": "Invoice added successfully.",
    "object": {
        "invoice_id": 3439,
        "invoice_serial": "INV_2023_01_01_828",
        "document_type": "Invoice",
        "creation_date_time": "2023-01-14 19:59:22"
    }
}

Example 2

Request 
curl --request POST 'https://your_account.modulus.biz/api/inv/v1/Invoice?token=YOUR_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{ 
    "customer_code": "1",
    "issue_date": "2024-01-01",
    "due_date": "2024-01-01",
    "book_id": 1,
    "status": "STATUS_DRAFT",
    "payment_term_id": 2,
    "items": [
        {
        "item_code": "451",
        "unit_id": 3,
        "quantity": 50,
        "unit_price": 100
        }
    ] }'
400 Bad Request 
{
     "result": false,
     "title": "Error",
     "message": "Missing branch code.",
     "object":{
         "error_code": xxx
     }
 }
Was this article helpful to you? Yes No

How can we help?