Create draft invoices

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.

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.

Line items#

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

Find an item's id with 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.

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.

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.

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.

Errors you may see#

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