# Create draft invoices

> How another system can prepare an invoice in Couplr through the API and, with a second ability, send it. The customer pays through Couplr's payment link; the API never charges a customer or records a payment.

- Canonical URL: https://couplrfsm.com/developers/draft-invoices
- Markdown: https://couplrfsm.com/developers/draft-invoices.md
- API version: v1 (base URL https://couplrfsm.com/api/v1)
- OpenAPI specification: https://couplrfsm.com/developers/openapi.yaml
- All documentation pages: https://couplrfsm.com/llms.txt

> **Flip:** You can hand me an invoice that is ready to go: the customer, the job and the lines. I save it as a draft and leave it in Couplr for someone in the office to look over. If your key is allowed to, you can also tell me to send it, and I email the customer my payment link. I never take money, or write down that money was taken, because an API call asked me to.

## What a draft is

A draft invoice is saved in the company's Couplr account with status `draft`. Creating one through the API:

- does not email or text the customer,
- does not create a payment link,
- does not charge a card or record a payment.

Someone opens the draft in Couplr, checks it, chooses how the customer will pay and sends it, or your integration sends it (below). From then on it behaves like any other Couplr invoice.

## Create one

Needs a key with the `invoices:write` ability.

```bash
curl -X POST "https://couplrfsm.com/api/v1/invoices" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: YOUR_UNIQUE_KEY" \
  -d '{"customer_id": 1842, "job_id": 9312, "notes": "Replaced condenser fan motor.", "line_items": [{"name": "Condenser fan motor", "quantity": 1, "unit_price": 289}, {"name": "Service call", "quantity": 1, "unit_price": 100}]}'
```

The response (`201`) is the invoice with `"status": "draft"` and its `line_items`. Every field is listed under [Create a draft invoice](https://couplrfsm.com/developers/api-reference/invoices#create-a-draft-invoice).

## Line items

Each line is one item with a quantity and a price in dollars.

| You send | What happens |
| --- | --- |
| `name` and `unit_price` | The line is matched to an item of the same name in the company's price book. If there is none, the item is added to the price book. |
| `price_book_item_id` | That price book item is used. `unit_price` is optional and defaults to the item's price. |

Find an item's id with [List price book items](https://couplrfsm.com/developers/api-reference/price-book#list-price-book-items).

Rules:

- `quantity` defaults to 1.
- An item can appear once per invoice. For two of the same thing, send one line with `"quantity": 2`. A repeated item is refused with `422`.
- Between 1 and 100 lines.
- The invoice total is worked out by Couplr from the lines. You do not send a total.

> **Flip:** If you type a name I have not seen, I add it to the price book so the office can reuse it. Use the same names each time and the price book stays tidy.

## Attach it to a job

Send `job_id` to tie the invoice to a job. The job must belong to the same customer.

A job holds one draft at a time. Creating another draft for the same job replaces the first one, so sending a corrected draft is safe. Once a job's invoice has been sent, a new draft for that job is refused with `422`.

## Send a draft

Needs a key with the `invoices:send` ability. There is no request body.

```bash
curl -X POST "https://couplrfsm.com/api/v1/invoices/INVOICE_ID/send" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_KEY"
```

This does what "Send invoice" does in the apps:

- The customer is emailed the invoice with Couplr's payment link, and pays through it. Card payments carry the all-in rate shown in the account.
- The response shows `"status": "processing"` while the link is prepared. Shortly after, the invoice is `sent`, `hosted_invoice_url` is filled in and the `invoice.sent` event is delivered.
- The draft goes out as it stands. Sending does not change its quantities, prices or notes. Each line goes out under its price book item's current name.
- Sales tax is worked out again when the invoice is sent, from the account's tax settings at that moment, the same as a send from Couplr. Read `amount` in the response for the amount billed.

A draft is refused with `422` on `invoice` when it is not a draft any more, when the customer has no email address, when online payments are not set up for the account, or when it was set up in Couplr to charge a saved card or as a split payment, or when one of its lines uses a price book item that has since been archived. Send those from Couplr.

> **Flip:** Sending is the one thing here a customer notices, so I only do it for a key that has `invoices:send`. Give that ability to an integration you trust to decide when a bill goes out.

## What you cannot do

- Charge a card, record cash or a check, or mark an invoice as paid. Every payment goes through Couplr's payment link.
- Choose how the customer pays. A draft goes out the way it was saved: with the payment link, or as a bank-only or financing invoice if someone set it up that way in Couplr.
- Change or delete an invoice after it is created, other than by replacing a job's draft.
- Set discounts, deposits, payment plans or maintenance plans. Those are chosen in Couplr. A deposit already credited on a draft in Couplr stays on it when the API sends it.

To find out when an invoice has been sent or paid, subscribe to the `invoice.sent` and `invoice.paid` events, or read invoices with `updated_since`. See [Keep data in sync](https://couplrfsm.com/developers/syncing).

## Errors you may see

| Status | Field | Meaning |
| --- | --- | --- |
| `422` | `customer_id` | No customer with this id in the company. |
| `422` | `job_id` | No job with this id for this customer. |
| `422` | `line_items.N.price_book_item_id` | No price book item with this id in the company. |
| `422` | `line_items.N` | The same item is on the invoice twice. Use one line with a quantity. |
| `422` | `line_items` | No lines, or more than 100. |
| `422` | `invoice` | On send: the invoice cannot be sent through the API. The message says why. |
| `403` | | The key does not have `invoices:write` (create) or `invoices:send` (send). |

`N` is the position of the line, starting at 0.