External API reference

Paginated, filterable list of products for your business.

Copy{
  "success": true,
  "count": 2, "total": 42, "page": 1, "pages": 3,
  "data": [
    { "_id": "66f1...", "description": "Blue Widget",
      "unitPrice": 199, "barcode": "GST00000123", … }
  ]
}

ref is a product's Mongo _id or its barcode — barcode is tried automatically when ref isn't a valid id. Pass ?by=false to require an exact _id match only.

Only description and unitPrice are required. Submitting the same name + price + labels again returns the existing product (200, alreadyExists: true) rather than duplicating it; if the price or labels differ you get a 409 — resend with forceCreateSeparate: true to create a separate product anyway. Omit barcode to have one assigned automatically.

Copy{
  "description": "Blue Widget",
  "unitPrice": 199,
  "gstRate": 18,
  "hsnCode": "8471",
  "category": "Hardware"
}

Copy{
  "success": true,
  "data": {
    "_id": "66f1a2...",
    "description": "Blue Widget",
    "unitPrice": 199,
    "barcode": "GST00000481", …
  }
}

multipart/form-data, field name images — up to 5 files per request, 5 per product total. JPEG, PNG, GIF, or WEBP, 5MB max each. Identical images (by content hash) are skipped as duplicates rather than rejected.

Copycurl -X POST \
  .../products/GST00000481/images \
  -H "X-API-Key: gstly_sk_..." \
  -F "[email protected]"

Copy{
  "success": true,
  "data": {
    "added": 1,
    "images": [{ "url": "https://…" }],
    "skippedDuplicates": [],
    "skippedCapacity": []
  }
}

Filter by status, billType, invoiceType, date range, and more — see the OpenAPI spec for the full parameter list.

Fetch one invoice by its Mongo _id.

The canonical JSON projection the PDF and QR code are built from — the recommended shape to parse programmatically, since it's guaranteed to agree with what a human sees on the document (statutory fields, GST summary, amount-in-words).

Creates a draft invoice — nothing is legally final until you publish it. No pre-existing customer record is required; one is resolved or created automatically from customerDetails.name at publish time.

Copy{
  "customerDetails": { "name": "Acme Corp" },
  "items": [{
    "description": "Blue Widget",
    "quantity": 2, "unitPrice": 199,
    "gstRate": 18
  }]
}

Copy{
  "success": true,
  "data": {
    "_id": "66f1b7...",
    "invoiceNumber": "INV-202608-000042",
    "status": "draft", …
  }
}

Same body shape as create. Editing a published invoice's items or other significant fields automatically reverts it to draft and reverses any stock deducted — it must be re-published. Paid and cancelled invoices can't be updated.

draft → published — the step that makes it a legal invoice. Requires the business name/address/GSTIN to be resolvable and at least one complete line item; 400 with a field-by-field list otherwise. Deducts stock for items linked to a productId.

Reverses a publish and any stock it deducted. Only valid from published.

Only valid from published. Paid invoices are immutable afterward.

Copy{ "paymentMethod": "upi" }

Only valid from published — paid invoices can't be cancelled. Reverses any stock deducted at publish.