---
title: "Create an invoice"
method: POST
path: "/invoices"
tags: ["Invoices"]
---

# Create an invoice

`POST /invoices`

Create an invoice or payment page. Set type='invoice' for a formal invoice or type='link' for a simple payment page. The invoice is created in draft state; call POST /invoices/{id}/issue to send it to the customer. Cannot be used to create GST invoices (use the Dashboard for those). Maximum 50 line items per invoice.

## Request body

- object
  - `type` 'invoice' | 'link', required — invoice: formal invoice; link: payment page.
  - `description` string
  - `customer_id` string — Existing customer ID (cust_*). Provide this OR customer object, not both.
  - `customer` object — Inline customer details. Used when no customer_id is available.
    - `name` string
    - `email` string
    - `contact` string
  - `line_items` object[] — Invoice line items. Each item must have name and amount (in paise), or an item_id to reference a catalog item.
    - `item_id` string — Reference a catalog item. Populates name, amount, currency automatically.
    - `name` string
    - `description` string
    - `amount` integer — Price in paise.
    - `quantity` integer
    - `currency` string
  - `currency` string
  - `receipt` string — Your internal reference number.
  - `comment` string
  - `terms` string — Payment terms shown on the invoice.
  - `partial_payment` boolean — Allow customer to pay a partial amount initially.
  - `first_payment_min_amount` integer — Minimum first payment amount in paise. Required when partial_payment=true.
  - `expire_by` integer — Unix timestamp after which the invoice expires. Must be at least 15 minutes in the future.
  - `notes` Notes — Key-value pairs for storing custom metadata. Maximum 15 pairs. Each key and value must not exceed 256 characters.

## Response `200`

Invoice created in draft state.

- Invoice — An invoice or payment page sent to a customer for payment. Cannot be used to create GST invoices (those must be created via the Dashboard).
  - `id` string — Invoice ID. Prefix: inv_
  - `entity` 'invoice'
  - `type` 'invoice' | 'link' — invoice: a formal invoice document. link: a payment page / payment link.
  - `status` 'draft' | 'issued' | 'partially_paid' | 'paid' | 'cancelled' | 'expired' | 'deleted' — Invoice lifecycle status. draft→issued→paid/partially_paid/cancelled/expired.
  - `invoice_number` string — Auto-generated invoice number (e.g. INV-001).
  - `customer_id` string — Customer ID (cust_*).
  - `customer` object — Inline customer details snapshot at time of invoice creation.
  - `order_id` string — Associated order ID (order_*).
  - `line_items` InvoiceLineItem[] — Up to 50 line items.
    - `id` string — Line item ID. Prefix: li_
    - `item_id` string — Referenced catalog item ID (item_*). Null for ad-hoc line items.
    - `name` string
    - `description` string
    - `amount` integer — Total line amount in paise (unit_amount × quantity).
    - `unit_amount` integer — Per-unit price in paise.
    - `quantity` integer
    - `currency` string
    - `type` 'invoice' | 'payment_page'
  - `payment_id` string — Payment ID (pay_*) of the successful payment, if paid.
  - `currency` string
  - `gross_amount` integer — Sum of all line item amounts before tax (paise).
  - `tax_amount` integer — Total tax amount (paise).
  - `taxable_amount` integer — Taxable base amount (paise).
  - `amount` integer — Total invoice amount including tax (paise).
  - `amount_paid` integer — Amount received so far (paise). Relevant for partial_payment invoices.
  - `amount_due` integer — Remaining amount due (paise).
  - `short_url` string — Hosted payment page URL to send to the customer.
  - `partial_payment` boolean — If true, customer can pay any amount ≥ first_payment_min_amount.
  - `first_payment_min_amount` integer — Minimum amount for the first partial payment (paise). Required when partial_payment=true.
  - `receipt` string — Your internal reference number.
  - `description` string
  - `comment` string — Internal comment (not shown on invoice).
  - `terms` string — Payment terms shown on the invoice.
  - `notes` Notes — Key-value pairs for storing custom metadata. Maximum 15 pairs. Each key and value must not exceed 256 characters.
  - `expire_by` integer — Unix timestamp after which the invoice expires and cannot be paid.
  - `issued_at` integer
  - `paid_at` integer
  - `cancelled_at` integer
  - `expired_at` integer
  - `created_at` integer

## Other responses

- `400` — Bad request. Invalid parameters or missing required fields.
- `401` — Authentication failed. Invalid or missing API key credentials.
- `429` — Rate limit exceeded. Implement exponential backoff with jitter before retrying.

---

[API](https://skmtc.net/razorpay/apis/razorpay-api.md) · [All operations](https://skmtc.net/razorpay/apis/razorpay-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/razorpay/razorpay-api/versions/824ca9e6faef/schema)