Endpoints: /v1/invoices
HTTP Method: POST
Headers:

Production: https://api.midtrans.com/v1/invoices

Sandbox: https://api.sandbox.midtrans.com/v1/invoices

Key	Description
Authorization	Basic Base64Encode(merchantServerKey:)

Idempotency Key

🚧
To prevent duplicate invoice creation during retries, send an X-Idempotency-Key header in your request.
Requests sent with the same idempotency key within 5 minutes will be treated as the same create operation, so the invoice will only be created once.
Use a unique and hard-to-guess value such as a UUID for each new invoice creation request.

Request Body

{
    "order_id": "7950c36a-d267-4f25-bb03-7a82b00z168t",
    "invoice_number": "7128c81b-cde5-4c33-8777-4d1d0fcd6377",
    "due_date": "2025-08-06 20:03:04 +0700",
    "invoice_date": "2025-01-06 20:03:04 +0700",
    "invoice_title": "INVOICE",
    "invoice_paid_title": "INVOICE",
    "customer_details": {
        "id": "customer_id",
        "name": "merchant A",
        "email": "merchant@midtrans.com",
        "phone": "82313123123"
    },
    "payment_type": "payment_link",
    "reference": "reference",
    "item_details": [
        {
            "item_id": "SKU1111",
            "description": "midtrans pillow",
            "quantity": 1,
            "price": 2000
        }
    ],
    "notes": "just a notes",
    "payment_link": {
        "is_custom_expiry": true,
        "enabled_payments": [
            "bca_va"
        ],
        "credit_card": {
            "secure": true,
            "type": "authorize",
            "bank": "bni",
            "whitelist_bins": [
                "48111111"
            ],
            "installment": {
                "required": true,
                "terms": {
                    "mandiri": [
                        3
                    ],
                    "bca": [
                        3
                    ],
                    "bni": [
                        3
                    ],
                    "bri": [
                        3
                    ],
                    "cimb": [
                        3
                    ],
                    "maybank": [
                        3
                    ],
                    "offline": [
                        3
                    ]
                }
            }
        },
        "bca_va": {
            "number": "12345678901",
            "free_text": {
                "inquiry": [
                    {
                        "id": "id inquiry",
                        "en": "en inquiry"
                    }
                ],
                "payment": [
                    {
                        "id": "id payment",
                        "en": "en payment"
                    }
                ]
            }
        },
        "bni_va": {
            "number": "12312312312"
        },
        "permata_va": {
            "number": "12312312312",
            "recipient_name": "name"
        },
        "bri_va": {
            "number": "12312312312"
        },
        "cimb_va": {
            "number": "12312312312"
        },
        "expiry": {
            "unit": "months",
            "duration": 1,
            "start_time": "2025-02-21 09:48:29 +0700"
        },
        "callbacks": {
            "finish": "https://google.com"
        }
    },
    "amount": {
        "discount": "1000",
        "shipping": "11"
    },
    "tax_mode": "exclusive",
    "taxes": [
        {
            "name": "PPN",
            "type": "percentage",
            "value": 0.2
        }
    ]
}

{
    "order_id": "7950c36a-d267-4f25-bb03-7a82b00z168t",
    "invoice_number": "7128c81b-cde5-4c33-8777-4d1d0fcd6377",
    "due_date": "2025-08-06 20:03:04 +0700",
    "invoice_date": "2025-01-06 20:03:04 +0700",
    "invoice_title": "INVOICE",
    "invoice_paid_title": "INVOICE",
    "customer_details": {
        "id": "customer_id",
        "name": "merchant A",
        "email": "merchant@midtrans.com",
        "phone": "82313123123"
    },
    "payment_type": "virtual_account",
    "reference": "reference",
    "item_details": [
        {
            "item_id": "SKU1111",
            "description": "midtrans pillow",
            "quantity": 1,
            "price": 2000
        }
    ],
    "notes": "just a notes",
    "virtual_accounts": [
        {
            "bank": "bca_va"
        }
    ],
    "amount": {
        "vat": "12313",
        "discount": "1000",
        "shipping": "11"
    }
}

{
  "document_type": "quotation",
  "quotation_date": "2026-07-06T20:03:04Z",
  "quotation_validity_date": "2026-08-06T20:03:04Z",
  "order_id": "7128c81b-cde5-4c33-8777-4d1d0fcd6377",
  "invoice_number": "7128c81b-cde5-4c33-8777-4d1d0fcd6377",
  "due_date": "2026-08-06T20:03:04Z",
  "invoice_date": "2026-07-20T20:03:04Z",
  "customer_details": {
    "id": "customer_id",
    "name": "merchant A",
    "email": "test@test.com",
    "phone": "6281398220123"
  },
  "item_details": [
    {
      "item_id": "SKU1111",
      "description": "Metal Gear REX",
      "quantity": "1",
      "price": "200"
    }
  ],
  "currency": "IDR",
  "notes": "just a notes",
  "payment_type": "payment_link",
  "payment_link": {
    "is_custom_expiry": true,
    "enabled_payments": [
      "bca_va"
    ],
    "credit_card": {
      "bank": "bni",
      "type": "authorize",
      "secure": false,
      "installment": {
        "required": true,
        "terms": {
          "mandiri": [
            3
          ],
          "bca": [
            3
          ],
          "bni": [
            3
          ],
          "bri": [
            3
          ],
          "cimb": [
            3
          ],
          "maybank": [
            3
          ],
          "offline": [
            3
          ]
        }
      }
    },
    "expiry": {
      "unit": "months",
      "duration": 5
    },
    "callbacks": {
      "finish": "https://google.com"
    }
  },
  "virtual_accounts": [
    {
      "number": "12345678901",
      "bank": "bca_va"
    }
  ],
  "amount": {
    "discount": "1000",
    "shipping": "11"
  },
  "tax_mode": "exclusive",
  "taxes": [
    {
      "name": "PPN",
      "type": "percentage",
      "value": 0.2
    }
  ]
}

Request JSON Body Details

Parameter	Description
order_id String (36) Required	Id for the order, must be unique for each invoice NOTE: only consist of alphanumeric characters [a-z, 0-9 ], hyphens [- ], underscores [_ ], tilde [~ ] and dot [. ]
invoice_number String (40) Required	Number of the invoice
due_date String (40) Required	Due date of transaction in ISO 8601 format. Default time zone: GMT+7 and has to be after invoice_date. For example: `2025-08-06 20: 03: 04 +0700`
invoice_date String (40) Required	Date of Invoice and will be used in email and PDF created in ISO 8601 format. Default time zone: GMT+7. For example: `2025-08-06 20: 03: 04 +0700`
invoice_title String (20)	Title of the Invoice on creation. This will be used on Invoice PDF when the Invoice is not paid yet.
invoice_paid_title String (20)	Title of the Invoice when status is Paid. This will be used on Invoice PDF when the Invoice is paid.
customer_details Required	Refer to Customer Details object section.
reference String(90): Optional	Reference of the invoice
item_details Array: Required (Min 1)	Refer to Item Detail object section (NOTE: total price must not be 0)
Notes String(1000): Optional	Notes of the invoice
payment_type String: Required	Either payment_link or virtual_account
payment_link Optional	Refer to Payment Link object section, nullable when payment_type is payment_link
virtual_accounts array<virtual_account> Optional (Min 1)	Refer to Virtual Account object section, required and must not empty when payment_type is virtual_account
amount Optional	Refer to Amount object section
document_type Optional	Type of document to be created. Use quotation to generate a quotation document. If this field is set to quotation, then `quotation_date` and `quotation_validity_date` are required. Possible values are `quotation` or `invoice`(default).
quotation_date String (40) Required (if document_type: quotation)	Date when the quotation is issued, in ISO 8601 format. Default time zone: GMT+7. For example: `2025-08-06 20: 03: 04 +0700`
quotation_validity_date String (40) Required (if document_type: quotation)	Expiration date of the quotation, in ISO 8601 format. Default time zone: GMT+7 and must be after quotation_date. For example: `2025-08-20 23: 59: 59 +0700`
tax_mode Optional	Tax calculation mode for the invoice. Possible values are `exclusive` or `inclusive`. Note: If tax_mode is passed as null, no tax will be applied to the invoice. This will override any default invoice tax settings configured in your dashboard.
taxes Array<tax>	List of tax entries applied to the invoice. Optional, but required when tax_mode is inclusive. Refer to Tax object section Note: The taxes and vat parameters cannot be used in the same request. The vat parameter is currently deprecated; please use taxes for all new implementations.

Response sample

{
  "order_id": "7950c36a-d267-4f25-bb03-7a82b00z168t",
  "invoice_number": "7128c81b-cde5-4c33-8777-4d1d0fcd6377",
  "invoice_title": "INVOICE",
  "invoice_paid_title": "INVOICE",
  "published_date": "2024-03-06 10:54:14 +0700",
  "due_date": "2025-08-06 20:03:04 +0700",
  "invoice_date": "2025-01-06 20:03:04 +0700",
  "reference": "reference",
  "customer_details": {
    "id": "customer_id",
    "name": "merchant A",
    "email": "merchant@midtrans.com",
    "phone": "82313123123"
  },
  "item_details": [
    {
      "item_id": "SKU1111",
      "description": "midtrans pillow",
      "quantity": 1,
      "price": 2000
    }
  ],
  "id": "65e7e8e657389830d04836fc",
  "status": "pending",
  "gross_amount": 13324,
  "pdf_url": "https://assets.midtrans.com/invoices/pdf/5a76417e-be8e-437a-8e16-38c916aea614",
  "payment_type": "payment_link",
  "virtual_accounts": [],
  "payment_link_url": "https://app.midtrans.com/payment-links/b1000b26-a311-42d4-9dc7-51a00ec8c681",
  "tax_mode": "exclusive",
  "taxes": [
    {
      "name": "PPN",
      "type": "percentage",
      "value": 0.2,
      "calculated_amount": 38
    }
  ],
  "document_type": "quotation",
  "quotation_date": "2026-07-07 03:03:04 +0700",
  "quotation_title": "QUOTATION TITLE",
  "quotation_validity_date": "2026-08-07 03:03:04 +0700",
  "quotation_pdf_url": "https://assets.stg.midtrans.com/quotations/8P1lnAJx",
  "quotation_terms_conditions": "QUOTATION TERMS & CONDITION",
  "converted_at": null,
  "created_as": "quotation",
  "quotation_published_date": "2026-04-28 16:45:43 +0700"
}

{
  "order_id": "7950c36a-d267-4f25-bb03-7a82b00z168t",
  "invoice_number": "7128c81b-cde5-4c33-8777-4d1d0fcd6377",
  "invoice_title": "INVOICE",
  "invoice_paid_title": "INVOICE",
  "published_date": "2024-03-06 10:54:14 +0700",
  "due_date": "2025-08-06 20:03:04 +0700",
  "invoice_date": "2025-01-06 20:03:04 +0700",
  "reference": "reference",
  "customer_details": {
    "id": "customer_id",
    "name": "merchant A",
    "email": "merchant@midtrans.com",
    "phone": "82313123123"
  },
  "item_details": [
    {
      "item_id": "SKU1111",
      "description": "midtrans pillow",
      "quantity": 1,
      "price": 2000
    }
  ],
  "id": "65e7e8e657389830d04836fc",
  "status": "pending",
  "gross_amount": 13324,
  "pdf_url": "https://assets.midtrans.com/invoices/pdf/5a76417e-be8e-437a-8e16-38c916aea614",
  "payment_type": "payment_link",
  "virtual_accounts": [],
  "payment_link_url": "https://app.midtrans.com/payment-links/b1000b26-a311-42d4-9dc7-51a00ec8c681",
  "tax_mode": "exclusive",
  "taxes": [
    {
      "name": "PPN",
      "type": "percentage",
      "value": 0.2,
      "calculated_amount": 38
    }
  ],
  "document_type": "quotation",
  "quotation_date": "2026-07-07 03:03:04 +0700",
  "quotation_title": "QUOTATION TITLE",
  "quotation_validity_date": "2026-08-07 03:03:04 +0700",
  "quotation_pdf_url": "https://assets.stg.midtrans.com/quotations/8P1lnAJx",
  "quotation_terms_conditions": "QUOTATION TERMS & CONDITION",
  "converted_at": null,
  "created_as": "quotation",
  "quotation_published_date": "2026-04-28 16:45:43 +0700"
}

{
 "error_messages": [
   "item must not be empty",
   "gross_amount must be more than 0"
 ]
}

--Occurred when creating an invoice using the same order id that was used previously.

{
   "error_messages": [
       "Duplicate order id"
   ]
}

{
   "error_messages": [
       "Internal server error"
   ]
}

Field	Description
order_id String	Id for the order
id String	invoice id
invoice_number String	Number of the invoice
invoice_title String	Title of the Invoice on creation. This will be used on Invoice PDF when the Invoice is not paid yet.
invoice_paid_title String	Title of the Invoice when status is Paid. This will be used on Invoice PDF when the Invoice is paid.
due_date String	Due date of transaction in ISO 8601 format. Default time zone: GMT+7.
invoice_date String	Date of Invoice and will be used in email and pdf created in ISO 8601 format. Default time zone: GMT+7.
customer_details Object	Refer to Customer Details object section.
item_details Array<item_detail>	Refer to Item Detail object section
payment_type String	Either payment_link or virtual_account
payment_link_url String	URL for payment link and only filled when payment_type is payment_link
virtual_accounts array <virtual_account>	Invoice virtual account and only filled when payment_type is virtual_account. Refer to Virtual Account object section.
pdf_url String	pdf_url of the invoice
gross_amount Integer	Total amount in invoice
status String	Status of the invoice, can be `draft`, `pending`,`published`, `expired`, `overdue`, `paid`, `voided`, `rejected` or `canceled`.
document_type String	Type of document returned by the API. Possible values are `quotation` or `invoice`(default)
quotation_title String	Title displayed on the quotation document (PDF/view).
quotation_date String	Quotation issue date in ISO 8601 format with default time zone GMT+7.
quotation_validity_date String	Quotation expiration date in ISO 8601 format with default time zone GMT+7. After this date, the quotation is no longer valid.
quotation_published_date String	Timestamp when the quotation was published/generated and made available (for example for PDF sharing), in ISO 8601 format with default time zone GMT+7.
quotation_pdf_url String	Public URL to access/download the generated quotation PDF file.
quotation_terms_conditions String	Terms and conditions text attached to the quotation document.
converted_at String	Timestamp when the quotation was converted to another document type (for example, invoice). null means it has not been converted.
created_as String	Original document mode when first created. Value quotation indicates this record was initially created as a quotation.
tax_mode String	Tax calculation mode for the invoice. Possible values are `exclusive` or `inclusive`
taxes Array<tax>	List of tax entries applied to the invoice. Refer to Tax object section