Ordering PCBs on CircuitHub via API

btw: you can also use our CLI to do the same thing. Our MCP server does not place orders yet.

Use https://api.circuithub.com and authenticate your requests. If you have not designed the board yet, read design feedback first: small runs that meet Grid Proto's rules cost much less.

Start by uploading your PCB in one of our supported design formats. Request upload URLs for your files, specifying the workspace, filenames and sizes.

POST /v1/projects/upload-urls

Upload each file to its returned URL, using the supplied headers.

PUT {uploadUrl}

Create the project with its name, workspace, uploaded file references and export classification declaration.

POST /v1/projects

Wait for the import to finish. Check its status until it is complete. If it is failed, resolve the import error before continuing.

GET /v1/projects/{projectId}/status

Once your design has been imported, carefully review the board configuration to make sure it's as you require.

[!NOTE] Our importer does not read all board properties from your EDA files, so it's imperative you review and adjust the board settings if you are not ok with our defaults.

Read the board configuration for the project revision you intend to order. Check the thickness, material, copper weights, finish, colours, stackup and any special requirements.

GET /v1/revisions/{revisionId}/board

Update the settings you want to change. Leave other settings unchanged.

PATCH /v1/revisions/{revisionId}/board

Include the board ID and version you read so an intervening change is not overwritten. Changes are refused while the revision's quote is locked.

If your board needs controlled impedance, set its impedance requirements.

PUT /v1/revisions/{revisionId}/board/impedances

Supply the complete list of requirements and the board ID and version. Review the updated configuration before requesting a quote.

Once you are happy with your board configuration, request a quote for the returned revision ID and your desired quantity.

POST /v1/quotes

Supply revisionId and quantity.

If the quote is not orderable, it gives you the reasons. Usually there is insufficient stock, no suitable supplier, or a BOM line has not been matched to an approved part. Some designs need manual review.

Read the BOM to inspect the affected lines. This endpoint currently returns the latest revision’s BOM.

GET /v1/projects/{projectId}/bom

For each affected line, search for a suitable part and check its available quantity. Allow for the number of components per board and assembly wastage; a fresh quote will check the actual requirement.

GET /v1/parts?q={partNumber}

Assign the chosen part to your BOM line using its partId.

PUT /v1/bom/{bomLineId}/part

Once the issues are addressed, request a fresh quote for the same revision and quantity.

POST /v1/quotes

You will receive the available offers, with manufacturing prices and ship dates. Choose an offer and keep its quote ID and offer ID. The manufacturing total excludes shipping and tax. The ship date is when the boards leave CircuitHub, not when they arrive.

Read the quote's designFeedback as well. When a change to the design would make the order cheaper, such as qualifying for Grid Proto, it lists each change and the request that makes it. Make the changes you want, then request a fresh quote.

Before ordering, check the board specifications and confirm that this is the design you want manufactured.

Add or update your billing details, including the person or company being billed and its billing address.

PUT /v1/workspaces/{workspace}/billing/details

Select a shipping address or add one. This is where the finished boards will be delivered and can differ from the billing address.

GET /v1/shipping-addresses?workspace={workspace}
POST /v1/shipping-addresses?workspace={workspace}

Get shipping options for your selected offer and shipping address. Choose a service and keep its option ID.

POST /v1/quotes/{quoteId}/offers/{offerId}/shipping-options

Supply shippingAddressId.

Select a payment method already available to the workspace. Approved payment terms appear here when available.

GET /v1/workspaces/{workspace}/billing/payment-methods

If needed, add a card in CircuitHub Settings. The add a payment method endpoint takes a token from the payment provider’s secure collection flow, which CircuitHub does not yet provide to API clients. Do not send raw card details to CircuitHub’s API.

POST /v1/workspaces/{workspace}/billing/payment-methods

Preview the order with your quote, offer, shipping address, shipping option and payment method.

POST /v1/orders/preview?workspace={workspace}

This calculates the price without creating an order or taking payment.

Review the manufacturing total, shipping, tax and full order total, along with what is due now or later. If tax cannot be calculated, resolve that before ordering. International duties may be payable separately.

Place the order with the same selections, the preview’s total as expectedTotal, and an optional poNumber.

POST /v1/orders?workspace={workspace}

CircuitHub recalculates the total before attempting payment. If it has changed, review a fresh preview before ordering. If the quote has expired, request a fresh quote and shipping options for it, then preview again; reading an expired quote does not renew it.

If the request times out, check whether the order was created before submitting again. Automatic retries are not guaranteed safe.

Once placed, check the order using its ID.

GET /v1/orders/{orderId}

You can also list your workspace’s orders.

GET /v1/orders?workspace={workspace}

The order status is in-progress, hold, completed or canceled. When it is marked completed, shippedDate records the shipment date. Tracking details are included when available. Check payment status separately.