CircuitHub Platform Docs

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.

Get billing details

GET /v1/workspaces/:workspace/billing/details

Read the billed party and address. The endpoint returns null if billing details have not been set.

circuithub billing details show --workspace acme-electronics

Output:

Billed to: Acme Electronics
Email:     accounts@example.com
Address:   100 Main Street, Boston, MA 02110, US

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

Response: 200 OK

{
  "name": "Acme Electronics",
  "isPerson": false,
  "email": "accounts@example.com",
  "phone": "+16175550100",
  "address": {
    "street1": "100 Main Street",
    "street2": null,
    "street3": null,
    "city": "Boston",
    "state": "MA",
    "zip": "02110",
    "countryCode": "US"
  }
}

Billing detail fields

Field	Type	Description
`name`	string	Required. Legal name of the billed company or person
`isPerson`	boolean	Required. True for an individual, false for a company
`email`	string	Required. Billing contact email
`phone`	string or null	Billing contact telephone
`address`	object	Required. Billing address; use the street, city, state, zip and countryCode fields shown below

Billing details may belong to a customer shared by multiple workspaces. Updating them can affect billing for those workspaces too. This call does not alter past invoices or grant tax exemption or payment terms.

Billing details are those of the workspace's CircuitHub billing account, which CircuitHub sets up and which its accounting system receives. A workspace without one is refused with 409 BILLING_ACCOUNT_REQUIRED. Changing details shared with workspaces you cannot change is refused with 403 FORBIDDEN.

Update billing details

PUT /v1/workspaces/:workspace/billing/details

Send the full billing details. Use the API body as billing.json. Setting billing details does not add a shipping address. Request a new order preview after changing them.

circuithub billing details set --workspace acme-electronics --file billing.json

Output:

Updated billing details for acme-electronics.

curl -X PUT -H "Authorization: Bearer $CIRCUITHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Acme Electronics",
  "isPerson": false,
  "email": "accounts@example.com",
  "phone": "+16175550100",
  "address": {
    "street1": "100 Main Street",
    "street2": null,
    "street3": null,
    "city": "Boston",
    "state": "MA",
    "zip": "02110",
    "countryCode": "US"
  }
}' \
  "https://api.circuithub.com/v1/workspaces/acme-electronics/billing/details"

Response: 200 OK

{
  "name": "Acme Electronics",
  "isPerson": false,
  "email": "accounts@example.com",
  "phone": "+16175550100",
  "address": {
    "street1": "100 Main Street",
    "street2": null,
    "street3": null,
    "city": "Boston",
    "state": "MA",
    "zip": "02110",
    "countryCode": "US"
  }
}

Add a payment method

POST /v1/workspaces/:workspace/billing/payment-methods

CircuitHub does not yet provide a secure card collection flow for API clients, so for now add cards in CircuitHub Settings. This endpoint takes a card token collected through the payment provider’s secure collection flow. Submit the token once. The endpoint uses the Portal’s existing Stripe token/source flow, not a PaymentIntent flow. tok_example illustrates a token and cannot be used to pay. Never send card numbers or security codes to this API.

circuithub billing payment-method add --workspace acme-electronics --file payment-token.json

Output:

Added payment method: card_abc123

curl -X POST -H "Authorization: Bearer $CIRCUITHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "token": "tok_example"
}' \
  "https://api.circuithub.com/v1/workspaces/acme-electronics/billing/payment-methods"

Response: 201 Created

{
  "id": "card_abc123",
  "type": "card",
  "brand": "visa",
  "last4": "4242",
  "isDefault": true
}

Request body

Field	Type	Description
`token`	string	Required. A fresh provider token from secure collection; do not log it

A token is not a saved payment-method ID. Keep the returned id for ordering. Adding a method does not place an order, charge it, grant credit or enable bank terms.

Get a payment method

GET /v1/workspaces/:workspace/billing/payment-methods/:paymentMethodId

Read a method available to this workspace. Treat its ID as opaque.

circuithub billing payment-method show card_abc123 --workspace acme-electronics

Output:

ID:      card_abc123
Type:    card
Details: Visa ending in 4242
Default: yes

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

Response: 200 OK

{
  "id": "card_abc123",
  "type": "card",
  "brand": "visa",
  "last4": "4242",
  "isDefault": true
}

Set the default payment method

PUT /v1/workspaces/:workspace/billing/payment-methods/:paymentMethodId/default

Set a saved card as the workspace default. Order submissions still explicitly select a method. This does not change payment on existing orders.

circuithub billing payment-method default card_abc123 --workspace acme-electronics

Output:

Default payment method: card_abc123

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

Response: 200 OK

{
  "id": "card_abc123",
  "type": "card",
  "brand": "visa",
  "last4": "4242",
  "isDefault": true
}

Remove a payment method

DELETE /v1/workspaces/:workspace/billing/payment-methods/:paymentMethodId

Remove a saved card. Approved terms and wire-payment access are managed by CircuitHub and cannot be created or removed through this call. Existing payments are unchanged.

circuithub billing payment-method remove card_abc123 --workspace acme-electronics

Output:

Removed payment method: card_abc123

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

Response: 204 No Content

No response body.

Payment method errors

Errors: 400 VALIDATION_ERROR for an invalid or used token, 404 NOT_FOUND for an unavailable method, 409 PAYMENT_METHOD_UNAVAILABLE for a method that cannot be used or changed, including a token that is not for a card, and 503 PAYMENTS_UNAVAILABLE when the provider is unavailable. Do not retry a token submission blindly after an uncertain result; list methods first.

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`; older payments can also be `bank_account`, `link` or `other`
`invoices`	string[]	Invoice names this payment is applied to
`orders`	object[]	`{ id, projectName }` for linked orders
`status`	string	`applied` or `pending`

List payment methods

Select the returned id for order preview and submission. Approved net terms and wire methods appear only when enabled for the workspace. A listed method is still checked for eligibility and available credit at order time.

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

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

Output:

ID             TYPE         DETAILS                      DEFAULT
card_abc123    card         Visa ending in 4242          yes
card_def456    card         Mastercard ending in 8888    no
net_301        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": "card_abc123",
      "type": "card",
      "brand": "visa",
      "last4": "4242",
      "isDefault": true
    },
    {
      "id": "card_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	Opaque payment method identifier; use exactly as returned
`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