API References
Create AccountSubmit FeedbackContact Support

Create Invoice

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

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

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

KeyDescription
AuthorizationBasic 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": "[email protected]",
        "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": "[email protected]",
        "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": "[email protected]",
    "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
    }
  ]
}
{
  "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": "[email protected]",
    "phone": "82313123123"
  },
  "payment_type": "qris",
  "reference": "reference",
  "item_details": [
    {
      "item_id": "SKU1111",
      "description": "midtrans pillow",
      "quantity": 1,
      "price": 2000
    }
  ],
  "notes": "just a notes",
  "qris": {
    "expiry": {
      "unit": "days",
      "duration": 120
    }
  },
  "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": "[email protected]",
    "phone": "82313123123"
  },
  "payment_type": "manual_payment",
  "reference": "reference",
  "item_details": [
    {
      "item_id": "SKU1111",
      "description": "midtrans pillow",
      "quantity": 1,
      "price": 2000
    }
  ],
  "notes": "just a notes",
  "amount": {
    "discount": "1000",
    "shipping": "11"
  },
  "tax_mode": "exclusive",
  "taxes": [
    {
      "name": "PPN",
      "type": "percentage",
      "value": 0.2
    }
  ]
}

Request JSON Body Details

ParameterDescription
order_id
String (36)
Required		ID for the order. Must be unique for each invoice.
NOTE: Only alphanumeric characters [a-z, 0-9], hyphens [-], underscores [_], tilde [~], and dots [.] are allowed.
invoice_number
String (40)
Required		Number of the invoice.
due_date
String (40)
Required		Due date of the transaction in ISO 8601 format. Default time zone: GMT+7. Must be after invoice_date.
Example: 2025-08-06 20:03:04 +0700
invoice_date
String (40)
Required		Date of the invoice. This date will be used in the generated email and PDF. Uses ISO 8601 format with GMT+7 as the default time zone.
Example: 2025-08-06 20:03:04 +0700
invoice_title
String (20)		Title displayed on the Invoice PDF before the invoice is paid.
invoice_paid_title
String (20)		Title displayed on the Invoice PDF after the invoice is paid.
customer_details
Required		Refer to Customer Details object.
reference
String (90)
Optional		Reference for the invoice.
item_details
Array
Required (Min 1)		Refer to Item Detail object.
NOTE: The total item price must not be 0.
notes
String (1000)
Optional		Notes for the invoice.
payment_type
String
Required		Determines how the invoice will be paid.
Possible values: payment_link, virtual_account, qris, or manual_payment.
payment_link
Optional		Payment Link configuration. Refer to Payment Link object. Applicable when payment_type is payment_link.
amount
Optional		Refer to Amount object.
virtual_accounts
Array<virtual_account>
Optional (Min 1)		Virtual Account configuration. Refer to Virtual Account object. Required and must not be empty when payment_type is virtual_account.
document_type
Optional		Type of document to create. Use quotation to generate a quotation document. If set to quotation, quotation_date and quotation_validity_date are required.
Possible values: 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.
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. Must be after quotation_date.
Example: 2025-08-20 23:59:59 +0700
tax_mode
Optional		Tax calculation mode for the invoice.
Possible values: exclusive or inclusive.
If tax_mode is explicitly passed as null, no tax will be applied. This overrides any default invoice tax settings configured in the dashboard.
taxes
Array<tax>		List of tax entries applied to the invoice. Optional, but required when tax_mode is inclusive.
Refer to Tax object.
NOTE: taxes and vat cannot be used in the same request. vat is deprecated; use taxes for new implementations.
qris
Optional		Refer to QRIS object.

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": "[email protected]",
    "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": "[email protected]",
    "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"
   ]
}

{
  "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": "[email protected]",
    "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": "qris",
  "virtual_accounts": [],
  "qris_url": "https://api.stg.midtrans.com/v2/qris/dd4e56ab-c100-4199-86d7-80ba19a41c77/qr-code",
  "qris": {
    "acquirer": "gopay",
    "qr_string": "00020101021226620014COM.GO-JEK.WWW011993600914377234911250210G7723491120303UKE51440014ID.CO.QRIS.WWW0215AID2945998244280303UKE520417615303360540710010005802ID5915Toko Test Farah6013JAKARTA PUSAT61051011062395028A120260930022630dyA30kI0eiID0703A01630425AB",
    "expiry": {
      "unit": "days",
      "duration": 120
    }
  },
  "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"
}
FieldDescription
order_id StringId 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
qris_url
String		URL used to retrieve the QRIS QR code image.
qris
Optional		Refer to QRIS object.

Updated about 1 month ago

Did this page help you?

Updated about 1 month ago

Did this page help you?