Invoices and payment pages for one-time or partial-payment collection. Create in draft, issue to the customer, and track payment status. Cannot be used for GST invoices (use the Dashboard for those). Maximum 50 line items per invoice.
openapi: 3.0.0
info:
title: Razorpay Bills Invoices API
version: 1.0.0
description: Razorpay payment gateway APIs for accepting payments, managing orders, processing refunds, payouts, and subscriptions. All amounts are in the smallest currency sub-unit (e.g. paise for INR). Supports 180+ payment methods including UPI, cards, netbanking, wallets, and EMI.
termsOfService: https://razorpay.com/terms/
contact:
name: Razorpay Support
url: https://razorpay.com/support/
email: support@razorpay.com
license:
name: Proprietary
url: https://razorpay.com/terms/
x-logo:
url: https://razorpay.com/favicon.png
x-auth-environments:
test:
keyPrefix: rzp_test_
description: Test mode — keys prefixed rzp_test_. Same API endpoint (https://api.razorpay.com/v1). No real money movement. Use test card numbers from https://razorpay.com/docs/payments/payments/test-card-details/.
live:
keyPrefix: rzp_live_
description: Live mode — keys prefixed rzp_live_. Real money movement. Requires KYC and business activation on the Razorpay Dashboard.
servers:
- url: https://api.razorpay.com/v1
description: Production
security:
- basicAuth: []
- oauth2:
- read_only
tags:
- name: Invoices
description: Invoices and payment pages for one-time or partial-payment collection. Create in draft, issue to the customer, and track payment status. Cannot be used for GST invoices (use the Dashboard for those). Maximum 50 line items per invoice.
paths:
/invoices:
post:
operationId: createInvoice
summary: Create an invoice
description: 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.
tags:
- Invoices
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- type
properties:
type:
type: string
enum:
- invoice
- link
description: 'invoice: formal invoice; link: payment page.'
description:
type: string
customer_id:
type: string
description: Existing customer ID (cust_*). Provide this OR customer object, not both.
customer:
type: object
description: Inline customer details. Used when no customer_id is available.
properties:
name:
type: string
email:
type: string
contact:
type: string
line_items:
type: array
maxItems: 50
description: Invoice line items. Each item must have name and amount (in paise), or an item_id to reference a catalog item.
items:
type: object
properties:
item_id:
type: string
description: Reference a catalog item. Populates name, amount, currency automatically.
name:
type: string
description:
type: string
amount:
type: integer
description: Price in paise.
quantity:
type: integer
default: 1
currency:
type: string
default: INR
currency:
type: string
default: INR
receipt:
type: string
description: Your internal reference number.
comment:
type: string
terms:
type: string
description: Payment terms shown on the invoice.
partial_payment:
type: boolean
description: Allow customer to pay a partial amount initially.
first_payment_min_amount:
type: integer
description: Minimum first payment amount in paise. Required when partial_payment=true.
expire_by:
type: integer
description: Unix timestamp after which the invoice expires. Must be at least 15 minutes in the future.
notes:
$ref: '#/components/schemas/Notes'
responses:
'200':
description: Invoice created in draft state.
content:
application/json:
schema:
$ref: '#/components/schemas/Invoice'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'429':
$ref: '#/components/responses/429'
get:
operationId: listInvoices
summary: List all invoices
description: Retrieve a list of invoices. Filter by type, status, customer, payment, or subscription. Returns up to 100 per call.
tags:
- Invoices
parameters:
- name: type
in: query
schema:
type: string
enum:
- invoice
- link
description: Filter by invoice type.
- name: payment_id
in: query
schema:
type: string
description: Filter invoices by the payment ID used to pay them.
- name: customer_id
in: query
schema:
type: string
description: Filter by customer ID (cust_*).
- name: subscription_id
in: query
schema:
type: string
description: Fetch all invoices generated for a subscription (sub_*).
- $ref: '#/components/parameters/from'
- $ref: '#/components/parameters/to'
- $ref: '#/components/parameters/count'
- $ref: '#/components/parameters/skip'
responses:
'200':
description: Collection of invoices.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Collection'
- properties:
items:
type: array
items:
$ref: '#/components/schemas/Invoice'
'401':
$ref: '#/components/responses/401'
'429':
$ref: '#/components/responses/429'
/invoices/{id}:
get:
operationId: fetchInvoice
summary: Fetch an invoice
description: Get full details of a specific invoice including status, line items, and payment information.
tags:
- Invoices
parameters:
- name: id
in: path
required: true
description: Invoice ID (inv_*).
schema:
type: string
responses:
'200':
description: Invoice details.
content:
application/json:
schema:
$ref: '#/components/schemas/Invoice'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
patch:
operationId: updateInvoice
summary: Update an invoice
description: 'Update invoice fields. Updatable fields depend on current status: draft=all fields; issued=partial_payment, receipt, comment, terms, notes, expire_by; paid/cancelled/expired=notes only.'
tags:
- Invoices
parameters:
- name: id
in: path
required: true
description: Invoice ID (inv_*).
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
description:
type: string
receipt:
type: string
comment:
type: string
terms:
type: string
partial_payment:
type: boolean
expire_by:
type: integer
notes:
$ref: '#/components/schemas/Notes'
line_items:
type: array
description: Replaces existing line items. Draft status only.
items:
type: object
responses:
'200':
description: Updated invoice.
content:
application/json:
schema:
$ref: '#/components/schemas/Invoice'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
delete:
operationId: deleteInvoice
summary: Delete a draft invoice
description: Permanently delete a draft invoice. Only invoices in draft status can be deleted.
tags:
- Invoices
parameters:
- name: id
in: path
required: true
description: Invoice ID (inv_*).
schema:
type: string
responses:
'200':
description: Invoice deleted.
content:
application/json:
schema:
type: object
description: Empty object on success.
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
/invoices/{id}/issue:
post:
operationId: issueInvoice
summary: Issue an invoice
description: Transition a draft invoice to issued status, sending a notification to the customer with the payment link. Once issued, line items cannot be changed.
tags:
- Invoices
parameters:
- name: id
in: path
required: true
description: Invoice ID (inv_*).
schema:
type: string
responses:
'200':
description: Invoice issued. short_url is now active.
content:
application/json:
schema:
$ref: '#/components/schemas/Invoice'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
/invoices/{id}/cancel:
post:
operationId: cancelInvoice
summary: Cancel an invoice
description: Cancel a draft or issued invoice. Cancelled invoices cannot be paid and cannot be reinstated.
tags:
- Invoices
parameters:
- name: id
in: path
required: true
description: Invoice ID (inv_*).
schema:
type: string
responses:
'200':
description: Invoice cancelled.
content:
application/json:
schema:
$ref: '#/components/schemas/Invoice'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
/invoices/{id}/notify_by/{medium}:
post:
operationId: sendInvoiceNotification
summary: Send invoice notification
description: Send or resend the invoice payment link to the customer via SMS or email.
tags:
- Invoices
parameters:
- name: id
in: path
required: true
description: Invoice ID (inv_*).
schema:
type: string
- name: medium
in: path
required: true
description: Notification channel.
schema:
type: string
enum:
- sms
- email
responses:
'200':
description: Notification sent.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
components:
schemas:
InvoiceLineItem:
type: object
properties:
id:
type: string
description: 'Line item ID. Prefix: li_'
item_id:
type: string
description: Referenced catalog item ID (item_*). Null for ad-hoc line items.
name:
type: string
description:
type: string
amount:
type: integer
description: Total line amount in paise (unit_amount × quantity).
unit_amount:
type: integer
description: Per-unit price in paise.
quantity:
type: integer
default: 1
currency:
type: string
default: INR
type:
type: string
enum:
- invoice
- payment_page
Invoice:
type: object
description: 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).
properties:
id:
type: string
description: 'Invoice ID. Prefix: inv_'
entity:
type: string
enum:
- invoice
type:
type: string
enum:
- invoice
- link
description: 'invoice: a formal invoice document. link: a payment page / payment link.'
status:
type: string
enum:
- draft
- issued
- partially_paid
- paid
- cancelled
- expired
- deleted
description: Invoice lifecycle status. draft→issued→paid/partially_paid/cancelled/expired.
invoice_number:
type: string
description: Auto-generated invoice number (e.g. INV-001).
customer_id:
type: string
description: Customer ID (cust_*).
customer:
type: object
description: Inline customer details snapshot at time of invoice creation.
order_id:
type: string
description: Associated order ID (order_*).
line_items:
type: array
maxItems: 50
description: Up to 50 line items.
items:
$ref: '#/components/schemas/InvoiceLineItem'
payment_id:
type: string
description: Payment ID (pay_*) of the successful payment, if paid.
currency:
type: string
default: INR
gross_amount:
type: integer
description: Sum of all line item amounts before tax (paise).
tax_amount:
type: integer
description: Total tax amount (paise).
taxable_amount:
type: integer
description: Taxable base amount (paise).
amount:
type: integer
description: Total invoice amount including tax (paise).
amount_paid:
type: integer
description: Amount received so far (paise). Relevant for partial_payment invoices.
amount_due:
type: integer
description: Remaining amount due (paise).
short_url:
type: string
description: Hosted payment page URL to send to the customer.
partial_payment:
type: boolean
description: If true, customer can pay any amount ≥ first_payment_min_amount.
first_payment_min_amount:
type: integer
description: Minimum amount for the first partial payment (paise). Required when partial_payment=true.
receipt:
type: string
description: Your internal reference number.
description:
type: string
comment:
type: string
description: Internal comment (not shown on invoice).
terms:
type: string
description: Payment terms shown on the invoice.
notes:
$ref: '#/components/schemas/Notes'
expire_by:
type: integer
description: Unix timestamp after which the invoice expires and cannot be paid.
issued_at:
type: integer
paid_at:
type: integer
cancelled_at:
type: integer
expired_at:
type: integer
created_at:
type: integer
Notes:
type: object
description: Key-value pairs for storing custom metadata. Maximum 15 pairs. Each key and value must not exceed 256 characters.
additionalProperties:
type: string
maxProperties: 15
Error:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: 'Error code. Examples: BAD_REQUEST_ERROR, GATEWAY_ERROR, SERVER_ERROR.'
description:
type: string
source:
type: string
description: Where the error originated (e.g. business, gateway).
step:
type: string
reason:
type: string
description: 'Machine-readable reason. Examples: insufficient_funds, invalid_expiry_date, declined_by_bank.'
metadata:
type: object
field:
type: string
Collection:
type: object
properties:
entity:
type: string
enum:
- collection
count:
type: integer
description: Number of items in the current page.
items:
type: array
items: {}
parameters:
from:
name: from
in: query
description: Unix timestamp (seconds). Fetch records created on or after this time.
schema:
type: integer
to:
name: to
in: query
description: Unix timestamp (seconds). Fetch records created on or before this time.
schema:
type: integer
skip:
name: skip
in: query
description: Number of records to skip. Use with count for pagination. Default 0.
schema:
type: integer
minimum: 0
default: 0
count:
name: count
in: query
description: Number of records to return per call. Maximum 100. Default 10.
schema:
type: integer
minimum: 1
maximum: 100
default: 10
responses:
'404':
description: Resource not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'400':
description: Bad request. Invalid parameters or missing required fields.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Authentication failed. Invalid or missing API key credentials.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Rate limit exceeded. Implement exponential backoff with jitter before retrying.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
basicAuth:
type: http
scheme: basic
description: HTTP Basic authentication using your Razorpay API key pair. Use key_id as the username and key_secret as the password. Encode as Base64(key_id:key_secret). Keys are environment-scoped (Test vs Live). Obtain keys at https://dashboard.razorpay.com/app/keys. Keys are case-sensitive.
oauth2:
type: oauth2
description: OAuth 2.0 via the Razorpay MCP server (mcp.razorpay.com). Supports Authorization Code with PKCE (S256) for user-delegated access and Client Credentials for server-to-server access. Tokens expire in 3600 seconds. Dynamic Client Registration available at the registration endpoint. For integration setup see https://razorpay.com/docs/build/llm-docs/mcp-server/oauth.md.
flows:
authorizationCode:
authorizationUrl: https://mcp.razorpay.com/authorize
tokenUrl: https://mcp.razorpay.com/token
refreshUrl: https://mcp.razorpay.com/token
scopes:
read_only: Read-only access to Razorpay account data (payments, orders, refunds, payouts, subscriptions, invoices)
clientCredentials:
tokenUrl: https://mcp.razorpay.com/token
scopes:
read_only: Read-only access to Razorpay account data (payments, orders, refunds, payouts, subscriptions, invoices)
externalDocs:
description: Razorpay API Documentation
url: https://razorpay.com/docs/api/
x-tagGroups:
- name: Core Payments
tags:
- Orders
- Payments
- Refunds
- Payment Downtimes
- name: Payment Collection
tags:
- Payment Links
- QR Codes
- name: Billing & Subscriptions
tags:
- Items
- Invoices
- Plans
- Subscriptions
- name: Customer Management
tags:
- Customers
- Documents
- name: Finance & Reconciliation
tags:
- Settlements
- Instant Settlements
- Disputes
- name: Route & Marketplace
tags:
- Linked Accounts
- Transfers
- name: Smart Collect
tags:
- Virtual Accounts
- name: Partners & Onboarding
tags:
- Partner Accounts
- Partner Products
- Partner Stakeholders
- Partner Documents
- Partner Webhooks
- name: Bills
tags:
- Bills
- name: RazorpayX
tags:
- X Contacts
- X Fund Accounts
- X Account Validation
- X Banking Balances
- X Payouts
- X Payout Links
- X Transactions
x-rateLimit:
description: Razorpay does not publish specific rate limits. If you receive HTTP 429, implement exponential backoff with jitter and retry. Add randomisation to avoid thundering-herd effects.
throttleStatus: 429
strategy: exponential backoff with jitter
x-pagination:
description: All list endpoints return at most 100 records per call (1000 for settlement recon). Use count and skip together to paginate. Date range filters (from/to) use Unix timestamps in seconds.
example: GET /payments?from=1700000000&to=1700086400&count=100&skip=100
x-amountEncoding:
description: 'All monetary amounts are in the smallest currency sub-unit. For INR: 1 rupee = 100 paise, so ₹500 = 50000. Minimum for INR is 100 paise (₹1). Three-decimal currencies (KWD, BHD, OMR): drop last decimal digit. Zero-decimal currencies (JPY): pass value as-is.'