Introduction

In the Ordermentum platform, an invoice represents a financial transaction between a supplier and a retailer. Invoices include details such as line items, totals, taxes, and payment status.

Overview of Invoice Management API Endpoints

The platform provides two endpoints to manage invoices:

/v2/invoices: Used for searching and retrieving a summary of invoices.
/v1/invoices/{id}: Used for retrieving detailed invoice information and making updates.

Summary Endpoints

/v2/invoices (Summary)

Purpose: Searching and filtering multiple invoices
Data Scope:
- Invoice status, totals, timestamps

/v1/invoices/{id} (Detailed)

Purpose: Fetching detailed invoice information
Data Scope:
- Full invoice details including line items

Creating Invoices

Invoices can be created using the POST /v2/invoices endpoint. The request body includes details such as:

Order IDs
Line items with name, SKU, quantity, price
Invoice number
Supplier ID
Due date and charges
Financial totals (total cost, freight, surcharge)

Key Differences Between v1 and v2 Endpoints

Feature	/v2/invoices (Summary)	/v1/invoices/{id} (Detailed)
Purpose	Searching and filtering invoices	Retrieving detailed invoice info
Data Scope	Invoice status, totals, timestamps	Full invoice details
Use Case	Bulk retrieval for analysis/reporting	Managing a single invoice in detail

Example Requests

Summary Data Request

curl -X GET "https://api.ordermentum.com/v2/invoices?supplierId=123e4567-e89b-12d3-a456-426614174000&pageSize=50&pageNo=1"

Detailed Data Request

curl -X GET "https://api.ordermentum.com/v1/invoices/789e0123-e45c-12d3-a456-426614174000"

Example Responses

Summary Invoice Response

{
  "data": [
    {
      "id": "789e0123-e45c-12d3-a456-426614174000",
      "number": "INV-20231001-001",
      "status": "Unpaid",
      "createdAt": "2023-10-01T12:34:56Z",
      "dueAt": "2023-10-15T00:00:00Z",
      "total": 616.00
    },
    {
      "id": "789e0123-e45c-12d3-a456-426614174001",
      "number": "INV-20231002-001",
      "status": "Paid",
      "createdAt": "2023-10-02T09:00:00Z",
      "dueAt": "2023-10-16T00:00:00Z",
      "total": 500.00
    }
  ],
  "meta": {
    "totalResults": 100,
    "pageSize": 50,
    "pageNo": 1
  }
}

Detailed Invoice Response

{
  "id": "789e0123-e45c-12d3-a456-426614174000",
  "number": "INV-20231001-001",
  "status": "Unpaid",
  "createdAt": "2023-10-01T12:34:56Z",
  "dueAt": "2023-10-15T00:00:00Z",
  "totalCost": 46.00,
  "totalFreight": 0.00,
  "surcharge": 10.00,
  "subtotal": 56.00,
  "totalGST": 56.00,
  "total": 616.00,
  "lineItems": [
    {
      "name": "Product A",
      "SKU": "PROD-A-001",
      "quantity": 10,
      "price": 50.00,
      "weight": 1.5,
      "taxable": true
    }
  ],
  "payments": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174001",
      "amount": 300.00,
      "status": "Paid",
      "createdAt": "2023-10-05T10:00:00Z"
    }
  ]
}

Creating Invoices

Example Request

curl -X POST "https://api.ordermentum.com/v2/invoices" \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     --data '{
       "orderIds": ["d5f16d11-985f-42d7-9281-418bb0139fd9"],
       "lineItems": [{
         "taxable": false,
         "unit": "unit",
         "randomWeight": false,
         "name": "Milk 2L Carton",
         "SKU": "123",
         "quantity": 2,
         "price": 23.00,
         "subtotal": 46.00,
         "tax": 0.00,
         "total": 46.00,
         "variantId": "e1104355-57c3-421b-84ca-6aa7e9e7504a"
       }],
       "number": "INV123xx",
       "supplierId": "ded83ba1-f2a7-4a7c-b668-4912694d24b2",
       "dueAt": "2024-04-30T07:13:50.729Z",
       "chargeAt": "2024-04-30T07:13:50.729Z",
       "totalCost": 46.00,
       "totalFreight": 0.00,
       "surcharge": 0.00,
       "subtotal": 46.00,
       "totalGST": 0.00,
       "credit": 0.00,
       "total": 46.00
     }'

Example Response

{
  "id": "789e0123-e45c-12d3-a456-426614174000",
  "number": "INV-20231001-001",
  "status": "Unpaid",
  "createdAt": "2023-10-01T12:34:56Z",
  "dueAt": "2023-10-15T00:00:00Z",
  "totalCost": 46.00,
  "totalFreight": 0.00,
  "surcharge": 0.00,
  "subtotal": 46.00,
  "totalGST": 0.00,
  "credit": 0.00,
  "total": 46.00,
  "lineItems": [
    {
      "name": "Milk 2L Carton",
      "SKU": "123",
      "quantity": 2,
      "price": 23.00,
      "weight": 1.5,
      "taxable": true
    }
  ]
}

Key Notes

Line Items: Ensure that line items include all products/services with name, SKU, quantity, price.
Totals: Match calculations from line items (e.g., totalCost = sum of line items).
Timestamps: Due/charge dates must be in ISO 8601 format.
Immutability: Invoices cannot be updated after creation; ensure details are accurate before submission.