aiml docs
ReferenceAPI reference

Credits

prepaid balance, ledger, top-ups and invoices

POST/v1/invoices/{id}/resend
AuthorizationBearer <token>

In: header

Path Parameters

id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

curl -X POST "https://example.com/v1/invoices/string/resend" \  -H "Content-Type: application/json" \  -d '{    "to": "finance@acme.example"  }'
{  "queued": true,  "to": "finance@acme.example"}
GET/v1/credits
AuthorizationBearer <token>

In: header

Response Body

application/json

application/json

curl -X GET "https://example.com/v1/credits"
{  "available_micro_usd": 12345678,  "held_micro_usd": 250000,  "granted_micro_usd": 0,  "display": {    "currency": "INR",    "amount": "1036.02"  },  "currency": "INR",  "fx_rate": "83.91750000"}
GET/v1/credits/ledger
AuthorizationBearer <token>

In: header

Query Parameters

cursor?string
limit?integer
Rangevalue <= 500
kind?string
format?unknown

csv streams the page as text/csv

Value in

  • "json"
  • "csv"

Response Body

application/json

curl -X GET "https://example.com/v1/credits/ledger"
{  "object": "list",  "data": [    {      "seq": 42,      "kind": "settle",      "amount_micro_usd": -489,      "request_id": "01J9ZK2K4Q7Q3M3QX1V0F1GATE",      "created_at": "2026-09-10T11:59:01Z"    },    {      "seq": 41,      "kind": "topup",      "amount_micro_usd": 11916466,      "ref_type": "topup",      "ref_id": "tup_01J9ZK2K4Q7Q3M3QX1V0F1TUP1",      "created_at": "2026-09-10T11:59:30Z"    }  ],  "next_cursor": ""}
GET/v1/credits/topups/quote
AuthorizationBearer <token>

In: header

Query Parameters

amount_minor*integer
Range1 <= value

Response Body

application/json

application/json

curl -X GET "https://example.com/v1/credits/topups/quote?amount_minor=1"
{  "rail": "razorpay",  "currency": "INR",  "amount_minor": 100000,  "tax_minor": 18000,  "total_minor": 118000,  "credits_micro": 11916466,  "fx_rate": "83.91750000",  "fx_day": "2026-09-10",  "fees": {    "rail": "razorpay",    "items": [      {        "method": "upi",        "bps": 0      },      {        "method": "netbanking",        "bps": 190      },      {        "method": "card_domestic",        "bps": 200      },      {        "method": "card_international",        "bps": 350      }    ]  },  "min_amount_minor": 50000,  "display": "INR 1000.00 of credits (USD 11.92) + tax INR 180.00 = INR 1180.00"}
GET/v1/credits/topups
AuthorizationBearer <token>

In: header

Query Parameters

cursor?string
limit?integer
Rangevalue <= 200

Response Body

application/json

application/json

curl -X GET "https://example.com/v1/credits/topups"
{  "object": "list",  "data": [    {      "id": "tup_01J9ZK2K4Q7Q3M3QX1V0F1TUP1",      "org_id": "org_01J9ZK2K4Q7Q3M3QX1V0F1ORG1",      "gateway": "razorpay",      "gateway_ref": "plink_Q9Mt7xF2d0kXtR",      "payment_ref": "pay_Q9MtPL2eZvKYlo",      "currency": "INR",      "amount_minor": 100000,      "tax_minor": 18000,      "total_minor": 118000,      "fee_minor": 0,      "fx_rate": "83.91750000",      "credits_micro": 11916466,      "method": "upi",      "status": "paid",      "invoice_id": "inv_01J9ZK2K4Q7Q3M3QX1V0F1INV1",      "source": "checkout",      "created_at": "2026-09-10T11:58:00Z",      "paid_at": "2026-09-10T11:59:30Z"    }  ]}
POST/v1/credits/topups
AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

curl -X POST "https://example.com/v1/credits/topups" \  -H "Content-Type: application/json" \  -d '{    "amount_minor": 100000  }'
{  "topup": {    "id": "tup_01J9ZK2K4Q7Q3M3QX1V0F1TUP1",    "org_id": "org_01J9ZK2K4Q7Q3M3QX1V0F1ORG1",    "gateway": "razorpay",    "gateway_ref": "plink_Q9Mt7xF2d0kXtR",    "currency": "INR",    "amount_minor": 100000,    "tax_minor": 18000,    "total_minor": 118000,    "fee_minor": 0,    "fx_rate": "83.91750000",    "credits_micro": 11916466,    "method": "upi",    "status": "pending",    "source": "checkout",    "created_at": "2026-09-10T11:58:00Z",    "checkout_url": "https://rzp.io/i/Q9Mt7xF2"  },  "checkout_url": "https://rzp.io/i/Q9Mt7xF2",  "quote": {    "rail": "razorpay",    "currency": "INR",    "amount_minor": 100000,    "tax_minor": 18000,    "total_minor": 118000,    "credits_micro": 11916466,    "fx_rate": "83.91750000",    "fx_day": "2026-09-10",    "fees": {      "rail": "razorpay",      "items": [        {          "method": "upi",          "bps": 0        },        {          "method": "netbanking",          "bps": 190        },        {          "method": "card_domestic",          "bps": 200        },        {          "method": "card_international",          "bps": 350        }      ]    },    "min_amount_minor": 50000,    "display": "INR 1000.00 of credits (USD 11.92) + tax INR 180.00 = INR 1180.00"  }}
GET/v1/credits/topups/{id}
AuthorizationBearer <token>

In: header

Path Parameters

id*string

Response Body

application/json

application/json

curl -X GET "https://example.com/v1/credits/topups/string"
{  "id": "tup_01J9ZK2K4Q7Q3M3QX1V0F1TUP1",  "org_id": "org_01J9ZK2K4Q7Q3M3QX1V0F1ORG1",  "gateway": "razorpay",  "gateway_ref": "plink_Q9Mt7xF2d0kXtR",  "payment_ref": "pay_Q9MtPL2eZvKYlo",  "currency": "INR",  "amount_minor": 100000,  "tax_minor": 18000,  "total_minor": 118000,  "fee_minor": 0,  "fx_rate": "83.91750000",  "credits_micro": 11916466,  "method": "upi",  "status": "paid",  "invoice_id": "inv_01J9ZK2K4Q7Q3M3QX1V0F1INV1",  "source": "checkout",  "created_at": "2026-09-10T11:58:00Z",  "paid_at": "2026-09-10T11:59:30Z"}
POST/v1/credits/topups/{id}/refund
AuthorizationBearer <token>

In: header

Path Parameters

id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/credits/topups/string/refund" \  -H "Content-Type: application/json" \  -d '{    "amount_minor": 30000,    "reason": "unused",    "idempotency_key": "rf-2026-09-10-1"  }'
{  "refund": {    "id": "rfd_01J9ZK2K4Q7Q3M3QX1V0F1RFD1",    "org_id": "org_01J9ZK2K4Q7Q3M3QX1V0F1ORG1",    "topup_id": "tup_01J9ZK2K4Q7Q3M3QX1V0F1TUP1",    "gateway": "razorpay",    "payment_ref": "pay_Q9MtPL2eZvKYlo",    "gateway_ref": "rfnd_Q9MtR5x",    "currency": "INR",    "amount_minor": 30000,    "tax_minor": 5400,    "total_minor": 35400,    "fx_rate": "83.91750000",    "credits_micro": 3574940,    "credit_note_id": "cn_01J9ZK2K4Q7Q3M3QX1V0F1CN01",    "status": "refunded",    "reason": "unused",    "created_at": "2026-09-10T13:00:00Z",    "settled_at": "2026-09-10T13:00:01Z",    "replay": true  }}
GET/v1/credits/refunds
AuthorizationBearer <token>

In: header

Query Parameters

cursor?string
limit?integer
Rangevalue <= 200

Response Body

application/json

application/json

curl -X GET "https://example.com/v1/credits/refunds"
{  "data": [    {      "id": "rfd_01J9ZK2K4Q7Q3M3QX1V0F1RFD1",      "org_id": "org_01J9ZK2K4Q7Q3M3QX1V0F1ORG1",      "topup_id": "tup_01J9ZK2K4Q7Q3M3QX1V0F1TUP1",      "gateway": "razorpay",      "payment_ref": "pay_Q9MtPL2eZvKYlo",      "gateway_ref": "rfnd_Q9MtR5x",      "currency": "INR",      "amount_minor": 30000,      "tax_minor": 5400,      "total_minor": 35400,      "fx_rate": "83.91750000",      "credits_micro": 3574940,      "credit_note_id": "cn_01J9ZK2K4Q7Q3M3QX1V0F1CN01",      "status": "refunded",      "reason": "unused",      "created_at": "2026-09-10T13:00:00Z",      "settled_at": "2026-09-10T13:00:01Z"    }  ]}
GET/v1/credits/refunds/{id}
AuthorizationBearer <token>

In: header

Path Parameters

id*string

Response Body

application/json

application/json

curl -X GET "https://example.com/v1/credits/refunds/string"
{  "refund": {    "id": "rfd_01J9ZK2K4Q7Q3M3QX1V0F1RFD1",    "org_id": "org_01J9ZK2K4Q7Q3M3QX1V0F1ORG1",    "topup_id": "tup_01J9ZK2K4Q7Q3M3QX1V0F1TUP1",    "gateway": "razorpay",    "payment_ref": "pay_Q9MtPL2eZvKYlo",    "gateway_ref": "rfnd_Q9MtR5x",    "currency": "INR",    "amount_minor": 30000,    "tax_minor": 5400,    "total_minor": 35400,    "fx_rate": "83.91750000",    "credits_micro": 3574940,    "credit_note_id": "cn_01J9ZK2K4Q7Q3M3QX1V0F1CN01",    "status": "refunded",    "reason": "unused",    "created_at": "2026-09-10T13:00:00Z",    "settled_at": "2026-09-10T13:00:01Z"  }}
GET/v1/credits/auto-topup
AuthorizationBearer <token>

In: header

Response Body

application/json

application/json

curl -X GET "https://example.com/v1/credits/auto-topup"
{  "mandate": {    "id": "mnd_01J9ZK2K4Q7Q3M3QX1V0F1MND1",    "org_id": "org_01J9ZK2K4Q7Q3M3QX1V0F1ORG1",    "gateway": "razorpay",    "method": "upi",    "mandate_ref": "inv_auth1",    "token_ref": "token_1",    "max_amount_minor": 1500000,    "currency": "INR",    "status": "active",    "auto_topup": {      "enabled": true,      "threshold_micro": 5000000,      "amount_minor": 100000    },    "notify_hours": 24,    "consecutive_failures": 0,    "registered_at": "2026-09-02T10:00:00Z",    "created_at": "2026-09-02T09:58:00Z"  },  "config": {    "enabled": true,    "threshold_micro": 5000000,    "amount_minor": 100000  },  "rail": "razorpay",  "methods": [    "upi",    "emandate",    "card"  ],  "cap_minor": 1500000,  "notify_hours": 24,  "currency": "INR",  "min_amount_minor": 50000}
PUT/v1/credits/auto-topup
AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

curl -X PUT "https://example.com/v1/credits/auto-topup" \  -H "Content-Type: application/json" \  -d '{    "enabled": true,    "threshold_micro": 5000000,    "amount_minor": 100000  }'
{  "mandate": {    "id": "mnd_01J9ZK2K4Q7Q3M3QX1V0F1MND1",    "org_id": "org_01J9ZK2K4Q7Q3M3QX1V0F1ORG1",    "gateway": "razorpay",    "method": "upi",    "mandate_ref": "inv_auth1",    "token_ref": "token_1",    "max_amount_minor": 1500000,    "currency": "INR",    "status": "active",    "auto_topup": {      "enabled": true,      "threshold_micro": 5000000,      "amount_minor": 100000    },    "notify_hours": 24,    "consecutive_failures": 0,    "registered_at": "2026-09-02T10:00:00Z",    "created_at": "2026-09-02T09:58:00Z"  },  "config": {    "enabled": true,    "threshold_micro": 5000000,    "amount_minor": 100000  },  "rail": "razorpay",  "methods": [    "upi",    "emandate",    "card"  ],  "cap_minor": 1500000,  "notify_hours": 24,  "currency": "INR",  "min_amount_minor": 50000}
POST/v1/credits/mandates
AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

curl -X POST "https://example.com/v1/credits/mandates" \  -H "Content-Type: application/json" \  -d '{    "method": "upi"  }'
{  "mandate": {    "id": "mnd_01J9ZK2K4Q7Q3M3QX1V0F1MND1",    "org_id": "org_01J9ZK2K4Q7Q3M3QX1V0F1ORG1",    "gateway": "razorpay",    "method": "upi",    "mandate_ref": "inv_auth1",    "max_amount_minor": 1500000,    "currency": "INR",    "status": "pending",    "auto_topup": {      "enabled": false,      "threshold_micro": 5000000,      "amount_minor": 100000    },    "notify_hours": 24,    "consecutive_failures": 0,    "created_at": "2026-09-02T09:58:00Z",    "hosted_url": "https://rzp.io/i/authQ9Mt"  },  "url": "https://rzp.io/i/authQ9Mt"}
DELETE/v1/credits/mandates
AuthorizationBearer <token>

In: header

Response Body

application/json

application/json

curl -X DELETE "https://example.com/v1/credits/mandates"
{  "mandate": {    "id": "mnd_01J9ZK2K4Q7Q3M3QX1V0F1MND1",    "org_id": "org_01J9ZK2K4Q7Q3M3QX1V0F1ORG1",    "gateway": "razorpay",    "method": "upi",    "mandate_ref": "inv_auth1",    "token_ref": "token_1",    "max_amount_minor": 1500000,    "currency": "INR",    "status": "cancelled",    "auto_topup": {      "enabled": false,      "threshold_micro": 5000000,      "amount_minor": 100000    },    "notify_hours": 24,    "consecutive_failures": 0,    "registered_at": "2026-09-02T10:00:00Z",    "created_at": "2026-09-02T09:58:00Z",    "cancelled_at": "2026-09-11T09:00:00Z"  }}
POST/v1/invoices/{id}/correction
AuthorizationBearer <token>

In: header

Path Parameters

id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

curl -X POST "https://example.com/v1/invoices/string/correction" \  -H "Content-Type: application/json" \  -d '{    "gstin": "29CCCCC2222C1Z5",    "reason": "moved to Bengaluru"  }'
{  "status": "ticket",  "ticket": {    "id": "tkt_01J9ZK2K4Q7Q3M3QX1V0F1TKT1",    "org_id": "org_01J9ZK2K4Q7Q3M3QX1V0F1ORG1",    "kind": "invoice_correction",    "status": "open",    "subject": "correction for AIML/26-27/000001",    "body": {      "invoice_id": "inv_01J9ZK2K4Q7Q3M3QX1V0F1INV1",      "gstin": "29CCCCC2222C1Z5",      "reason": "moved to Bengaluru"    },    "created_by": "alice@acme.example",    "created_at": "2026-09-08T10:00:00Z"  }}
GET/v1/plans
AuthorizationBearer <token>

In: header

Response Body

application/json

application/json

curl -X GET "https://example.com/v1/plans"
{  "data": [    {      "id": "payg",      "name": "Pay as you go",      "monthly_minor": 0,      "currency": "",      "included_micro": 0,      "limits": {        "rpm": 600,        "tpm": 2000000,        "concurrency": 32,        "keys": 50,        "projects": 10      },      "features": {},      "description": "Prepaid credits, no monthly fee.",      "public": true,      "sort": 10    },    {      "id": "team-small",      "name": "Team S",      "monthly_minor": 4900,      "currency": "USD",      "included_micro": 50000000,      "limits": {        "rpm": 3000,        "tpm": 10000000,        "concurrency": 128,        "keys": 200,        "projects": 50      },      "features": {        "priority_support": false,        "sso": false      },      "description": "USD 49 per month, USD 50 of credits included, higher limits.",      "public": true,      "sort": 20    }  ]}
GET/v1/billing/subscription
AuthorizationBearer <token>

In: header

Response Body

application/json

application/json

curl -X GET "https://example.com/v1/billing/subscription"
{  "subscription": {    "org_id": "org_01J9ZK2K4Q7Q3M3QX1V0F1ORG1",    "plan_id": "team-small",    "status": "active",    "period_start": "2026-09-01T00:00:00Z",    "period_end": "2026-10-01T00:00:00Z",    "started_at": "2026-09-10T15:00:00Z"  },  "plan": {    "id": "team-small",    "name": "Team S",    "monthly_minor": 4900,    "currency": "USD",    "included_micro": 50000000,    "limits": {      "rpm": 3000,      "tpm": 10000000,      "concurrency": 128,      "keys": 200,      "projects": 50    },    "features": {      "priority_support": false,      "sso": false    },    "description": "USD 49 per month, USD 50 of credits included, higher limits.",    "public": true,    "sort": 20  }}
POST/v1/billing/subscription
AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

curl -X POST "https://example.com/v1/billing/subscription" \  -H "Content-Type: application/json" \  -d '{    "plan_id": "team-small"  }'
{  "subscription": {    "org_id": "org_01J9ZK2K4Q7Q3M3QX1V0F1ORG1",    "plan_id": "team-small",    "status": "active",    "period_start": "2026-09-01T00:00:00Z",    "period_end": "2026-10-01T00:00:00Z",    "started_at": "2026-09-10T15:00:00Z"  },  "plan": {    "id": "team-small",    "name": "Team S",    "monthly_minor": 4900,    "currency": "USD",    "included_micro": 50000000,    "limits": {      "rpm": 3000,      "tpm": 10000000,      "concurrency": 128,      "keys": 200,      "projects": 50    },    "features": {      "priority_support": false,      "sso": false    },    "description": "USD 49 per month, USD 50 of credits included, higher limits.",    "public": true,    "sort": 20  },  "invoice": {    "id": "inv_01J9ZK2K4Q7Q3M3QX1V0F1INV2",    "org_id": "org_01J9ZK2K4Q7Q3M3QX1V0F1ORG1",    "number": "AIML/26-27/000002",    "fy": "26-27",    "kind": "tax_invoice",    "currency": "INR",    "place_of_supply": "23",    "supplier_gstin": "23AAAAA0000A1Z5",    "recipient_gstin": "23AAAAA0000A1ZA",    "recipient": {      "legal_name": "Acme Pvt Ltd",      "gstin": "23AAAAA0000A1ZA",      "country": "IN"    },    "lines": [      {        "description": "Team S plan · 01 Sep – 30 Sep 2026 (prorated 21/30 days) (USD 34.30 at 1 USD = 83.91750000 INR)",        "kind": "proration",        "sac": "998315",        "quantity": 1,        "unit_minor": 287837,        "amount_minor": 287837      }    ],    "taxable_minor": 287837,    "cgst_minor": 25905,    "sgst_minor": 25905,    "igst_minor": 0,    "total_minor": 339647,    "hsn_sac": "998315",    "irn_status": "generated",    "irn": "cb2f7329dc18db6262dd1365844b7ef5e6d3550753067424beaf06d35a286674",    "fx_rate": "83.91750000",    "issued_at": "2026-09-10T11:59:30Z",    "status": "paid",    "credited_minor": 0,    "plan_id": "team-small",    "period_start": "2026-09-01T00:00:00Z",    "period_end": "2026-10-01T00:00:00Z"  },  "fee_micro": 34300000,  "included_micro": 35000000,  "prorated_bps": 7000,  "effective": "now"}
GET/v1/invoices
AuthorizationBearer <token>

In: header

Query Parameters

cursor?string
limit?integer
Rangevalue <= 200

Response Body

application/json

application/json

curl -X GET "https://example.com/v1/invoices"
{  "object": "list",  "data": [    {      "id": "inv_01J9ZK2K4Q7Q3M3QX1V0F1INV1",      "org_id": "org_01J9ZK2K4Q7Q3M3QX1V0F1ORG1",      "number": "AIML/26-27/000001",      "fy": "26-27",      "kind": "tax_invoice",      "currency": "INR",      "place_of_supply": "23",      "supplier_gstin": "23AAAAA0000A1Z5",      "recipient_gstin": "23AAAAA0000A1ZA",      "recipient": {        "legal_name": "Acme Pvt Ltd",        "gstin": "23AAAAA0000A1ZA",        "country": "IN"      },      "lines": [        {          "description": "Prepaid API credits (USD 11.92 at 1 USD = 83.91750000 INR)",          "kind": "credits",          "sac": "998315",          "quantity": 1,          "unit_minor": 100000,          "amount_minor": 100000        }      ],      "taxable_minor": 100000,      "cgst_minor": 9000,      "sgst_minor": 9000,      "igst_minor": 0,      "total_minor": 118000,      "hsn_sac": "998315",      "irn_status": "generated",      "irn": "cb2f7329dc18db6262dd1365844b7ef5e6d3550753067424beaf06d35a286674",      "topup_id": "tup_01J9ZK2K4Q7Q3M3QX1V0F1TUP1",      "fx_rate": "83.91750000",      "issued_at": "2026-09-10T11:59:30Z",      "status": "paid",      "credited_minor": 0    }  ]}
GET/v1/invoices/{id}
AuthorizationBearer <token>

In: header

Path Parameters

id*string

Response Body

application/json

application/json

curl -X GET "https://example.com/v1/invoices/string"
{  "id": "inv_01J9ZK2K4Q7Q3M3QX1V0F1INV1",  "org_id": "org_01J9ZK2K4Q7Q3M3QX1V0F1ORG1",  "number": "AIML/26-27/000001",  "fy": "26-27",  "kind": "tax_invoice",  "currency": "INR",  "place_of_supply": "23",  "supplier_gstin": "23AAAAA0000A1Z5",  "recipient_gstin": "23AAAAA0000A1ZA",  "recipient": {    "legal_name": "Acme Pvt Ltd",    "gstin": "23AAAAA0000A1ZA",    "country": "IN"  },  "lines": [    {      "description": "Prepaid API credits (USD 11.92 at 1 USD = 83.91750000 INR)",      "kind": "credits",      "sac": "998315",      "quantity": 1,      "unit_minor": 100000,      "amount_minor": 100000    }  ],  "taxable_minor": 100000,  "cgst_minor": 9000,  "sgst_minor": 9000,  "igst_minor": 0,  "total_minor": 118000,  "hsn_sac": "998315",  "irn_status": "generated",  "irn": "cb2f7329dc18db6262dd1365844b7ef5e6d3550753067424beaf06d35a286674",  "topup_id": "tup_01J9ZK2K4Q7Q3M3QX1V0F1TUP1",  "fx_rate": "83.91750000",  "issued_at": "2026-09-10T11:59:30Z",  "status": "paid",  "credited_minor": 0}
GET/v1/invoices/{id}/pdf
AuthorizationBearer <token>

In: header

Path Parameters

id*string

Response Body

application/pdf

application/json

curl -X GET "https://example.com/v1/invoices/string/pdf"
"string"
GET/v1/invoices/{id}/html
AuthorizationBearer <token>

In: header

Path Parameters

id*string

Response Body

text/html

application/json

curl -X GET "https://example.com/v1/invoices/string/html"
"string"