Issue the GST tax invoice for an order
Issues the GST tax invoice for an order, computing the lines, the rates and the CGST/SGST/IGST split from the order itself and drawing a number from a GAPLESS per-financial-year sequence. IT MINTS A LEGAL DOCUMENT. Unlike every other create on this API it cannot be undone by removing the row, because the series has already moved. 201 EVEN ON A REPEAT, and the body is the invoice NOW IN FORCE. An order that already has a standing invoice gets that one back without consuming a second number, so a retrying pipeline cannot punch holes in the sequence. Compare the id you get back if you need to know which happened; branching the status on it would tell a key holding only the write grant whether an invoice exists, which is a read. THE STORE MUST HAVE GST ENABLED. A store with no configuration, or one with enabled false, is refused 409 rather than issuing an untaxed document. EVERYTHING THE DOCUMENT ASSERTS ABOUT ITSELF IS REFUSED BY NAME: the number, the financial year, the five amounts, the lines and issued_by are computed or stamped here. Only order_id and place_of_supply are yours to send. issued_by is stamped and NOT published back: the column holds a merchant staff user id on a dashboard-issued invoice, and a scope over tax documents is not a grant over the staff directory.
Authorizations
A secret API key. Publishable keys cannot reach this API. A key may carry an expiry, and an expired key is refused exactly like an unknown one, with a 401 that names no reason; check the key's expires_at in the dashboard rather than inferring it from a response. When a merchant rolls a key's secret they choose a grace window of up to 3 days, and for its duration BOTH the new secret and the one it replaced authenticate, so an integration moves over on its own deploy schedule instead of at the instant the button is pressed. Move before the window closes: after it, the old secret is refused. Nothing else about this contract moves with a roll. The key keeps its id and its scopes, so the only thing an integration updates is the credential itself.
Headers
A unique key per logical write. Replaying a request with the same key returns the first response byte for byte instead of applying the write twice.
Body
Computes the lines, rates and CGST/SGST/IGST split from the order and draws a number from a GAPLESS per-financial-year sequence. 201 EVEN ON A REPEAT, and the body is the invoice NOW IN FORCE: an order with a standing invoice gets that one back without consuming a second number. Compare the id if you need to know which happened; branching the status on it would tell a key holding only the write grant whether an invoice exists. THE STORE MUST HAVE GST ENABLED, or the call is 409 rather than an untaxed document. EVERYTHING THE DOCUMENT ASSERTS ABOUT ITSELF IS REFUSED BY NAME: invoice_number, financial_year, the five amounts, lines, currency_code, supplier_gstin and issued_by are computed or stamped by the server. A caller-supplied number would claim a place in a series the counter never issued, and a caller-supplied issued_by would make an api write indistinguishable from a person issuing from the dashboard. issued_by IS STAMPED BUT NEVER PUBLISHED BACK. The same column holds a merchant staff user id on any invoice issued from the dashboard, so reading it would answer "who works here" from a scope granted over tax documents.
The order to invoice. It must belong to this store, and its own line items are what the invoice is computed from.
The RECIPIENT's two-digit GST state code, 01 to 38. Equal to the supplier's state means an intra-state supply and a CGST/SGST split; anything else means IGST. Omit it for the supplier's own state. A code outside the set is a 400 rather than a guess, because guessing wrong taxes the supply under the wrong heads.
Response
Created
