Create Invoice

Invoicing for Pay on Demand contracts operates with unique flexibility compared to other contract types. Unlike traditional invoicing, Pay on Demand invoices allow employers to choose when to generate each invoice, specify the amount, and select the currency—all without adherence to a fixed pay cycle.

Additionally, employers can adjust critical parameters such as currency and amount with each new invoice, giving them the freedom to adapt to changing payment needs without being bound by previous selections. This flexibility enables responsive and dynamic invoicing tailored to individual circumstances and requirements.

Key Differences in Pay on Demand Invoicing

No Pay Cycle Requirement: Invoices can be generated at any time, independent of a fixed pay cycle, giving employers flexibility to align with specific payment needs.
Amount Selection: Employers can specify the amount to bill with each invoice, providing flexibility based on the immediate needs or agreed-upon amounts with the employee.
Currency Selection: Employers can choose the preferred currency during invoice creation, supporting a range of international payment requirements.

Invoice Status

Invoices progress through several statuses to indicate their current state:

Status	Description
DRAFT	The invoice has been created but not yet submitted for approval.
UNDER_APPROVAL	The invoice is awaiting approval from relevant parties.
PAYMENT_PENDING	The invoice has been approved, and payment is pending from the payer.
OVERDUE	The payment for the invoice is overdue.
PAYMENT_PROCESSING	Payment for the invoice is currently being processed.
PAYMENT_FAILED	The payment attempt failed; further action may be required.
RECEIVED_BY_NIURAL	Niural has received the payment for the invoice.
PAYOUT_PROCESSING	The payout to the intended recipient is currently being processed by Niural.
PAYOUT_FAILED	The payout attempt failed; further action may be required.
PAID	The invoice has been fully paid, and the process is complete.
VOID	The invoice has been voided and is no longer valid.
REJECTED	The invoice was rejected during the approval process and will not proceed further.

In the API, ensure these statuses are accurately reflected as the invoice progresses through each stage, supporting clear visibility into its status.

Create an Invoice API

This API allows you to create an invoice associated with a specific contract. Invoices can be created with details such as the contract ID, invoice title, amount, billing cycle dates, issued date, and due date.

HTTP Method

POST

Endpoint

POST /invoices

The specific path to create a new invoice. The base URL will differ between sandbox and production environments.

cURL Sample Request

This is a sample request using the curl command to demonstrate how to create an invoice. The curl request contains all the necessary headers and data to make the API call.

curl --request POST \
     --url https://api-live.niural.com/invoices \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "currency": "USD",
  "contract_id": "71af9f4-59c2-48b8-8c3e-3689de7d9a",
  "invoice_title": "Consulting Service",
  "amount": "1500",
  "cycle_start_date": "2023-01-01",
  "cycle_end_date": "2023-01-31",
  "issued_date": "2023-02-01",
  "due_date": "2023-02-15"
}
'

Request Structure

Request Body Parameters

The following parameters are required to create an invoice:

Name	Required	Type	Description	Example
contract_id	TRUE	string	The unique identifier for the contract.	71af9f4-59c2-48e1-8324-abc5d739f2e2
currency	TRUE	string	The currency in which the invoice is issued.	USD
invoice_title	TRUE	string	The title or description of the invoice.	Consulting Services
amount	TRUE	string	The total amount of the invoice.	1500
cycle_start_date	FALSE	date	The start date of the billing cycle. Defaults to null	2023-01-01
cycle_end_date	FALSE	date	The end date of the billing cycle. Defaults to null.	2023-01-31
issued_date	TRUE	date	The date when the invoice was issued.	2023-02-01
due_date	TRUE	date	The date by which the invoice should be paid.	2023-02-15

Request body sample

This is an example JSON object that would be sent as the request body when creating an invoice. It contains all the necessary fields like contract_id, currency, invoice_title, and dates.


{
  "currency": "USD",
  "contract_id": "71af9f4-59c2-48b8-8c3e-3689de7d9a",
  "invoice_title": "Consulting Service",
  "amount": "1500",
  "cycle_start_date": "2023-01-01",
  "cycle_end_date": "2023-01-31",
  "issued_date": "2023-02-01",
  "due_date": "2023-02-15"
}


{
  "currency": "AUD",
  "contract_id": "71af9f4-59c2-48b8-8c3e-3689de7d9a",
  "invoice_title": "Consulting Service",
  "amount": "1000",
  "cycle_start_date": "2023-01-01",
  "cycle_end_date": "2023-01-31",
  "issued_date": "2023-02-01",
  "due_date": "2023-02-15"
}

Response Structure

After successfully creating an invoice, the API will return a JSON object containing the invoice details and status.

Successful Response (200)

{
    "data": {
        "invoice_id": "AUTOM-SKJEENSR",
        "currency": "USD",
        "status": "PAYMENT_PENDING",
        "total_amount": 1500.0,
        "issued_date": "2023-02-01",
        "due_date": "2023-02-15",
        "invoice_items": [
            {
                "description": "Consulting Service",
                "quantity": 1.0,
                "item_code": "PAY_ON_DEMAND",
                "cost_per_unit": 1500.0,
                "discount_per_unit": 0.0,
                "total_discount": 0.0,
                "total_amount": 1500.0,
                "currency": "USD",
                "references": []
            }
        ],
        "payer_id": "1e0ed20e-c50c-42c9-b039-5c2de4d88511",
        "payer_name": "automation",
        "payer_email": "[email protected]",
        "invoice_title": "Consulting Service",
        "contract_id": "71af9f4-59c2-48b8-8c3e-3689de7d9a",
        "contractor_id": "9d3ce8ad-6cf3-4a26-8353-fe97c4299076",
        "cycle_start_date": "2023-01-01",
        "cycle_end_date": "2023-01-31",
        "tags": {}
    }
}

{
    "data": {
        "invoice_id": "AUTOM-NUZ5SJUW",
        "currency": "AUD",
        "status": "PAYMENT_PENDING",
        "total_amount": 1000.0,
        "issued_date": "2023-02-01",
        "due_date": "2023-02-15",
        "invoice_items": [
            {
                "description": "Consulting Service",
                "quantity": 1.0,
                "item_code": "PAY_ON_DEMAND",
                "cost_per_unit": 1000.0,
                "discount_per_unit": 0.0,
                "total_discount": 0.0,
                "total_amount": 1000.0,
                "currency": "AUD",
                "references": []
            }
        ],
        "payer_id": "1e0ed20e-c50c-42c9-b039-5c2de4d88511",
        "payer_name": "automation",
        "payer_email": "[email protected]",
        "invoice_title": "Consulting Service",
        "contract_id": "71af9f4-59c2-48b8-8c3e-3689de7d9a",
        "contractor_id": "9d3ce8ad-6cf3-4a26-8353-fe97c4299076",
        "cycle_start_date": "2023-01-01",
        "cycle_end_date": "2023-01-31",
        "tags": {}
    }
}

Notes

This API allows the creation of invoices for contracts already created in the system.
The currency can be a fiat currency (e.g., USD) or a cryptocurrency (e.g., USDT), depending on platform support.
Ensure the contract_id and other required fields are provided correctly to avoid 400 or 404 errors.