# Create an invoice

> Creates a draft invoice. Add line items, then finalize it to send it for payment. Set `document_type` to `quote` to create a quote the customer can accept before it becomes an invoice. If you leave `invoice_number` empty, Bolt assigns the next number in sequence when the invoice is finalized.

Source: https://help.boltapp.com/api-reference/invoicing/invoices/createinvoice

`POST /v1/invoices`

## OpenAPI definition

This endpoint as it appears in the OpenAPI document, with every schema it references included.

```json
{
  "openapi": "3.2.0",
  "info": {
    "title": "Invoicing API",
    "version": "v1",
    "description": "API for creating and managing invoices, and for listing a customer's invoices in the customer portal."
  },
  "servers": [
    {
      "url": "https://api.boltapp.com",
      "description": "The Production URL (Live Data)."
    },
    {
      "url": "https://api-sandbox.boltapp.com",
      "description": "The Sandbox URL (Test Data)."
    },
    {
      "url": "https://api-staging.boltapp.com",
      "description": "The Staging URL (Staged Data)."
    }
  ],
  "security": [
    {
      "X-API-Key": [],
      "X-Publishable-Key": []
    }
  ],
  "paths": {
    "/v1/invoices": {
      "post": {
        "operationId": "createInvoice",
        "summary": "Create an invoice",
        "description": "Creates a draft invoice. Add line items, then finalize it to send it for payment.\n\nSet `document_type` to `quote` to create a quote the customer can accept before it becomes an invoice.\n\nIf you leave `invoice_number` empty, Bolt assigns the next number in sequence when the invoice is finalized.\n",
        "tags": [
          "Invoices"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "currency"
                ],
                "properties": {
                  "currency": {
                    "type": "string",
                    "description": "Three-letter ISO 4217 currency code.",
                    "examples": [
                      "USD"
                    ]
                  },
                  "to_invoice_consumer_id": {
                    "type": "string",
                    "description": "Public ID of the customer being billed. An invoice needs a customer before it can be finalized.",
                    "examples": [
                      "ic_8hTq2Lm4Vx"
                    ]
                  },
                  "from_invoice_consumer_id": {
                    "type": "string",
                    "description": "Public ID of the party issuing the invoice, if it is not you."
                  },
                  "invoice_number": {
                    "type": "string",
                    "description": "Your invoice number. Must be unique across your invoices. Leave empty to have one assigned at finalization.",
                    "examples": [
                      "INV-2026-0042"
                    ]
                  },
                  "document_type": {
                    "type": "string",
                    "enum": [
                      "invoice",
                      "quote"
                    ],
                    "default": "invoice",
                    "description": "Whether this is an invoice or a quote."
                  },
                  "deposit_amount": {
                    "type": "integer",
                    "format": "int64",
                    "minimum": 0,
                    "description": "Deposit due up front, in minor units.",
                    "examples": [
                      5000
                    ]
                  },
                  "due_at": {
                    "type": "string",
                    "format": "date-time",
                    "description": "When payment is due.",
                    "examples": [
                      "2026-10-31T00:00:00Z"
                    ]
                  },
                  "metadata": {
                    "type": "string",
                    "description": "Your own notes for this invoice, as a string (for example, serialized JSON)."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The draft invoice was created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Invoice"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - missing currency, invalid `document_type`, negative `deposit_amount`, an invoice number already in use, or an unknown customer."
          },
          "401": {
            "description": "Unauthorized - Invalid or missing API key."
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Invoice": {
        "type": "object",
        "properties": {
          "public_id": {
            "type": "string",
            "description": "Public ID of the invoice. Starts with `inv_`, or `quo_` for a quote.",
            "examples": [
              "inv_9Pq3Xw7Rt2"
            ]
          },
          "invoice_number": {
            "type": "string",
            "description": "The invoice number. Empty on a draft until it is finalized, if you didn't set one.",
            "examples": [
              "INV-2026-0042"
            ]
          },
          "to_invoice_consumer_id": {
            "type": "string",
            "description": "Public ID of the customer being billed.",
            "examples": [
              "ic_8hTq2Lm4Vx"
            ]
          },
          "from_invoice_consumer_id": {
            "type": "string",
            "description": "Public ID of the party issuing the invoice, if set."
          },
          "status": {
            "$ref": "#/components/schemas/InvoiceStatus"
          },
          "document_type": {
            "type": "string",
            "enum": [
              "invoice",
              "quote"
            ],
            "description": "Whether this is an invoice or a quote.",
            "examples": [
              "invoice"
            ]
          },
          "total_amount": {
            "type": "integer",
            "format": "int64",
            "description": "The full amount billed, including line items, adjustments and any late fee. Payments do not reduce it.",
            "examples": [
              15000
            ]
          },
          "amount_due": {
            "type": "integer",
            "format": "int64",
            "description": "What is still owed. Goes down as payments arrive, and is `0` on a paid invoice.",
            "examples": [
              15000
            ]
          },
          "deposit_amount": {
            "type": "integer",
            "format": "int64",
            "description": "Deposit due up front."
          },
          "late_fee_amount": {
            "type": "integer",
            "format": "int64",
            "description": "Late fee added because the invoice was paid late."
          },
          "early_pay_discount_amount": {
            "type": "integer",
            "format": "int64",
            "description": "Discount for paying early."
          },
          "currency": {
            "type": "string",
            "description": "Three-letter ISO 4217 currency code.",
            "examples": [
              "USD"
            ]
          },
          "payment_link": {
            "type": "string",
            "format": "uri",
            "description": "Link where the customer can pay. Only present while the invoice can be paid."
          },
          "billing_period_start": {
            "type": "string",
            "format": "date-time",
            "description": "Start of the billing cycle, for an invoice raised by a subscription."
          },
          "billing_period_end": {
            "type": "string",
            "format": "date-time",
            "description": "End of the billing cycle, for an invoice raised by a subscription."
          },
          "entity_type": {
            "type": "string",
            "description": "What raised the invoice, for example `subscription`. Absent for an invoice you created directly.",
            "examples": [
              "subscription"
            ]
          },
          "entity_id": {
            "type": "string",
            "description": "Public ID of what raised the invoice, for example the subscription's ID.",
            "examples": [
              "s_3fKq8Lw2Zp"
            ]
          },
          "order_token": {
            "type": "string",
            "description": "Token of the order created for payment, once there is one."
          },
          "quote_accepted_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the customer accepted the quote."
          },
          "issued_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the invoice was issued."
          },
          "sent_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the invoice was sent to the customer."
          },
          "due_at": {
            "type": "string",
            "format": "date-time",
            "description": "When payment is due."
          },
          "finalized_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the invoice was finalized."
          },
          "paid_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the invoice was paid in full."
          },
          "voided_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the invoice was voided."
          },
          "metadata": {
            "type": "string",
            "description": "Your own notes for this invoice."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the invoice was created."
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the invoice was last changed."
          }
        }
      },
      "InvoiceStatus": {
        "type": "string",
        "enum": [
          "draft",
          "finalized",
          "sent",
          "paid",
          "past_due",
          "uncollectible",
          "voided"
        ],
        "description": "- `draft`: being prepared. Can be edited or deleted.\n- `finalized`: locked and ready to send.\n- `sent`: sent to the customer and awaiting payment.\n- `paid`: paid in full.\n- `past_due`: unpaid after its due date.\n- `uncollectible`: written off as unpaid.\n- `voided`: cancelled.\n",
        "examples": [
          "draft"
        ]
      }
    },
    "securitySchemes": {
      "X-API-Key": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "X-Publishable-Key": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Publishable-Key"
      },
      "PortalToken": {
        "type": "http",
        "scheme": "bearer",
        "description": "A customer portal token."
      },
      "PortalTokenQuery": {
        "type": "apiKey",
        "in": "query",
        "name": "token",
        "description": "A customer portal token, passed as a query parameter."
      }
    }
  }
}
```
