Create Replacement Invoice API

What is a replacement invoice?

A replacement invoice is issued when an e-invoice that has already been issued and accepted by the tax authority turns out to need a correction. Once the replacement is issued successfully, the original is flagged replaced and is no longer in force.

Unlike an adjustment invoice, which records only the difference, a replacement carries the full correct content of the new invoice: line items, quantities, unit prices, tax rates and the buyer details.

For example: the original invoice has the wrong product name and unit price on two lines. Instead of issuing several adjustment invoices, you can issue one replacement with the whole content corrected.

Origin invoice requirements

The origin invoice is identified by original_invoice_reference_code (the reference_code of a previously created invoice, under the same provider_account_id).

The origin invoice must:

• Have been issued successfully and accepted by the tax authority. Draft or in-progress invoices cannot be replaced.
• Be a new invoice, a replacement invoice or an already-adjusted invoice.
• Not have been replaced or cancelled.
• Never have been replaced before. Each origin invoice can be replaced once only.

A replacement invoice can itself be replaced if a mistake is found. An already-adjusted invoice can also be replaced.

How it works in the SePay eInvoice API

POST v1/invoices/replace takes original_invoice_reference_code together with the full content of the new invoice.

The API returns a tracking_code as soon as it accepts the request. Signing and filing the invoice with the tax authority are processed asynchronously. Use the tracking_code with the invoice status tracking API to follow the status and get the final result.

Each origin invoice can be replaced once only. If the replacement itself has a mistake, you adjust or replace that replacement - not the original invoice again.

API Endpoint

API Request

API Response

{
  "success": true,
  "data": {
    "tracking_code": "3f8b1c2a-7d95-11f1-aef4-52c7e9b4f41b",
    "tracking_url": "https://einvoice-api.sepay.vn/v1/invoices/replace/check/3f8b1c2a-7d95-11f1-aef4-52c7e9b4f41b",
    "message": "Đã tạo yêu cầu xuất hóa đơn thay thế"
  }
}

Error Handling

Usage Notes

• items uses the same parameters as the create invoice API - it contains the full corrected content of the invoice, NOT the difference. The invoice total cannot be negative.
• Goods/services and promotional lines (line_type = 1, 2) require item_code, unit and a quantity greater than 0.
• buyer is required - a replacement re-states the whole invoice, including buyer information.
• payment_method is optional - when omitted, the origin invoice's payment method is reused.
• issued_date is optional and must always be today (defaults to the API call time).
• is_draft=true creates a draft replacement invoice - issue it later via the issue invoice API using the draft's reference_code. is_draft=false creates and issues immediately.
• After a successful request, use tracking_url to call the invoice status tracking API - always poll until a terminal result (success or failure).

Sample Code

curl --request POST \
  --url https://einvoice-api.sepay.vn/v1/invoices/replace \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"provider_account_id":"0aea3134-da40-11f0-aef4-52c7e9b4f41b","original_invoice_reference_code":"084e179d-d95a-11f0-aef4-52c7e9b4f41b","issued_date":"2026-07-30 00:00:00","reference_code":"3f8b1c2a-7d95-11f1-aef4-52c7e9b4f41b","payment_method":"CK","is_draft":false,"buyer":{"type":"personal","name":"Công ty TNHH ABC","legal_name":"CÔNG TY CỔ PHẦN ABC","tax_code":"0123456789","address":"123 Đường ABC, Quận 1, TP.HCM","email":"contact@abc.com","phone":"0901234567","buyer_code":"KH-001","national_id":"001234567890"},"items":[{"line_number":1,"line_type":1,"item_code":"SP001","item_name":"Sản phẩm A","unit":"cái","quantity":10,"unit_price":100000,"tax_rate":10,"discount_tax":10,"discount_amount":100000,"before_discount_and_tax_amount":4500000}],"notes":"Thay thế cho hóa đơn ký hiệu C26TSE số 589 ngày 26/01/2026","total_amount":4950000}'

Sample Parameters

Basic replacement invoice

{
    "provider_account_id": "{{your-provider-account-id}}",
    "original_invoice_reference_code": "084e179d-d95a-11f0-aef4-52c7e9b4f41b",
    "buyer": {
        "type": "company",
        "name": "Công ty ABC",
        "legal_name": "CÔNG TY TNHH ABC",
        "tax_code": "0101234567",
        "address": "123 Đường A, Quận B, Hà Nội",
        "email": "buyer@example.com"
    },
    "items": [
        {
            "line_number": 1,
            "line_type": 1,
            "item_code": "SP001",
            "item_name": "Sản phẩm A",
            "unit": "cái",
            "quantity": 2,
            "unit_price": 4500000,
            "tax_rate": 10
        }
    ],
    "notes": "Thay thế cho hóa đơn ký hiệu C26TSE số 589 ngày 26/01/2026",
    "payment_method": "CK",
    "is_draft": false
}

Replacement invoice with a discount and a trade discount line

{
    "provider_account_id": "{{your-provider-account-id}}",
    "original_invoice_reference_code": "084e179d-d95a-11f0-aef4-52c7e9b4f41b",
    "reference_code": "replacement-invoice-001",
    "buyer": {
        "type": "personal",
        "name": "Nguyễn Văn A",
        "address": "Số 88 Đường Ánh Sao, Phường Bình An, Quận 9, TP Hồ Chí Minh",
        "email": "buyeremaildemo@gmail.com"
    },
    "items": [
        {
            "line_number": 1,
            "line_type": 1,
            "item_code": "SP001",
            "item_name": "Sản phẩm A",
            "unit": "cái",
            "quantity": 10,
            "unit_price": 100000,
            "discount_tax": 10,
            "tax_rate": 10
        },
        {
            "line_number": 2,
            "line_type": 3,
            "item_name": "Chiết khấu thương mại",
            "before_discount_and_tax_amount": 50000,
            "tax_rate": 10
        }
    ],
    "notes": "Thay thế cho hóa đơn ký hiệu C26TSE số 589 ngày 26/01/2026",
    "payment_method": "TM/CK",
    "is_draft": true
}

Next Steps

After a successful request returning a tracking_code:

1. Track invoice status - Use the tracking_code to check the processing result (required)