Patch Invoice

patch/v1/invoices/{invoice_id}

Partially updates an invoice's attributes (and optionally its issuer/receiver relationships) within the active workspace. Side effects: persists the changes, bumps updated_at, and recomputes totals when amounts change. Setting payment_status requires the current override_version as a compare-and-swap token to avoid clobbering a concurrent override.

Requires a bearer token: Authorization: Bearer <token>.

Path parameters

Name	Type	Required	Description
invoice_id	string <uuid>	Yes	Public UUID of the invoice to update.e.g. 11111111-0000-4000-8000-0000000000b1

Request

cURL

curl -X PATCH https://api.wellapp.ai/v1/invoices/{invoice_id} \
  -H "Authorization: Bearer $WELL_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "data": {
    "type": "invoices",
    "attributes": {
      "status": "paid",
      "payment_status": "paid",
      "override_version": 0
    }
  }
}'

Request body

{
  "data": {
    "type": "invoices",
    "attributes": {
      "status": "paid",
      "payment_status": "paid",
      "override_version": 0
    }
  }
}

Responses

200 — The updated invoice.

{
  "data": {
    "type": "invoice",
    "id": "11111111-0000-4000-8000-0000000000b1",
    "attributes": {
      "reference_number": "ANT-2026-0412",
      "issue_date": "2026-04-12",
      "due_date": "2026-05-12",
      "currency": "USD",
      "document_type_code": "380",
      "terms": "Net 30",
      "status": "paid",
      "billing_context": "subscription",
      "description": "Claude API usage, April 2026",
      "totals": {
        "items_total": 1200,
        "tax_total": 0,
        "grand_total": 1200
      },
      "payment_status_value": "paid",
      "override_version": 1,
      "created_at": "2026-04-12T08:00:00Z",
      "updated_at": "2026-05-01T14:00:00Z",
      "deleted_at": null
    },
    "relationships": {
      "issuer": {
        "data": {
          "type": "company",
          "id": "22222222-0000-4000-8000-0000000000c1"
        }
      },
      "receiver": {
        "data": {
          "type": "company",
          "id": "22222222-0000-4000-8000-0000000000c2"
        }
      },
      "invoice_items": {
        "data": [
          {
            "type": "invoice_item",
            "id": "33333333-0000-4000-8000-0000000000d1"
          }
        ]
      },
      "payment_means": {
        "data": []
      }
    }
  }
}

400 — Bad request

{
  "code": "BAD_REQUEST",
  "status": 400,
  "title": "Bad Request",
  "message": "See title.",
  "meta": {
    "trace_id": "a1b2c3",
    "log_id": "a1b2c3"
  }
}

401 — Unauthorized

{
  "code": "UNAUTHORIZED",
  "status": 401,
  "title": "Unauthorized",
  "message": "See title.",
  "meta": {
    "trace_id": "a1b2c3",
    "log_id": "a1b2c3"
  }
}

404 — Not found

{
  "code": "NOT_FOUND",
  "status": 404,
  "title": "Not Found",
  "message": "See title.",
  "meta": {
    "trace_id": "a1b2c3",
    "log_id": "a1b2c3"
  }
}