On production, SePay CLI only reads invoices: einvoice invoice list and einvoice invoice get (Read invoices on production). The other einvoice commands run on the sandbox only, with simulated data; on production, use the eInvoice API or my.sepay.vn.
Use the einvoice commands (short form inv) of SePay CLI to try creating and issuing eInvoices on the sandbox. Invoices you create or issue there are not sent to the tax authority.
invoice create sends the invoice data to SePay; the invoice is a draft when is_draft: true. invoice issue issues a draft; on production, that is when the invoice goes to the tax authority.
You need to be signed in, have Test mode enabled for your company and see at least one provider account in sepay einvoice account list. invoice issue runs on the sandbox only and asks for confirmation; without a terminal, add --yes.
Command order (if you create the invoice with is_draft: false, skip the two issue steps):
account get → invoice create → create-status → invoice issue → issue-status → invoice get
einvoice auth and einvoice quota
The CLI fetches sandbox credentials when it needs them and doesn't print them. Check that they're ready and when they expire:
$ sepay einvoice authenv: sandboxPRODUCT ENV AUTH EXPIRESeinvoice sandbox bearer 2026-11-02T16:10:17Z--refresh fetches a new set; --insecure-storage stores the credentials in a 0600 file instead of the keychain.
Show how many invoices you have left:
$ sepay einvoice quotaenv: sandboxQUOTA REMAINING TAX APPROVED999 -TAX APPROVED is the date the tax authority approved the account, - until then. einvoice quota runs on the sandbox only; to see the invoices left on production, use sepay quota --env production (the einvoice line).
einvoice account
List your e-invoice provider accounts:
$ sepay einvoice account listenv: sandboxID PROVIDER ACTIVEc6448697-xxxx-xxxx-xxxx-a6006ab65aca matbao yespage 1/1 · 1 of 1Show one account and its invoice templates:
$ sepay einvoice account get c6448697-xxxx-xxxx-xxxx-a6006ab65acaenv: sandboxID: c6448697-xxxx-xxxx-xxxx-a6006ab65acaProvider: matbaoActive: yesTax approved: - TEMPLATE SERIES LABEL1 C26TSE 1 - C26TSE - Hóa đơn giá trị gia tăng2 C26TSE 2 - C26TSE - Hóa đơn bán hàngThe account ID is your provider_account_id; the TEMPLATE and SERIES columns are the template_code and invoice_series in the invoice data.
invoice create
Submits invoice data to SePay. The command returns a tracking code right away; the result is ready a few seconds later, and you check it with create-status.
Parameters
| Parameter | Description |
|---|---|
<payload> | The invoice data: @path (a file), - (stdin) or a JSON string |
The data is the body of the invoice creation API (Create eInvoice: field meanings, line items, tax rates, error codes).
Example
invoice.json (a draft invoice):
{"provider_account_id": "<id>","template_code": "2","invoice_series": "C26TSE","issued_date": "<today, YYYY-MM-DD HH:MM:SS>","currency": "VND","buyer": {"name": "Công ty ABC","tax_code": "0101234567","address": "123 Đường A, Quận B, Hà Nội","email": "ketoan@congtyabc.vn"},"items": [{"line_number": 1,"line_type": 1,"item_code": "SP001","item_name": "Sản phẩm A","unit": "cái","quantity": 1,"unit_price": 50000}],"is_draft": true}
$ sepay einvoice invoice create @invoice.json✓ submitted (tracking 084e179d-xxxx-xxxx-xxxx-3a6f1e2d8c40)poll: sepay einvoice invoice create-status 084e179d-xxxx-xxxx-xxxx-3a6f1e2d8c40Notes
- The tracking code is also the invoice's
reference_code. With--json, the code is in thetracking_codefield. issued_datemust be today's date (Vietnam time, inYYYY-MM-DD HH:MM:SSformat). Any other date is rejected withISSUED_DATE_INVALID, so replace the sample value before you run the command.is_draftis a boolean, not a string; if it's missing or the wrong type, the command exits with exit code 2.
On the sandbox, the invoice is not sent to the tax authority. On production, an issued invoice can't be cancelled or withdrawn, only replaced or adjusted.
invoice create-status
Checks the status of an invoice creation.
$ sepay einvoice invoice create-status 084e179d-xxxx-xxxx-xxxx-3a6f1e2d8c40Ref: 084e179d-xxxx-xxxx-xxxx-3a6f1e2d8c40Status: SuccessStatus | Meaning | Exit |
|---|---|---|
Pending | SePay and the provider are still processing it; check again after 2 to 3 seconds | 0 |
Success | The invoice has been created | 0 |
Failed | The provider rejected it; the Reason: line gives the cause | 1 |
The command checks once and exits; it doesn't wait. When the invoice already has a number, the output also prints Number: and Total:. Because Pending and Success both exit with 0, a script should read the status field of the --json output:
tracking=$(sepay einvoice invoice create @invoice.json --json | jq -r '.tracking_code // empty')[ -n "$tracking" ] || exit 1 # the error is already on stderrfor i in $(seq 1 10); do# Non-zero exit: Failed (reason in the message field) or another error (already on stderr)if ! out=$(sepay einvoice invoice create-status "$tracking" --json); then[ -n "$out" ] && echo "$out" >&2exit 1fiif [ "$(echo "$out" | jq -r '.status')" = "Success" ]; thenecho "Invoice $tracking created"; exit 0fisleep 3 # Pendingdoneecho "Timed out; check again: sepay einvoice invoice create-status $tracking" >&2exit 1
invoice issue and invoice issue-status
Issues a draft invoice created with invoice create.
Issue the draft invoice:
$ sepay einvoice invoice issue 084e179d-xxxx-xxxx-xxxx-3a6f1e2d8c40Check the issue status:
$ sepay einvoice invoice issue-status 084e179d-xxxx-xxxx-xxxx-3a6f1e2d8c40invoice issue takes the draft invoice's reference_code (the tracking code from when you created it) and prints the tracking code of the issuing request, which is the same reference_code. issue-status gives the same output and exit codes as create-status; on Success, Number: is the official invoice number. Reuse the create-status polling loop for issue <reference_code> --yes and issue-status.
invoice issue always asks for confirmation. Don't run issue twice on the same draft: the second request is accepted, then the provider marks the invoice Failed (ExistsFkey).
invoice get and invoice list
Show an issued invoice:
$ sepay einvoice invoice get 522746a3-xxxx-xxxx-xxxx-940387b5e986env: sandboxRef: 522746a3-xxxx-xxxx-xxxx-940387b5e986Number: 326602Series: C26TSEStatus: issuedIssued: 2026-10-17Payment: TM/CKBuyer: Cong ty Nghiem Thu (MST 0101234567)Subtotal: 300.000Tax: 30.000Total: 330.000PDF: https://...List invoices created through the API:
$ sepay einvoice invoice list --source api --per-page 50invoice get takes a reference_code and prints the invoice fields, followed by a line-item table (ITEM, QTY, UNIT PRICE, TAX%, AMOUNT), plus links to the PDF and XML files (pdf_url, xml_url) once the provider has generated them.
invoice list flag | Type | Description |
|---|---|---|
--source | string | manual (created on my.sepay.vn) | api (created through the API and CLI) |
--page, --per-page | int | Pagination; up to 100 |
Read invoices on production
invoice list and invoice get also run on production. Both only read, so they don't ask for confirmation, and default_env: production counts too. The CLI reads invoices with your sign-in session:
$ sepay einvoice invoice list --env production --per-page 50 -o json$ sepay einvoice invoice get <reference_code> --env production -o json- The token needs the
einvoice:readscope; without it the command exits with exit code 5 and printstoken lacks the required scope, run: sepay auth refresh --scopes einvoice:read. - Your account needs the eInvoice permission in the company; without it, exit code 8,
your account lacks permission for this action; ask an admin of your company. - Amounts are integers (
total_before_tax,tax_amount,total_amount); a total the server sends asnullreads as0.buyeralways hasname, and may havetax_code,address,email. - The
-o jsonoutput oflistis an array, with no page information. Read all pages as withpg order list, keyed byreference_code.
Creating, issuing, replacing and adjusting invoices on production are not in the CLI yet.
Error codes
| Message or code | Exit / error_code | Cause |
|---|---|---|
Exit code 2 from invoice create | 2 / usage_error | is_draft is missing or is a string, or the JSON is malformed |
Failed (create-status, issue-status) | 1 / none; status: Failed on stdout | The provider rejected it; the reason is in Reason: or message. API error codes: Create eInvoice |
no invoice with that reference code | 1 / EINVOICE_DOCUMENT_NOT_FOUND | The reference_code doesn't exist, usually because of a typo or the wrong environment (invoice list lists the invoices that exist) |
this company has no e-invoice provider account | 1 / EINVOICE_ACCOUNT_NOT_FOUND | The company has no provider account; einvoice account list shows no rows |
einvoice_provision_failed, einvoice_token_failed | 1 | SePay hasn't finished setting up the sandbox e-invoice environment or couldn't issue a credential; run again, and report it to SePay if it keeps failing |