CircuitHub Platform Docs

An order represents a manufacturing request in CircuitHub — placing PCBs for fabrication and assembly based on your project revisions. Each order belongs to a project and tracks production through to completion.

Get shipping options

POST /v1/quotes/:quoteId/offers/:offerId/shipping-options

Request services for the selected offer and delivery address. An empty list means no service is available for this selection. Option IDs identify available services, not saved shipping quotations; prices are recalculated at preview and submission.

circuithub order shipping-options --quote 50001 --offer 880002 --shipping-address 6101 --workspace acme-electronics

Output:

ID          SERVICE     SHIPPING
ups_ground  UPS Ground  $25.00

curl -X POST -H "Authorization: Bearer $CIRCUITHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "shippingAddressId": 6101
}' \
  "https://api.circuithub.com/v1/quotes/50001/offers/880002/shipping-options"

Response: 200 OK

{
  "quoteId": 50001,
  "offerId": 880002,
  "shippingAddressId": 6101,
  "currency": "USD",
  "shippingOptions": [
    {
      "id": "ups_ground",
      "label": "UPS Ground",
      "amount": "25.00"
    }
  ]
}

Request and response fields

Field	Type	Description
`shippingAddressId`	integer	Required request field. Saved address available to the quote’s workspace
`shippingOptions[].id`	string	Opaque service option ID to use in preview
`shippingOptions[].label`	string	Service display name
`shippingOptions[].amount`	string	Shipping charge before tax, as a decimal string
`currency`	string	`USD`

Request options again after changing the offer or address. Manufacturing ship dates are dispatch dates, not delivery dates. Shipping charges do not include tax or international import duties.

A quote, offer or address that is not the workspace's is 404 NOT_FOUND; an address missing details needed for shipping is 400 VALIDATION_ERROR. If shipping rates cannot be fetched, the request fails with 503 SHIPPING_UNAVAILABLE; request options again later.

Preview an order

POST /v1/orders/preview

Calculate the complete price without saving a checkout, creating an order or taking payment. Use the API body as order-selection.json. The workspace query parameter is required; every selection must belong to or be usable by that workspace.

circuithub order preview --workspace acme-electronics --file order-selection.json

Output:

Manufacturing: $774.45
Shipping:      $25.00
Tax:           $49.97
Order total:   $849.42
Due now:       $849.42
Due later:     $0.00
Orderable:     yes

curl -X POST -H "Authorization: Bearer $CIRCUITHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "quoteId": 50001,
  "offerId": 880002,
  "shippingAddressId": 6101,
  "shippingOptionId": "ups_ground",
  "paymentMethodId": "card_abc123"
}' \
  "https://api.circuithub.com/v1/orders/preview?workspace=acme-electronics"

Response: 200 OK

{
  "quoteId": 50001,
  "offerId": 880002,
  "shippingAddressId": 6101,
  "shippingOptionId": "ups_ground",
  "paymentMethodId": "card_abc123",
  "currency": "USD",
  "orderable": true,
  "blockers": [],
  "price": {
    "manufacturingSubtotal": "1180.00",
    "discounts": [
      {
        "type": "grid_proto",
        "code": null,
        "label": "Grid Proto",
        "amount": "319.50"
      },
      {
        "type": "account",
        "code": null,
        "label": "Your pricing",
        "amount": "86.05"
      }
    ],
    "manufacturingTotal": "774.45",
    "shipping": "25.00",
    "tax": "49.97",
    "total": "849.42"
  },
  "payment": {
    "amountDueNow": "849.42",
    "amountDueLater": "0.00",
    "terms": null
  },
  "taxStatus": "calculated",
  "quoteExpiresAt": "2026-11-03T11:00:00Z"
}

Request body

Field	Type	Description
`quoteId / offerId`	integer	Required. An offer belonging to this quote
`shippingAddressId`	integer	Required. Saved delivery address
`shippingOptionId`	string	Required. Option returned for this offer and address
`paymentMethodId`	string	Required. Available workspace payment method

Preview fields

Field	Type	Description
`currency`	string	Currency for all amounts; `USD`
`orderable`	boolean	Whether this selection can currently be submitted
`blockers`	array	Reasons it cannot be ordered; objects with `code` and `message`
`price.manufacturingSubtotal`	string or null	Manufacturing price before discounts; null if historical detail was not recorded
`price.discounts`	array or null	Positive savings, already reflected in manufacturingTotal
`price.manufacturingTotal`	string	Manufacturing price after discounts
`price.shipping`	string	Shipping charge before tax
`price.tax`	string or null	Calculated tax; null when unavailable, never substituted with zero
`price.total`	string or null	Manufacturing total + shipping + tax; null when tax is unavailable
`payment.amountDueNow / payment.amountDueLater`	string or null	Amounts payable now and later under the selected method; null when a complete price cannot be calculated
`payment.terms`	string or null	Approved payment terms when applicable
`taxStatus`	string	`calculated` or `unavailable`; a calculated zero tax is valid
`quoteExpiresAt`	string	Original quote expiry; preview does not extend it

All amounts are decimal strings. Discounts are already deducted from manufacturingTotal; do not deduct them again. For a valid preview, amountDueNow + amountDueLater = total. The example pays in full by card. Approved terms may instead show zero due now and the full total due later; the server decides from the account and selected method. Credit limits are not a discount.

If tax calculation is unavailable, return orderable: false, taxStatus: "unavailable", a TAX_UNAVAILABLE blocker, and null tax, total and payment amounts. Resolve it before ordering. International duties may be payable separately and are not included in this total.

A net terms method without enough available credit for the total gives a PAYMENT_METHOD_UNAVAILABLE blocker. A selection that is not the workspace's, or a payment method it does not list, is 404 NOT_FOUND.

A preview does not reserve stock, fix shipping prices or hold credit. There is no preview ID to save. Review a fresh preview after changing any selection or billing details.

Place an order

POST /v1/orders

Submit the same selections you previewed, with the reviewed total. Use the API body as order.json. This operation creates a manufacturing order and may charge the selected method. Read the returned order ID and payment status.

circuithub order create --workspace acme-electronics --file order.json

Output:

Order:   8001
Status:  in-progress
Payment: Paid

curl -X POST -H "Authorization: Bearer $CIRCUITHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "quoteId": 50001,
  "offerId": 880002,
  "shippingAddressId": 6101,
  "shippingOptionId": "ups_ground",
  "paymentMethodId": "card_abc123",
  "expectedTotal": "849.42",
  "poNumber": "PO-2026-042"
}' \
  "https://api.circuithub.com/v1/orders?workspace=acme-electronics"

Response: 201 Created

{
  "id": 8001,
  "urn": "acme-electronics/00001f41",
  "name": "ORD-8001",
  "status": "in-progress",
  "quantity": 10,
  "createdAt": "2026-11-03T10:05:00Z",
  "updatedAt": "2026-11-03T10:05:00Z",
  "quotedShippingDate": "2026-11-06T00:00:00Z",
  "estimatedShippingDate": null,
  "shippedDate": null,
  "trackingNumber": null,
  "shippingService": "UPS Ground",
  "value": 774.45,
  "paymentStatus": "Paid",
  "poNumber": "PO-2026-042",
  "projectId": 12345,
  "projectName": "Power Supply Board",
  "revisionId": 99001,
  "revisionNumber": 3
}

Request body

The five selection fields are the same as the preview request.

Field	Type	Description
`expectedTotal`	string	Required. Exact decimal total reviewed in the preview, in the quote currency
`poNumber`	string	Optional. Your purchase order reference; not a duplicate-request key

CircuitHub validates the quote, address, shipping service, billing details, payment method and stock again. It recalculates the total and refuses a mismatch before attempting payment. An equal total is a price check, not a guarantee that every component of the preview is unchanged.

The response uses the existing order representation below. Its value is the existing stored order value, not the new preview’s all-in total or amount due. The read API does not return a saved copy of the preview. Keep your reviewed calculation if you need it; invoices and payments are separate billing records.

Submission errors and retries

HTTP status	Code	Action
400	`VALIDATION_ERROR`	Correct the supplied selections or expected total
409	`TOTAL_CHANGED`	Review a new preview and submit its total
404	`NOT_FOUND`	A selection is not the workspace's; use IDs it lists
409	`ORDER_NOT_ORDERABLE`	Resolve stock, billing, shipping or payment eligibility blockers. A quote that has already been ordered is refused this way, and the message names its order
410	`QUOTE_EXPIRED`	Request a fresh quote, shipping options and preview
422	`PAYMENT_FAILED`	Review the payment failure; check for an existing order before trying again
503	`TAX_UNAVAILABLE`	Wait for tax calculation to recover and preview again
503	`SHIPPING_UNAVAILABLE`	Wait for shipping rates to recover, then request shipping options and a preview again

Do not automatically retry order submission after a timeout, connection loss or server error. An order or payment may already exist. List the workspace’s recent orders and inspect likely matches. A PO number is not unique; if the result is uncertain, contact CircuitHub before resubmitting. Submissions are not idempotent and charging is not exactly-once. Two submissions of the same quote at the same moment are not prevented from both taking payment, so submit an order once and wait for the outcome.

List orders

GET /v1/orders

circuithub order list --workspace acme-electronics

Output:

ID      Status        Date          Qty   Payment   Project
8001    in-progress   2025-03-01    10    Paid      Power Supply Board
8002    completed     2025-02-28    25    Paid      Sensor Module

curl -H "Authorization: Bearer $CIRCUITHUB_API_KEY" \
  "https://api.circuithub.com/v1/orders?workspace=acme-electronics"

Response:

{
  "orders": [
    {
      "id": 8001,
      "urn": "acme-electronics/00001f41",
      "name": "ORD-8001",
      "status": "in-progress",
      "quantity": 10,
      "createdAt": "2025-03-01T14:00:00Z",
      "updatedAt": "2025-03-02T11:00:00Z",
      "quotedShippingDate": "2025-03-15T00:00:00Z",
      "estimatedShippingDate": "2025-03-14T00:00:00Z",
      "shippedDate": null,
      "trackingNumber": null,
      "shippingService": null,
      "value": 790.50,
      "paymentStatus": "Paid",
      "poNumber": "PO-2025-042",
      "projectId": 12345,
      "projectName": "Power Supply Board",
      "revisionId": 99001,
      "revisionNumber": 3
    }
  ]
}

Query parameters

Parameter	Type	Description
`workspace`	string	Required. Workspace slug

Response fields

Field	Type	Description
`id`	integer	Order ID
`urn`	string	Order URN
`name`	string	Order name/number
`status`	string	`in-progress`, `hold`, `completed` or `canceled`
`quantity`	integer	Number of boards ordered
`createdAt`	string	ISO 8601 creation timestamp
`updatedAt`	string	ISO 8601 last update timestamp
`quotedShippingDate`	string	Quoted shipping date, ISO 8601
`estimatedShippingDate`	string \| null	Estimated shipping date, ISO 8601
`shippedDate`	string \| null	Actual ship date, ISO 8601
`trackingNumber`	string \| null	Shipment tracking number
`shippingService`	string \| null	Shipping carrier/service
`value`	number	Existing stored order value in USD; not the preview’s all-in total
`paymentStatus`	string	`Unpaid`, `Paid` or `PartiallyPaid`; separate from manufacturing status
`poNumber`	string	Purchase order number
`projectId`	integer	Project this order belongs to
`projectName`	string	Project name
`revisionId`	integer	Project revision used for this order
`revisionNumber`	integer	Human-readable revision number

Get an order

GET /v1/orders/:orderId

circuithub order show 8001 --workspace acme-electronics

Output:

Order:    8001
URN:      acme-electronics/00001f41
Name:     ORD-8001
Status:   in-progress
Quantity: 10
Value:    $790.50
Payment:  Paid
PO:       PO-2025-042

Project:  Power Supply Board (ID: 12345, rev 3)

Created:  2025-03-01T14:00:00Z
Quoted:   2025-03-15T00:00:00Z

curl -H "Authorization: Bearer $CIRCUITHUB_API_KEY" \
  https://api.circuithub.com/v1/orders/8001

Response:

{
  "id": 8001,
  "urn": "acme-electronics/00001f41",
  "name": "ORD-8001",
  "status": "in-progress",
  "quantity": 10,
  "createdAt": "2025-03-01T14:00:00Z",
  "updatedAt": "2025-03-02T11:00:00Z",
  "quotedShippingDate": "2025-03-15T00:00:00Z",
  "estimatedShippingDate": "2025-03-14T00:00:00Z",
  "shippedDate": null,
  "trackingNumber": null,
  "shippingService": null,
  "value": 790.50,
  "paymentStatus": "Paid",
  "poNumber": "PO-2025-042",
  "projectId": 12345,
  "projectName": "Power Supply Board",
  "revisionId": 99001,
  "revisionNumber": 3
}

Orders

Get shipping options

Request and response fields

Preview an order

Request body

Preview fields

Place an order

Request body

Submission errors and retries

List orders

Query parameters

Response fields

Get an order

On this page