POST
Issue the GST tax invoice for an order

Authorizations

Authorization
string
header
required

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

Idempotency-Key
string
required

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

application/json

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.

order_id
string
required

The order to invoice. It must belong to this store, and its own line items are what the invoice is computed from.

place_of_supply
string

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

data
object