Customers

Customer master records for sales documents.

GET/api/v1/customers

List customers

Scope: customers.read

Parameters

Name	In	Type	Required	Description
`page`	query	number	Optional	1-based page number.
`limit`	query	number	Optional	Page size, max 200.
`q`	query	string	Optional	Free-text search across display name, GSTIN, phone, email.

Example request

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

Example response

JSON

{
  "id": "clx1a2b3c4d5e6f7g8h9i0j1",
  "organizationId": "clx0org000000000000000001",
  "displayName": "Bansal Textiles Pvt Ltd",
  "legalName": "Bansal Textiles Private Limited",
  "email": "accounts@bansaltextiles.in",
  "phone": "9876543210",
  "gstin": "07AAACB1234C1Z5",
  "pan": "AAACB1234C",
  "currencyCode": "INR",
  "paymentTermId": "clxpt00000000000000000001",
  "paymentTermsDays": 30,
  "placeOfSupplyStateCode": "07",
  "billingAddress": {
    "line1": "12 Nehru Market",
    "line2": "Chandni Chowk",
    "city": "New Delhi",
    "state": "Delhi",
    "stateCode": "07",
    "pincode": "110006",
    "country": "India"
  },
  "shippingAddress": null,
  "openingBalance": 15000.5,
  "notes": "Prefers e-invoices before the 5th of every month.",
  "isActive": true,
  "tenantOrgId": null,
  "portalEnabled": false,
  "portalEnabledAt": null,
  "createdBy": "clxusr0000000000000000001",
  "updatedBy": "clxusr0000000000000000001",
  "createdAt": "2026-08-01T09:15:00.000Z",
  "updatedAt": "2026-08-20T11:42:00.000Z"
}

Possible errors: unauthorized, insufficient_scope, forbidden

POST/api/v1/customers

Create a customer

Scope: customers.create

Request body

Field	Type	Required	Constraints
`displayName`	string	Required	min length 1; max length 191
`legalName`	any	Optional	—
`email`	any	Optional	—
`phone`	any	Optional	—
`gstin`	any	Optional	—
`pan`	any	Optional	—
`currencyCode`	string	Optional	min length 3; max length 3; default "INR"
`paymentTermId`	any	Optional	—
`priceListId`	any	Optional	—
`salespersonId`	string	Optional	max length 30
`placeOfSupplyStateCode`	any	Optional	—
`openingBalance`	number	Optional	min 0; default 0
`billingAddress`	object	Optional	—
`line1`	string	Optional	max length 255
`line2`	string	Optional	max length 255
`city`	string	Optional	max length 100
`state`	string	Optional	max length 100
`stateCode`	string	Optional	min length 2; max length 2
`pincode`	string	Optional	max length 10
`country`	string	Optional	max length 100
`shippingAddress`	object	Optional	—
`line1`	string	Optional	max length 255
`line2`	string	Optional	max length 255
`city`	string	Optional	max length 100
`state`	string	Optional	max length 100
`stateCode`	string	Optional	min length 2; max length 2
`pincode`	string	Optional	max length 10
`country`	string	Optional	max length 100
`notes`	any	Optional	—

Example request

curl -X POST "https://invoice.avscorp.in/api/v1/customers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "displayName": "Bansal Textiles Pvt Ltd",
  "email": "accounts@bansaltextiles.in",
  "gstin": "07AAACB1234C1Z5",
  "currencyCode": "INR"
}'

Example response

JSON

{
  "id": "clx1a2b3c4d5e6f7g8h9i0j1",
  "organizationId": "clx0org000000000000000001",
  "displayName": "Bansal Textiles Pvt Ltd",
  "legalName": "Bansal Textiles Private Limited",
  "email": "accounts@bansaltextiles.in",
  "phone": "9876543210",
  "gstin": "07AAACB1234C1Z5",
  "pan": "AAACB1234C",
  "currencyCode": "INR",
  "paymentTermId": "clxpt00000000000000000001",
  "paymentTermsDays": 30,
  "placeOfSupplyStateCode": "07",
  "billingAddress": {
    "line1": "12 Nehru Market",
    "line2": "Chandni Chowk",
    "city": "New Delhi",
    "state": "Delhi",
    "stateCode": "07",
    "pincode": "110006",
    "country": "India"
  },
  "shippingAddress": null,
  "openingBalance": 15000.5,
  "notes": "Prefers e-invoices before the 5th of every month.",
  "isActive": true,
  "tenantOrgId": null,
  "portalEnabled": false,
  "portalEnabledAt": null,
  "createdBy": "clxusr0000000000000000001",
  "updatedBy": "clxusr0000000000000000001",
  "createdAt": "2026-08-01T09:15:00.000Z",
  "updatedAt": "2026-08-20T11:42:00.000Z"
}

Possible errors: unauthorized, insufficient_scope, forbidden, validation_error

GET/api/v1/customers/{id}

Get a customer

Scope: customers.read

Parameters

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

Example request

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

Example response

JSON

{
  "id": "clx1a2b3c4d5e6f7g8h9i0j1",
  "organizationId": "clx0org000000000000000001",
  "displayName": "Bansal Textiles Pvt Ltd",
  "legalName": "Bansal Textiles Private Limited",
  "email": "accounts@bansaltextiles.in",
  "phone": "9876543210",
  "gstin": "07AAACB1234C1Z5",
  "pan": "AAACB1234C",
  "currencyCode": "INR",
  "paymentTermId": "clxpt00000000000000000001",
  "paymentTermsDays": 30,
  "placeOfSupplyStateCode": "07",
  "billingAddress": {
    "line1": "12 Nehru Market",
    "line2": "Chandni Chowk",
    "city": "New Delhi",
    "state": "Delhi",
    "stateCode": "07",
    "pincode": "110006",
    "country": "India"
  },
  "shippingAddress": null,
  "openingBalance": 15000.5,
  "notes": "Prefers e-invoices before the 5th of every month.",
  "isActive": true,
  "tenantOrgId": null,
  "portalEnabled": false,
  "portalEnabledAt": null,
  "createdBy": "clxusr0000000000000000001",
  "updatedBy": "clxusr0000000000000000001",
  "createdAt": "2026-08-01T09:15:00.000Z",
  "updatedAt": "2026-08-20T11:42:00.000Z"
}

Possible errors: unauthorized, insufficient_scope, forbidden, not_found

PATCH/api/v1/customers/{id}

Update a customer

Scope: customers.update

PATCH validates against the full customer schema (same as create) — displayName is required in every update, not just changed fields.

Parameters

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

Request body

Field	Type	Required	Constraints
`displayName`	string	Required	min length 1; max length 191
`legalName`	any	Optional	—
`email`	any	Optional	—
`phone`	any	Optional	—
`gstin`	any	Optional	—
`pan`	any	Optional	—
`currencyCode`	string	Optional	min length 3; max length 3; default "INR"
`paymentTermId`	any	Optional	—
`priceListId`	any	Optional	—
`salespersonId`	string	Optional	max length 30
`placeOfSupplyStateCode`	any	Optional	—
`openingBalance`	number	Optional	min 0; default 0
`billingAddress`	object	Optional	—
`line1`	string	Optional	max length 255
`line2`	string	Optional	max length 255
`city`	string	Optional	max length 100
`state`	string	Optional	max length 100
`stateCode`	string	Optional	min length 2; max length 2
`pincode`	string	Optional	max length 10
`country`	string	Optional	max length 100
`shippingAddress`	object	Optional	—
`line1`	string	Optional	max length 255
`line2`	string	Optional	max length 255
`city`	string	Optional	max length 100
`state`	string	Optional	max length 100
`stateCode`	string	Optional	min length 2; max length 2
`pincode`	string	Optional	max length 10
`country`	string	Optional	max length 100
`notes`	any	Optional	—

Example request

curl -X PATCH "https://invoice.avscorp.in/api/v1/customers/clx1a2b3c4d5e6f7g8h9i0j1" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "displayName": "Bansal Textiles Pvt Ltd",
  "email": "accounts@bansaltextiles.in",
  "gstin": "07AAACB1234C1Z5",
  "currencyCode": "INR",
  "phone": "9000011111"
}'

Example response

JSON

{
  "id": "clx1a2b3c4d5e6f7g8h9i0j1",
  "organizationId": "clx0org000000000000000001",
  "displayName": "Bansal Textiles Pvt Ltd",
  "legalName": "Bansal Textiles Private Limited",
  "email": "accounts@bansaltextiles.in",
  "phone": "9876543210",
  "gstin": "07AAACB1234C1Z5",
  "pan": "AAACB1234C",
  "currencyCode": "INR",
  "paymentTermId": "clxpt00000000000000000001",
  "paymentTermsDays": 30,
  "placeOfSupplyStateCode": "07",
  "billingAddress": {
    "line1": "12 Nehru Market",
    "line2": "Chandni Chowk",
    "city": "New Delhi",
    "state": "Delhi",
    "stateCode": "07",
    "pincode": "110006",
    "country": "India"
  },
  "shippingAddress": null,
  "openingBalance": 15000.5,
  "notes": "Prefers e-invoices before the 5th of every month.",
  "isActive": true,
  "tenantOrgId": null,
  "portalEnabled": false,
  "portalEnabledAt": null,
  "createdBy": "clxusr0000000000000000001",
  "updatedBy": "clxusr0000000000000000001",
  "createdAt": "2026-08-01T09:15:00.000Z",
  "updatedAt": "2026-08-20T11:42:00.000Z"
}

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

DELETE/api/v1/customers/{id}

Delete a customer

Scope: customers.delete

Parameters

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

Example request

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

Example response

JSON

{
  "deleted": true
}

Possible errors: unauthorized, insufficient_scope, forbidden, not_found

GET/api/v1/customers/{id}/ledger-pdf

Render the customer ledger statement as a PDF

Scope: customers.read

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

Parameters

Name	In	Type	Required	Description
`id`	path	string	Required	Customer ID.
`from`	query	string	Optional	Statement start date, YYYY-MM-DD. Omit for no lower bound.
`to`	query	string	Optional	Statement end date, YYYY-MM-DD. Omit for no upper bound.

Example request

curl "https://invoice.avscorp.in/api/v1/customers/clx1a2b3c4d5e6f7g8h9i0j1/ledger-pdf" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

Binary response — application/pdf. The ledger statement as a PDF, streamed inline with a Content-Disposition filename.

Possible errors: unauthorized, insufficient_scope, forbidden, not_found