Invoices

Customer invoices — the one fully write-enabled sales document in the API.

GET/api/v1/invoices

List invoices

Scope: invoices.read

Parameters

Name	In	Type	Required	Description
`page`	query	number	Optional	1-based page number.
`limit`	query	number	Optional	Page size, max 200.

Example request

curl "https://invoice.avscorp.in/api/v1/invoices" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

JSON

{
  "id": "clx2inv001000000000000001",
  "organizationId": "clx2org001000000000000001",
  "invoiceNumber": "INV-2026-0102",
  "customerId": "clx2cus001000000000000001",
  "salesOrderId": null,
  "salespersonId": null,
  "status": "SENT",
  "invoiceDate": "2026-09-07T00:00:00.000Z",
  "dueDate": "2026-10-07T00:00:00.000Z",
  "sellerLegalName": "AVS Textiles Pvt Ltd",
  "sellerGstin": "27AAAAA0000A1Z5",
  "sellerStateCode": "27",
  "placeOfSupplyStateCode": "27",
  "currencyCode": "INR",
  "exchangeRate": 1,
  "subTotal": 13000,
  "discountTotal": 0,
  "documentDiscount": 0,
  "documentDiscountIsPercent": false,
  "cgstTotal": 1170,
  "sgstTotal": 1170,
  "igstTotal": 0,
  "adjustmentLabel": null,
  "adjustmentAmount": 0,
  "roundOff": 0,
  "total": 15340,
  "amountPaid": 0,
  "balanceDue": 15340,
  "warehouseId": "clx2wh0001000000000000001",
  "ewayBillStatus": "NOT_REQUIRED",
  "ewayBillId": null,
  "emailSentAt": null,
  "pdfTemplateId": null,
  "notes": "Thank you for your business",
  "termsAndConditions": null,
  "createdBy": "clx2usr001000000000000001",
  "updatedBy": null,
  "createdAt": "2026-09-07T10:00:00.000Z",
  "updatedAt": "2026-09-07T10:00:00.000Z"
}

Possible errors: unauthorized, insufficient_scope, forbidden

POST/api/v1/invoices

Create an invoice

Scope: invoices.createSupports Idempotency-Key

Accepts an optional Idempotency-Key header. Returns only { id, status, total } — fetch the invoice afterward for the full row.

Request body

Field	Type	Required	Constraints
`customerId`	string	Required	min length 1
`salespersonId`	string	Optional	max length 30
`sellerRegistrationId`	any	Optional	—
`invoiceDate`	string	Required	—
`dueDate`	any	Optional	—
`currencyCode`	string	Optional	min length 3; max length 3; default "INR"
`exchangeRate`	number	Optional	default 1
`placeOfSupplyStateCode`	any	Optional	—
`warehouseId`	any	Optional	—
`notes`	any	Optional	—
`termsAndConditions`	any	Optional	—
`status`	string	Optional	one of: DRAFT, SENT; default "DRAFT"
`applyCustomerCredit`	boolean	Optional	default false
`schemeIds`	array	Optional	—
`lines`	array	Required	—
`adjustments`	object	Optional	default {"documentDiscount":0,"documentDiscountIsPercent":false,"adjustmentAmount":0,"adjustmentLabel":null}
`documentDiscount`	number	Optional	min 0; default 0
`documentDiscountIsPercent`	boolean	Optional	default false
`adjustmentAmount`	number	Optional	default 0
`adjustmentLabel`	any	Optional	—

Example request

curl -X POST "https://invoice.avscorp.in/api/v1/invoices" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "customerId": "clx2cus001000000000000001",
  "invoiceDate": "2026-09-07",
  "dueDate": "2026-10-07",
  "currencyCode": "INR",
  "placeOfSupplyStateCode": "27",
  "warehouseId": "clx2wh0001000000000000001",
  "status": "SENT",
  "lines": [
    {
      "itemId": "clx2itm001000000000000001",
      "description": "Cotton Fabric - Blue",
      "quantity": 20,
      "unit": "MTR",
      "rate": 650,
      "taxRatePercent": 18
    }
  ],
  "adjustments": {
    "documentDiscount": 0,
    "documentDiscountIsPercent": false,
    "adjustmentAmount": 0
  }
}'

Example response

JSON

{
  "id": "clx2inv001000000000000001",
  "status": "SENT",
  "total": 15340
}

Possible errors: unauthorized, insufficient_scope, forbidden, validation_error, conflict

GET/api/v1/invoices/{id}

Get an invoice

Scope: invoices.read

Includes line items under `lines`.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Required	Invoice ID.

Example request

curl "https://invoice.avscorp.in/api/v1/invoices/clx2inv001000000000000001" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

JSON

{
  "id": "clx2inv001000000000000001",
  "organizationId": "clx2org001000000000000001",
  "invoiceNumber": "INV-2026-0102",
  "customerId": "clx2cus001000000000000001",
  "salesOrderId": null,
  "salespersonId": null,
  "status": "SENT",
  "invoiceDate": "2026-09-07T00:00:00.000Z",
  "dueDate": "2026-10-07T00:00:00.000Z",
  "sellerLegalName": "AVS Textiles Pvt Ltd",
  "sellerGstin": "27AAAAA0000A1Z5",
  "sellerStateCode": "27",
  "placeOfSupplyStateCode": "27",
  "currencyCode": "INR",
  "exchangeRate": 1,
  "subTotal": 13000,
  "discountTotal": 0,
  "documentDiscount": 0,
  "documentDiscountIsPercent": false,
  "cgstTotal": 1170,
  "sgstTotal": 1170,
  "igstTotal": 0,
  "adjustmentLabel": null,
  "adjustmentAmount": 0,
  "roundOff": 0,
  "total": 15340,
  "amountPaid": 0,
  "balanceDue": 15340,
  "warehouseId": "clx2wh0001000000000000001",
  "ewayBillStatus": "NOT_REQUIRED",
  "ewayBillId": null,
  "emailSentAt": null,
  "pdfTemplateId": null,
  "notes": "Thank you for your business",
  "termsAndConditions": null,
  "createdBy": "clx2usr001000000000000001",
  "updatedBy": null,
  "createdAt": "2026-09-07T10:00:00.000Z",
  "updatedAt": "2026-09-07T10:00:00.000Z",
  "lines": [
    {
      "id": "clx2ivi001000000000000001",
      "organizationId": "clx2org001000000000000001",
      "invoiceId": "clx2inv001000000000000001",
      "itemId": "clx2itm001000000000000001",
      "itemVariantId": "clx2var001000000000000001",
      "description": "Cotton Fabric - Blue",
      "hsnOrSac": "5208",
      "quantity": 20,
      "unit": "MTR",
      "rate": 650,
      "discount": 0,
      "taxRatePercent": 18,
      "taxableAmount": 13000,
      "cgstAmount": 1170,
      "sgstAmount": 1170,
      "igstAmount": 0,
      "total": 15340,
      "sortOrder": 0,
      "width": null,
      "height": null,
      "lengthUnit": null,
      "qtyCount": null
    }
  ]
}

Possible errors: unauthorized, insufficient_scope, forbidden, not_found

PATCH/api/v1/invoices/{id}

Update an invoice

Scope: invoices.update

Only DRAFT or SENT invoices are editable. Returns only { id, status, total }.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Required	Invoice ID.

Request body

Field	Type	Required	Constraints
`customerId`	string	Required	min length 1
`salespersonId`	string	Optional	max length 30
`sellerRegistrationId`	any	Optional	—
`invoiceDate`	string	Required	—
`dueDate`	any	Optional	—
`currencyCode`	string	Optional	min length 3; max length 3; default "INR"
`exchangeRate`	number	Optional	default 1
`placeOfSupplyStateCode`	any	Optional	—
`warehouseId`	any	Optional	—
`notes`	any	Optional	—
`termsAndConditions`	any	Optional	—
`status`	string	Optional	one of: DRAFT, SENT; default "DRAFT"
`applyCustomerCredit`	boolean	Optional	default false
`schemeIds`	array	Optional	—
`lines`	array	Required	—
`adjustments`	object	Optional	default {"documentDiscount":0,"documentDiscountIsPercent":false,"adjustmentAmount":0,"adjustmentLabel":null}
`documentDiscount`	number	Optional	min 0; default 0
`documentDiscountIsPercent`	boolean	Optional	default false
`adjustmentAmount`	number	Optional	default 0
`adjustmentLabel`	any	Optional	—

Example request

curl -X PATCH "https://invoice.avscorp.in/api/v1/invoices/clx2inv001000000000000001" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "customerId": "clx2cus001000000000000001",
  "invoiceDate": "2026-09-07",
  "dueDate": "2026-10-07",
  "currencyCode": "INR",
  "placeOfSupplyStateCode": "27",
  "warehouseId": "clx2wh0001000000000000001",
  "status": "SENT",
  "lines": [
    {
      "itemId": "clx2itm001000000000000001",
      "description": "Cotton Fabric - Blue",
      "quantity": 20,
      "unit": "MTR",
      "rate": 650,
      "taxRatePercent": 18
    }
  ],
  "adjustments": {
    "documentDiscount": 0,
    "documentDiscountIsPercent": false,
    "adjustmentAmount": 0
  }
}'

Example response

JSON

{
  "id": "clx2inv001000000000000001",
  "status": "SENT",
  "total": 15340
}

Possible errors: unauthorized, insufficient_scope, forbidden, not_found, validation_error, conflict

POST/api/v1/invoices/{id}/void

Void an invoice

Scope: invoices.update

Reverses stock movements for the document. 409 if the current status isn't voidable.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Required	Invoice ID.

Example request

curl -X POST "https://invoice.avscorp.in/api/v1/invoices/clx2inv001000000000000001/void" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

JSON

{
  "id": "clx2inv001000000000000001",
  "status": "VOID"
}

Possible errors: unauthorized, insufficient_scope, forbidden, not_found, conflict

DELETE/api/v1/invoices/{id}

Delete an invoice

Scope: invoices.delete

DRAFT invoices only — 409 conflict for any other status; void issued invoices instead.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Required	Invoice ID.

Example request

curl -X DELETE "https://invoice.avscorp.in/api/v1/invoices/clx2inv001000000000000001" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

JSON

{
  "ok": true
}

Possible errors: unauthorized, insufficient_scope, forbidden, not_found, conflict

POST/api/v1/invoices/{id}/send

Mark a DRAFT invoice as SENT

Scope: invoices.update

Allocates a real invoice number and drains stock. A safe, persisted-data-only transition — no total recompute or line-item mutation. 409 if the invoice isn't currently DRAFT.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Required	Invoice ID.

Example request

curl -X POST "https://invoice.avscorp.in/api/v1/invoices/clx2inv001000000000000001/send" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

JSON

{
  "id": "clx2inv001000000000000001",
  "status": "SENT",
  "invoiceNumber": "INV-2026-0102"
}

Possible errors: unauthorized, insufficient_scope, forbidden, not_found, conflict

GET/api/v1/invoices/{id}/payments

List payments applied to an invoice

Scope: paymentsReceived.read

Allocation rows joined with their parent payment, newest first. An invoice with no payments returns an empty array, not a 404.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Required	Invoice ID.

Example request

curl "https://invoice.avscorp.in/api/v1/invoices/clx2inv001000000000000001/payments" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

JSON

[
  {
    "paymentId": "clx2pr0001000000000000001",
    "paymentNumber": "PR-2026-0044",
    "paymentDate": "2026-09-07T00:00:00.000Z",
    "mode": "BANK_TRANSFER",
    "amount": 15340
  }
]

Possible errors: unauthorized, insufficient_scope, forbidden

GET/api/v1/invoices/{id}/pdf

Render the invoice as a PDF

Scope: invoices.read

Bearer-token counterpart to the session-authed web invoice PDF — same rendering pipeline, so the two are always in sync.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Required	Invoice ID.

Example request

curl "https://invoice.avscorp.in/api/v1/invoices/clx2inv001000000000000001/pdf" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

Binary response — application/pdf. The invoice rendered using the org's configured template, streamed inline with a Content-Disposition filename.

Possible errors: unauthorized, insufficient_scope, forbidden, not_found