Create Bulk Invoices

This POST endpoint allows you to create multiple invoices in the system with a single request. The request body should include an array of invoice objects.

Endpoint

• URL: /invoices/bulk
• Method: POST

Authentication

• Header: accessToken
• Type: Bearer Token
• Value: <ACCESS-TOKEN>

Request Headers

Header	Type	Description
Content-Type	string	Must be application/json.
accessToken	string	Access token for authentication. (required)

Request Body

The body of the request should be a JSON object containing an array of order IDs. Invoices will be automatically generated for each order based on the order information.

Field	Type	Requirements/Notes
orderIds	array	Required - Array of order IDs to generate invoices for (strings).

Sample Request Body

{
    "orderIds": [
        "69ab24db449866373d5e3e35",
        "69ab24db449866373d5e3e40",
        "69ab24db449866373d5e3e51"
    ]
}

Response

• Status Code: 201 Created

Success Response Body

A successful response will confirm the creation of the invoices:

Field	Type	Description
success	boolean	Indicates whether the invoices were created.
data	array	Array of created invoice objects.
message	string	Success message.

Sample Response Body

{
    "success": true,
    "data": [
        {
            "order": "6932f96b8cd64c28a4fb5873",
            "entityId": "1",
            "lineItems": [
                {
                    "lineItemId": "6932f96b8cd64c28a4fb5876",
                    "quantity": 30,
                    "id": "693738682fa9114d9af87d2a"
                },
                {
                    "lineItemId": "6932f96b8cd64c28a4fb5877",
                    "quantity": 20,
                    "id": "693738682fa9114d9af87d2b"
                }
            ],
            "total": 3684.78,
            "createdBy": {
                "id": "6852dc137d290c8e310f258e",
                "name": "Sam Nabahani",
                "type": "admin"
            },
            "metaFields": [],
            "createdAt": "2025-12-08T20:43:20.608Z",
            "updatedAt": "2025-12-08T20:43:20.608Z",
            "id": "693738682fa9114d9af87d29"
        },
        {
            "order": "6932f96b8cd64c28a4fb5880",
            "entityId": "2",
            "lineItems": [
                {
                    "lineItemId": "6932f96b8cd64c28a4fb5881",
                    "quantity": 15,
                    "id": "693738682fa9114d9af87d3a"
                }
            ],
            "total": 1842.39,
            "createdBy": {
                "id": "6852dc137d290c8e310f258f",
                "name": "Jane Admin",
                "type": "api"
            },
            "metaFields": [],
            "createdAt": "2025-12-08T20:44:20.608Z",
            "updatedAt": "2025-12-08T20:44:20.608Z",
            "id": "693738682fa9114d9af87d3b"
        }
    ],
    "count": 2
}

Example Request

curl --location --request POST '<BASE-URL>/invoices/bulk' \
--header 'Content-Type: application/json' \
--header 'accessToken: <ACCESS-TOKEN>' \
--data-raw '{
    "orderIds": [
        "69ab24db449866373d5e3e35",
        "69ab24db449866373d5e3e40"
    ]
}'

Error Responses

400 Bad Request

{
    "success": false,
    "message": "Validation error: orderIds is required and must be an array"
}

404 Not Found

{
    "success": false,
    "message": "Order not found: 69ab24db449866373d5e3e35"
}

401 Unauthorized

{
    "success": false,
    "message": "Invalid or missing access token"
}

500 Internal Server Error

{
    "success": false,
    "message": "An error occurred while creating invoices"
}

Notes

• Invoices are automatically generated based on order data (line items, totals, etc.).
• The system generates unique entityId values for each invoice.
• The bulk endpoint creates invoices as a batch operation.
• Ensure all referenced orders exist in the system before creating invoices.
• If any order is not found, the operation may fail or skip that order (depending on implementation).