{"openapi":"3.1.0","info":{"title":"NegoBill API","version":"1.0.0","description":"Create sales, contacts and payments in a NegoBill business from your own software. Money is integer paise; times are ISO 8601 UTC. Every call needs the API Access add-on on the business and a key with the scope named on the operation."},"servers":[{"url":"https://api.negobill.com/v1"}],"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic","description":"Key ID as the username, Key Secret as the password: Authorization: Basic base64(keyId:keySecret)."}},"schemas":{"Error":{"type":"object","properties":{"status":{"type":"boolean","const":false},"statusCode":{"type":"integer"},"code":{"type":"string","description":"NB-B-<MODULE>-<nnnn>, see the error table."},"message":{"type":"string"},"correlationId":{"type":"string"},"details":{"description":"Field-level issues or figures, when the code has them."}},"required":["status","statusCode","code","message","correlationId"]}}},"paths":{"/me":{"get":{"summary":"Who am I","description":"Confirms the credentials and tells you which business, store and billing profile this key acts for. The quickstart call. Required scope: contacts:read.","security":[{"basicAuth":[]}],"tags":["me"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"boolean","const":true},"statusCode":{"type":"integer"},"correlationId":{"type":"string"},"results":{"type":"object","properties":{"business":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-fA-F]{24}$","description":""},"name":{"type":"string","description":""}},"description":""},"store":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-fA-F]{24}$","description":""},"name":{"type":"string","description":""},"timezone":{"type":"string","description":"IANA zone, e.g. Asia/Kolkata."}},"description":"The store every sale made with this key belongs to."},"billingProfile":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-fA-F]{24}$","description":""},"legalName":{"type":["string","null"],"description":""},"gstNumber":{"type":["string","null"],"description":"When null the business issues BILLs only; INVOICE is refused."}},"description":""},"plan":{"type":"object","properties":{"code":{"type":"string","description":"STARTER, STANDARD or PRO."},"label":{"type":"string","description":""}},"description":""},"key":{"type":"object","properties":{"keyId":{"type":"string","description":""},"label":{"type":"string","description":""},"scopes":{"type":"string","description":""},"environment":{"type":"string","description":"LIVE or TEST."}},"description":""}}}},"required":["status","statusCode","correlationId","results"]},"example":{"status":true,"statusCode":200,"correlationId":"2f6c1e0a9b3d4","results":{"business":{"id":"66f1a2b3c4d5e6f7a8b9c0a0","name":"Kiran Super Mart"},"store":{"id":"66f1a2b3c4d5e6f7a8b9c0a1","name":"Main store","timezone":"Asia/Kolkata"},"billingProfile":{"id":"66f1a2b3c4d5e6f7a8b9c0a2","legalName":"Kiran Super Mart","gstNumber":"33AAAAA0000A1Z5"},"plan":{"code":"BUSINESS","label":"Business"},"key":{"keyId":"nbk_live_Ab3dEf6hIj9kLm2n","label":"Shopify connector","scopes":["contacts:read","sales:write"],"environment":"LIVE"}}}}}},"4XX":{"description":"Error envelope (see components.schemas.Error).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/contacts":{"post":{"summary":"Find or create a contact","description":"Looks for an existing contact by reference, then by gstNumber, then by phone; a match is returned with created:false (and takes your reference if it had none). Otherwise the contact is created and returned with created:true. Phone and GST number are unique within a business, which is why matching comes first. Required scope: contacts:write.","security":[{"basicAuth":[]}],"tags":["contacts"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":80},"description":"Makes the call safe to retry: the same key with the same body returns the stored answer; a different body under the same key is refused (409)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reference":{"type":"string","description":"Your own id for this contact, 1–80 characters. Unique within the business."},"name":{"type":"string","description":"Required unless phone is given. Max 300."},"businessName":{"type":"string","description":"Max 500."},"phone":{"type":"string","description":"Digits only, national number without the country code, 4–15 digits. Required unless name is given."},"phoneCountryCode":{"type":"string","description":"Digits without +, default the store country's (India: \"91\")."},"email":{"type":"string","description":"Max 200."},"gstNumber":{"type":"string","description":"15-character GSTIN. Its first two digits are the state code; a contradicting address.stateCode is refused."},"roles":{"type":"string","description":"Each CUSTOMER or SUPPLIER. Default [\"CUSTOMER\"]."},"address":{"type":"object","properties":{"line1":{"type":"string","description":""},"line2":{"type":"string","description":""},"city":{"type":"string","description":""},"district":{"type":"string","description":""},"state":{"type":"string","description":""},"stateCode":{"type":"string","description":"2 digits."},"pincode":{"type":"string","description":"6 digits."}},"description":""},"note":{"type":"string","description":"Max 300."}}},"example":{"reference":"cust-1001","name":"Asha Stores","phone":"9876543210","email":"asha@example.com","gstNumber":"33ABCDE1234F1Z5","address":{"line1":"12 Market Road","city":"Chennai","state":"Tamil Nadu","pincode":"600001"}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"boolean","const":true},"statusCode":{"type":"integer"},"correlationId":{"type":"string"},"results":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-fA-F]{24}$","description":"The contact id. Use it as contactId on a sale."},"name":{"type":["string","null"],"description":""},"businessName":{"type":["string","null"],"description":"Registered name, if a business."},"phone":{"type":["string","null"],"description":"Digits only, national number."},"phoneCountryCode":{"type":["string","null"],"description":"Dialling code without +, e.g. \"91\"."},"email":{"type":["string","null"],"description":""},"gstNumber":{"type":["string","null"],"description":"15-character GSTIN."},"roles":{"type":"string","description":"Each one of CUSTOMER, SUPPLIER."},"address":{"type":"object","properties":{"line1":{"type":["string","null"],"description":""},"line2":{"type":["string","null"],"description":""},"city":{"type":["string","null"],"description":""},"district":{"type":["string","null"],"description":""},"state":{"type":["string","null"],"description":""},"stateCode":{"type":["string","null"],"description":"GST state code, 2 digits."},"pincode":{"type":["string","null"],"description":"6 digits."}},"description":"Every key present, null when unknown."},"reference":{"type":["string","null"],"description":"Your own id for this contact, if you gave one."},"status":{"type":"string","description":"ACTIVE or INACTIVE."},"createdAt":{"type":"string","description":"ISO 8601 UTC."},"created":{"type":"boolean","description":"true when this call created the contact."}}}},"required":["status","statusCode","correlationId","results"]},"example":{"status":true,"statusCode":201,"correlationId":"2f6c1e0a9b3d4","results":{"id":"66f1a2b3c4d5e6f7a8b9c0d1","name":"Asha Stores","businessName":null,"phone":"9876543210","phoneCountryCode":"91","email":"asha@example.com","gstNumber":"33ABCDE1234F1Z5","roles":["CUSTOMER"],"address":{"line1":"12 Market Road","line2":null,"city":"Chennai","district":null,"state":"Tamil Nadu","stateCode":"33","pincode":"600001"},"reference":"cust-1001","status":"ACTIVE","createdAt":"2026-09-18T09:30:00.000Z","created":true}}}}},"4XX":{"description":"Error envelope (see components.schemas.Error).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"Look up contacts","description":"Exact lookups by reference, phone or gstNumber (any combination, all must match), or a word search. At most 50 rows; this is a lookup, not a way to copy the contact list. Required scope: contacts:read.","security":[{"basicAuth":[]}],"tags":["contacts"],"parameters":[{"name":"reference","in":"query","required":false,"schema":{"type":"string"},"description":""},{"name":"phone","in":"query","required":false,"schema":{"type":"string"},"description":"Digits only."},{"name":"gstNumber","in":"query","required":false,"schema":{"type":"string"},"description":""},{"name":"search","in":"query","required":false,"schema":{"type":"string"},"description":"Any word of the name, nickname, business or trade name; digits match the start of the phone. Ignored when an exact key is given."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"},"description":"1–50, default 20."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"boolean","const":true},"statusCode":{"type":"integer"},"correlationId":{"type":"string"},"results":{"type":"object","properties":{"contacts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-fA-F]{24}$","description":"The contact id. Use it as contactId on a sale."},"name":{"type":["string","null"],"description":""},"businessName":{"type":["string","null"],"description":"Registered name, if a business."},"phone":{"type":["string","null"],"description":"Digits only, national number."},"phoneCountryCode":{"type":["string","null"],"description":"Dialling code without +, e.g. \"91\"."},"email":{"type":["string","null"],"description":""},"gstNumber":{"type":["string","null"],"description":"15-character GSTIN."},"roles":{"type":"string","description":"Each one of CUSTOMER, SUPPLIER."},"address":{"type":"object","properties":{"line1":{"type":["string","null"],"description":""},"line2":{"type":["string","null"],"description":""},"city":{"type":["string","null"],"description":""},"district":{"type":["string","null"],"description":""},"state":{"type":["string","null"],"description":""},"stateCode":{"type":["string","null"],"description":"GST state code, 2 digits."},"pincode":{"type":["string","null"],"description":"6 digits."}},"description":"Every key present, null when unknown."},"reference":{"type":["string","null"],"description":"Your own id for this contact, if you gave one."},"status":{"type":"string","description":"ACTIVE or INACTIVE."},"createdAt":{"type":"string","description":"ISO 8601 UTC."}}},"description":""}}}},"required":["status","statusCode","correlationId","results"]},"example":{"status":true,"statusCode":200,"correlationId":"2f6c1e0a9b3d4","results":{"contacts":[{"id":"66f1a2b3c4d5e6f7a8b9c0d1","name":"Asha Stores","businessName":null,"phone":"9876543210","phoneCountryCode":"91","email":"asha@example.com","gstNumber":"33ABCDE1234F1Z5","roles":["CUSTOMER"],"address":{"line1":"12 Market Road","line2":null,"city":"Chennai","district":null,"state":"Tamil Nadu","stateCode":"33","pincode":"600001"},"reference":"cust-1001","status":"ACTIVE","createdAt":"2026-09-18T09:30:00.000Z"}]}}}}},"4XX":{"description":"Error envelope (see components.schemas.Error).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/contacts/{id}":{"get":{"summary":"Read a contact","description":"Required scope: contacts:read.","security":[{"basicAuth":[]}],"tags":["contacts"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-fA-F]{24}$"},"description":""}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"boolean","const":true},"statusCode":{"type":"integer"},"correlationId":{"type":"string"},"results":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-fA-F]{24}$","description":"The contact id. Use it as contactId on a sale."},"name":{"type":["string","null"],"description":""},"businessName":{"type":["string","null"],"description":"Registered name, if a business."},"phone":{"type":["string","null"],"description":"Digits only, national number."},"phoneCountryCode":{"type":["string","null"],"description":"Dialling code without +, e.g. \"91\"."},"email":{"type":["string","null"],"description":""},"gstNumber":{"type":["string","null"],"description":"15-character GSTIN."},"roles":{"type":"string","description":"Each one of CUSTOMER, SUPPLIER."},"address":{"type":"object","properties":{"line1":{"type":["string","null"],"description":""},"line2":{"type":["string","null"],"description":""},"city":{"type":["string","null"],"description":""},"district":{"type":["string","null"],"description":""},"state":{"type":["string","null"],"description":""},"stateCode":{"type":["string","null"],"description":"GST state code, 2 digits."},"pincode":{"type":["string","null"],"description":"6 digits."}},"description":"Every key present, null when unknown."},"reference":{"type":["string","null"],"description":"Your own id for this contact, if you gave one."},"status":{"type":"string","description":"ACTIVE or INACTIVE."},"createdAt":{"type":"string","description":"ISO 8601 UTC."}}}},"required":["status","statusCode","correlationId","results"]},"example":{"status":true,"statusCode":200,"correlationId":"2f6c1e0a9b3d4","results":{"id":"66f1a2b3c4d5e6f7a8b9c0d1","name":"Asha Stores","businessName":null,"phone":"9876543210","phoneCountryCode":"91","email":"asha@example.com","gstNumber":"33ABCDE1234F1Z5","roles":["CUSTOMER"],"address":{"line1":"12 Market Road","line2":null,"city":"Chennai","district":null,"state":"Tamil Nadu","stateCode":"33","pincode":"600001"},"reference":"cust-1001","status":"ACTIVE","createdAt":"2026-09-18T09:30:00.000Z"}}}}},"4XX":{"description":"Error envelope (see components.schemas.Error).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/products":{"get":{"summary":"Look up products","description":"An exact code (barcode) lookup, or a word search; at most 50 rows with the stock left at the key's store. Keep your own copy of your catalogue — this call is for looking a product up, not for serving your storefront. Required scope: products:read.","security":[{"basicAuth":[]}],"tags":["products"],"parameters":[{"name":"code","in":"query","required":false,"schema":{"type":"string"},"description":"Exact product code / barcode. When given, search is ignored."},{"name":"search","in":"query","required":false,"schema":{"type":"string"},"description":"Any word of the name or search tag; a prefix of each word matches."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"},"description":"1–50, default 20."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"boolean","const":true},"statusCode":{"type":"integer"},"correlationId":{"type":"string"},"results":{"type":"object","properties":{"products":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-fA-F]{24}$","description":""},"name":{"type":"string","description":""},"code":{"type":["string","null"],"description":"Barcode / product code."},"hsnSac":{"type":["string","null"],"description":""},"taxPercent":{"type":"number","description":"One of 0, 5, 12, 18, 24, 28, 40."},"mrp":{"type":"integer","description":"Paise."},"salePrice":{"type":"integer","description":"Paise, GST-inclusive retail price."},"wholesalePrice":{"type":["integer","null"],"description":"Paise."},"unit":{"type":["string","null"],"description":"Primary unit code, e.g. \"PCS\", \"KG\"."},"isStockTracked":{"type":"boolean","description":""},"stockLeft":{"type":["number","null"],"description":"Units left at the key's store; null when the product is not stock-tracked."},"status":{"type":"string","description":"ACTIVE or INACTIVE."},"batches":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-fA-F]{24}$","description":""},"batchNo":{"type":["string","null"],"description":""},"stockLeft":{"type":"number","description":"Units left in this batch."},"mrp":{"type":["integer","null"],"description":"Paise, this batch's printed MRP."},"salePrice":{"type":["integer","null"],"description":"Paise, this batch's price."},"expiryDate":{"type":["string","null"],"description":"YYYY-MM-DD."}}},"description":"Only on GET /products/{id}, only when the store sells by batch: the batches with stock, oldest first. Name one on a sale line as batchId, or leave it out and the oldest is taken."}}},"description":""}}}},"required":["status","statusCode","correlationId","results"]},"example":{"status":true,"statusCode":200,"correlationId":"2f6c1e0a9b3d4","results":{"products":[{"id":"66f1a2b3c4d5e6f7a8b9c0f3","name":"Aashirvaad Atta 5 kg","code":"8901058000123","hsnSac":"1101","taxPercent":5,"mrp":31000,"salePrice":29500,"wholesalePrice":28000,"unit":"PCS","isStockTracked":true,"stockLeft":28,"status":"ACTIVE","batches":[{"id":"66f1a2b3c4d5e6f7a8b9c0b7","batchNo":"B-0912","stockLeft":28,"mrp":31000,"salePrice":29500,"expiryDate":"2027-03-31"}]}]}}}}},"4XX":{"description":"Error envelope (see components.schemas.Error).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/products/{id}":{"get":{"summary":"Read a product","description":"One product with its prices and the stock left at the key's store. Required scope: products:read.","security":[{"basicAuth":[]}],"tags":["products"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-fA-F]{24}$"},"description":""}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"boolean","const":true},"statusCode":{"type":"integer"},"correlationId":{"type":"string"},"results":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-fA-F]{24}$","description":""},"name":{"type":"string","description":""},"code":{"type":["string","null"],"description":"Barcode / product code."},"hsnSac":{"type":["string","null"],"description":""},"taxPercent":{"type":"number","description":"One of 0, 5, 12, 18, 24, 28, 40."},"mrp":{"type":"integer","description":"Paise."},"salePrice":{"type":"integer","description":"Paise, GST-inclusive retail price."},"wholesalePrice":{"type":["integer","null"],"description":"Paise."},"unit":{"type":["string","null"],"description":"Primary unit code, e.g. \"PCS\", \"KG\"."},"isStockTracked":{"type":"boolean","description":""},"stockLeft":{"type":["number","null"],"description":"Units left at the key's store; null when the product is not stock-tracked."},"status":{"type":"string","description":"ACTIVE or INACTIVE."},"batches":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-fA-F]{24}$","description":""},"batchNo":{"type":["string","null"],"description":""},"stockLeft":{"type":"number","description":"Units left in this batch."},"mrp":{"type":["integer","null"],"description":"Paise, this batch's printed MRP."},"salePrice":{"type":["integer","null"],"description":"Paise, this batch's price."},"expiryDate":{"type":["string","null"],"description":"YYYY-MM-DD."}}},"description":"Only on GET /products/{id}, only when the store sells by batch: the batches with stock, oldest first. Name one on a sale line as batchId, or leave it out and the oldest is taken."}}}},"required":["status","statusCode","correlationId","results"]},"example":{"status":true,"statusCode":200,"correlationId":"2f6c1e0a9b3d4","results":{"id":"66f1a2b3c4d5e6f7a8b9c0f3","name":"Aashirvaad Atta 5 kg","code":"8901058000123","hsnSac":"1101","taxPercent":5,"mrp":31000,"salePrice":29500,"wholesalePrice":28000,"unit":"PCS","isStockTracked":true,"stockLeft":28,"status":"ACTIVE","batches":[{"id":"66f1a2b3c4d5e6f7a8b9c0b7","batchNo":"B-0912","stockLeft":28,"mrp":31000,"salePrice":29500,"expiryDate":"2027-03-31"}]}}}}},"4XX":{"description":"Error envelope (see components.schemas.Error).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/sales":{"post":{"summary":"Create a sale","description":"Send what was sold — the server prices catalogue lines from the product, computes GST per line, the totals, the rounding and the stock movement, and numbers the bill. Never send totals. A line with productId is a catalogue line (price from the product unless unitPrice is given, which must not be below the product's minimum sale price); a line with name and no productId is a free-text line and needs unitPrice and taxPercent. Sends no payment: a sale is unpaid until a payment is recorded (see POST /sales/{id}/payments). A sale with a contactId may stay unpaid; a sale without one must be paid with the next call. If a COMPLETED sale already carries the same reference it is returned with created:false and nothing is created. Counts in the plan's monthly sale quota like a sale made at the counter. Required scope: sales:write.","security":[{"basicAuth":[]}],"tags":["sales"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":80},"description":"Makes the call safe to retry: the same key with the same body returns the stored answer; a different body under the same key is refused (409)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reference":{"type":"string","description":"Your order id, 1–80 characters. Unique within the business; makes the call safe to retry."},"contactId":{"type":"string","pattern":"^[0-9a-fA-F]{24}$","description":"The customer (from POST /contacts). Required for a sale that will not be paid at once."},"docType":{"type":"string","description":"BILL or INVOICE. Omit to let the store's setting decide. INVOICE needs a billing profile with a GST number."},"saleDate":{"type":"string","description":"YYYY-MM-DD in the store timezone; today or a past day of this or the previous financial year. Default today."},"lines":{"type":"array","items":{"type":"object","properties":{"productId":{"type":"string","pattern":"^[0-9a-fA-F]{24}$","description":"A catalogue product. Either this or name."},"batchId":{"type":"string","pattern":"^[0-9a-fA-F]{24}$","description":"Catalogue lines in a batch-selling store: the batch to sell from (see GET /products/{id}). Left out, the oldest batch with stock is taken."},"name":{"type":"string","description":"Free-text line name, max 1000. Either this or productId."},"kind":{"type":"string","description":"Free-text lines only: PRODUCT or SERVICE, default SERVICE."},"quantity":{"type":"number","description":"Up to 4 decimals."},"unitPrice":{"type":"integer","description":"Paise, GST-inclusive, per unit. Required for free-text lines; optional override for catalogue lines. 0 is allowed (free item)."},"taxPercent":{"type":"number","description":"Free-text lines only: one of 0, 5, 12, 18, 24, 28, 40. Default 0. Catalogue lines take the product's."},"hsnSac":{"type":"string","description":"Free-text lines only, 4–8 digits."},"unit":{"type":"string","description":"Catalogue lines: a sale-unit tier name of the product (e.g. \"BOX\"); free-text lines: a label printed beside the quantity."},"note":{"type":"string","description":"Printed under the line, max 500 — the phone model a skin is for, an engraving text, a measurement."},"addOns":{"type":"string","description":"Catalogue lines only: keys of the product's add-on options to charge with this line (see GET /products/{id} → addOns). Each becomes a SERVICE line under the product at the option's catalogue price; an unknown key is refused with NB-B-SAL-1024; while the shop has add-on options switched off (Settings → Product) any key is refused with NB-B-SAL-1026."}},"required":["quantity"]},"description":"1–500 lines."},"overallDiscount":{"type":"integer","description":"Paise taken off the whole bill, spread across the lines with GST recomputed per line."},"note":{"type":"string","description":"Max 300, printed on the bill."}},"required":["lines"]},"example":{"reference":"order-5501","contactId":"66f1a2b3c4d5e6f7a8b9c0d1","lines":[{"productId":"66f1a2b3c4d5e6f7a8b9c0f3","quantity":2},{"name":"Delivery charge","kind":"SERVICE","quantity":1,"unitPrice":5000,"taxPercent":18,"hsnSac":"996812"}],"note":"Web order 5501"}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"boolean","const":true},"statusCode":{"type":"integer"},"correlationId":{"type":"string"},"results":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-fA-F]{24}$","description":"The sale id."},"saleNo":{"type":"string","description":"The bill / invoice number as printed, e.g. \"A20262027104\"."},"docType":{"type":"string","description":"BILL or INVOICE (Tax Invoice)."},"status":{"type":"string","description":"COMPLETED or REVERSED (cancelled)."},"saleDate":{"type":"string","description":"ISO 8601 UTC instant."},"saleDay":{"type":"string","description":"YYYY-MM-DD in the store timezone."},"reference":{"type":["string","null"],"description":"Your reference, if you gave one."},"contactId":{"type":["string","null"],"pattern":"^[0-9a-fA-F]{24}$","description":""},"customer":{"type":"object","properties":{"name":{"type":["string","null"],"description":""},"phone":{"type":["string","null"],"description":""},"gstNumber":{"type":["string","null"],"description":""}},"description":"The customer as snapshotted on the sale."},"lines":{"type":"array","items":{"type":"object","properties":{"productId":{"type":["string","null"],"pattern":"^[0-9a-fA-F]{24}$","description":"null for a free-text line."},"name":{"type":"string","description":""},"kind":{"type":"string","description":"PRODUCT or SERVICE."},"quantity":{"type":"number","description":""},"unit":{"type":["string","null"],"description":""},"unitPrice":{"type":"integer","description":"Paise, GST-inclusive."},"mrp":{"type":["integer","null"],"description":"Paise."},"taxPercent":{"type":"number","description":""},"taxAmount":{"type":"integer","description":"Paise, the GST inside this line."},"amount":{"type":"integer","description":"Paise, line total including GST."},"note":{"type":["string","null"],"description":"The line note as printed under the name (e.g. the phone model a skin was cut for)."},"lineGroup":{"type":["string","null"],"description":"Set on a product line that carries add-on options and on each of its option lines — the same value groups them."},"addOnKey":{"type":["string","null"],"description":"On an add-on option line: the option key from the product (e.g. LOGO-CUT). null on ordinary lines."}}},"description":"In the order NegoBill stores them (free-text lines before catalogue lines) — match by productId or name, not by position."},"totals":{"type":"object","properties":{"taxable":{"type":"integer","description":"Sum of line amounts before GST."},"tax":{"type":"integer","description":"Total GST."},"total":{"type":"integer","description":"taxable + tax."},"roundOff":{"type":"integer","description":"Paise added (or removed, negative) to reach a whole rupee."},"grandTotal":{"type":"integer","description":"What the customer pays. Whole rupees, in paise."},"amountInWords":{"type":"string","description":""}},"description":"All paise."},"paid":{"type":"integer","description":"Paise received so far."},"due":{"type":"integer","description":"Paise still unpaid. 0 = settled."},"note":{"type":["string","null"],"description":""},"createdAt":{"type":"string","description":"ISO 8601 UTC."},"created":{"type":"boolean","description":"Only on POST: true when this call made the sale, false when a sale with the same reference already existed and was returned instead."}}}},"required":["status","statusCode","correlationId","results"]},"example":{"status":true,"statusCode":201,"correlationId":"2f6c1e0a9b3d4","results":{"id":"66f1a2b3c4d5e6f7a8b9c0e2","saleNo":"A20262027104","docType":"INVOICE","status":"COMPLETED","saleDate":"2026-09-18T09:31:12.000Z","saleDay":"2026-09-18","reference":"order-5501","contactId":"66f1a2b3c4d5e6f7a8b9c0d1","customer":{"name":"Asha Stores","phone":"9876543210","gstNumber":"33ABCDE1234F1Z5"},"lines":[{"productId":"66f1a2b3c4d5e6f7a8b9c0f3","name":"Aashirvaad Atta 5 kg","kind":"PRODUCT","quantity":2,"unit":"PCS","unitPrice":29500,"mrp":31000,"taxPercent":5,"taxAmount":2810,"amount":59000},{"productId":null,"name":"Delivery charge","kind":"SERVICE","quantity":1,"unit":null,"unitPrice":5000,"mrp":null,"taxPercent":18,"taxAmount":763,"amount":5000}],"totals":{"taxable":60427,"tax":3573,"total":64000,"roundOff":0,"grandTotal":64000,"amountInWords":"Six Hundred Forty Rupees Only"},"paid":0,"due":64000,"note":"Web order 5501","createdAt":"2026-09-18T09:31:12.000Z","created":true}}}}},"4XX":{"description":"Error envelope (see components.schemas.Error).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"Look up sales","description":"By reference or saleNo (exact), by contactId, or by a day range; newest first, at most 50. Required scope: sales:read.","security":[{"basicAuth":[]}],"tags":["sales"],"parameters":[{"name":"reference","in":"query","required":false,"schema":{"type":"string"},"description":""},{"name":"saleNo","in":"query","required":false,"schema":{"type":"string"},"description":""},{"name":"contactId","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-9a-fA-F]{24}$"},"description":""},{"name":"from","in":"query","required":false,"schema":{"type":"string"},"description":"YYYY-MM-DD, inclusive."},{"name":"to","in":"query","required":false,"schema":{"type":"string"},"description":"YYYY-MM-DD, inclusive."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"},"description":"1–50, default 20."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"boolean","const":true},"statusCode":{"type":"integer"},"correlationId":{"type":"string"},"results":{"type":"object","properties":{"sales":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-fA-F]{24}$","description":"The sale id."},"saleNo":{"type":"string","description":"The bill / invoice number as printed, e.g. \"A20262027104\"."},"docType":{"type":"string","description":"BILL or INVOICE (Tax Invoice)."},"status":{"type":"string","description":"COMPLETED or REVERSED (cancelled)."},"saleDate":{"type":"string","description":"ISO 8601 UTC instant."},"saleDay":{"type":"string","description":"YYYY-MM-DD in the store timezone."},"reference":{"type":["string","null"],"description":"Your reference, if you gave one."},"contactId":{"type":["string","null"],"pattern":"^[0-9a-fA-F]{24}$","description":""},"customer":{"type":"object","properties":{"name":{"type":["string","null"],"description":""},"phone":{"type":["string","null"],"description":""},"gstNumber":{"type":["string","null"],"description":""}},"description":"The customer as snapshotted on the sale."},"lines":{"type":"array","items":{"type":"object","properties":{"productId":{"type":["string","null"],"pattern":"^[0-9a-fA-F]{24}$","description":"null for a free-text line."},"name":{"type":"string","description":""},"kind":{"type":"string","description":"PRODUCT or SERVICE."},"quantity":{"type":"number","description":""},"unit":{"type":["string","null"],"description":""},"unitPrice":{"type":"integer","description":"Paise, GST-inclusive."},"mrp":{"type":["integer","null"],"description":"Paise."},"taxPercent":{"type":"number","description":""},"taxAmount":{"type":"integer","description":"Paise, the GST inside this line."},"amount":{"type":"integer","description":"Paise, line total including GST."},"note":{"type":["string","null"],"description":"The line note as printed under the name (e.g. the phone model a skin was cut for)."},"lineGroup":{"type":["string","null"],"description":"Set on a product line that carries add-on options and on each of its option lines — the same value groups them."},"addOnKey":{"type":["string","null"],"description":"On an add-on option line: the option key from the product (e.g. LOGO-CUT). null on ordinary lines."}}},"description":"In the order NegoBill stores them (free-text lines before catalogue lines) — match by productId or name, not by position."},"totals":{"type":"object","properties":{"taxable":{"type":"integer","description":"Sum of line amounts before GST."},"tax":{"type":"integer","description":"Total GST."},"total":{"type":"integer","description":"taxable + tax."},"roundOff":{"type":"integer","description":"Paise added (or removed, negative) to reach a whole rupee."},"grandTotal":{"type":"integer","description":"What the customer pays. Whole rupees, in paise."},"amountInWords":{"type":"string","description":""}},"description":"All paise."},"paid":{"type":"integer","description":"Paise received so far."},"due":{"type":"integer","description":"Paise still unpaid. 0 = settled."},"note":{"type":["string","null"],"description":""},"createdAt":{"type":"string","description":"ISO 8601 UTC."},"created":{"type":"boolean","description":"Only on POST: true when this call made the sale, false when a sale with the same reference already existed and was returned instead."}}},"description":""}}}},"required":["status","statusCode","correlationId","results"]},"example":{"status":true,"statusCode":200,"correlationId":"2f6c1e0a9b3d4","results":{"sales":[{"id":"66f1a2b3c4d5e6f7a8b9c0e2","saleNo":"A20262027104","docType":"INVOICE","status":"COMPLETED","saleDate":"2026-09-18T09:31:12.000Z","saleDay":"2026-09-18","reference":"order-5501","contactId":"66f1a2b3c4d5e6f7a8b9c0d1","customer":{"name":"Asha Stores","phone":"9876543210","gstNumber":"33ABCDE1234F1Z5"},"lines":[{"productId":"66f1a2b3c4d5e6f7a8b9c0f3","name":"Aashirvaad Atta 5 kg","kind":"PRODUCT","quantity":2,"unit":"PCS","unitPrice":29500,"mrp":31000,"taxPercent":5,"taxAmount":2810,"amount":59000},{"productId":null,"name":"Delivery charge","kind":"SERVICE","quantity":1,"unit":null,"unitPrice":5000,"mrp":null,"taxPercent":18,"taxAmount":763,"amount":5000}],"totals":{"taxable":60427,"tax":3573,"total":64000,"roundOff":0,"grandTotal":64000,"amountInWords":"Six Hundred Forty Rupees Only"},"paid":0,"due":64000,"note":"Web order 5501","createdAt":"2026-09-18T09:31:12.000Z"}]}}}}},"4XX":{"description":"Error envelope (see components.schemas.Error).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/sales/{id}":{"get":{"summary":"Read a sale","description":"Including what is paid and what is still due. Required scope: sales:read.","security":[{"basicAuth":[]}],"tags":["sales"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-fA-F]{24}$"},"description":""}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"boolean","const":true},"statusCode":{"type":"integer"},"correlationId":{"type":"string"},"results":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-fA-F]{24}$","description":"The sale id."},"saleNo":{"type":"string","description":"The bill / invoice number as printed, e.g. \"A20262027104\"."},"docType":{"type":"string","description":"BILL or INVOICE (Tax Invoice)."},"status":{"type":"string","description":"COMPLETED or REVERSED (cancelled)."},"saleDate":{"type":"string","description":"ISO 8601 UTC instant."},"saleDay":{"type":"string","description":"YYYY-MM-DD in the store timezone."},"reference":{"type":["string","null"],"description":"Your reference, if you gave one."},"contactId":{"type":["string","null"],"pattern":"^[0-9a-fA-F]{24}$","description":""},"customer":{"type":"object","properties":{"name":{"type":["string","null"],"description":""},"phone":{"type":["string","null"],"description":""},"gstNumber":{"type":["string","null"],"description":""}},"description":"The customer as snapshotted on the sale."},"lines":{"type":"array","items":{"type":"object","properties":{"productId":{"type":["string","null"],"pattern":"^[0-9a-fA-F]{24}$","description":"null for a free-text line."},"name":{"type":"string","description":""},"kind":{"type":"string","description":"PRODUCT or SERVICE."},"quantity":{"type":"number","description":""},"unit":{"type":["string","null"],"description":""},"unitPrice":{"type":"integer","description":"Paise, GST-inclusive."},"mrp":{"type":["integer","null"],"description":"Paise."},"taxPercent":{"type":"number","description":""},"taxAmount":{"type":"integer","description":"Paise, the GST inside this line."},"amount":{"type":"integer","description":"Paise, line total including GST."},"note":{"type":["string","null"],"description":"The line note as printed under the name (e.g. the phone model a skin was cut for)."},"lineGroup":{"type":["string","null"],"description":"Set on a product line that carries add-on options and on each of its option lines — the same value groups them."},"addOnKey":{"type":["string","null"],"description":"On an add-on option line: the option key from the product (e.g. LOGO-CUT). null on ordinary lines."}}},"description":"In the order NegoBill stores them (free-text lines before catalogue lines) — match by productId or name, not by position."},"totals":{"type":"object","properties":{"taxable":{"type":"integer","description":"Sum of line amounts before GST."},"tax":{"type":"integer","description":"Total GST."},"total":{"type":"integer","description":"taxable + tax."},"roundOff":{"type":"integer","description":"Paise added (or removed, negative) to reach a whole rupee."},"grandTotal":{"type":"integer","description":"What the customer pays. Whole rupees, in paise."},"amountInWords":{"type":"string","description":""}},"description":"All paise."},"paid":{"type":"integer","description":"Paise received so far."},"due":{"type":"integer","description":"Paise still unpaid. 0 = settled."},"note":{"type":["string","null"],"description":""},"createdAt":{"type":"string","description":"ISO 8601 UTC."},"created":{"type":"boolean","description":"Only on POST: true when this call made the sale, false when a sale with the same reference already existed and was returned instead."}}}},"required":["status","statusCode","correlationId","results"]},"example":{"status":true,"statusCode":200,"correlationId":"2f6c1e0a9b3d4","results":{"id":"66f1a2b3c4d5e6f7a8b9c0e2","saleNo":"A20262027104","docType":"INVOICE","status":"COMPLETED","saleDate":"2026-09-18T09:31:12.000Z","saleDay":"2026-09-18","reference":"order-5501","contactId":"66f1a2b3c4d5e6f7a8b9c0d1","customer":{"name":"Asha Stores","phone":"9876543210","gstNumber":"33ABCDE1234F1Z5"},"lines":[{"productId":"66f1a2b3c4d5e6f7a8b9c0f3","name":"Aashirvaad Atta 5 kg","kind":"PRODUCT","quantity":2,"unit":"PCS","unitPrice":29500,"mrp":31000,"taxPercent":5,"taxAmount":2810,"amount":59000},{"productId":null,"name":"Delivery charge","kind":"SERVICE","quantity":1,"unit":null,"unitPrice":5000,"mrp":null,"taxPercent":18,"taxAmount":763,"amount":5000}],"totals":{"taxable":60427,"tax":3573,"total":64000,"roundOff":0,"grandTotal":64000,"amountInWords":"Six Hundred Forty Rupees Only"},"paid":0,"due":64000,"note":"Web order 5501","createdAt":"2026-09-18T09:31:12.000Z"}}}}},"4XX":{"description":"Error envelope (see components.schemas.Error).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/sales/{id}/paper":{"get":{"summary":"The bill as HTML","description":"The printable A4 bill, rendered by NegoBill from the sale exactly as the shop prints it (text/html, not JSON). Required scope: sales:read.","security":[{"basicAuth":[]}],"tags":["sales"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-fA-F]{24}$"},"description":""}],"responses":{"200":{"description":"text/html — a complete HTML document.","content":{"text/html":{"schema":{"type":"string"}}}},"4XX":{"description":"Error envelope (see components.schemas.Error).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/sales/{id}/share":{"post":{"summary":"A public link to the bill","description":"A link the customer opens with no login (the same link the shop's Share button makes). Its life follows the shop's Settings → Sales → Share link expiry; a cancelled or edited sale retires the link. Required scope: sales:read.","security":[{"basicAuth":[]}],"tags":["sales"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-fA-F]{24}$"},"description":""}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"boolean","const":true},"statusCode":{"type":"integer"},"correlationId":{"type":"string"},"results":{"type":"object","properties":{"url":{"type":"string","description":""},"expiresAt":{"type":["string","null"],"description":"ISO 8601 UTC; null = never."}}}},"required":["status","statusCode","correlationId","results"]},"example":{"status":true,"statusCode":200,"correlationId":"2f6c1e0a9b3d4","results":{"url":"https://bill.negobill.com/share/sale/eyJ2Ijp7ImlkIjoi…","expiresAt":"2026-10-18T09:31:12.000Z"}}}}},"4XX":{"description":"Error envelope (see components.schemas.Error).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/sales/{id}/payments":{"post":{"summary":"Record a payment","description":"Records money received against this sale under one of the business's payment methods (by name, case-insensitive — the error lists the names when yours is unknown). The amount must not exceed what is due. If a receipt already carries the same reference it is returned with created:false. Required scope: payments:write.","security":[{"basicAuth":[]}],"tags":["sales"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-fA-F]{24}$"},"description":"The sale."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":80},"description":"Makes the call safe to retry: the same key with the same body returns the stored answer; a different body under the same key is refused (409)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reference":{"type":"string","description":"Your payment id, 1–80 characters. Unique within the business."},"amount":{"type":"integer","description":"Paise, at most the sale's due."},"method":{"type":"string","description":"A payment method name of the business, e.g. \"UPI\", \"Cash\", \"Bank transfer\", \"Card\"."},"note":{"type":"string","description":"Max 300."}},"required":["amount","method"]},"example":{"reference":"pay-5501","amount":64000,"method":"UPI"}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"boolean","const":true},"statusCode":{"type":"integer"},"correlationId":{"type":"string"},"results":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-fA-F]{24}$","description":"The receipt id."},"receiptNo":{"type":"string","description":""},"amount":{"type":"integer","description":"Paise."},"method":{"type":["string","null"],"description":"The payment method name."},"saleId":{"type":["string","null"],"pattern":"^[0-9a-fA-F]{24}$","description":""},"reference":{"type":["string","null"],"description":""},"receiptDate":{"type":"string","description":"ISO 8601 UTC."},"due":{"type":"integer","description":"Paise still unpaid on the sale after this receipt."},"created":{"type":"boolean","description":"Only on POST: false when a receipt with the same reference already existed and was returned instead."}}}},"required":["status","statusCode","correlationId","results"]},"example":{"status":true,"statusCode":201,"correlationId":"2f6c1e0a9b3d4","results":{"id":"66f1a2b3c4d5e6f7a8b9c1a4","receiptNo":"R20262027211","amount":64000,"method":"UPI","saleId":"66f1a2b3c4d5e6f7a8b9c0e2","reference":"pay-5501","receiptDate":"2026-09-18T09:32:40.000Z","due":0,"created":true}}}}},"4XX":{"description":"Error envelope (see components.schemas.Error).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"Payments on a sale","description":"Required scope: payments:read.","security":[{"basicAuth":[]}],"tags":["sales"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-fA-F]{24}$"},"description":""}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"boolean","const":true},"statusCode":{"type":"integer"},"correlationId":{"type":"string"},"results":{"type":"object","properties":{"payments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9a-fA-F]{24}$","description":"The receipt id."},"receiptNo":{"type":"string","description":""},"amount":{"type":"integer","description":"Paise."},"method":{"type":["string","null"],"description":"The payment method name."},"saleId":{"type":["string","null"],"pattern":"^[0-9a-fA-F]{24}$","description":""},"reference":{"type":["string","null"],"description":""},"receiptDate":{"type":"string","description":"ISO 8601 UTC."},"due":{"type":"integer","description":"Paise still unpaid on the sale after this receipt."},"created":{"type":"boolean","description":"Only on POST: false when a receipt with the same reference already existed and was returned instead."}}},"description":""},"due":{"type":"integer","description":"Paise still unpaid."}}}},"required":["status","statusCode","correlationId","results"]},"example":{"status":true,"statusCode":200,"correlationId":"2f6c1e0a9b3d4","results":{"payments":[{"id":"66f1a2b3c4d5e6f7a8b9c1a4","receiptNo":"R20262027211","amount":64000,"method":"UPI","saleId":"66f1a2b3c4d5e6f7a8b9c0e2","reference":"pay-5501","receiptDate":"2026-09-18T09:32:40.000Z","due":0}],"due":0}}}}},"4XX":{"description":"Error envelope (see components.schemas.Error).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}