eInvoice in SePay CLI

Use SePay CLI with eInvoices: create and issue test invoices on sandbox, and list or read invoices on production, with their PDF and XML files.

||
Production has only the invoice read commands

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):

Code
1
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 1

Show 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àng

The 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

ParameterDescription
<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):

JSON
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
{
"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-3a6f1e2d8c40

Notes

  • The tracking code is also the invoice's reference_code. With --json, the code is in the tracking_code field.
  • issued_date must be today's date (Vietnam time, in YYYY-MM-DD HH:MM:SS format). Any other date is rejected with ISSUED_DATE_INVALID, so replace the sample value before you run the command.
  • is_draft is a boolean, not a string; if it's missing or the wrong type, the command exits with exit code 2.
is_draft: false issues the invoice immediately, without asking again

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:  Success
StatusMeaningExit
PendingSePay and the provider are still processing it; check again after 2 to 3 seconds0
SuccessThe invoice has been created0
FailedThe provider rejected it; the Reason: line gives the cause1

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:

Bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
tracking=$(sepay einvoice invoice create @invoice.json --json | jq -r '.tracking_code // empty')
[ -n "$tracking" ] || exit 1 # the error is already on stderr
 
for 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" >&2
exit 1
fi
if [ "$(echo "$out" | jq -r '.status')" = "Success" ]; then
echo "Invoice $tracking created"; exit 0
fi
sleep 3 # Pending
done
echo "Timed out; check again: sepay einvoice invoice create-status $tracking" >&2
exit 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-3a6f1e2d8c40

Check the issue status:

$ sepay einvoice invoice issue-status 084e179d-xxxx-xxxx-xxxx-3a6f1e2d8c40

invoice 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.

An issued invoice can't be cancelled or withdrawn

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 50

invoice 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 flagTypeDescription
--sourcestringmanual (created on my.sepay.vn) | api (created through the API and CLI)
--page, --per-pageintPagination; 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:read scope; without it the command exits with exit code 5 and prints token 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 as null reads as 0. buyer always has name, and may have tax_code, address, email.
  • The -o json output of list is an array, with no page information. Read all pages as with pg order list, keyed by reference_code.

Creating, issuing, replacing and adjusting invoices on production are not in the CLI yet.

Error codes

Message or codeExit / error_codeCause
Exit code 2 from invoice create2 / usage_erroris_draft is missing or is a string, or the JSON is malformed
Failed (create-status, issue-status)1 / none; status: Failed on stdoutThe provider rejected it; the reason is in Reason: or message. API error codes: Create eInvoice
no invoice with that reference code1 / EINVOICE_DOCUMENT_NOT_FOUNDThe 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 account1 / EINVOICE_ACCOUNT_NOT_FOUNDThe company has no provider account; einvoice account list shows no rows
einvoice_provision_failed, einvoice_token_failed1SePay 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