iotoms Docs

Issue an invoice for a sales order

POST
/api/v1/sales/orders/{orderId}/invoice

Issues the tax invoice for a confirmed sales order, allocating the invoice number and snapshotting the tax position. Idempotent: issuing again for the same order returns the first invoice. Optional invoiceDate, dueDate and notes.

How to use it

  1. Take a sales order through Submit a sales order and Confirm a sales order; any pending price override must be approved first.
  2. Optionally call Preview the invoice for a sales order and check blockedReason is empty and the GST details are complete.
  3. Send invoiceDate, dueDate and notes if you need them; otherwise the invoice is dated today and due in 30 days.
  4. The invoice is created as POSTED with a new invoice number and a frozen tax snapshot; its ledger state starts as PENDING.
  5. Calling again for the same order returns the same invoice rather than a second one.

Authorization

BearerAuth
headerAuthorizationBearer <JWT>

Path Parameters

orderId*string

ID of the confirmed sales order to invoice, from List sales orders.

Formatuuid

Header Parameters

X-TenantID*string

Your merchant's tenant code — the value typed in the Domain field on the iotoms login screen. See Concepts.

Request Body

application/json
  1. body
invoiceDate?|

Invoice date (YYYY-MM-DD). Defaults to today.

Formatdate
dueDate?|

Payment due date (YYYY-MM-DD). Defaults to 30 days after the invoice date.

Formatdate
notes?|

Free-text notes to keep on the invoice.

Response Body

OK

*/*
  1. response
status*string

Outcome of the call: SUCCESS when the request was processed; otherwise an error status.

message*string

Short human-readable message describing the outcome, e.g. which record was saved or why the call failed.

data?

The sales invoice with its lines and tax snapshot.

Example Request
curl -X POST 'https://beta.iotoms.com/api/v1/sales/orders/497f6eca-6276-4993-bfeb-53cbbbba6f08/invoice' \  -H 'X-TenantID: your-tenant-code' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "status": "string",  "message": "string",  "data": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "invoiceNumber": "string",    "seriesCode": "string",    "salesOrderId": "9bd8f312-a044-4003-9f73-706a82f71a8f",    "salesOrderNumber": "string",    "transactionId": "75906707-8c31-479c-b354-aa805c4cefbc",    "customerStoreId": 0,    "customerStoreName": "string",    "customerNumber": "string",    "customerNameSnapshot": "string",    "storeId": 0,    "status": "DRAFT",    "invoiceDate": "2019-08-24",    "dueDate": "2019-08-24",    "currency": "string",    "target": "OWN_BOOKS",    "ledgerState": "NOT_APPLICABLE",    "targetRef": "string",    "targetLastError": "string",    "targetLastAttemptAt": "2019-08-24T14:15:22Z",    "sellerGstin": "string",    "sellerStateCode": "string",    "buyerGstin": "string",    "buyerStateCode": "string",    "placeOfSupply": "string",    "isInterstate": true,    "gstIncomplete": true,    "subtotal": 0,    "discountTotal": 0,    "taxTotal": 0,    "grandTotal": 0,    "directReason": "string",    "notes": "string",    "issuedBy": "string",    "issuedAt": "2019-08-24T14:15:22Z",    "sentAt": "2019-08-24T14:15:22Z",    "sentTo": "string",    "reprintCount": 0,    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z",    "lines": [      {        "id": 0,        "itemId": "string",        "itemName": "string",        "hsnCode": "string",        "uomCode": "string",        "uqcCode": "string",        "quantity": 0,        "unitPrice": 0,        "discountAmount": 0,        "taxableValue": 0,        "cgstRate": 0,        "cgstAmount": 0,        "sgstRate": 0,        "sgstAmount": 0,        "igstRate": 0,        "igstAmount": 0,        "cessAmount": 0,        "taxAmount": 0,        "lineTotal": 0,        "lineNumber": 0      }    ]  }}