API · for people and agents

Order harnesses from code or your AI agent.

Public JSON, no API key. Price any design, create an order, and get a Stripe checkout link for whoever pays. Prices are the same ones the configurator shows.

OpenAPI spec llms.txt llms-full.txt Configurator

Quickstart

1. Price an order

POST /api/quote takes the same body as an order and creates nothing.

Request

curl -X POST https://acornharness.com/api/quote \
  -H 'Content-Type: application/json' \
  -d '{"items": [
     {"connector": "xt30-22", "length_mm": 350, "end_b": "ra-down", "quantity": 10},
     {"connector": "xt30", "length_mm": 200, "end_b": "unterminated", "quantity": 4}
   ]}'

Response (abridged)

{
  "currency": "USD",
  "items": [
    {
      "name": "Acorn XT30(2+2) 350 mm 16AWG ST/RA-D",
      "quantity": 10,
      "unit_price": 26.95,
      "total": 269.5,
      "design_url": "https://acornharness.com/?k=…#design"
    },
    {
      "name": "Acorn XT30 pigtail 200 mm 16AWG ST",
      "quantity": 4,
      "unit_price": 16.76,
      "total": 67.04,
      "design_url": "https://acornharness.com/?k=…#design"
    }
  ],
  "harnesses": 14,
  "volume_discount": 0.05,
  "subtotal": 336.54,
  "shipping_options": [
    {
      "label": "US Ground",
      "price": 12
    },
    {
      "label": "US Two-Day",
      "price": 28
    }
  ]
}

2. Create the order

POST /api/orders returns the same pricing plus a checkout_url (valid 24 hours). Send an Idempotency-Key so a retry returns the same order instead of a second one.

Request

curl -X POST https://acornharness.com/api/orders \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: po-1234' \
  -d '{"items": [
     {"connector": "xt30-22", "length_mm": 350, "end_b": "ra-down", "quantity": 10},
     {"connector": "xt30", "length_mm": 200, "end_b": "unterminated", "quantity": 4}
   ],
   "email": "buyer@example.com",
   "reference": "PO-1234"}'

Response (201, abridged)

{
  "id": "cs_live_a1B2…",
  "object": "order",
  "status": "awaiting_payment",
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_live_a1B2…",
  "expires_at": "2026-11-03T17:00:00.000Z",
  "status_url": "https://acornharness.com/api/orders/cs_live_a1B2…",
  "reference": "PO-1234",
  "subtotal": 336.54,
  …
}

3. Pay and track

Whoever pays opens checkout_url. Stripe takes the card, Link or wallet payment, the US shipping address and speed, and sales tax. Nothing is charged or built until then. Poll the order for its status.

Request

curl https://acornharness.com/api/orders/cs_live_a1B2…

Response (abridged)

{
  "id": "cs_live_a1B2…",
  "status": "paid",
  "reference": "PO-1234",
  "harnesses": 14,
  "subtotal": 336.54,
  "shipping": { "label": "US Ground", "price": 12 },
  "tax": …,
  "total": …,
  "fulfillment": "Built and shipped within 5 business days; tracking is emailed to the buyer."
}

Describing a harness

items holds 1–40 designs. Each is an object of the fields below. Any field you leave out takes the default design's value, and unknown fields are rejected so a typo can't order the wrong part. An item can also be a complete design code or a design_url string, as returned by the quote API or copied from the configurator.

Field	Values	Default
`connector`	"xt30" (XT30, power only, 2 pins); "xt30-22" (XT30(2+2), power + 2 signal pins)	"xt30-22"
`length_mm`	30–3000, rounded to 5 mm. Wire only: back of one plug to the back of the other, or to the wire tips on a pigtail.	350
`power_gauge`	14, 16, 18 (AWG). XT30(2+2) signal wires are always 24 AWG.	16
`end_a`	"straight", "ra-up", "ra-down". Up/down as seen from the wire side.	"straight"
`end_b`	"straight", "ra-up", "ra-down", "unterminated". "unterminated" makes a pigtail: no plug, wires stripped 6 mm and tinned.	"ra-down"
`colors`	Array in pin order. XT30: PIN+, PIN-. XT30(2+2): PIN+, PIN-, SIG1, SIG2. Power red/black, signal green/yellow.	red, black (+ green, yellow)
`twisted`	true / false. XT30(2+2) signal pair.	true
`quantity`	1–5000	1
`design`	Optional starting point: a complete design code or design_url. The other fields override it.	none

Order-level fields: email (prefills checkout; the receipt and tracking go there) and reference (your PO or note, up to 200 characters, echoed back on the order).

Pricing and shipping

Volume discounts count every harness in the order, across all designs: 10+ 5% off, 100+ 10% off, 1000+ 20% off.
Shipping is priced by order weight and chosen at checkout: US Ground, Two-Day, Next Day, or free San Francisco pickup.
Sales tax is added at checkout where it applies. US shipping only.
Every order is built, tested and shipped within 5 business days.

Order status

status	Meaning
`awaiting_payment`	Created; checkout_url is still valid.
`payment_processing`	Paid with a method that settles later, such as a bank debit.
`payment_failed`	That payment didn't go through. Create a new order.
`paid`	On the bench. Ships within 5 business days; tracking is emailed to the buyer.
`expired`	Not paid within 24 hours. Create a new order.

The order id is the only credential, so keep it private. Status responses never include addresses or contact details.

Errors

Errors are JSON {"error": "…"} with a message that names the bad field:

400  {"error": "items[1].length_mm must be a number from 30 to 3000"}

Code	When
400	Invalid body, item or field.
404	No such order.
409	Idempotency-Key reused with a different body.
502	Stripe was unreachable. Retry with the same Idempotency-Key.

All endpoints

Endpoint	What it does
`POST /api/orders`	Create an order; returns pricing and a Stripe checkout_url.
`GET /api/orders/{id}`	Payment status and charged totals.
`POST /api/quote`	Price a multi-design order without creating it.
`GET /api/quote?k=22&l=350…`	Quick quote for one design from design-code parameters.
`GET /api/spec?k=22&l=350…`	The manufacturing spec, an Almond Harness Studio .harness.json file.
`GET /openapi.json`	OpenAPI 3.1 description of all of the above.

Questions, or need net terms on a PO? Email hello@almond.bot.