CircuitHub Platform Docs

Billing is coming soon. The endpoints below describe the planned API surface — they are not yet available. We'd love your feedback on the design.

Billing data in CircuitHub is scoped to your workspace. Each workspace sees only its own invoices, payments, and payment methods. Credit balance and net terms are granted at the company level but visible per workspace when enabled.

List invoices

GET /v1/workspaces/:workspaceSlug/billing/invoices

circuithub billing invoice list --workspace acme-electronics
# filter by status or date range
circuithub billing invoice list --workspace acme-electronics --status open
circuithub billing invoice list --workspace acme-electronics --from 2025-01-01 --to 2025-03-31

Output:

ID      NAME         TYPE             TOTAL      STATUS        DUE DATE
50123   INV-4821     order_shipment   $1,240.00  paid_in_full  2025-02-15
50124   INV-4835     charge           $85.00     open          2025-03-20
50125   CM-0312      credit_memo      -$120.00   fully_applied

curl -H "Authorization: Bearer $CIRCUITHUB_API_KEY" \
  "https://api.circuithub.com/v1/workspaces/acme-electronics/billing/invoices?status=open"

Response:

{
  "invoices": [
    {
      "id": 50124,
      "name": "INV-4835",
      "type": "charge",
      "recordType": "invoice",
      "orderId": 8001,
      "transactionDate": "2025-03-01T00:00:00Z",
      "dueDate": "2025-03-20T00:00:00Z",
      "totalNoTax": 80.00,
      "tax": 5.00,
      "total": 85.00,
      "amountPaid": 0.00,
      "amountUnpaid": 85.00,
      "status": "open",
      "description": "Additional testing services"
    }
  ]
}

Query parameters

Parameter	Type	Description
`status`	string	Filter by status: `open`, `paid_in_full`, `approved_for_posting`, `fully_applied` (optional)
`from`	string	Start date filter, ISO 8601 date (optional)
`to`	string	End date filter, ISO 8601 date (optional)

Response fields

Field	Type	Description
`id`	integer	Invoice transaction ID
`name`	string	Invoice number (e.g. `INV-4835`)
`type`	string	`order_shipment`, `charge`, `credit_memo`, or `custom`
`recordType`	string	`invoice`, `creditmemo`, or `journalentry`
`orderId`	integer \| null	Linked order ID, if applicable
`transactionDate`	string	ISO 8601 invoice date
`dueDate`	string \| null	ISO 8601 payment due date
`totalNoTax`	number	Amount before tax
`tax`	number \| null	Tax amount
`total`	number	Total amount including tax
`amountPaid`	number \| null	Amount already paid
`amountUnpaid`	number \| null	Outstanding balance
`status`	string	`open`, `paid_in_full`, `approved_for_posting`, or `fully_applied`
`description`	string \| null	Line item description

Get an invoice

GET /v1/workspaces/:workspaceSlug/billing/invoices/:invoiceId

circuithub billing invoice show 50124 --workspace acme-electronics

Output:

ID:           50124
Name:         INV-4835
Type:         charge
Order:        Power Supply Board (8001)
Date:         2025-03-01
Due:          2025-03-20
Total:        $85.00 ($80.00 + $5.00 tax)
Paid:         $0.00
Unpaid:       $85.00
Status:       open
Description:  Additional testing services

curl -H "Authorization: Bearer $CIRCUITHUB_API_KEY" \
  https://api.circuithub.com/v1/workspaces/acme-electronics/billing/invoices/50124

Response:

{
  "id": 50124,
  "name": "INV-4835",
  "type": "charge",
  "recordType": "invoice",
  "orderId": 8001,
  "transactionDate": "2025-03-01T00:00:00Z",
  "dueDate": "2025-03-20T00:00:00Z",
  "totalNoTax": 80.00,
  "tax": 5.00,
  "total": 85.00,
  "amountPaid": 0.00,
  "amountUnpaid": 85.00,
  "status": "open",
  "description": "Additional testing services"
}

Download invoice PDF

GET /v1/workspaces/:workspaceSlug/billing/invoices/:invoiceId/pdf

circuithub billing invoice show 50124 --workspace acme-electronics --download
# specify output directory
circuithub billing invoice show 50124 --workspace acme-electronics --download --output ./invoices/

Output:

Downloaded: CircuitHub #INV-4835.pdf

curl -H "Authorization: Bearer $CIRCUITHUB_API_KEY" \
  -o "INV-4835.pdf" \
  https://api.circuithub.com/v1/workspaces/acme-electronics/billing/invoices/50124/pdf

Response: 200 OK with Content-Type: application/pdf

Download statement

GET /v1/workspaces/:workspaceSlug/billing/statement

Generate a PDF statement covering a date range.

circuithub billing statement --workspace acme-electronics --from 2025-01-01 --to 2025-03-31
# save to a specific directory
circuithub billing statement --workspace acme-electronics --from 2025-01-01 --to 2025-03-31 --output ./statements/

Output:

Downloaded: CircuitHub Statement.pdf

curl -H "Authorization: Bearer $CIRCUITHUB_API_KEY" \
  -o "statement-q1-2025.pdf" \
  "https://api.circuithub.com/v1/workspaces/acme-electronics/billing/statement?startDate=2025-01-01&endDate=2025-03-31"

Response: 200 OK with Content-Type: application/pdf

List payments

GET /v1/workspaces/:workspaceSlug/billing/payments

circuithub billing payment list --workspace acme-electronics

Output:

ID      NAME         DATE          AMOUNT      METHOD       INVOICES        STATUS
60001   PMT-1192     2025-02-16    $1,240.00   card         INV-4821        applied
60002   PMT-1201     2025-03-05    $500.00     net_terms    INV-4835        applied
60003   (pending)    2025-03-10    $85.00      card                         pending

curl -H "Authorization: Bearer $CIRCUITHUB_API_KEY" \
  https://api.circuithub.com/v1/workspaces/acme-electronics/billing/payments

Response:

{
  "payments": [
    {
      "id": 60001,
      "name": "PMT-1192",
      "date": "2025-02-16T00:00:00Z",
      "amount": 1240.00,
      "method": "card",
      "invoices": ["INV-4821"],
      "orders": [
        {
          "id": 8001,
          "projectName": "Power Supply Board"
        }
      ],
      "status": "applied"
    },
    {
      "id": null,
      "name": null,
      "date": "2025-03-10T12:00:00Z",
      "amount": 85.00,
      "method": "card",
      "invoices": [],
      "orders": [],
      "status": "pending"
    }
  ]
}

Response fields

Field	Type	Description
`id`	integer \| null	Payment transaction ID (null for pending Stripe payments)
`name`	string \| null	Payment reference number
`date`	string	ISO 8601 payment date
`amount`	number	Payment amount in USD
`method`	string	`card`, `net_terms`, or `wire`
`invoices`	string[]	Invoice names this payment is applied to
`orders`	object[]	`{ id, projectName }` for linked orders
`status`	string	`applied` or `pending`

List payment methods

GET /v1/workspaces/:workspaceSlug/billing/payment-methods

circuithub billing payment-method list --workspace acme-electronics

Output:

TYPE          DETAILS                    DEFAULT
card          Visa ending in 4242        yes
card          Mastercard ending in 8888  no
net_terms     Net 30                     no

curl -H "Authorization: Bearer $CIRCUITHUB_API_KEY" \
  https://api.circuithub.com/v1/workspaces/acme-electronics/billing/payment-methods

Response:

{
  "paymentMethods": [
    {
      "id": "pm_abc123",
      "type": "card",
      "brand": "visa",
      "last4": "4242",
      "isDefault": true
    },
    {
      "id": "pm_def456",
      "type": "card",
      "brand": "mastercard",
      "last4": "8888",
      "isDefault": false
    },
    {
      "id": "net_301",
      "type": "net_terms",
      "terms": "net_30",
      "isDefault": false
    }
  ]
}

Response fields

Field	Type	Description
`id`	string	Payment method identifier (for example Stripe IDs, `wire_`, or `net_`)
`type`	string	`card`, `net_terms`, or `wire`
`brand`	string	Card brand (cards only): `visa`, `mastercard`, `amex`, etc.
`last4`	string	Last 4 digits (cards only)
`terms`	string	Net terms type (net terms only): `net_30`, `net_60`, etc.
`isDefault`	boolean	Whether this is the default payment method

Get balance

GET /v1/workspaces/:workspaceSlug/billing/balance

circuithub billing balance --workspace acme-electronics

Output:

Balance:       $2,450.00
Credit limit:  $10,000.00
Available:     $7,550.00

If the workspace has no credit:

No credit balance for this workspace.

curl -H "Authorization: Bearer $CIRCUITHUB_API_KEY" \
  https://api.circuithub.com/v1/workspaces/acme-electronics/billing/balance

Response:

{
  "balance": 2450.00,
  "creditLimit": 10000.00
}

Returns null if the workspace has no credit enabled:

null

Response fields

Field	Type	Description
`balance`	number	Current outstanding balance in USD
`creditLimit`	number	Total credit limit in USD

Billing

On this page