# Create invoice

Creates a new invoice.

Endpoint: POST /invoices/create
Version: 2.0.0
Security: bearerAuth

## Request fields (application/json):

  - `channel_id` (string)
    Unique channel identifier. Required when using multi-channel keys.
    Example: "12345"

  - `customer_id` (string, required)
    Unique customer identifier.
    Example: "cust_01KMG2ABYPF6XS5DMJQ817C429"

  - `line_items` (array, required)
    Line items applied to the invoice.
    Example: [{"product_price_id":"e6f26db1-f633-4723-ab08-50ddee7bc648","quantity":1,"description":"Great product"}]

  - `line_items.product_price_id` (string, required)
    Unique product price identifier.
    Example: "12345"

  - `line_items.quantity` (integer, required)
    Number of product units.
    Example: 1

  - `line_items.description` (string)
    Line item description.
    Example: "Great product"

  - `discounts` (array) — one of:
    Discounts applied to the invoice using coupons.
    Example: [{"coupon_code":"WINTER25"}]
    - Coupon ID:
      - `coupon_id` (string, required)
        Unique coupon identifier.
        Example: "0291b87b-deac-4eb4-8732-2a70d247a171"
    - Coupon code:
      - `coupon_code` (string, required)
        Code of the associated coupon.
        Example: "WINTER25"

  - `due_at` (string)
    Date and time when the invoice is due, truncated to whole seconds. Must be in the future and no more than 1 year from now.
    Example: "2026-01-24T11:45:00.000000Z"

  - `notes` (string)
    Additional notes for the invoice.
    Example: "Base pack"

## Response 200 fields (application/json):

  - `id` (string, required)
    Unique invoice identifier.
    Example: "inv_01KPWT0K1PQWEYYRT7J1H3NC85"

  - `created_at` (string, required)
    Date and time when the invoice was created.
    Example: "2025-12-24T11:45:00.000000Z"

  - `updated_at` (string, required)
    Date and time when the invoice was updated.
    Example: "2025-12-24T11:47:00.000000Z"

  - `status` (string, required)
    Current invoice status.
    Enum: "DRAFT", "OPEN", "PAID", "VOIDED"

  - `total_amount` (integer, required)
    Total invoice amount in minor units.
    Example: 990

  - `currency` (string, required)
    Three-letter ISO-4217 currency code.
    Example: "USD"

  - `line_items` (array, required)
    Line items applied to the invoice.
    Example: [{"product_price_id":"e6f26db1-f633-4723-ab08-50ddee7bc648","description":"Great product","amount":990,"currency":"USD","amount_details":{"subtotal":1000,"discount":100,"taxable":900,"tax":90},"quantity":1,"tax":{"category_id":"taxc_01JJVD830C789HBQVTVCWJ6AK2","mode":"EXCLUSIVE","rate":10}}]

  - `line_items.product_price_id` (string)
    Identifier of the associated product price.
    Example: "e6f26db1-f633-4723-ab08-50ddee7bc648"

  - `line_items.description` (string)
    Line item description.
    Example: "Great product"

  - `line_items.amount` (integer, required)
    Line item amount in minor units.
    Example: 990

  - `line_items.currency` (string, required)
    Three-letter ISO-4217 currency code.
    Example: "USD"

  - `line_items.amount_details` (object, required)
    Represents invoice amount details.
    Example: {"subtotal":1000,"discount":100,"taxable":900,"tax":90}

  - `line_items.amount_details.subtotal` (integer, required)
    Subtotal amount in minor units before discounts and taxes.
    Example: 1000

  - `line_items.amount_details.discount` (integer, required)
    Discount amount in minor units.
    Example: 100

  - `line_items.amount_details.taxable` (integer)
    Taxable amount in minor units.
    Example: 900

  - `line_items.amount_details.tax` (integer)
    Tax amount in minor units.
    Example: 90

  - `line_items.quantity` (integer, required)
    Number of product units.
    Example: 1

  - `line_items.tax` (object)
    Tax details for the line item.
    Example: {"category_id":"taxc_01JJVD830C789HBQVTVCWJ6AK2","mode":"EXCLUSIVE","rate":10}

  - `line_items.tax.category_id` (string)
    Identifier of the tax category.
    Example: "taxc_01JJVD830C789HBQVTVCWJ6AK2"

  - `line_items.tax.mode` (string)
    Tax calculation mode.
    Enum: "EXCLUSIVE", "INCLUSIVE"

  - `line_items.tax.rate` (number)
    Tax rate as a percentage.
    Example: 10

  - `customer` (object, required)
    Represents customer snapshot details for invoice.
    Example: {"id":"cust_01KMG2ABYPF6XS5DMJQ817C429","first_name":"John","last_name":"Doe","email":"customer@example.com","phone":"+1234567890","address":{"city":"Anytown","country":"USA","line1":"123 Main St","line2":"Suite 456","state":"CA","postal_code":"12345"},"tax":{"taxability":"TAXABLE"}}

  - `customer.id` (string, required)
    Unique customer identifier.
    Example: "cust_01KMG2ABYPF6XS5DMJQ817C429"

  - `customer.first_name` (string)
    Customer first name.
    Example: "John"

  - `customer.last_name` (string)
    Customer last name.
    Example: "Doe"

  - `customer.email` (string)
    Customer email.
    Example: "customer@example.com"

  - `customer.phone` (string)
    Customer phone number.
    Example: "+1234567890"

  - `customer.address` (object)
    Customer address.
    Example: {"city":"Anytown","country":"USA","line1":"123 Main St","line2":"Suite 456","state":"CA","postal_code":"12345"}

  - `customer.address.city` (string)
    City name.
    Example: "Anytown"

  - `customer.address.country` (string)
    Country according to the ISO-3166 alpha-3 country code.
    Example: "USA"

  - `customer.address.line1` (string)
    Address line 1.
    Example: "123 Main St"

  - `customer.address.line2` (string)
    Address line 2.
    Example: "Suite 456"

  - `customer.address.state` (string)
    State or province.
    Example: "CA"

  - `customer.address.postal_code` (string)
    Postal or ZIP code.
    Example: "12345"

  - `customer.tax` (object, required)
    Provides customer tax information.
    Example: {"taxability":"TAXABLE"}

  - `customer.tax.taxability` (string, required)
    Indicates if the customer is subject to tax.
    Enum: "EXEMPT", "TAXABLE"

  - `due_at` (string)
    Date and time when the invoice is due.
    Example: "2026-01-24T11:45:00.000000Z"

  - `amount_details` (object, required)
    Represents invoice amount details.
    Example: {"subtotal":1000,"discount":100,"taxable":900,"tax":90}

  - `discounts` (array)
    Discounts applied to the invoice.
    Example: [{"coupon_id":"0291b87b-deac-4eb4-8732-2a70d247a171","coupon_code":"WINTER25"}]

  - `discounts.coupon_id` (string)
    Unique identifier of the associated coupon.
    Example: "0291b87b-deac-4eb4-8732-2a70d247a171"

  - `discounts.coupon_code` (string)
    Code of the associated coupon.
    Example: "WINTER25"

  - `notes` (string)
    Additional notes for the invoice.
    Example: "Base pack"

## Response 400 fields (application/json):

  - `code` (string, required)
    Code identifying the error type.
    Enum: "VALIDATION"

  - `message` (string, required)
    Message describing the error.
    Example: "One or more fields failed validation due to constraints"

  - `context` (object, required)
    Additional context about the validation error, including specific constraints.
    Example: {"constraints":{"email":{"type":"TYPE","message":"The 'email' field must be a valid email address"},"age":{"type":"MIN","message":"The 'age' field must be a number greater than or equal to 18"}}}

  - `context.constraints` (object, required)
    Failed constraints keyed by the field name.
    Example: {"email":{"type":"TYPE","message":"The 'email' field must be a valid email address"},"age":{"type":"MIN","message":"The 'age' field must be a number greater than or equal to 18"}}

## Response 401 fields (application/json):

  - `code` (string, required)
    Code identifying the error type.
    Enum: "UNAUTHENTICATED"

  - `message` (string, required)
    Message describing the error.
    Example: "Credentials are invalid or missing"

## Response 403 fields (application/json):

  - `code` (string, required)
    Code identifying the error type.
    Enum: "PERMISSION_DENIED"

  - `message` (string, required)
    Message describing the error.
    Example: "Permission denied"

## Response 422 fields (application/json):

  - `code` (string, required)
    Code identifying the error type.
    Enum: "PRODUCT_NOT_FOUND", "PRICE_NOT_FOUND", "CUSTOMER_NOT_FOUND", "PRODUCT_NOT_ACTIVE", "PRICE_NOT_ACTIVE", "PRODUCT_NOT_ONE_TIME", "INCOMPATIBLE_CURRENCY", "COUPON_NOT_FOUND", "COUPON_NOT_ACTIVE", "COUPON_CODE_NOT_FOUND", "COUPON_CODE_NOT_ACTIVE"

  - `message` (string, required)
    Message describing the error.
    Example: "The request conflicts with the current state"

  - `context` (object)
    Additional error context.

## Response 429 fields (application/json):

  - `code` (string, required)
    Code identifying the error type.
    Enum: "RATE_LIMIT"

  - `message` (string, required)
    Message describing the error.
    Example: "Rate limit exhausted"

  - `context` (object)
    Additional context about the error.

  - `context.next_try_at` (string)
    Timestamp indicating when to retry the request.
    Example: "2024-12-31T23:59:59.000000Z"