--- title: "Create an invoice" method: POST path: "/invoices" tags: ["Invoices"] --- # Create an invoice `POST /invoices` Creates a one-off invoice for a customer, in the `live` or `test` mode of the API key used. The invoice is not tied to a subscription and starts in `draft` status. Fintoc does not charge the invoice until you finalize it. The `total` is the sum of the `lines`, which must all share the same `currency`. Fintoc charges the invoice automatically against `default_payment_method`, so `collection_method` is always `charge_automatically`. ## Request body - object - `customer` string, required — ID of the customer the invoice bills. - `default_payment_method` string, required — Payment method Fintoc charges when the invoice is finalized. Must belong to the specified `customer`. - `lines` object[], required — Line items the invoice bills for. All lines must share the same `currency`, which becomes the invoice currency. - `amount` integer, required — Total amount of the line, in the currency's smallest unit. `CLP` has no minor unit, so `60000` is 60,000 CLP. - `currency` 'CLP' | 'MXN', required — Three-letter ISO 4217 currency code, in uppercase. One of `CLP` or `MXN`. - `name` string, required — Short name of the line. - `description` string — Longer description of the line. - `quantity` integer, required — Number of units the line bills for. Must be greater than 0. - `collection_method` 'charge_automatically' — How Fintoc collects the invoice. Only `charge_automatically` is supported. Defaults to `charge_automatically`. - `metadata` object — Set of key-value pairs you can attach to the invoice. ## Response `201` The created invoice, in `draft` status. - Invoice - `id` string, required — Unique identifier of the invoice. - `hosted_invoice_url` string, nullable, required — URL of the hosted invoice page, where your customer can view and pay the invoice. `null` for `test` mode invoices and for invoices that are not `open`. - `object` 'invoice', required — Type of the object. Always `invoice`. - `attempt_count` integer, required — Number of automatic charge attempts Fintoc has made on the invoice. `0` until the invoice is finalized and charged for the first time. - `created_at` string, date-time, required — ISO 8601 timestamp of when the invoice was created. - `currency` 'CLP' | 'MXN', required — Currency of the invoice, as an ISO 4217 code. Every line item uses this currency. - `customer` string, required — `id` of the customer the invoice bills. - `default_payment_method` string, nullable, required — `id` of the payment method Fintoc charges when the invoice is finalized. `null` for invoices without one, such as subscription invoices. - `lines` InvoiceLineItem[], required — Line items that make up the invoice total. - `id` string, required — Unique identifier of the line item. - `object` 'line_item', required — Type of the object. Always `line_item`. - `amount` integer, required — Amount of the line item, in the smallest unit of `currency` (for example, `30000` for $30000 CLP, since CLP has no minor unit, or `3000` for $30.00 MXN). - `currency` 'CLP' | 'MXN', required — Currency of the line item, as an ISO 4217 code. Always matches the invoice currency. - `description` string, nullable, required — Additional details about the line item shown on the invoice. `null` when the line item has no description. - `name` string, required — Display name for the line item shown on the invoice. - `period_end` string, date-time, nullable, required — ISO 8601 datetime in UTC marking the end of the billing period covered by the line item. `null` for line items on invoices not tied to a subscription. - `period_start` string, date-time, nullable, required — ISO 8601 datetime in UTC marking the start of the billing period covered by the line item. `null` for line items on invoices not tied to a subscription. - `quantity` integer, required — Number of units billed by the line item. - `metadata` object, nullable, required — Set of key-value pairs attached to the invoice. `null` when the invoice has no metadata. - `mode` 'live' | 'test', required — Mode of the invoice. `live` invoices use real data; `test` invoices use fake data for integration testing. An API key only sees invoices that share its mode. - `next_payment_attempt_at` string, date-time, nullable, required — ISO 8601 timestamp of the next scheduled automatic charge attempt. `null` when no further attempt is scheduled. - `payments` object[], required — Payment attempts to collect the invoice. - `amount` integer, required — Amount of the payment, in the smallest unit of `currency` (for example, `30000` for $30000 CLP, since CLP has no minor unit, or `3000` for $30.00 MXN). - `currency` 'CLP' | 'MXN', required — Currency of the payment, as an ISO 4217 code. Always matches the invoice currency. - `payment_intent` string, required — `id` of the payment intent created to collect the invoice. - `status` 'pending' | 'succeeded' | 'failed', required — Status of the payment attempt. - `status` 'draft' | 'open' | 'paid' | 'void', required — Status of the invoice. Invoices start as `draft`, become `open` when finalized, and end as `paid` or `void`. - `subscription` string, nullable, required — `id` of the subscription that generated the invoice. `null` for invoices not tied to a subscription. - `total` integer, required — Total amount of the invoice, in the smallest unit of `currency` (for example, `30000` for $30000 CLP, since CLP has no minor unit, or `3000` for $30.00 MXN). Equals the sum of the line item amounts. ## Other responses - `400` — Invalid request. - `401` — Invalid or missing API key. - `404` — The customer does not exist, or the payment method does not exist or does not belong to the customer. - `409` — The currency is not allowed for the organization's country. Chilean organizations bill in `CLP` and Mexican organizations bill in `MXN`. --- [API](https://skmtc.net/fintoc/apis/fintoc-api.md) · [All operations](https://skmtc.net/fintoc/apis/fintoc-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/fintoc/fintoc-api/revisions/9dafa63688a3/schema)