Invoice

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/curlec/json-schema/curlec-invoice-schema.json",
  "title": "Invoice",
  "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).",
  "x-generated": "2026-11-04",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/curlec-invoices-api-openapi.yml#/components/schemas/Invoice",
  "type": "object",
  "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": "#/$defs/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": "#/$defs/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"
    }
  },
  "$defs": {
    "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"
          ]
        }
      }
    },
    "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
    }
  }
}