Invoices

Base URL: https://couplrfsm.com/api/v1. Conventions shared by every endpoint (examples, ids, dates, money) are on the API reference page. Errors, pagination and idempotency are in Errors, limits and retries.

List invoices#

GET /api/v1/invoices · requires the invoices:read ability

Query parameters

Example request

curl "https://couplrfsm.com/api/v1/invoices" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response (200)

{
    "data": [
        {
            "id": "9d3f6a52-0c1e-4c57-9d0a-3a0f8a4a7b21",
            "invoice_number": "1047",
            "customer_id": 1842,
            "customer_name": "Dana Whitfield",
            "job_id": 9312,
            "status": "paid",
            "amount": "389.00",
            "notes": null,
            "hosted_invoice_url": null,
            "created_at": "2026-12-02T17:20:05+00:00",
            "updated_at": "2026-12-02T18:01:44+00:00"
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 25,
        "total": 1,
        "last_page": 1
    }
}

Errors

Create a draft invoice#

POST /api/v1/invoices · requires the invoices:write ability · accepts Idempotency-Key

Creates an invoice with status draft. Nothing is sent to the customer and nothing is charged. The draft appears in Couplr, where someone reviews it and sends it, or you send it with POST /invoices/{id}/send. An invoice cannot be marked as paid or charged through the API.

A line with price_book_item_id uses that price book item. A line without one is matched to a price book item with the same name, or added to the price book as a new item. A job can have one draft: creating another for the same job replaces the first.

Headers

Request body (application/json)

Fields not listed are ignored. The invoice is always created as a draft.

Example request

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}]}'

Example response (201)

{
    "data": {
        "id": "9d3f6a52-0c1e-4c57-9d0a-3a0f8a4a7b21",
        "invoice_number": "1047",
        "customer_id": 1842,
        "customer_name": "Dana Whitfield",
        "job_id": 9312,
        "status": "paid",
        "amount": "389.00",
        "notes": null,
        "hosted_invoice_url": null,
        "created_at": "2026-12-02T17:20:05+00:00",
        "updated_at": "2026-12-02T18:01:44+00:00"
    }
}

Errors

Get an invoice#

GET /api/v1/invoices/{id} · requires the invoices:read ability

Includes line_items.

Path parameters

Example request

curl "https://couplrfsm.com/api/v1/invoices/9d3f6a52-0c1e-4c57-9d0a-3a0f8a4a7b21" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response (200)

{
    "data": {
        "id": "9d3f6a52-0c1e-4c57-9d0a-3a0f8a4a7b21",
        "invoice_number": "1047",
        "customer_id": 1842,
        "customer_name": "Dana Whitfield",
        "job_id": 9312,
        "status": "paid",
        "amount": "389.00",
        "notes": null,
        "hosted_invoice_url": null,
        "created_at": "2026-12-02T17:20:05+00:00",
        "updated_at": "2026-12-02T18:01:44+00:00"
    }
}

Errors

Send a draft invoice#

POST /api/v1/invoices/{id}/send · requires the invoices:send ability · accepts Idempotency-Key

Sends a draft invoice to the customer by email with Couplr's payment link, the same as "Send invoice" in the apps. The customer pays through that link. Nothing is charged by this call, and there is no way to record a payment made any other way.

A draft that was saved in Couplr as a bank-only or a financing invoice is sent that way, and a deposit already credited on the draft stays on it. You cannot choose how the customer pays or set a deposit.

There is no request body. The draft is sent as it stands: its quantities, prices, notes and extra recipients are not changed. Each line goes out under its price book item's current name, and sales tax is worked out again from the account's current tax settings, as it is whenever an invoice is sent from Couplr. Read amount in the response for the amount billed.

The response has status processing while Couplr prepares the payment link. A moment later the invoice becomes sent, hosted_invoice_url is filled in and the invoice.sent event is delivered.

Refused with 422 on invoice when: the invoice is not a draft; the customer has no email address; online payments are not set up for the account; or the draft was set up in Couplr with a payment option the API does not send (a charge to a saved card, or split payments); a line uses a price book item that has been archived; or another send of the same invoice is in progress. Send those from Couplr.

Path parameters

Headers

Example request

curl -X POST "https://couplrfsm.com/api/v1/invoices/9d3f6a52-0c1e-4c57-9d0a-3a0f8a4a7b21/send" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response (200)

{
    "data": {
        "id": "9d3f6a52-0c1e-4c57-9d0a-3a0f8a4a7b21",
        "invoice_number": "1047",
        "customer_id": 1842,
        "customer_name": "Dana Whitfield",
        "job_id": 9312,
        "status": "processing",
        "amount": "389.00",
        "notes": "Replaced condenser fan motor.",
        "hosted_invoice_url": null,
        "created_at": "2026-12-02T17:20:05+00:00",
        "updated_at": "2026-12-02T18:01:44+00:00",
        "line_items": [
            {
                "name": "Condenser fan motor",
                "quantity": 1,
                "rate": "289.00"
            },
            {
                "name": "Service call",
                "quantity": 1,
                "rate": "100.00"
            }
        ]
    }
}

Errors

Invoice object#