---
title: "Link or unlink what an invoice bills"
method: POST
path: "/invoices/{id}/billing-source"
tags: ["Invoices"]
---

# Link or unlink what an invoice bills

`POST /invoices/{id}/billing-source`

## Request

- Base URL: `https://app.buildworkpro.com/api/v1`
- URL: `https://app.buildworkpro.com/api/v1/invoices/{id}/billing-source`
- Auth: HTTP bearer

Attach an existing invoice to the pay application, payment-schedule installment and/or bid it bills, or detach it (send `null`). Allowed in every status except `voided`, so an imported, manual or already-paid invoice can be linked after the fact; only the link columns and the derived `sourceType` change — never lines, totals or status — and nothing is pushed to QuickBooks. The pay app must be on the invoice's own project, live (submitted, sent, approved or paid) and not already claimed by another live invoice; the installment must be on the project's bid's payment term and not billed by another live invoice. An invoice bills a pay app or an installment, not both. The response carries the project's billed figures before and after; `dryRun: true` returns them without saving.

## Path parameters

- `id` integer, required

## Headers

- `Idempotency-Key` string, uuid

## Request body

- object
  - `sourcePayAppId` integer, nullable: Pay application this invoice bills (same project, submitted/sent/approved/paid, not claimed by another live invoice). null unlinks.
  - `paymentTermInstallmentId` integer, nullable: Payment-schedule installment this invoice bills (on the project's bid's payment term, not billed by another live invoice). null unlinks.
  - `sourceBidId` integer, nullable: The project's bid, printed on the invoice PDF. null unlinks.
  - `dryRun` boolean: Validate and return the billed-figure preview without saving.

## Response `200`

Linked

- object
  - `data` InvoiceBillingSourceResult, required
    - `invoice` Invoice, required
      - `id` integer, required
      - `tenantId` integer, required
      - `invoiceNumber` string, required
      - `projectId` integer, nullable, required
      - `contactId` integer, nullable, required
      - `status` 'draft' | 'sent' | 'partial' | 'paid' | 'voided', required
      - `issueDate` string, date-time, nullable, required
      - `dueDate` string, date-time, nullable, required
      - `subtotal` string, required
      - `taxAmount` string, required
      - `total` string, required
      - `amountPaid` string, required
      - `balanceDue` string, required
      - `notesToCustomer` string, nullable, required
      - `createdAt` string, date-time, required
      - `updatedAt` string, date-time, required
    - `before` object, required
      - `sourcePayAppId` integer, nullable, required
      - `paymentTermInstallmentId` integer, nullable, required
      - `sourceBidId` integer, nullable, required
      - `sourceType` 'bid' | 'pay_app' | 'ad_hoc', required
    - `after` object, required
      - `sourcePayAppId` integer, nullable, required
      - `paymentTermInstallmentId` integer, nullable, required
      - `sourceBidId` integer, nullable, required
      - `sourceType` 'bid' | 'pay_app' | 'ad_hoc', required
    - `changed` boolean, required
    - `dryRun` boolean, required
    - `billing` object, required
      - `before` ProjectBillingFigures, required
        - `invoiced` number, required
        - `invoicedPreTax` number, required
        - `paid` number, required
        - `outstanding` number, required
        - `invoiceCount` integer, required
        - `payAppBilled` number, required
        - `billedTotal` number, required
        - `billedCash` number, required
        - `outstandingCash` number, required
        - `retainageHeld` number, required
        - `remaining` number, required
        - `hasBilling` boolean, required
      - `after` ProjectBillingFigures, required
        - `invoiced` number, required
        - `invoicedPreTax` number, required
        - `paid` number, required
        - `outstanding` number, required
        - `invoiceCount` integer, required
        - `payAppBilled` number, required
        - `billedTotal` number, required
        - `billedCash` number, required
        - `outstandingCash` number, required
        - `retainageHeld` number, required
        - `remaining` number, required
        - `hasBilling` boolean, required
  - `meta` ResponseMeta, required
    - `request_id` string: Server-generated request identifier
    - `pagination` PaginationMeta
      - `cursor` string, nullable, required: Opaque cursor for the next page; null when no more results
      - `has_more` boolean, required: Whether more pages are available after this one
      - `count` integer, required: Items in this page

## Other responses

- `404`: Error
- `409`: Error
- `422`: Error

---

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