Aalam Invoicer
API docs by Redocly

Invoicer (0.8.0)

Download OpenAPI specification:

Authentication

Every API request should be sent with a valid token. The token can be fetched by registering a remote application in your account's Settings -> Users & Groups -> Remote applications. The token of the remote application should be passed along with the header X-Auth-Token and also make sure the remote application is authorized with necessary permissions.

Bills

API related to the bill

Delete bill

Deletes a bill and all associated data.

This endpoint permanently removes the specified bill along with its items, add-ons, settlements, return associations, generated documents, and related stock claim (if any). Associated bill documents stored on the server are also removed.

Purchase and purchase-return bills can only be deleted by users authorized to manage purchase bills.

Features

  • Delete a bill by its identifier.
  • Remove all bill items and add-ons.
  • Remove bill settlements.
  • Remove return bill associations.
  • Delete associated stock claims.
  • Remove generated bill documents.
  • Record the deletion in the audit log.
  • Perform bill account cleanup asynchronously.

Notes

  • Requires Snp/delete-bill permission.
  • Purchase and purchase-return bills additionally require Snp/manage-purchase-bills permission.
  • This operation permanently deletes the bill and its related records.
  • Deleted bills cannot be recovered.

Permissions

Snp/delete-bill is needed

path Parameters
bill_id
required
integer

Identifier of the bill to delete.

Responses

Response samples

Content type
{
  • "message": "string"
}

Get bill details

Retrieves complete information about a bill.

A bill can be retrieved either by its unique identifier or by providing the bill number and bill type. The response includes bill information, customer details, purchased items, settlements, coupons, loyalty information, bill parameters, linked documents, and references to related bills.

The endpoint also supports returning the bill as a PDF document or returning tax-related information.

Features

  • Retrieve a bill using its identifier.
  • Retrieve a bill using bill number and bill type.
  • Return complete bill details in JSON format.
  • Generate the bill as a PDF.
  • Retrieve tax-specific information.
  • Include bill items, settlements, coupons, loyalty details, add-ons, parameters, and attached documents.
  • Include linked return bills and bills against which returns were created.
  • Customer-authenticated users can access only their own bills.
  • Purchase and purchase-return bills are available only to authorized users.

Notes

  • Either bill_id or both bill_number and bill_type must be provided.
  • Customer-authenticated requests are automatically restricted to the authenticated customer's bills.
  • PDF output is returned when format=pdf.
  • Tax information is returned when format=taxerinfo.
  • Requires Snp/access-bills permission for internal users.
  • Viewing purchase and purchase-return bills additionally requires Snp/manage-purchase-bills permission.
path Parameters
bill_id
integer

Identifier of the bill.

query Parameters
bill_number
string

Bill number used when bill_id is not provided.

bill_type
string

Bill type corresponding to the supplied bill number.

format
string
Enum: "pdf" "taxerinfo"

Response format. Omit this parameter to receive the complete bill information as JSON.

heading
string

Custom heading for the generated PDF.

subheading
string

Custom subheading for the generated PDF.

item_fields
string

Comma-separated list of item fields to include in the response.

params_barcode_fmt
string

Barcode format used while generating bill parameters.

Responses

Response samples

Content type
{
  • "addons": [
    ],
  • "against_bill": {
    },
  • "app_id": null,
  • "bill_number": "INV-1001",
  • "bill_type": "sale",
  • "cancelled": false,
  • "contact_addr_id": 5,
  • "contact_id": 12,
  • "contact_name": "John Doe",
  • "contact_wallet": 250.5,
  • "coupons": [
    ],
  • "created": "2026-08-05T09:15:00Z",
  • "created_by": "admin@example.com",
  • "documents": {
    },
  • "due_date": "2026-08-15T00:00:00Z",
  • "item_savings": {
    },
  • "items": [
    ],
  • "last_updated": "2026-08-05T09:30:42Z",
  • "last_updated_by": "admin@example.com",
  • "loyalty": [
    ],
  • "loyalty_last_updated": "2026-08-05T09:20:00Z",
  • "manual_disc": {
    },
  • "params": {
    },
  • "referring_bills": [
    ],
  • "settled": 1500,
  • "settlements": [
    ],
  • "shipping_addr_id": 8,
  • "total": 1500,
  • "total_logic": null
}

Update bill

Updates one or more properties of an existing bill.

This endpoint supports modifying bill information such as the bill number, bill date, due date, contact and shipping addresses, manual discounts, coupons, cancellation status, bill parameters, linked bills, and bill calculation logic.

Depending on the fields being updated, the bill may be automatically recalculated and the updated totals returned.

Features

  • Update one or more bill properties.
  • Change the bill number.
  • Update the bill creation date.
  • Update the due date.
  • Update billing and shipping addresses.
  • Apply or remove coupons.
  • Apply manual discount by percentage or amount.
  • Cancel or restore a bill.
  • Update custom bill parameters.
  • Change the linked (against) bill.
  • Convert a proforma bill.
  • Update bill calculation logic.
  • Automatically recalculate the bill when required.

Notes

  • Requires Snp/create-bill or Snp/modify-bill permission.
  • Purchase and purchase-return bills additionally require Snp/manage-purchase-bills permission.
  • Sale-return and purchase-return bills additionally require return authorization.
  • Updating the bill number is restricted to administrators or authorized users.
  • Parameters beginning with param. are treated as custom bill parameters.
  • When total_logic is supplied, logic_is_temp must also be supplied.
  • The response indicates whether the bill was recalculated.

Permissions

Any of the following permissions are needed

  • Snp/create-bill
  • Snp/modify-bill
path Parameters
bill_id
required
integer

Identifier of the bill to update.

query Parameters
contact
integer

Update the contact identifier.

bill_type
string

Update the bill type.

bill_number
string

Update the bill number.

created_on
string <date-time>

Update the bill creation date.

due_date
string <date-time>

Update the due date.

contact_addr_id
integer

Update the billing address.

shipping_addr_id
integer

Update the shipping address.

coupon
string

Apply or remove a coupon. Prefix the coupon code with - to remove it.

cancelled
boolean

Cancel or restore the bill.

discount_rate
number

Manual discount percentage.

discount_amount
number

Manual discount amount.

total_logic
string

Updated bill calculation logic.

logic_is_temp
boolean

Indicates whether the supplied logic is temporary.

against_bill_number
string

Link the bill using the bill number.

against_bill_id
integer

Link the bill using the bill identifier.

convert
boolean

Convert a proforma bill.

noclaim
boolean

Remove the associated stock claim.

noaccnt
boolean

Exclude the bill from accounting.

Responses

Response samples

Content type
application/json
{
  • "addons": {
    },
  • "recalc": true,
  • "total": 1540
}

Add items to a bill

Adds items and optional add-ons to an existing bill.

This endpoint updates an existing bill by adding one or more items and recalculating the bill totals, loyalty benefits, discounts, and applicable add-ons.

For sale-return bills, exchange items can also be supplied. In that case, the API automatically creates a new exchange sale bill, adds the supplied exchange items, optionally applies bill parameters and add-ons, and returns details of both the updated return bill and the newly created exchange bill.

Features

  • Add one or more items to an existing bill.
  • Add preset bill add-ons.
  • Automatically recalculate totals, discounts and loyalty.
  • Update stock claims when applicable.
  • Create an exchange invoice for sale-return bills.
  • Add exchange items, parameters and add-ons.
  • Return details of newly added bill rows.
  • Generate audit logs for all changes.

Notes

  • Requires Snp/create-bill or Snp/modify-bill permission.
  • At least one of items, addons, or exch_items must be supplied.
  • Exchange items are supported only for sale-return bills.
  • Purchase and purchase-return bills additionally require Snp/manage-purchase-bills permission.
  • Return bills require appropriate return permissions.

Permissions

Any of the following permissions are needed

  • Snp/create-bill
  • Snp/modify-bill
path Parameters
bill_id
required
integer

Identifier of the bill.

Request Body schema: application/json
required
addons
Array of objects

Preset add-ons to apply.

exch_addons
Array of objects

Add-ons for the exchange bill.

exch_items
Array of objects

Exchange items to create a new exchange bill. Applicable only for sale-return bills.

exch_params
object

Parameters for the exchange bill.

items
Array of objects

Items to add to the bill.

Responses

Request samples

Content type
application/json
{
  • "addons": [
    ],
  • "exch_addons": [
    ],
  • "exch_items": [
    ],
  • "exch_params": { },
  • "items": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "addons": {
    },
  • "loyalty": {
    },
  • "manual_disc_amnt": 0,
  • "new_rows": [
    ],
  • "total": {
    }
}

Recalculate bill

Recalculates the total amount of an existing bill.

This endpoint evaluates the bill using its configured bill-total logic, recalculates all applicable add-ons and totals, updates the bill's last modified information, and returns the updated values.

This operation does not add or remove bill items. It only recalculates the bill based on its current contents.

Features

  • Recalculate bill totals.
  • Re-evaluate configured bill total logic.
  • Recalculate preset add-ons.
  • Update the bill's last modified timestamp.
  • Update the user who performed the recalculation.

Notes

  • Requires Snp/create-bill or Snp/modify-bill permission.
  • The bill must exist.
  • Item quantities and bill rows are not modified.

Permissions

Any of the following permissions are needed

  • Snp/create-bill
  • Snp/modify-bill
path Parameters
bill_id
required
integer

Identifier of the bill to recalculate.

Responses

Response samples

Content type
application/json
{
  • "addons": {
    },
  • "total": 1560
}

Delete bill item

Deletes one or more item rows from an existing bill.

This endpoint removes either a specific bill item row or all item rows from the bill. After deletion, the bill is automatically recalculated, including totals, discounts, loyalty rewards, and applicable add-ons.

If the bill is linked to the stock module, the associated stock claim is updated or recreated as required.

Features

  • Delete a single bill item row.
  • Delete all bill item rows using *.
  • Automatically recalculate bill totals.
  • Update loyalty rewards and discounts.
  • Update or recreate stock claims.
  • Return the latest bill totals and add-ons.
  • Generate audit logs for the deletion.

Notes

  • Requires Snp/create-bill or Snp/modify-bill permission.
  • Purchase and purchase-return bills additionally require Snp/manage-purchase-bills permission.
  • Return bills require appropriate return permissions.
  • Specify * as the row identifier to delete all items from the bill.

Permissions

Any of the following permissions are needed

  • Snp/create-bill
  • Snp/modify-bill
path Parameters
bill_id
required
integer

Identifier of the bill.

row_id
required
string

Identifier of the bill item row.

Specify * to delete all item rows from the bill.

Responses

Response samples

Content type
application/json
{
  • "addons": {
    },
  • "item_savings": {
    },
  • "items": [
    ],
  • "last_updated": "2026-08-06T10:45:30Z",
  • "last_updated_by": "admin@example.com",
  • "loyalty": {
    },
  • "manual_disc_amnt": 0,
  • "offer": {
    },
  • "total": {
    }
}

Update bill item

Updates one or more items in an existing bill.

This endpoint allows modifying the details of bill items, such as quantity, price, discount, discount price, sales person, and other supported row attributes. The endpoint can update either a single bill row or multiple rows in a single request.

After updating the item(s), the bill is automatically recalculated. Any applicable bill add-ons, offers, loyalty benefits, manual discounts, and totals are recalculated before the response is returned.

If updating an item causes additional rows to be created (for example due to offer or bundle processing), the newly created rows are returned in the response.

Sale-return and purchase-return bills require return authorization before items can be modified.

Features

  • Update a single bill item.
  • Update multiple bill items in one request.
  • Automatically recalculate bill totals.
  • Recalculate discounts, offers, loyalty benefits, and add-ons.
  • Return newly created bill rows when applicable.
  • Record edit history for auditing.

Notes

  • Requires Snp/create-bill or Snp/modify-bill permission.
  • Updating return bills additionally requires return authorization.
  • When row_id is _, the rows request body is mandatory.
  • Purchase and purchase-return bills require purchase authorization.

Permissions

All of the following permissions are needed

  • Snp/create-bill
  • Snp/modify-bill
path Parameters
bill_id
required
integer

Identifier of the bill.

row_id
required
string

Identifier of the bill row to update.

Specify _ to update multiple rows using the rows request body.

Request Body schema: application/json
optional
rows
Array of objects

List of bill rows to update when row_id is _.

Responses

Request samples

Content type
application/json
{
  • "rows": [
    ]
}

Response samples

Content type
application/json
{
  • "addons": [
    ],
  • "loyalty": [
    ],
  • "manual_disc_amnt": 50,
  • "new_rows": [
    ],
  • "recalc": true,
  • "total": 1585
}

Send bill

Sends a bill to the associated contact using the configured communication service.

The bill is prepared and submitted for delivery using the contact's available communication channels, such as email, SMS, or WhatsApp, depending on the system configuration.

The communication request includes the bill details, a PDF version of the invoice as an attachment, and any applicable loyalty point information.

Features

  • Send a bill to the associated contact.
  • Automatically attach the bill as a PDF.
  • Include bill information for communication templates.
  • Include loyalty point information, when available.
  • Use the configured communication channels.
  • Return the communication service response.

Notes

  • Requires Snp/access-bills permission.
  • The bill must exist.
  • The communication response depends on the configured communication provider.
  • Delivery success depends on the availability of valid contact communication details.

Permissions

Snp/access-bills is needed

path Parameters
bill_id
required
integer

Identifier of the bill to send.

Responses

Response samples

Content type
application/json
{ }

Get bill summary

Retrieves a summarized view of a single bill.

This endpoint returns the bill's basic information along with optional sections such as items, settlements, add-ons, coupons, bill parameters, documents, and calculated savings depending on the query parameters supplied.

It is intended for applications that require a lightweight representation of a bill without retrieving the complete bill details.

Features

  • Retrieve summary information for a bill.
  • Include bill items.
  • Include settlement details.
  • Include bill add-ons.
  • Include coupon information.
  • Include bill parameters.
  • Include attached documents.
  • Include calculated item savings.
  • Include linked bill information for return bills.
  • Purchase and purchase-return bills are accessible only to authorized users.

Notes

  • Requires Snp/access-bills permission.
  • Viewing purchase and purchase-return bills additionally requires Snp/manage-purchase-bills permission.
  • When no query parameters are supplied, the response includes items, settlements, addons, and params by default.
  • Optional sections are included only when their corresponding query parameters are specified.

Permissions

Snp/access-bills is needed

path Parameters
bill_id
required
integer

Identifier of the bill.

query Parameters
items
boolean

Include bill items.

settlements
boolean

Include settlement details.

addons
boolean

Include bill add-ons and calculated item savings.

coupons
boolean

Include applied coupons.

params
boolean

Include bill parameters.

documents
boolean

Include attached bill documents.

item_savings
boolean

Include calculated item savings.

Responses

Response samples

Content type
application/json
{
  • "addons": [
    ],
  • "against_bill_date": "2026-08-01T11:00:00Z",
  • "against_bill_number": "INV-0988",
  • "against_invoice_id": 88,
  • "bill_number": "INV-1001",
  • "bill_type": "sale",
  • "contact_addr_id": 5,
  • "contact_id": 12,
  • "coupons": [
    ],
  • "created": "2026-08-05T09:15:00Z",
  • "created_by": "admin@example.com",
  • "documents": {
    },
  • "item_savings": {
    },
  • "items": [
    ],
  • "last_updated": "2026-08-05T09:30:42Z",
  • "last_updated_by": "admin@example.com",
  • "manual_disc": {
    },
  • "params": {
    },
  • "settled": 1500,
  • "settlements": [
    ],
  • "shipping_addr_id": 8,
  • "total": 1500
}

Get bills

Retrieves bills matching the supplied filters.

This endpoint returns bill details for sales, purchase, return, and other supported bill types based on the authenticated user's permissions. Customer-authenticated requests automatically return only bills belonging to the authenticated customer.

The response can be customized by selecting specific fields, filtering records, sorting results, limiting the number of returned records, or requesting summary information.

Features

  • Retrieve bills using multiple filter criteria.
  • Return only selected fields using the fields parameter.
  • Filter by customer, bill type, bill number, date, due date, settlement status, cancellation status, and custom parameters.
  • Filter bills containing specific items or sales persons.
  • Retrieve aggregate summary information using the summary parameter.
  • Sort results by supported fields.
  • Limit the number of returned records.
  • Include dynamic bill parameters using param.* or param.<parameter_name>.
  • Customer-authenticated users receive only their own bills.
  • Supports CSV/download mode for authorized internal users.

Notes

  • Requires Snp/access-bills permission.
  • Customer-authenticated users cannot use download mode.
  • Purchase and purchase-return bills are returned only to users authorized with Snp/manage-purchase-bills.
  • Invalid field names or unsupported sort fields result in a 400 Bad Request response.
  • The dues and settled filters cannot be used together.

Permissions

Snp/access-bills is needed

query Parameters
fields
string

Comma-separated list of fields to include in the response. Supports param.* and param.<parameter_name> for dynamic bill parameters.

contact
string

Filter by contact identifier.

bill_type
string

Comma-separated list of bill types to retrieve.

settled
boolean

Return only fully settled bills.

dues
boolean

Return only bills with pending dues.

cancelled
boolean

Filter by cancellation status.

due_date
string

Filter by due date.

date
string

Filter by bill creation date.

item_ids
string

Comma-separated list of item identifiers.

sp_ids
string

Comma-separated list of sales person identifiers.

sort
string

Sorting expression in the format <field>.asc or <field>.desc.

max
integer

Maximum number of records to return.

summary
boolean

Return bill summary grouped by bill type.

download
boolean

Generate a downloadable export instead of returning the bill list. Available only for authorized internal users.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Create bill

Creates a new bill.

This endpoint creates sales, purchase, return, quotation, and proforma bills. Bills can be created for an existing contact, a newly created contact, or against an existing bill for return and exchange workflows.

During creation, items, bill parameters, add-ons, coupons, exchange items, and related metadata can also be added. After successful creation, bill totals are calculated, audit logs are generated, pending bill parameters are checked asynchronously, and the bill can optionally be sent to the customer.

Features

  • Create sale, purchase, sale-return and purchase-return bills.
  • Create quotations and proforma invoices.
  • Create bills for existing or new contacts.
  • Create return bills against an existing bill.
  • Create exchange bills together with return bills.
  • Add bill items.
  • Add exchange items.
  • Add bill add-ons.
  • Add bill parameters.
  • Apply coupons.
  • Automatically generate bill numbers.
  • Optionally cancel previous outstanding invoices.
  • Optionally send the bill immediately after creation.
  • Automatically create stock claims when applicable.
  • Generate audit logs.

Notes

  • Requires Snp/create-bill or Snp/modify-bill permission.
  • Creating purchase and purchase-return bills additionally requires Snp/manage-purchase-bills permission.
  • Creating return bills additionally requires the return bill permission.
  • Either contact, contact_name, against_bill_id, or against_bill_number must be supplied.
  • quotation and proforma cannot be used together.
  • against_bill_number is supported only for return bills.
  • Exchange invoices are created only for sale-return bills that include exch_items.

Permissions

Any of the following permissions are needed

  • Snp/create-bill
  • Snp/modify-bill
query Parameters
quotation
string

Create a quotation.

proforma
boolean

Create a proforma invoice.

noclaim
boolean

Do not create a stock claim.

noaccnt
boolean

Skip accounting entry generation.

send
boolean

Send the bill after creation.

claim-exch
boolean

Create claim for exchange invoice.

accnt-exch
boolean

Generate accounting entry for exchange invoice.

Request Body schema: application/json
required
addons
Array of objects
against_bill_id
integer

Existing bill identifier for return/exchange bills.

against_bill_number
string

Existing bill number for return bills.

bill_number
string

Custom bill number.

bill_type
string
Enum: "sale" "purchase" "sale-return" "purchase-return"
cancel_old_invoices
boolean

Cancel previous unpaid invoices for the contact.

contact
integer

Existing contact identifier.

contact_name
string

Creates a new contact when contact is omitted.

coupon
string

Coupon code.

exch_addons
Array of objects
exch_items
Array of objects
exch_params
object
items
Array of objects
params
object

Responses

Request samples

Content type
application/json
{
  • "addons": [
    ],
  • "bill_type": "sale",
  • "contact": 12,
  • "coupon": "NEWYEAR25",
  • "items": [
    ],
  • "params": {
    }
}

Response samples

Content type
application/json
{
  • "id": 2451,
  • "new_rows": [
    ]
}

Export invoices

Exports invoices for the specified date range.

The from parameter is mandatory and specifies the start date/time of the export range.

The optional to parameter specifies the end date/time. If to is not provided, the current UTC date/time is used.

Additional request parameters are passed to the invoice export serializer and can be used to control the exported invoice data.

Permissions

Snp/access-bills is needed

query Parameters
from
required
string

Start date/time for the invoice export.

to
string

End date/time for the invoice export.

If not provided, the current UTC date/time is used.

Responses

Response samples

Content type
{
  • "message": "string"
}

Get output formats

Retrieves the list of available output formats that can be used to generate or print bills.

Output formats may be contributed by installed applications through extension hooks as well as by the built-in SNP module.

Each output format identifies the output type, the endpoint used to generate it, the application providing it, and whether it is currently configured as the default.

Features

  • Returns all available bill output formats.
  • Includes both PDF and print output formats.
  • Identifies the application providing each format.
  • Indicates the default output format for each type.
  • Includes built-in SNP output formats.

Notes

  • Requires authentication.
  • Built-in SNP output formats are always included.
  • Additional output formats may be contributed by installed applications.
  • The is_default field is present only for the configured default format of a given output type.

Permissions

  • Denied for anonymous users (Users / Apps not registered in the settings)

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Get print formats

Retrieves the list of available bill print formats.

Print formats are contributed by installed applications through registered hooks. Each entry contains metadata describing a print format along with the URL used to generate or preview it.

The exact fields returned depend on the application providing the print format.

Features

  • Retrieve all available bill print formats.
  • Includes print formats contributed by installed applications.
  • Returns metadata associated with each print format.
  • Used by clients to discover supported print layouts.

Notes

  • Requires an authenticated user.
  • Returns an empty array if no print formats are registered.

Permissions

  • Denied for anonymous users (Users / Apps not registered in the settings)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get bills summary

Retrieves summarized bill information matching the supplied filter criteria.

Unlike the bill listing endpoint, this API returns a compact representation of each bill including item summaries, add-ons, manual discounts, linked bills, and optionally settlement information. It is primarily intended for reporting, synchronization, analytics, and offline processing.

At least one filter parameter must be supplied to prevent accidental retrieval of the complete bill database.

Features

  • Retrieve summarized bill information.
  • Filter using supported bill fields.
  • Sort the results.
  • Limit the number of returned records.
  • Include bill items and calculated item savings.
  • Include manual discounts and add-ons.
  • Include linked return bill information.
  • Optionally include settlement details.
  • Purchase and purchase-return bills are returned only to authorized users.

Notes

  • Requires Snp/access-bills permission.
  • Viewing purchase and purchase-return bills additionally requires Snp/manage-purchase-bills permission.
  • At least one filter parameter must be supplied.
  • The settlements field is returned only when the settlements query parameter is specified.
  • When max is omitted, a maximum of 30 records are returned.
  • Only id, date, and total support sorting.

Permissions

Snp/access-bills is needed

query Parameters
contact
integer

Filter by contact identifier.

bill_number
string

Filter by bill number.

bill_type
string

Filter by bill type.

total
number

Filter by bill total.

settled
number

Filter by settled amount.

cancelled
boolean

Filter by cancellation status.

date
string

Filter by bill creation date.

updated_on
string

Filter by last update timestamp.

gen_updated_on
string

Filter by generated update timestamp.

sort
string

Sorting expression in the format <field>.asc or <field>.desc.

Supported fields are:

  • id
  • date
  • total
max
integer

Maximum number of bills to return.

settlements
boolean

Include settlement details for each bill.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get bill logic

Retrieves the bill total calculation logic configured for one or more bill types.

By default, the endpoint returns the logic configured for the sale bill type.

When bill_type=* is supplied, the endpoint returns the logic for all supported bill types.

The returned logic is converted into its human-readable form, where addon references are represented using addon titles instead of internal identifiers.

Supported bill types

  • sale
  • sale-return
  • purchase
  • purchase-return

Notes

  • Requires one of the following permissions:
    • Snp/create-bill
    • Snp/modify-bill
    • Snp/access-bills
  • If bill_type is omitted, sale is used.
  • Specify bill_type=* to retrieve the logic for all supported bill types.
  • Logic is returned in human-readable form.

Permissions

Any of the following permissions are needed

  • Snp/create-bill
  • Snp/modify-bill
  • Snp/access-bills
query Parameters
bill_type
string
Default: "sale"
Enum: "sale" "sale-return" "purchase" "purchase-return" "*"

Bill type whose calculation logic should be returned.

Specify * to retrieve the logic for all supported bill types.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Update bill logic

Updates the bill total calculation logic for a bill type.

The supplied logic is validated before being saved. If the logic contains syntax errors or references invalid addons, the request is rejected.

If the current logic is already associated with one or more existing bills, a new logic version is created. Otherwise, the existing logic definition is updated in place.

Any addon references used by the logic are automatically tracked.

Notes

  • Requires one of the following permissions:
    • Snp/create-bill
    • Snp/modify-bill
    • Snp/manage-addon
  • If bill_type is omitted, sale is used.
  • The supplied logic is validated before it is stored.
  • Existing bills continue using the logic version associated with them.
  • Addon references are automatically updated.

Permissions

Any of the following permissions are needed

  • Snp/create-bill
  • Snp/modify-bill
  • Snp/manage-addon
query Parameters
bill_total_logic
required
string

Bill total calculation logic.

bill_type
string
Default: "sale"
Enum: "sale" "sale-return" "purchase" "purchase-return"

Bill type whose calculation logic should be updated.

Responses

Response samples

Content type
{
  • "message": "string"
}

Get items summary

Retrieves bill transaction summaries for one or more items.

This endpoint returns every bill in which the specified item appears, together with the quantity sold or purchased, price, discount, discounted price, bill number, and bill date.

Multiple item identifiers can be supplied as a comma-separated list.

Features

  • Retrieve transaction history for one or more items.
  • Filter by contact.
  • Filter by bill settlement status.
  • Filter by bill type.
  • Filter using bill creation date or last updated date.
  • Sort the results.
  • Limit the number of returned records.
  • Purchase and purchase-return transactions are available only to authorized users.

Notes

  • Requires Snp/access-bill permission.
  • Multiple item IDs may be supplied as a comma-separated list.
  • Supported sort fields are id, date, and total.
  • Purchase and purchase-return bill types require Snp/manage-purchase-bills permission.
  • Invalid filter expressions or unsupported sort fields return 400 Bad Request.
path Parameters
item_id
required
string

Item identifier or comma-separated list of item identifiers.

query Parameters
contact
integer

Filter by contact identifier.

bill_type
string
Enum: "sale" "sale-return" "purchase" "purchase-return"

Bill type to retrieve.

settled
boolean

Filter by settlement status.

  • true returns fully settled bills.
  • false returns bills with pending balance.
bill_date
string

Filter by bill creation date.

updated_date
string

Filter by last updated timestamp.

sort
string

Sorting expression in the format <field>.asc or <field>.desc.

Supported fields are:

  • id
  • date
  • total
max
integer

Maximum number of records to return.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Get taxer info

Retrieves the tax provider configurations registered in the billing module.

Each configuration contains the tax provider URL, whether the provider expects tax-inclusive prices, and any additional contact fields required by the provider.

Features

  • Returns all registered tax provider configurations.
  • Includes the tax provider endpoint.
  • Indicates whether prices are tax inclusive.
  • Returns additional contact fields required by the provider.

Notes

  • Requires Snp/access-bills permission.
  • Additional contact fields are returned as key-value pairs.
  • For backward compatibility, the GSTIN provider automatically includes the GSTIN contact field when it is not already configured.

Permissions

Snp/access-bills is needed

Responses

Response samples

Content type
application/json
[]

Update taxer info

Updates the tax configuration for the authenticated internal application.

The configuration is stored for the calling application and is used by the billing module when integrating with external tax providers.

Features

  • Updates the tax provider URL.
  • Configures whether prices are tax inclusive.
  • Stores the configuration for the authenticated application.

Notes

  • Only authenticated internal applications can invoke this API.
  • External clients and users are not permitted.
  • The url parameter is mandatory.
  • The tax_inclusive parameter defaults to false when omitted.

Permissions

  • Allowed for all internal applications
query Parameters
url
required
string

URL of the tax provider service.

tax_inclusive
boolean
Default: false

Indicates whether bill prices should be treated as tax-inclusive.

Responses

Response samples

Content type
{
  • "message": "string"
}

Addons

API related to the addons

Delete addon

Deletes an existing bill addon.

If the addon is not referenced by any bill logic or other addons, it is permanently removed along with all of its logic versions.

If the addon is still referenced, it is not deleted. Instead, the system automatically renames the addon to a unique title so that existing references remain valid while preventing future use of the original title.

Notes

  • Requires Snp/manage-addon permission.
  • Referenced addons are renamed instead of being deleted.
  • Unreferenced addons are permanently removed.
  • All addon logic versions are deleted when the addon is permanently removed.

Permissions

Snp/manage-addon is needed

path Parameters
addon_id
required
integer

Identifier of the addon to delete.

Responses

Response samples

Content type
{
  • "message": "string"
}

Update addon

Updates an existing bill addon.

This endpoint allows updating one or both of the following:

  • Addon title.
  • Addon logic.

When the title is updated, the system verifies that no other addon already uses the same title.

When the logic is updated, the supplied logic is validated, checked for cyclic references, compiled into a new logic version, and stored as the latest version of the addon.

At least one of title or logic_code must be supplied.

Notes

  • Requires Snp/manage-addon permission.
  • Updating the title fails if another addon already has the same title.
  • Updating the logic creates a new version instead of modifying the existing one.
  • Logic is validated before being saved.
  • Cyclic addon references are not allowed.

Permissions

Snp/manage-addon is needed

path Parameters
addon_id
required
integer

Identifier of the addon to update.

query Parameters
title
string

New title for the addon.

logic_code
string

New addon calculation logic.

The supplied logic is validated before being stored. A new logic version is created if validation succeeds.

Responses

Response samples

Content type
{
  • "message": "string"
}

Get addons

Retrieves bill addons and their latest logic definitions.

By default, the endpoint returns all configured addons along with the latest version of their calculation logic.

When the search query parameter is supplied, the endpoint performs a title-based search and returns only matching addons.

The returned logic is converted into its human-readable form, where addon references are represented using addon titles instead of internal identifiers.

Notes

  • Requires one of the following permissions:
    • Snp/manage-addon
    • Snp/access-bills
    • Snp/create-bill
  • Supplying search requires the title_like parameter.
  • The latest logic version is returned for each addon.
  • Logic references are returned in human-readable form.

Permissions

Any of the following permissions are needed

  • Snp/manage-addon
  • Snp/access-bills
  • Snp/create-bill
query Parameters
search
boolean

Enables title-based addon search.

When specified, the title_like parameter becomes mandatory.

title_like
string

Searches for addons whose titles match the supplied value.

Required when search is specified.

max
integer

Maximum number of search results to return.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Create addon

Creates a new bill addon with the specified calculation logic.

The supplied logic is validated before the addon is created. If the logic is valid, an initial logic version is created and associated with the addon.

Features

  • Creates a new bill addon.
  • Validates the supplied addon logic.
  • Creates the initial logic version.
  • Stores logic references used by the addon.
  • Returns the identifier of the newly created addon.

Notes

  • Requires Snp/manage-addon permission.
  • The addon title must be unique.
  • The supplied logic must be syntactically valid.
  • The initial logic version is automatically created.

Permissions

Snp/manage-addon is needed

query Parameters
title
required
string

Name of the addon.

logic_code
required
string

Logic expression used to calculate the addon amount.

Responses

Response samples

Content type
application/json
{
  • "id": 12
}

Settlements

API related to the settlements

Delete bill settlement

Deletes a payment settlement associated with a bill.

Only users with payment management permission can delete a settlement entry.

If the settlement is linked to a return exchange or wallet payment, related settlement adjustments are handled automatically.

Notes

  • Requires one of the following permissions:
    • Snp/create-bill
    • Snp/modify-bill
    • Snp/manage-payments
  • Deleting settlements requires Snp/manage-payments permission.
  • bill_id and settlement_id must be numeric.
  • Returns 404 if the settlement does not exist for the given bill.

Permissions

Any of the following permissions are needed

  • Snp/create-bill
  • Snp/modify-bill
  • Snp/manage-payments
path Parameters
bill_id
required
integer

ID of the bill containing the settlement.

settlement_id
required
integer

ID of the settlement to delete.

Responses

Response samples

Content type
{
  • "message": "string"
}

Update bill settlement

Updates an existing settlement entry associated with a bill.

The API allows updating payment amount, payment mode, settlement date, instrument details, deposited date, notes, and user information.

Features

  • Update existing bill payment settlements.
  • Change payment amount and payment mode.
  • Update cheque/instrument details.
  • Update settlement notes.
  • Recalculates bill settled amount when required.
  • Updates related accounting and reward information.

Notes

  • Requires one of the following permissions:
    • Snp/create-bill
    • Snp/modify-bill
    • Snp/manage-payments
  • bill_id and settlement_id must be numeric.
  • At least one update parameter must be supplied.
  • Only supported settlement fields can be updated.
  • Updating amount, date, or mode requires payment management permission after the allowed update period.
  • Purchase and purchase-return settlements require purchase authorization.
  • System payment modes may restrict instrument number updates.

Permissions

Any of the following permissions are needed

  • Snp/create-bill
  • Snp/modify-bill
  • Snp/manage-payments
path Parameters
bill_id
integer

Identifier of the bill.

settlement_id
integer

Identifier of the settlement entry.

query Parameters
amount
number <float>

Updated settlement amount.

mode
string

Updated payment mode.

date
string <date-time>

Updated settlement date.

instr_date
string <date-time>

Updated instrument date.

instr_num
string

Updated instrument number.

instr_bank
string

Updated instrument bank name.

deposited_date
string <date-time>

Updated deposited date.

notes
string

Updated settlement notes.

user
string

User identifier associated with the update.

Responses

Response samples

Content type
{
  • "message": "string"
}

Delete all bill settlements

Deletes all payment settlement entries associated with a bill.

This API is mainly used by the e-commerce application to remove all settlements for a bill at once.

System payment modes are handled separately before removing all settlement records.

Notes

  • Requires one of the following permissions:
    • Snp/create-bill
    • Snp/modify-bill
    • Snp/manage-payments
  • Actual deletion requires Snp/manage-payments permission.
  • bill_id must be numeric.
  • The bill settlement amount is reset to zero after deletion.
  • Purchase bills require appropriate purchase authorization.

Permissions

Any of the following permissions are needed

  • Snp/create-bill
  • Snp/modify-bill
  • Snp/manage-payments
path Parameters
bill_id
required
integer

ID of the bill whose settlements should be deleted.

Responses

Response samples

Content type
{
  • "message": "string"
}

Create bill settlement

Adds a new payment settlement entry for a bill.

The settlement records the payment amount, payment mode, transaction details, and optional notes. The bill settled amount is updated after successful creation.

Features

  • Add payments against a bill.
  • Supports different payment modes.
  • Supports instrument details such as number, bank, and dates.
  • Automatically creates payment mode entries when allowed.
  • Generates payment received events for eligible bill types.

Notes

  • Requires one of the following permissions:
    • Snp/create-bill
    • Snp/modify-bill
    • Snp/manage-payments
  • amount and mode are mandatory.
  • Bill ID must be a numeric value.
  • Purchase and purchase-return bill settlements require purchase authorization.
  • Payments cannot be updated for quotation bills.
  • Settlement dates outside the allowed range require payment management permission.

Permissions

Any of the following permissions are needed

  • Snp/create-bill
  • Snp/modify-bill
  • Snp/manage-payments
path Parameters
bill_id
integer

Identifier of the bill.

query Parameters
amount
number <float>

Settlement amount.

mode
string

Payment mode.

date
string <date-time>

Settlement date.

instr_date
string <date-time>

Instrument date.

instr_num
string

Instrument number.

instr_bank
string

Instrument bank name.

deposited_date
string <date-time>

Date when payment instrument was deposited.

notes
string

Additional settlement notes.

noconvert
boolean

Prevent conversion of proforma bills during settlement.

Responses

Response samples

Content type
application/json
{
  • "id": 501,
  • "instr_id": 20
}

Delete payment mode

Deletes an existing custom payment mode.

The payment mode is deleted only if it is not a system-defined payment mode and is not currently being used.

Notes

  • Requires Snp/manage-payments permission.
  • System-defined payment modes cannot be deleted.
  • A payment mode that is already referenced cannot be deleted.
  • Deleting an unused payment mode succeeds without returning any data.

Permissions

Snp/manage-payments is needed

path Parameters
mode
string

Name of the payment mode to delete.

Responses

Response samples

Content type
{
  • "message": "string"
}

Create or update payment mode

Creates a new payment mode or renames an existing payment mode.

Specify _ as the mode path parameter to create a new payment mode. Otherwise, the specified payment mode is renamed to the value supplied in new_val.

Notes

  • Requires Snp/manage-payments permission.
  • The new_val parameter is mandatory.
  • Specify mode=_ to create a new payment mode.
  • Payment mode names must be unique.

Permissions

Snp/manage-payments is needed

path Parameters
mode
string

Payment mode to update.

Specify _ to create a new payment mode.

query Parameters
new_val
string

Name of the new or updated payment mode.

Responses

Response samples

Content type
{
  • "message": "string"
}

Get payment modes

Retrieves all configured user-defined payment modes available for billing and settlement operations.

Only custom payment modes are returned. System-defined payment modes are excluded from the response.

Notes

  • Requires Snp/access-bills permission.
  • Returns only non-system payment modes.
  • The response contains the payment mode names.

Permissions

Snp/access-bills is needed

Responses

Response samples

Content type
application/json
[
  • "Cash",
  • "UPI",
  • "Credit Card",
  • "Bank Transfer",
  • "Cheque"
]

Get bill settlements

Retrieves payment settlement records for bills.

Supports retrieving detailed settlement information, downloading settlement data as CSV, and generating settlement summaries grouped by payment mode and bill type.

Features

  • Retrieves settlement details with bill and contact information.
  • Supports filtering and sorting settlements.
  • Supports CSV download format.
  • Supports summary mode grouped by payment mode and bill type.

Notes

  • Requires Snp/access-bills permission.
  • Purchase and purchase-return settlements require purchase authorization.
  • The summary parameter returns aggregated settlement counts and amounts.
  • The download parameter returns settlement data in CSV format.
  • Invalid filters or sorting fields return a bad request error.

Permissions

Snp/access-bills is needed

query Parameters
download
boolean

Downloads settlement data in CSV format.

summary
boolean

Returns settlement summary grouped by payment mode and bill type.

bill_type
string
Enum: "sale" "sale-return" "purchase" "purchase-return"

Filters settlements by bill type.

reconciled
boolean

Filters settlements based on reconciliation status.

max
integer

Maximum number of settlement records to return.

sort
string

Sorting fields for settlement records.

Example: date.desc,id.desc

filter
string

Settlement filter expression.

Responses

Response samples

Content type
{ }

Attachments

API related to the settlements

Delete bill document

Deletes a document attached to a bill.

The document file is removed from storage and its metadata is removed from the bill document records.

Notes

  • Requires one of the following permissions:
    • Snp/create-bill
    • Snp/delete-bill
  • If the document does not exist, the API completes without error.
  • bill_id and doc_name identify the document to delete.

Permissions

Any of the following permissions are needed

  • Snp/create-bill
  • Snp/delete-bill
path Parameters
bill_id
required
integer

ID of the bill containing the document.

doc_name
required
string

Name of the document to delete.

Responses

Response samples

Content type
{
  • "message": "string"
}

Download bill document

Downloads a document attached to a bill.

The requested document file is returned from bill document storage.

Notes

  • Requires one of the following permissions:
    • Snp/access-bills
    • Snp/create-bill
    • Snp/delete-bill
  • bill_id and doc_name are required to identify the document.
  • Returns not found when the requested document does not exist.

Permissions

Any of the following permissions are needed

  • Snp/access-bills
  • Snp/create-bill
  • Snp/delete-bill
path Parameters
bill_id
required
integer

ID of the bill containing the document.

doc_name
required
string

Name of the document to download.

Responses

Response samples

Content type
{
  • "message": "string"
}

Attach documents to a bill

Uploads and attaches documents to an existing bill.

Documents are uploaded using multipart form data and stored against the specified bill. Existing document metadata is preserved when updating attachments.

Features

  • Supports uploading multiple documents.
  • Supports document descriptions.
  • Updates existing bill document attachments.
  • Stores document metadata for future retrieval.

Notes

  • Requires one of the following permissions:
    • Snp/create-bill
    • Snp/delete-bill
  • Request content type must be multipart/form-data.
  • bill_id must refer to an existing bill.
  • Invalid content types return a bad request error.

Permissions

Any of the following permissions are needed

  • Snp/create-bill
  • Snp/delete-bill
path Parameters
bill_id
required
integer

ID of the bill to attach documents to.

Request Body schema: multipart/form-data
required
property name*
additional property
string <binary>

Responses

Response samples

Content type
{
  • "message": "string"
}

Logs

API related to the logs

Get edit logs

Retrieves audit logs of changes made to bills and related operations.

The response includes information about the user or application that performed the action, the changed field, action type, remarks, and previous and updated values.

Features

  • Supports filtering edit logs.
  • Supports sorting by date.
  • Returns bill and contact details when filtering by bill is not used.

Notes

  • Requires Snp/access-bills permission.
  • Default limit is 50 records.
  • Invalid filter expressions return a bad request error.
  • Results are sorted by date ascending by default.
  • Use sort=date.desc to retrieve latest logs first.

Permissions

Snp/access-bills is needed

query Parameters
bill_id
integer

Filter logs by bill ID.

app_id
string

Filter logs by application ID.

user_id
string

Filter logs by user ID.

action
string

Filter logs by action type.

key
string

Filter logs by changed field key.

limit
integer
Default: 50

Maximum number of edit logs to return.

sort
string
Enum: "date.desc" "date.asc"

Sort order for logs based on date.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get items logs

Retrieves historical transaction details for specified items.

The response contains item quantities, prices, discounts, and discounted prices from bills before the specified date.

Features

  • Retrieves logs for multiple item IDs.
  • Supports filtering by bill type.
  • Supports retrieving records before a specific date.
  • Limits the number of returned records per item.

Notes

  • Requires Snp/access-bills permission.
  • item_ids parameter is mandatory.
  • Default bill type is sale.
  • Default maximum records per item is 10.
  • Invalid or missing item_ids returns a bad request error.

Permissions

Snp/access-bills is needed

query Parameters
item_ids
required
Array of integers

List of item IDs whose transaction logs should be retrieved.

bill_type
string
Default: "sale"
Enum: "sale" "sale-return" "purchase" "purchase-return"

Bill type used to filter item transactions.

from
string <date-time>

Retrieves transactions before this date.

max
integer
Default: 10

Maximum number of records returned per item.

Responses

Response samples

Content type
application/json
{
  • "property1": [
    ],
  • "property2": [
    ]
}

Get wallet logs

Retrieves wallet transaction history for a contact.

The API returns the current wallet balance along with wallet transaction details.

The contact_id path parameter can be:

  • A specific contact ID (requires bill management permission).
  • self to retrieve the authenticated customer's wallet logs.

Notes

  • self can only be used by authenticated customers.
  • Supports filtering and sorting wallet transactions.
  • Supports retrieving opening balance using opening_balance.
path Parameters
contact_id
required
string

Contact identifier.

Use self to retrieve the wallet logs of the authenticated customer.

query Parameters
opening_balance
string <date-time>

Date from which the opening wallet balance should be calculated.

max
integer

Maximum number of wallet transactions to return.

sort
string

Sorting order for wallet transactions.

Responses

Response samples

Content type
application/json
{
  • "current_balance": 0,
  • "logs": [
    ],
  • "opening_balance": 0
}

Stats

API related to the stats

Get stats

Retrieves billing statistics and analytical data for the dashboard.

The response contains overview details, item statistics, payment information, charges, salesperson performance, offers, loyalty points, and sales distribution by weekday and hour.

Notes

  • Requires Snp/view-stats permission.
  • Date range filters are mandatory.
  • Supports filtering by customers, items, item types, salespersons, offers, loyalty streams, weekdays, and hours.

Permissions

Snp/view-stats is needed

query Parameters
date_ge
string <date-time>

Start date of the statistics range.

date_le
string <date-time>

End date of the statistics range.

customer_nature
string
Enum: "new" "return"

Filter statistics by customer type.

new returns new customers. return returns returning customers.

item_ids
string

Comma-separated list of item IDs to filter statistics.

item_types
string

Comma-separated list of item type IDs.

sp_ids
string

Comma-separated list of salesperson IDs.

offer_ids
string

Comma-separated list of offer IDs.

stream_ids
string

Comma-separated list of loyalty/reward stream IDs.

weekday
string

Filter by weekdays.

Supports weekday names (sun, mon, etc.) or numbers from 1 to 7.

hour
string

Filter by hour of the day.

Valid values are between 0 and 23.

Responses

Response samples

Content type
application/json
{
  • "charges": { },
  • "hourly": { },
  • "item_types": { },
  • "loyalty_pnts": { },
  • "offers": { },
  • "overview": { },
  • "payments": { },
  • "sales_person": { },
  • "streams": { },
  • "weekday": { }
}

Get stats items

Retrieves item-level sales statistics including quantity, net sales amount, discounts, purchase amount, and return details.

The API supports filtering statistics by date ranges, bill type, items, and other supported statistics filters.

Multiple date ranges can be requested using range.<index> query parameters. When multiple ranges are provided, the response contains results grouped by each range key.

Notes

  • Requires Snp/view-stats permission.
  • Default bill type is sale.
  • Supports CSV download.
  • Supports sorting by quantity or net price.

Permissions

Snp/view-stats is needed

query Parameters
range.<index>
string

Date range filter.

Format: <from_date>;<to_date>

Example: range.0=2026-01-01;2026-01-31

Multiple ranges can be provided using different indexes.

date_ge
string <date-time>

Start date filter.

date_le
string <date-time>

End date filter.

bill_type
string

Bill type used for statistics.

Defaults to sale.

item_id
string

Comma-separated item IDs to filter.

sort
string
Enum: "qty" "net_pr"

Sort results.

qty sorts by quantity. net_pr sorts by net price.

max
integer

Maximum number of items to return.

download
boolean

Download statistics report.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Settings

API related to the settings

Get invoice headings

Retrieves the configured invoice headings and subheadings along with their default values.

Notes

  • Requires Snp/modify-bill or Snp/delete-bill permission.

Permissions

Any of the following permissions are needed

  • Snp/modify-bill
  • Snp/delete-bill

Responses

Response samples

Content type
application/json
{
  • "headings": {
    },
  • "subheadings": {
    }
}

Update invoice headings

Updates the available invoice headings and subheadings along with their default values.

Headings and subheadings can be added by specifying their names, or removed by prefixing the value with -.

Notes

  • Requires Snp/modify-bill or Snp/delete-bill permission.
  • The current default heading or subheading cannot be removed unless a new default is specified.

Permissions

Any of the following permissions are needed

  • Snp/modify-bill
  • Snp/delete-bill
Request Body schema:
required
default_heading
string

Default invoice heading.

default_subheading
string

Default invoice subheading.

headings
string

Comma-separated invoice headings.

Prefix a heading with - to remove it.

subheadings
string

Comma-separated invoice subheadings.

Prefix a subheading with - to remove it.

Responses

Request samples

Content type
{
  • "default_heading": "string",
  • "default_subheading": "string",
  • "headings": "string",
  • "subheadings": "string"
}

Response samples

Content type
{
  • "message": "string"
}

Get bill prefix

Retrieves the currently configured bill number prefix used when generating new bill numbers.

Notes

  • Requires Snp/modify-bill or Snp/delete-bill permission.

Permissions

Any of the following permissions are needed

  • Snp/modify-bill
  • Snp/delete-bill

Responses

Response samples

Content type
application/json
{
  • "value": "INV"
}

Update bill prefix

Updates the default prefix used when generating new bill numbers.

The updated prefix is stored in the application settings and is applied to newly created bills. Existing bill numbers are not modified.

Notes

  • Requires Snp/modify-bill or Snp/delete-bill permission.
  • The prefix parameter is mandatory.

Permissions

Any of the following permissions are needed

  • Snp/modify-bill
  • Snp/delete-bill
query Parameters
prefix
required
string

New bill prefix to use for subsequently generated bill numbers.

Responses

Response samples

Content type
{
  • "message": "string"
}

Update one-touch invoicing

Enables or disables the one-touch invoicing feature.

When enabled for the first time, a default Walkin Customer contact is automatically created if one does not already exist. The created contact ID is returned in the response.

Notes

  • Requires Snp/modify-bill or Snp/delete-bill permission.
  • Specify either enable or disable.
  • Both parameters cannot be supplied together.

Permissions

Any of the following permissions are needed

  • Snp/modify-bill
  • Snp/delete-bill
query Parameters
enable
boolean

Enables one-touch invoicing.

disable
boolean

Disables one-touch invoicing.

Responses

Response samples

Content type
application/json
{
  • "contact_id": 101
}

Get bill serial numbers

Retrieves the current bill prefix along with the next serial numbers that will be assigned to sale and sale-return bills.

Notes

  • Requires Snp/modify-bill or Snp/delete-bill permission.
  • The returned serial numbers represent the next values that will be assigned when new bills are created.

Permissions

Any of the following permissions are needed

  • Snp/modify-bill
  • Snp/delete-bill

Responses

Response samples

Content type
application/json
{
  • "bill_prefix": "INV",
  • "sale": 1025,
  • "sale-return": 78
}

Update bill serial numbers

Updates the next serial numbers used for bill generation.

You can update the next serial number for sale bills, sale-return bills, or both.

The values supplied become the next bill numbers that will be generated by the system.

Notes

  • Requires Snp/modify-bill or Snp/delete-bill permission.
  • At least one of sale or sale-return must be provided.

Permissions

Any of the following permissions are needed

  • Snp/modify-bill
  • Snp/delete-bill
Request Body schema:
required
sale
integer

Next serial number for sale bills.

sale-return
integer

Next serial number for sale-return bills.

Responses

Request samples

Content type
{
  • "sale": 0,
  • "sale-return": 0
}

Response samples

Content type
{
  • "message": "string"
}

Bill Due Date

API related to the bill fue date

Get bill due date settings

Retrieves the bill due date configuration along with all configured due date reminders.

The response includes the default due period, notification templates, notification time, and reminder schedules.

Notes

  • Requires Snp/modify-bill or Snp/delete-bill permission.

Permissions

Any of the following permissions are needed

  • Snp/modify-bill
  • Snp/delete-bill

Responses

Response samples

Content type
application/json
{
  • "due_days": 30,
  • "email": {
    },
  • "mobile": "Your payment is due.",
  • "reminders": [
    ],
  • "time": "10:00"
}

Update bill due date settings

Updates bill due date configuration and reminder schedule.

You can update:

  • Number of due days.
  • Reminder trigger time.
  • Existing reminder intervals.
  • Add new reminders.

Reminder indexes must remain continuous starting from 0.

When reminder days are modified, the corresponding communication events are automatically recreated and the reminder scheduler is refreshed.

Permissions

Any of the following permissions are needed

  • Snp/modify-bill
  • Snp/delete-bill
Request Body schema: application/json
required
due_days
integer

Number of days after which a bill becomes due.

Array of objects

Reminder configuration list.

Existing reminders are updated using their index. New reminders must include both index and days.

time
string

Daily time at which due-date reminders are processed.

Example: 09:00

Responses

Request samples

Content type
application/json
{
  • "due_days": 0,
  • "reminders": [
    ],
  • "time": "string"
}

Response samples

Content type
{
  • "message": "string"
}

Delete bill due date reminder

Deletes a bill due date reminder by its index.

After deletion:

  • The associated communication event is removed.
  • Remaining reminders are re-indexed to maintain consecutive indexes.
  • The updated reminder list is returned.

Permissions

Any of the following permissions are needed

  • Snp/modify-bill
  • Snp/delete-bill
path Parameters
reminder_index
required
integer

Index of the reminder to delete.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Roundoff

API related to the RoundOff

Get roundoff settings

Retrieves the configured invoice roundoff settings.

If no roundoff configuration exists, an empty object is returned.

Permissions

Any of the following permissions are needed

  • Snp/modify-bill
  • Snp/delete-bill

Responses

Response samples

Content type
application/json
{
  • "cutoffs": [
    ],
  • "scale": 0
}

Update roundoff settings

Updates invoice roundoff configuration.

A roundoff scale must always be provided. Optionally, one or more cutoff values can be configured for the selected scale.

Supported scale values are:

  • 0.1
  • 1
  • 10
  • 100
  • 1000
  • 10000

Permissions

Any of the following permissions are needed

  • Snp/modify-bill
  • Snp/delete-bill
Request Body schema: application/x-www-form-urlencoded
required
scale
required
number
Enum: 0.1 1 10 100 1000 10000

Roundoff scale.

property name*
additional property
number

Optional cutoff mapping.

Property names must follow the format:

cutoff.<value>

Example:

  • cutoff.0.5
  • cutoff.5

Each property's value specifies the rounded value to apply.

Responses

Response samples

Content type
{
  • "message": "string"
}

Coupons

API related to the Coupons

Delete coupon

Deletes an existing coupon identified by its coupon code.

The coupon cannot be deleted if it is already in use.

Notes

  • Requires Coupons/manage permission.
  • The coupon is identified by the code path parameter.
  • Returns a conflict if the coupon is currently in use.

Permissions

Coupons/manage is needed

path Parameters
code
required
string

Coupon code to delete.

Responses

Response samples

Content type
{
  • "message": "string"
}

Get coupon details

Retrieves the details of a coupon using its coupon code.

The response includes the coupon validity period, exclusivity, applicable users, discount configuration, usage limit, price restrictions, applicable items or item types, and optional discount ranges.

Permissions

Coupons/manage is needed

path Parameters
code
required
string

Coupon code.

Responses

Response samples

Content type
application/json
{
  • "description": "string",
  • "is_exclusive": true,
  • "item_types": [
    ],
  • "items": [
    ],
  • "max_sprice": 0,
  • "min_sprice": 0,
  • "price": 0,
  • "ranges": [
    ],
  • "rate": 0,
  • "rate_ceiling": 0,
  • "rule": 0,
  • "usage_limit": 0,
  • "users": [
    ],
  • "valid_from": "2019-08-24T14:15:22Z",
  • "valid_to": "2019-08-24T14:15:22Z"
}

Update coupon

Updates an existing coupon.

The API supports two operations:

  1. Update coupon details by providing one or more supported parameters.
  2. Check whether the coupon is valid for a specific contact by providing the check and contact parameters.

When updating users or items, positive IDs are added and negative IDs are removed.

When check is provided, no coupon update is performed. The API checks whether the coupon can be applied to the specified contact.

Notes

  • Requires Coupons/manage permission.
  • The coupon is identified by the code path parameter.
  • At least one update parameter must be supplied for a normal update.
  • rule=1 requires rate.
  • rule=2 requires price.
  • The coupon rule cannot be changed after the coupon has been used in a bill.

Permissions

Coupons/manage is needed

path Parameters
code
required
string

Coupon code to update or validate.

query Parameters
check
boolean

Checks whether the coupon is valid for a contact instead of updating the coupon.

When supplied, contact is mandatory.

contact
integer

Contact ID used when checking coupon validity.

Required when check is supplied.

users
string

Comma-separated contact IDs.

Positive IDs are added to the coupon. Negative IDs are removed from the coupon.

Example: users=101,102,-103

items
string

Comma-separated item IDs.

Positive IDs are added to the coupon. Negative IDs are removed.

Example: items=10,20,-30

item_types
string

Comma-separated item type IDs.

Positive IDs are added to the coupon. Negative IDs are removed.

valid_from
string <date-time>

Date and time from which the coupon becomes valid.

valid_to
string or null <date-time>

Date and time until which the coupon remains valid.

Set to an empty value to remove the expiry date.

is_exclusive
boolean

Whether the coupon is exclusive.

rule
integer
Enum: 1 2

Coupon discount rule.

1 = percentage/rate discount. 2 = fixed-price discount.

The rule cannot be changed if the coupon has already been used.

rate
number

Discount rate.

Required when rule=1.

price
number

Fixed discount price.

Required when rule=2.

min_sprice
number

Minimum sale price required for the coupon.

max_sprice
number

Maximum sale price to which the coupon applies.

rate_ceiling
number

Maximum discount rate/amount allowed.

ranges
string

Coupon discount ranges.

The value uses the coupon range representation expected by the API.

description
string

Description of the coupon.

usage_limit
integer

Maximum number of times the coupon can be used.

Responses

Response samples

Content type
application/json
null

Get coupon statistics

Retrieves statistics for the specified coupon for a given date range.

By default, statistics are returned grouped by date. When the date parameter is provided, statistics are returned bill-wise for that date.

Notes

  • Requires Coupons/manage permission.

  • Either from or date must be provided.

  • When date is provided, the response is returned bill-wise.

  • When date is not provided, the response is returned date-wise.

  • The to parameter can be used together with from to specify an end date.

  • If to is not provided, the from date is used as the end date.

  • Only positive coupon savings are included in the statistics.

  • Tagged under Coupons.

Permissions

Coupons/manage is needed

path Parameters
code
required
string

Coupon code for which statistics are requested.

Example: SAVE10

query Parameters
from
string <date>

Start date of the statistics period.

Either from or date must be provided.

Example: 2026-08-01

to
string <date>

End date of the statistics period.

Used together with from.

If omitted, the from date is used as the end date.

Example: 2026-08-08

date
string <date>

Specific date for which bill-wise coupon statistics are requested.

When this parameter is provided, the response contains one entry per bill instead of being grouped by date.

Example: 2026-08-08

Responses

Response samples

Content type
application/json
Example
[
  • {
    }
]

Search coupons

Retrieves a list of coupons.

Authorized users with Coupons/manage permission can search all coupons. Authenticated customers can search coupons associated with themselves.

Coupons can be filtered by ID, code, user, exclusivity, validity dates, and other supported filter expressions.

Results can also be sorted and limited.

Notes

  • Customers can only access coupons associated with their account.
  • Default maximum result count is controlled by the query parameters.
  • Supports sorting by id, code, and valid_from.
query Parameters
id
integer

Filter by coupon ID.

code
string

Filter by coupon code.

user
string

Filter by customer/contact ID. Multiple IDs can be supplied as a comma-separated value.

is_exclusive
boolean

Filter coupons by whether they are exclusive.

valid_from
string <date-time>

Return coupons whose validity starts on or after this date.

valid_to
string <date-time>

Return coupons that are valid until this date or have no expiry date.

sort
string

Sort results using comma-separated fields.

Supported fields are id, code, and valid_from.

Each field must use asc or desc.

Example: sort=valid_from.desc,code.asc

limit
integer

Maximum number of coupons to return.

max
integer

Alternative parameter for limiting the maximum number of results. Used when limit is not provided.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a coupon

Creates a new coupon with the specified discount rule and optional validity, usage, user, item, and price restrictions.

The code and rule fields are mandatory.

Rule 1 requires a rate, while rule 2 requires a price.

The coupon code may contain only letters, numbers, underscores, and hyphens, and cannot start with a hyphen.

Permissions

Coupons/manage is needed

Request Body schema: application/x-www-form-urlencoded
required
code
required
string

Unique coupon code.

description
string

Description of the coupon.

is_exclusive
boolean

Whether the coupon is exclusive.

item_types
string

Comma-separated item type IDs to which the coupon applies.

items
string

Comma-separated item IDs to which the coupon applies.

max_sprice
number

Maximum sale price allowed for the coupon.

min_sprice
number

Minimum sale price required to use the coupon.

price
number

Fixed discount price. Required when rule is 2.

Array of objects

Optional range-based coupon configuration.

rate
number

Discount rate. Required when rule is 1.

rate_ceiling
number

Maximum discount rate allowed.

rule
required
integer

Coupon discount rule. Rule 1 uses a percentage/rate discount. Rule 2 uses a fixed price discount.

usage_limit
integer

Maximum number of times the coupon can be used.

users
string

Comma-separated user IDs allowed to use the coupon.

valid_from
string <date-time>

Coupon validity start date and time.

valid_to
string <date-time>

Coupon validity end date and time.

Responses

Response samples

Content type
application/json
{
  • "id": 0
}

PDF

API related to the PDF

Generate bill PDF

Generates a PDF invoice for the specified bill.

The bill can optionally be generated with a custom heading and subheading. If no heading or subheading is provided, the configured default invoice heading and subheading are used.

The generated PDF includes the bill details, items, item properties, customer information, settlements, discounts, coupons, loyalty details, and other invoice information.

Query Parameters:

  • bill_id is mandatory.
  • heading is optional.
  • subheading is optional.

The endpoint may use a configured external PDF generator when one is configured. Otherwise, the PDF is generated internally.

Notes

  • Requires Snp/access-bills or Snp/create-bill permission.
  • Tagged under pdf.

Permissions

Any of the following permissions are needed

  • Snp/access-bills
  • Snp/create-bill
query Parameters
bill_id
required
integer

ID of the bill for which the PDF should be generated.

Example: bill_id=123

heading
string

Custom invoice heading.

If omitted, the configured default bill heading is used.

subheading
string

Custom invoice subheading.

If omitted, the configured default bill subheading is used.

Responses

Response samples

Content type
{
  • "message": "string"
}

Generate bill PDF for communications

Generates a PDF invoice for use by authorized communication services.

The request is allowed only for authenticated internal applications that are authorized to access the PDF generation service.

The generated response is a PDF file that can be downloaded and opened using a PDF viewer.

Notes

  • This endpoint is intended for internal communication applications.
  • Requests from unauthorized applications return 404 Not Found.
query Parameters
bill_id
required
integer

ID of the bill for which the PDF should be generated.

Example: bill_id=123

heading
string

Custom invoice heading.

If omitted, the configured default bill heading is used.

subheading
string

Custom invoice subheading.

If omitted, the configured default bill subheading is used.

Responses

Response samples

Content type
{
  • "message": "string"
}

Get PDF invoice logo

Retrieves the logo configured for PDF invoices.

If a PDF invoice logo is configured, the response returns the logo image file.

If no logo is configured, the response indicates that the logo should be redirected to the default application logo.

Notes

  • This endpoint does not require a specific permission.
  • The response is an image file when a logo is available.
  • The supported logo format is PNG.

Responses

Response samples

Content type
{
  • "message": "string"
}

Get PDF invoice resource

Retrieves PDF invoice resources and settings.

When resource is *, the response returns all configured PDF invoice resources, including the default print format, default PDF format, signature name, invoice terms, bank details, and URLs for the configured logo and signature.

When resource is logo or signature, the corresponding image file is returned.

Notes

  • Requires Snp/access-bills permission.
  • Use * to retrieve all PDF invoice settings.
  • Use logo to retrieve the invoice logo image.
  • Use signature to retrieve the invoice signature image.

Permissions

Snp/access-bills is needed

path Parameters
resource
required
string
Enum: "*" "logo" "signature"

PDF resource to retrieve.

* returns all configured PDF invoice settings and resource URLs.

logo returns the configured invoice logo as a PNG image.

signature returns the configured invoice signature as a PNG image.

Responses

Response samples

Content type
{
  • "bank_details": {
    },
  • "default_pdf_format": {
    },
  • "default_print_format": {
    },
  • "logo": "string",
  • "signature": "string",
  • "signature_name": "string",
  • "terms": "string"
}

Update PDF invoice settings

Updates the PDF invoice settings, including the invoice logo, signature, signature name, PDF format, print format, terms, and bank details.

The request must use multipart/form-data.

Notes

  • Requires Snp/create-bill permission.
  • Only the documented form-data fields are accepted.

Permissions

Snp/create-bill is needed

Request Body schema: multipart/form-data
required
bank_details
string

Bank details for the invoice.

Must contain a valid JSON object.

default_pdf_format
string

Default PDF invoice format.

default_print_format
string

Default print format for invoices.

logo
string <binary>

Invoice logo image.

signature
string <binary>

Invoice signature image.

signature_name
string

Name displayed with the invoice signature.

terms
string

Terms and conditions displayed on the invoice.

Responses

Response samples

Content type
{
  • "message": "string"
}

Sales Person

API related to the PDF

Assign salesperson to bill items

Assigns or removes a salesperson from specific items of a bill.

The row_ids parameter determines which bill items are affected.

Positive row IDs assign the specified salesperson to the corresponding bill items. Negative row IDs remove the salesperson assignment from those bill items.

Multiple row IDs can be provided as a comma-separated list.

Notes

  • Requires Snp/create-bill, Snp/modify-bill, or Snp/delete-bill permission.
  • The specified salesperson must exist.
  • The row_ids parameter is mandatory.
  • A positive row ID assigns the salesperson.
  • A negative row ID removes the salesperson assignment.
  • Users without Snp/modify-bill permission cannot modify an invoice item that already has a salesperson assigned.

Permissions

Any of the following permissions are needed

  • Snp/create-bill
  • Snp/modify-bill
  • Snp/delete-bill
path Parameters
bill_id
required
integer
Example: 123

ID of the bill whose items will be updated.

sid
required
integer
Example: 15

ID of the salesperson to assign to the bill items.

Request Body schema: application/x-www-form-urlencoded
required
row_ids
required
string

Comma-separated bill item row IDs.

Positive IDs assign the salesperson.

Negative IDs remove the salesperson assignment.

Example: row_ids=101,102,-103

In this example, salesperson 15 is assigned to rows 101 and 102, while the salesperson assignment is removed from row 103.

Responses

Response samples

Content type
{
  • "message": "string"
}

Delete a salesperson

Deletes an existing salesperson.

If the salesperson has not been associated with any bill items, the salesperson is permanently deleted.

If the salesperson is already associated with bill items, the salesperson is not permanently deleted. Instead, the salesperson is marked as deleted so that existing bill records remain intact.

Notes

  • Requires Snp/create-bill, Snp/modify-bill, or Snp/delete-bill permission.
  • The salesperson ID is provided in the URL path.
  • Existing bill records are preserved when the salesperson is already associated with bill items.

Permissions

Any of the following permissions are needed

  • Snp/create-bill
  • Snp/modify-bill
  • Snp/delete-bill
path Parameters
sid
required
integer
Example: 15

ID of the salesperson to delete.

Responses

Response samples

Content type
{
  • "message": "string"
}

Update a salesperson

Updates the name of an existing salesperson.

Notes

  • Requires Snp/create-bill, Snp/modify-bill, or Snp/delete-bill permission.
  • The name parameter is mandatory.
  • The salesperson must exist before it can be updated.
  • The salesperson ID is provided in the URL path.

Permissions

Any of the following permissions are needed

  • Snp/create-bill
  • Snp/modify-bill
  • Snp/delete-bill
path Parameters
sid
required
integer
Example: 15

ID of the salesperson to update.

Request Body schema: application/x-www-form-urlencoded
required
name
required
string <= 32 characters

New name for the salesperson.

Responses

Response samples

Content type
{
  • "message": "string"
}

Get salespersons

Retrieves a list of all active salespersons.

Salespersons that have been marked as deleted are excluded from the response.

Notes

  • Authentication is required.
  • Deleted salespersons are not included in the response.
  • The response contains the salesperson ID and name.

Permissions

  • Denied for anonymous users (Users / Apps not registered in the settings)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a salesperson

Creates a new salesperson with the specified name.

Notes

  • Requires Snp/create-bill, Snp/modify-bill, or Snp/delete-bill permission.
  • The name field is mandatory.
  • The salesperson name can contain up to 32 characters.
  • A unique salesperson ID is generated when the salesperson is created.

Permissions

Any of the following permissions are needed

  • Snp/create-bill
  • Snp/modify-bill
  • Snp/delete-bill
Request Body schema: application/x-www-form-urlencoded
required
name
required
string <= 32 characters

Name of the salesperson to create.

Responses

Response samples

Content type
application/json
{
  • "id": 15
}

Tally

API related to the Tally

Update Tally ledger name

Updates Tally ledger names for sales or purchase transactions.

Ledger names can be updated for item types, items, addons, and payment modes.

The txn parameter determines whether the ledger names are updated for sale or purchase transactions.

The subclass parameter determines whether the intra-state or inter-state ledger name is updated. It defaults to intra.

Ledger names are specified using parameter names with the following formats:

  • type.<type_id> for item types.
  • item.<item_id> for items.
  • addon.<addon_id> for addons.
  • paymode.<paymode_id> for payment modes.

Permissions

Any of the following permissions are needed

  • Snp/create-bill
  • Snp/modify-bill
  • Snp/delete-bill
query Parameters
txn
required
string
Enum: "sale" "purchase"

Transaction type.

sale updates sales ledger names. purchase updates purchase ledger names.

subclass
string
Default: "intra"
Enum: "intra" "inter"

Ledger name subclass to update.

intra updates the intra-state ledger name. inter updates the inter-state ledger name.

Defaults to intra.

type.<type_id>
string

Ledger name for an item type.

Replace <type_id> with the item type ID.

Example: type.10=Sales Ledger

item.<item_id>
string

Ledger name for an item.

Replace <item_id> with the item ID.

Example: item.125=Product Sales

addon.<addon_id>
string

Ledger name for an addon.

Replace <addon_id> with the addon ID.

Example: addon.5=Service Charges

paymode.<paymode_id>
string

Ledger name for a payment mode.

Replace <paymode_id> with the payment mode ID.

Example: paymode.1=CASH

Responses

Response samples

Content type
{
  • "message": "string"
}

Get Tally ledger names

Retrieves ledger names configured for item types, items, addons, and payment modes.

The ledger names are returned based on the transaction type (sale or purchase) and the IDs provided in the request.

At least one of the following parameters is required: type_ids, item_ids, addons, or paymodes.

The txn parameter is mandatory and must be either sale or purchase.

Notes

  • Requires Snp/create-bill, Snp/modify-bill, or Snp/delete-bill permission.
  • Ledger names are resolved separately for sales and purchases.
  • If a custom ledger name is not configured, the applicable default ledger name is returned.
  • For payment modes, CASH is used as the default ledger name for the cash payment mode; other payment modes default to BANK.
  • Multiple IDs can be provided as comma-separated values.

Permissions

Any of the following permissions are needed

  • Snp/create-bill
  • Snp/modify-bill
  • Snp/delete-bill
query Parameters
txn
required
string
Enum: "sale" "purchase"

Transaction type used to determine the ledger configuration.

Allowed values:

  • sale - Returns sales ledger names.
  • purchase - Returns purchase ledger names.
type_ids
string

Comma-separated item type IDs for which ledger names should be retrieved.

Example: type_ids=1,2,3

item_ids
string

Comma-separated item IDs for which ledger names should be retrieved.

Example: item_ids=101,102,103

addons
string

Comma-separated addon IDs for which ledger names should be retrieved.

Example: addons=1,2

paymodes
string

Comma-separated payment mode identifiers for which ledger names should be retrieved.

Example: paymodes=cash,card

Responses

Response samples

Content type
application/json
Example
{
  • "addons": {
    }
}

Loyalty

API related to the Loyalty

Dry run loyalty for a bill

Performs a dry run of loyalty point and reward calculations for an existing bill without applying the calculated results to the bill.

The request must provide at least one of point or reward. The supplied loyalty calculation logic is validated and then applied to the specified bill for simulation.

The response contains the calculated loyalty point results under point and reward results under reward.

The stream_id identifies the loyalty stream to use for the dry run. If stream_id is omitted, the default value is 0.

Permissions

Loyalty/manage is needed

path Parameters
bill_id
required
integer
Example: 1250

ID of the bill for which the loyalty calculation is simulated.

query Parameters
stream_id
integer
Default: 0
Example: stream_id=25

ID of the loyalty stream used for the dry run.

point
string
Example: point=...

Loyalty point calculation logic to be tested.

At least one of point or reward must be provided. The exact structure is validated by the loyalty point logic validator.

reward
string
Example: reward=...

Loyalty reward calculation logic to be tested.

At least one of point or reward must be provided. The exact structure is validated by the loyalty reward logic validator.

Responses

Response samples

Content type
application/json
{
  • "point": [
    ],
  • "reward": [
    ]
}

Get loyalty ledger

Returns the loyalty ledger entries for a customer.

The ledger can contain:

  • reward entries for loyalty points earned.
  • redeem entries for loyalty points redeemed.
  • discount entries for loyalty discounts applied to bills.

By default, up to 30 ledger entries are returned.

The endpoint supports filtering, sorting, and pagination using query parameters.

If the request is made by an authenticated customer, the ledger is automatically retrieved for that customer.

For non-customer authenticated users, contact_id can be supplied to retrieve the ledger for a specific customer.

query Parameters
contact_id
integer
Example: contact_id=125

Customer/contact ID whose loyalty ledger should be retrieved.

This parameter is used when the authenticated user is not a customer. For an authenticated customer, the endpoint automatically uses the authenticated customer's ID.

type
string
Enum: "reward" "redeem" "discount" "reward,redeem" "reward,discount" "redeem,discount" "reward,redeem,discount"
Example: type=reward,redeem

Filters the ledger by transaction type.

Supported values:

  • reward - Loyalty points earned.
  • redeem - Loyalty points redeemed.
  • discount - Loyalty discounts applied to bills.

Multiple types can be supplied as a comma-separated list.

If omitted, all supported transaction types are returned.

max
integer
Default: 30
Example: max=30

Maximum number of ledger entries to return.

sort
string
Default: "date.asc"
Enum: "date.asc" "date.desc"
Example: sort=date.desc

Sorts the ledger entries by date.

date.asc returns the oldest entries first.

date.desc returns the newest entries first.

id
integer
Example: id=1250

Filters the ledger by ledger entry ID.

date
string
Example: date=2026-08-09

Filters the ledger by ledger entry date.

ldgr_id
integer
Example: ldgr_id=1250

Filters by loyalty ledger entry ID.

ldgr_date
string
Example: ldgr_date=2026-08-09

Filters by loyalty ledger entry date.

bill_id
integer
Example: bill_id=5001

Filters ledger entries by bill ID.

Use 0 to retrieve ledger entries that are not associated with a bill.

bill_date
string
Example: bill_date=2026-08-09

Filters entries by bill creation date.

bill_xid
integer
Example: bill_xid=5001002

Filters entries using the combined bill/stream identifier.

bill_num
string
Example: bill_num=INV-10025

Filters by bill number.

stream_id
integer
Example: stream_id=25

Filters entries by loyalty stream ID.

Responses

Response samples

Content type
application/json
Example
{
  • "data": [
    ],
  • "next_page": null
}

Add loyalty points to a customer's ledger

Adds a loyalty points entry to the ledger for a customer.

The customer is identified using contact_id and the loyalty stream is identified using stream_id.

The points value represents the number of loyalty points to add. The ledger entry defaults to the reward direction if direction is not provided.

The rfrl_points and notes fields are optional.

If date is not provided, the current date and time are used.

The request requires the following fields:

  • contact_id
  • stream_id
  • points

The implementation converts contact_id, stream_id, and points to floating-point values before creating the ledger entry.

Permissions

Customers/manage is needed

query Parameters
contact_id
required
number <float>
Example: contact_id=125

ID of the customer/contact for whom the loyalty points should be added.

stream_id
required
number <float>
Example: stream_id=25

ID of the loyalty stream to which the points should be added.

points
required
number <float>
Example: points=100

Number of loyalty points to add to the customer's ledger.

rfrl_points
number <float>
Example: rfrl_points=10

Optional referral points associated with the ledger entry.

notes
string
Example: notes=Manual loyalty points adjustment

Optional notes to be stored with the ledger entry.

direction
string
Enum: "reward" "redeem"
Example: direction=reward

Direction of the loyalty ledger entry.

If omitted, the value defaults to reward.

date
string
Example: date=2026-08-09 18:30:00

Date and time of the ledger entry.

The value is interpreted using the user's configured timezone.

If omitted, the current date and time are used.

Responses

Response samples

Content type
application/json
{
  • "id": 456
}

Delete loyalty ledger

Deletes a loyalty points ledger entry identified by ledger_id.

A ledger entry can only be deleted if it has not been associated with a bill or settlement.

If the ledger entry is associated with a bill or settlement, the operation is rejected because generated ledger points cannot be modified.

Permissions

Customers/manage is needed

path Parameters
ledger_id
required
integer
Example: 456

ID of the loyalty ledger entry to delete.

Responses

Response samples

Content type
{
  • "message": "string"
}

Get loyalty status for a customer

Returns the loyalty status of a customer, including loyalty points earned and redeemed for each loyalty stream.

The response contains a points_map with the customer's loyalty point balances and a streams list containing the loyalty stream details.

For streams where the customer has received rewards in the past, the response also includes the corresponding past_rewards.

path Parameters
contact_id
required
integer
Example: 125

ID of the customer contact.

Responses

Response samples

Content type
application/json
{
  • "points_map": {
    },
  • "streams": [
    ]
}

Delete a loyalty stream

Deletes an existing loyalty stream using its stream ID.

If the loyalty stream has not been used and contains only a recent version, the stream and its associated version data are permanently removed.

If the loyalty stream has already been used in reward points or bills, or has multiple versions, the stream is not physically removed. Instead, it is marked as deleted by setting its valid_to timestamp.

The loyalty stream must exist before it can be deleted.

Permissions

Loyalty/manage is needed

path Parameters
stream_id
required
integer
Example: 25

ID of the loyalty stream to delete.

Responses

Response samples

Content type
application/json
{ }

Get loyalty stream details

Retrieves the complete details of a loyalty stream using its stream ID.

The response includes the loyalty stream configuration and metadata, including its point and reward logic, code, description, creation date, last updated date, pause date, and deletion date when applicable.

The stream must exist and must be a loyalty stream.

Permissions

Loyalty/manage is needed

path Parameters
stream_id
required
integer
Example: 25

ID of the loyalty stream.

Responses

Response samples

Content type
application/json
{
  • "code": "LOYALTY10",
  • "created_on": "2026-08-09T10:30:00Z",
  • "deleted_on": null,
  • "description": "Standard customer loyalty program",
  • "id": 25,
  • "last_updated_on": "2026-08-09T12:15:30Z",
  • "paused_on": null,
  • "point": {
    },
  • "reward": { }
}

Update loyalty stream

Updates an existing loyalty stream.

The endpoint can be used to update the loyalty stream code, description, point calculation logic, reward calculation logic, or to pause/resume the loyalty stream.

Only the fields provided in the request are updated. When point or reward logic is updated, the new logic is validated before a new loyalty stream version is created.

The pause parameter pauses the loyalty stream, while the resume parameter resumes a previously paused stream.

If only code or description is updated, the endpoint does not return a response body.

Permissions

Loyalty/manage is needed

path Parameters
stream_id
required
integer
Example: 25

ID of the loyalty stream to update.

Request Body schema: application/x-www-form-urlencoded
required
code
string

New code for the loyalty stream. The code must be unique.

description
string

New description for the loyalty stream.

pause
boolean

Pauses the loyalty stream.

When provided, the current reward logic is disabled while preserving the previous reward configuration.

point
string

New point calculation logic for the loyalty stream. The supplied logic is validated before the update is applied.

resume
boolean

Resumes a previously paused loyalty stream.

reward
string

New reward calculation logic for the loyalty stream. The supplied logic is validated before the update is applied.

Responses

Request samples

Content type
application/x-www-form-urlencoded
Example
pause=true

Response samples

Content type
application/json
{ }

Get loyalty stream stats

Returns statistics for a loyalty stream for the requested date range.

The fields parameter controls which type of statistics is returned.

Supported values:

  • sale - Returns sales and loyalty savings statistics.
  • points - Returns loyalty points statistics.

The default value of fields is sale,points.

Note: Based on the current implementation, when fields contains sale, the sale statistics are returned and the points statistics are not processed because the implementation uses elif for points.

The loyalty stream is identified using stream_id.

Permissions

Loyalty/manage is needed

path Parameters
stream_id
required
integer
Example: 25

ID of the loyalty stream.

query Parameters
from
required
string
Example: from=2026-08-01

Start date of the statistics period.

The date is interpreted using the user's configured timezone.

to
string
Example: to=2026-08-09

End date of the statistics period.

If omitted, the current date is used.

fields
string
Enum: "sale" "points" "sale,points"
Example: fields=sale

Specifies which statistics should be returned.

sale returns sales-related loyalty statistics.

points returns loyalty point statistics.

The default value is sale,points.

With the current implementation, if sale is included, the points branch is not executed.

Responses

Response samples

Content type
application/json
Example
{
  • "points": [
    ]
}

Get loyalty streams

Retrieves loyalty streams based on the specified filters.

The endpoint returns loyalty stream details including the stream ID, code, description, validity period, exclusive status, and paused date.

Loyalty streams can be filtered by status, validity date, deletion status, and other supported filter fields.

Supported status values:

  • active: Returns streams that are not paused and have not expired.
  • paused: Returns streams that are currently paused.
  • expired: Returns streams whose validity period has ended.

Results can be sorted by valid_from, code, or id in ascending or descending order.

Permissions

Loyalty/manage is needed

query Parameters
status
string
Enum: "active" "paused" "expired"

Filters loyalty streams by their current status.

valid_from
string

Returns loyalty streams whose valid_from date is greater than or equal to the specified date.

deleted
boolean

When provided, filters loyalty streams that have a valid_to value.

sort
string

Sorts the results using one or more fields.

Supported fields:

  • valid_from
  • code
  • id

Each field must be followed by .asc or .desc.

Multiple sort fields can be separated by commas.

Example: sort=valid_from.desc,code.asc

max
integer

Maximum number of loyalty streams to return.

id
string

Filters loyalty streams by their ID.

code
string

Filters loyalty streams by their code.

is_exclusive
boolean

Filters loyalty streams based on whether they are exclusive.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Create loyalty stream

Creates a new loyalty stream with the specified code and loyalty calculation logic.

The code parameter is mandatory and must contain only letters, numbers, underscores, and hyphens. The code cannot start with a hyphen.

At least one of point or reward must be provided.

The point and reward logic are validated before the loyalty stream is created. A unique loyalty stream code is also required.

If the loyalty stream is created successfully, the endpoint returns the ID of the newly created loyalty stream.

Permissions

Loyalty/manage is needed

Request Body schema: application/x-www-form-urlencoded
required
code
required
string

Unique code for the loyalty stream.

Allowed characters are letters, numbers, underscores, and hyphens. The code cannot start with a hyphen.

description
string

Description of the loyalty stream.

is_exclusive
boolean

Indicates whether the loyalty stream is exclusive.

point
string

Point calculation logic used to calculate loyalty points. The value is validated by the loyalty logic processor.

reward
string

Reward calculation logic used to determine the reward. The value is validated by the loyalty reward logic processor.

Responses

Response samples

Content type
application/json
{
  • "id": 25
}

Customers

API related to the Customers

Get contact

Returns the details of a customer contact, including the customer's name, tags, wallet balance, referral information, default billing and shipping addresses, and loyalty points.

The contact_id path parameter supports three modes:

  • A numeric customer ID - Returns details for the specified customer.
  • self - Returns details for the currently authenticated customer. When using self, only public customer tags are returned.
  • * - Returns a list of customers. This mode requires administrative access or Customers/manage permission.

When * is used, the optional download parameter can be supplied to request the customer data as a downloadable result.

path Parameters
required
integer or string
Example: 125

Customer identifier.

Use a numeric ID to retrieve a specific customer, self to retrieve the authenticated customer's details, or * to retrieve multiple customers when the caller has the required permissions.

query Parameters
download
string
Example: download=true

When contact_id is *, supplying this parameter requests the customer data in downloadable form.

Other query parameters can be supplied along with download and are passed to the customer query.

Responses

Response samples

Content type
application/json
{
  • "contact_addr_id": 102,
  • "loyalty": [
    ],
  • "name": "John Doe",
  • "referrals": [ ],
  • "referred_by": {
    },
  • "shipping_addr_id": 103,
  • "tags": [
    ],
  • "wallet_balance": 2500
}

Update contact

Updates one customer contact setting using the specified parameter.

The endpoint supports the following operations:

  • tags - Adds, removes, or changes the visibility of customer tags.
  • rfrd_by - Sets the customer who referred this customer.
  • contact_addr_id - Sets the default billing address for the customer.
  • shipping_addr_id - Sets the default shipping address for the customer.
  • wallet_topup - Adds money to the customer's wallet or updates an existing wallet transaction.

Only one supported operation is processed per request. If multiple supported parameters are supplied, the first matching operation in the implementation is processed.

For tags:

  • A tag without a prefix is added as a private tag.
  • A tag prefixed with + is added as a private tag.
  • A tag prefixed with @ is added as a public tag.
  • A tag prefixed with - is removed.

For wallet_topup, notes is mandatory when creating a new wallet top-up. If both wallet_bill_id and wallet_settlement_id are supplied, the existing wallet transaction is updated instead.

Permissions

Customers/manage is needed

path Parameters
contact_id
required
integer
Example: 125

ID of the customer contact to update.

query Parameters
tags
string
Example: tags=VIP,@WHOLESALE,-OLD_CUSTOMER

Comma-separated list of tags to add, make public, or remove.

Tag prefixes:

  • tag or +tag - Add a private tag.
  • @tag - Add a public tag.
  • -tag - Remove the tag.

This parameter cannot be empty.

rfrd_by
integer
Example: rfrd_by=450

Customer contact ID of the customer who referred this customer.

contact_addr_id
integer
Example: contact_addr_id=102

ID of the address to use as the customer's default billing address.

shipping_addr_id
integer
Example: shipping_addr_id=103

ID of the address to use as the customer's default shipping address.

wallet_topup
number <float>
Example: wallet_topup=1000

Amount to add to the customer's wallet.

If wallet_bill_id and wallet_settlement_id are not supplied, the notes parameter is also required and a new wallet top-up transaction is created.

wallet_bill_id
integer
Example: wallet_bill_id=2500

Existing bill ID associated with the wallet transaction.

Used together with wallet_settlement_id to update an existing wallet transaction instead of creating a new one.

wallet_settlement_id
integer
Example: wallet_settlement_id=750

Existing settlement ID associated with the wallet transaction.

Used together with wallet_bill_id to update an existing wallet transaction instead of creating a new one.

notes
string
Example: notes=Wallet top-up received from customer

Notes for the wallet top-up.

This parameter is mandatory when creating a new wallet top-up without wallet_bill_id and wallet_settlement_id.

Responses

Response samples

Content type
application/json
{
  • "bill_id": 2500,
  • "settled": 1000,
  • "total": 1000
}

Update customer tag

Renames an existing customer tag.

Both the existing tag name and the new tag name are converted to uppercase before the update is performed.

The rename parameter is mandatory. The update changes all customer tag records matching the specified tag_name.

Permissions

Customers/manage is needed

path Parameters
tag_name
required
string
Example: VIP

Name of the customer tag to rename.

The tag name is converted to uppercase before the update.

query Parameters
rename
required
string
Example: rename=PREMIUM

New name for the customer tag.

The new tag name is converted to uppercase before the update.

Responses

Response samples

Content type
application/json
{ }

Get customer tags

Returns the customer tags available in the system along with the number of customers associated with each tag.

The tag parameter can be used to filter the results.

Results are grouped by tag and include the number of customers associated with each tag.

Permissions

Customers/manage is needed

query Parameters
tag
string
Example: tag=VIP

Filter customer tags using the supported query filter syntax.

If omitted, all customer tags are returned.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]