---
title: "Invoice anyone for anything, paid into your connected bank account"
method: POST
path: "/api/v1/invoices"
tags: ["invoices"]
---

# Invoice anyone for anything, paid into your connected bank account

`POST /api/v1/invoices`

## Request

- Base URL: `https://www.orgo.ai`
- URL: `https://www.orgo.ai/api/v1/invoices`
- Auth: HTTP bearer

Creates and finalizes a one-off invoice and answers with `url`, the Stripe page where your customer pays it (card). Nothing is sent: share `url`, or POST /api/v1/invoices/{id}/send to email it from your business name. Amounts are integer cents. Give `amount`, or `line_items` (then `amount` may be left out, or must equal their total). `customer` needs an email or a phone. `due_date` is a date (2026-11-01, due at the end of that day UTC) or unix seconds, within 365 days; without one the invoice is due 30 days after it is made. Every create needs an Idempotency-Key header (a UUID, new for each invoice): a retry with the same key within 24 hours answers with the same invoice instead of making a second one.

Money: a destination charge to your Stripe Connect account, made on its behalf, so the invoice, the payment page and the card statement carry your business name. Orgo keeps only what Stripe charges it for the invoice, the card fee (2.9% + 30¢) and the Invoicing fee (0.5%), as `orgo_fee`; `payout` is paid out to you. Needs Invoicing (every paid plan) and payouts set up in Settings → Invoicing. Use an account-wide API key.

## Headers

- `Idempotency-Key` string, required

## Request body

- CreateInvoice
  - `amount` integer: Total in cents. Required without line_items.
  - `currency` 'usd'
  - `description` string, required: What it is for; shown on the invoice and in the email.
  - `line_items` InvoiceLineItemInput[]
    - `description` string, required
    - `unit_amount` integer, required: Price of one, in cents.
    - `quantity` integer
  - `customer` object, required: Who pays. An email or a phone is required.
    - `email` string, email
    - `phone` string
    - `name` string
  - `due_date` union
    - string: A date or date-time.
    - integer: Unix seconds.
  - `metadata` object: Your own keys (not `type` or `orgo_*`), returned as sent.
  - `workspace_id` string, uuid: Tag it with one of your workspaces, to filter the list by.

## Response `201`

Created and open. `url` is where the customer pays.

- Invoice
  - `id` string, required
  - `status` 'draft' | 'open' | 'paid' | 'void' | 'uncollectible', required
  - `amount` integer, required: Total, in cents.
  - `amount_paid` integer
  - `amount_remaining` integer
  - `currency` string, required
  - `url` string, nullable, required: Stripe’s hosted invoice page, where the customer pays.
  - `pdf_url` string, nullable
  - `number` string, nullable
  - `description` string, nullable
  - `customer` object
    - `email` string, nullable
    - `phone` string, nullable
    - `name` string, nullable
  - `line_items` object[]
    - `description` string, nullable
    - `quantity` integer
    - `unit_amount` integer, nullable
    - `amount` integer
  - `due_date` string, date-time, nullable
  - `created` string, date-time, required
  - `paid_at` string, date-time, nullable
  - `voided_at` string, date-time, nullable
  - `last_sent_at` string, date-time, nullable
  - `orgo_fee` integer: Orgo’s fee in cents: Stripe’s card and Invoicing fees.
  - `payout` integer: What reaches your bank when it is paid, in cents.
  - `workspace_id` string, uuid, nullable
  - `metadata` object

## Other responses

- `400`: Bad input (invalid_request, with `param`), no Idempotency-Key header (idempotency_key_required), or a malformed one (invalid_idempotency_key).
- `401`: Unauthenticated.
- `403`: Invoicing is off for this account (UPGRADE_REQUIRED on Free, MANAGED_ACCOUNTS_DISABLED), or a workspace-scoped key.
- `404`: workspace_id is not a workspace you can write to (workspace_not_found).
- `409`: Payouts are not set up yet (payouts_not_ready, with `connect_url`), or a request with this Idempotency-Key is still running (idempotency_in_progress).
- `422`: This Idempotency-Key was used for a different invoice (idempotency_key_reused), or the invoice it made was discarded (idempotency_key_spent). Use a new key.
- `429`: Over one of the account's rate limits (rate_limited): `limit` names it, `retry_after` and Retry-After say how many seconds to wait. Limits are per account (the workspace owner when the request acts on a computer or a workspace) and set by its plan (x-rate-limits).
- `502`: Stripe did not answer (stripe_unavailable). Retry with the same Idempotency-Key.
- `503`: Invoicing is not available yet (invoicing_unavailable), or the invoice could not be saved (invoice_not_saved; the error says whether to retry with a new or the same Idempotency-Key).

## Changes

- **2026-11-01** `60e768a2bb9d`: 6 info
  - added the optional property `docs_url` to the response with the `400` status
  - added the optional property `docs_url` to the response with the `409` status
  - added the optional property `next` to the response with the `400` status
  - added the optional property `next` to the response with the `409` status
  - …2 more
- **2026-10-30** `afb6f0ee1aac`: 1 info
  - added the non-success response with the status `429`
- **2026-10-09** `41babeff7892`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/orgo/apis/orgo-api/changes/api/v1/invoices/post.md)

---

[API](https://skmtc.dev/orgo/apis/orgo-api.md) - [All operations](https://skmtc.dev/orgo/apis/orgo-api/llms.txt) - [OpenAPI document](https://skmtc.dev/orgo/apis/orgo-api/revisions/e4c1e7379fa5?raw)