Estimating API

Drive an estimate from your own system, for example a web shop:

1. Create the estimate with the customer's graphic, the materials they may choose and a designer link.
2. Send your customer to the designer link, where they draw the parts on their graphic.
3. Poll until they click Finish.
4. Pull everything they drew, with the quote, nests and cut-file links.

All calls are team-scoped under /a/<team_slug>/estimating/api/v1/ and need an API key (see the API overview). The examples use this shell setup:

export HOST=https://app.example.com
export AUTH="Authorization: Api-Key $API_KEY"

Create an estimate in one call#

Send multipart/form-data (needed to include a file) or JSON. You need either name or file; everything else is optional.

curl -sS -X POST "$HOST/a/acme/estimating/api/v1/estimates/" -H "$AUTH" \
  -F "file=@postcard-a.pdf;type=application/pdf" \
  -F "external_id=order-1001" \
  -F "customer_name=C-102" \
  -F "reference=PO-5555" \
  -F "material_ids=7" -F "material_ids=8" \
  -F "default_material=7" \
  -F 'metadata={"order_id": 1001, "source": "webshop"}' \
  -F 'designer_link={"role": "customer", "label": "Proof for C-102", "return_url": "https://example.com/orders/1001/done", "expires_in_days": 14}'

The create is all or nothing: if any field or part fails, nothing is stored. When your team's storage is full the graphic is refused with 507 and the code quota_exceeded (see Storage), and no estimate is kept. Part errors come back by position: {"parts": {"1": {"size": ["..."]}}}. The response (201) is the estimate. Besides the fields above it has id, revision, totals (part_count, total_area_sq_in, total_cost, total_price), documents (with their download URLs and page sizes), designer_links, designer_url (the newest active link, or null), designer_submitted_at and data_url. With parts it also has parts (as the parts endpoints return them) and quote.

A quote without artwork, in one call:

curl -sS -X POST "$HOST/a/acme/estimating/api/v1/estimates/" -H "$AUTH" -H "Content-Type: application/json" -d '{
  "name": "Spring promo", "customer_name": "Larkfold Studio", "price": true,
  "parts": [
    {"name": "Postcard A", "size": "4x6", "quantity": 5000, "alt_quantities": [10000], "material": 41,
     "route": "offset", "inks": "4/4", "external_id": "L-1"},
    {"name": "Event poster", "width": 24, "height": 36, "unit": "in", "quantity": 10, "material": 7},
    {"name": "Design fee", "route": "custom", "price_each": "75.00"}
  ]}'

The same in separate calls. Create with JSON, then add the file, set the materials and create a link:

From Files. To add a file your team already has in Files, send its version's id (version_id, from the Files API) instead of uploading it again. The document shows that version: its bytes aren't copied, and a newer version of the file doesn't change the estimate. The same type and size rules apply (400 on version_id); a version that isn't in your team's library, or whose file is in the trash, gets 404. Designer links can't add files this way.

Document downloads. A document's url and preview_url point at this API, never at file storage: fetch them with the same Authorization header (or a signed-in session). The bytes come back as uploaded, under the original file name; the preview is the first page as an image. Designer link pages get the same files through the link.

PATCH changes the header fields, external_id, metadata, material_ids and default_material. It refuses file and designer_link, which only work on create. PUT on an estimate answers 405.

Designer links#

Designer links for customers and staff explains links from the app's side. A designer link is an unguessable URL (https://app.example.com/estimating/d/<token>/) that opens this one estimate in the Takeoff designer, with no sign-in. The token in the URL is the credential: treat the link like a password and revoke it when you're done.

What each role can do. The server enforces this, not only the page.

A customer can edit and delete the parts they added. Their saves never remove a part your team added by size or a price-only line, and never change its costs, hand prices, finishing or quantities to quote. Price-only lines can't be added from a customer link (400). A customer sees a box line read-only, with its dies and plates as one-off rows priced when show_prices is on; its production group (part-<uuid>) answers 404 on a customer link.

Manage links later with these:

A revoked or expired link answers 410 Gone, and its page tells the visitor the link is no longer available. Whatever they saved is kept.

Estimate lines#

An estimate's parts are its lines. A part is drawn on a page of the graphic, sized by hand (no graphic needed), a box sized by its dieline, or a price-only item (a design fee, outsourced work). Every part has a quantity, up to 3 other quantities to quote, a material, a route (roll for wide format, sheet for digital sheets, offset, blank for made-to-size board, or custom for a price you type), inks and finishing.

A custom part sent without a size is a price-only item ("kind": "item" says the same). Parts come back with id, source (drawn, manual or item), description, the size in the estimate's unit and in inches, area, perimeter, sides, family, spec, plan (a family part priced on its own: ups, press sheet, machines; null otherwise), tooling (its one-off dies and plates: key, label, total_cost, total_price, billing, tool) and price (total, each, tooling, pending, blocked; tooling is the one-off tooling billed on its own row, not in total). Sizes of drawn parts come from the drawing: changing one gets 400 (sending a part's own values back, as GET gave them, is fine).

Boxes#

A box is a part with "shape": "dieline" and a dieline: its outline, size, area and perimeter come from the dieline, so size and points are refused on it (400), and so are width and height (or width_in, height_in) unless they equal the box's blank: a box's own part, as GET gave it, can be sent back. The board follows the part's material: the server stores the material's catalogue board, caliper and allowances in the dieline, and keeps them until you update the box. A caliper_mm you send in the dieline is the box's own caliper: it wins over the material's, also when the material changes, until you update the box. A box without all three sizes is saved and waits for them, like a part with no size.

{"name": "Shipping box", "shape": "dieline", "material_sku": "C32-MTS", "route": "blank", "quantity": 1000,
 "dieline": {"style": "fefco_0201", "L": 12, "W": 10, "D": 8, "unit": "in"}}

• Routes: sheet (printed on sheets, cut on the cutting table, ganged with the flat parts on the same stock), offset (die-cut cartons, each priced on its own: press, die-cutter, folder-gluer and a die from your rate card; and litho-laminated corrugated: a corrugated grade on offset is laminated to an offset-printed sheet, with spec.litho_material the sheet stock and spec.litho_inks its inks, and needs a laminator), blank (board made to size: converted on a flexo folder-gluer or die-cut, or priced per blank by its rectangle: ft², m² or 1,000 ft²) and custom. A box on roll gets 400. A flat part on blank gets 400.
• family is carton or corrugated, from the style. spec holds the costing options: convert (how the box is made: die for die-cut and folder-gluer, table for the cutting table, ffg for a flexo folder-gluer, none for board only, litho_lam for litho-laminated; the route's default when left out), versions (artworks sharing one die, 1 to 50), tooling_billing (separate, the default: dies and plates on their own one-off row; included: in the line's price) and, on corrugated, print_panels (1, 2 or 4) and joint (glued). A carton on offset or with convert: die, and corrugated converted on blank, is priced on its own in production group part-<uuid>.
• The die (die-cut and litho-laminated boxes, see Die on hand or a new die): die_policy is prefer_on_hand (a die on hand that fits, else a new die; the team's default when left out), compare (the least all-in), standing (the die in tool, else the cheapest one on hand) or new; tool is the id of a die of your library to use (on hand; with die_policy: standing also one at the die maker or in repair); die_rush (true/false) adds the rate card's rush percentage to a new die; tool_accepted_near ({"tool", "kind", "dist_mm", "geometry_hash"}, null clears it) makes a near match count for this box while geometry_hash is the part's dieline_info.hash (it lapses when the box changes). An unknown policy, a die of another team or an archived one gets 400 on that key. A customer designer link's spec has none of tool, die_policy, die_rush and tool_accepted_near; its save keeps the stored ones, and one sent gets 403.
• A size or option out of range comes back as {"dieline": {"L": ["..."]}}.
• Parts come back with dieline, dieline_info (the blank's size and area, MSF per 1,000, outline, grain and line lengths, in inches) and downloads (one URL per file format).
• Update. A box keeps the geometry it was quoted with. To redraw it with the current box generator and its material's current caliper and allowances, send its dieline without caliper_mm and allowances.

A box from a CAD dieline#

Send die_design (the id of a folding carton or corrugated single-up dieline in Tools & dies, active and your team's) instead of a dieline. The box takes its blank, rule lengths and family from it and never redraws it; its board still follows the material. dieline comes back null, dieline_info.style.id is imported, and the part adds die_design and die_design_summary (id, name, family, format, facts, file_version).

{"name": "Tuck box", "shape": "dieline", "die_design": 12, "material_sku": "SBS-18-2840", "route": "offset",
 "quantity": 10000}

• Another team's, an archived or an unknown dieline, or one whose family is not folding carton or corrugated, gets 400 {"die_design": ["..."]}; a stock of the other family gets 400 on material. A dieline archived after the part took it stays on the part.
• The single-up's facts give what the file can't: gluer (none, straight_line, crash_lock, four_corner, six_corner), glue_points, grain_axis. On a way of making that folds and glues (convert die, ffg or litho_lam) a box with no gluer class is blocked with imported_facts_missing; on the others it prices with the notice imported_gluer_unknown. The part's blank is rebuilt from the single-up's current facts the next time the part is saved.
• downloads has pdf, dxf, cf2 (drawn from the stored single-up; no template, no fold check) and original (a redirect to the die file it was read from, when there is one).
• Designer links never get die_design or die_design_summary, and customers can't pick one.

format is pdf (the dieline for the die maker or cutting table), template (for your designer), dxf, cf2 or svg; pdf when left out. A CAD dieline box takes pdf, dxf, cf2 or original (302 to the original file). It answers like the dieline export: the die files wait for the fold check (409 foldcheck_failed, 503 while it runs), the template and the SVG never do. A flat part, a box with no size yet, or a box that can't be drawn (its stock has no caliper, or its blank is too large; its downloads is null) gets 404.

curl -sS -H "$AUTH" -OJ "$HOST/a/acme/estimating/api/v1/estimates/42/parts/$PART/dieline/?format=cf2"

Filter with source, route or external_id.

PATCH changes only the fields you send.

One call creates, updates and deletes up to 500 parts, all or nothing: {"create": [...], "update": [{"id": "...", "quantity": 250}], "delete": ["..."]}. Errors come back by section, even for one operation: {"create": {"0": {...}}, "update": {"<id>": {...}}, "delete": {"<id>": [...]}}.

Concurrency. Every write bumps the estimate's revision and answers with ETag: "<revision>". Send If-Match: "<revision>" (or base_revision in the body) to get 409 with the current revision when someone changed the estimate since you read it.

The quote#

The quote has lines (one per part), groups (the parts sharing a route and a material) and the totals: price, cost, margin, rounding, minimum, pieces and pending_groups, plus valid_until and currency. On a line, total_price and total_cost are the all-in figures (material, printing, cutting, press, finishing and hand prices); cost and price keep their earlier meaning, the material alone. Groups priced on sheets or offset are worked out on the server: by default this call prices the ones without a fresh price first, within budget seconds (10, at most 20); any left have pending: true and no price yet. refresh=0 answers at once.

Products and finishing#

Products are saved parts with defaults (size, quantity, route, stock, inks and finishing), picked when adding a line. A starter set (postcard, flyer, business card, posters, banner, sticker, rigid sign, custom item, design fee) is created the first time the team's products are read; it carries no prices. DELETE archives a product.

Send defaults with any of the part fields above in inches (width_in, height_in, corner_radius_in, bleed_in) plus size_presets, or part (a part id) to save a part's current fields. A material or finishing operation that isn't in the library is left off with a warnings entry.

Finishing operations are priced per piece, per 1,000, per sheet, per ft² or m², per linear ft or m of perimeter, each (grommets every so many inches) or per job, with a setup and a minimum. routes limits them to some routes (empty: every route); per-sheet pricing needs sheet or offset. DELETE archives an operation.

Stocks are materials: materials/ also takes runs_on (any, digital, offset), weight_label, weight_gsm, caliper_in, finish, grain, paper_key (the same paper in other sheet sizes), preset_key and board_id (a board of the shared board catalogue, for folding carton and corrugated board). The pricing units follow the material: per sheet and per 1,000 sheets need a sheet size, per 1,000 ft² is for corrugated board and per 1,000 in² for label stock; anything else is 400 on pricing_unit.

Set up a product family#

A team with no presses, machines or rate cards can quote a box at once with a hand price; to price it, one call creates what the family prices with. Nothing is ever created with prices you didn't send.

family is carton (the Tuck box: offset press, die-cutter, folder-gluer, board, die rate card, coating) or corrugated (the Shipping box: flexo folder-gluer, corrugated grade, plate rate card, bundling). Every section is optional and takes any field of its row:

{"estimate": 42,
 "press": {"hourly_rate": "250", "plate_cost": "18", "speed_sph": 10000, "makeready_min_per_pass": 15},
 "machines": {"die_cutter": {"hourly_rate": "160", "speed": 5000, "setup_min": 45},
              "folder_gluer": {"hourly_rate": "120", "speed": 150, "speed_unit": "m_per_min", "setup_min": 30}},
 "stock": {"price_per_unit": "0.60"},
 "tool_rates": {"steel_rule_die": {"base_cost": "250", "cut_cost_per_in": "0.35", "crease_cost_per_in": "0.30"}},
 "finishing": {"finish.aqueous_coating": {"price_per_unit": "0.02"}}}

A row that exists is only filled where it is empty (no value, 0, or a missing key of its settings), so the call can be repeated and never overwrites a rate you set. The answer lists the ids of the rows it made (created), the fields it filled (filled) and every row it touched (rows), and with estimate that estimate's readiness list after the set-up. A refused value is 400 with the errors by section ({"machines": {"die_cutter": {"speed": ["..."]}}}) and nothing is written. Set the new stock on your lines with the parts API. Booklets and labels come in a later release (404 until then).

Poll for the result#

When your customer clicks Finish in the designer, their work is saved, the link's submitted_at and the estimate's designer_submitted_at are set, and the browser goes to return_url (or shows a thank-you message). They can keep editing afterwards; a second Finish updates the times.

# By your own id
curl -sS -G "$HOST/a/acme/estimating/api/v1/estimates/" -H "$AUTH" --data-urlencode "external_id=order-1001"
# Everything changed since your last poll
curl -sS -G "$HOST/a/acme/estimating/api/v1/estimates/" -H "$AUTH" --data-urlencode "updated_since=2026-09-25T00:00:00Z"

The list is paged. Poll every 30 to 60 seconds; updated_at also changes on every save while someone is drawing, so wait for designer_submitted_at.

The data export#

One JSON document with everything generated for the estimate. schema_version is 1: fields may be added, and a rename or removal would bump the version. URLs are absolute. Lengths are in inches and areas in square inches; page coordinates are PDF points (or pixels for images) from the top-left corner; money is in US dollars.

Changes. Parts sized by hand and price-only items have no graphic: their document, page and points_page are null, a sized part's outline_in is its outline in inches and an item's is null, and kind can be item. If your code reads parts[].document without checking for null, handle it or pass ?sources=drawn (a comma list of drawn, manual, item). The quote always covers every part, so filtered parts may not add up to its total. Quote lines gained the all-in total_price and total_cost; their cost and price are still the material alone.

Nests and cut files#

Groups are named by route and material: roll-7, sheet-34, offset-34. A bare material id (7) still means its roll group. Each roll group of an estimate is nested on its roll, and the quote uses the nested length. Nests run automatically while someone draws. When a group's fresh is false, run one yourself:

With {"optimize": true} it searches for 10 seconds and keeps the current nest unless it finds a shorter one; improved says which. Send revision to get 409 when the drawing changed since you read it.

format is pdf, dxf or cff2; without it you get the cutting machine's own format. pages=beds gives one PDF page per cutter bed. A group whose nest is missing or out of date, or whose material isn't cut, gets 400. Layouts longer than 200 inches carry an X-Cut-File-Warning header.

A planned part (a carton on offset or die-cut, a corrugated box converted on blank, a litho-laminated box) is priced alone in group part-<uuid>. Its summary has key, route, family, material, fresh, status, blocked, notices, needs_rates, plan (ups, sheets, MSF …; for a die-cut box also the die, below), sheet (the cost sheet: material, machine steps, finishing, tooling and outside lines with their cost and price), alternates, compare (the other way of making it, filled by extras/) and equipment. nest/ plans it ({"force": true} plans again); GET quote/ plans the ones without a fresh plan within its budget. PATCH takes equipment ({role: machine id}, null for the kind's default), press, the sheet size, spoilage_pct, makeready_sheets, setup_sheets and plan_overrides (ups; null clears a value). A blocked summary has fix_url, the page where it is fixed. cutfile/ answers 400: a box's die line is its dieline download. save-tool/ adds the die the box's plan prices to the tool library as ordered, with the stations of the plan's nest when its ups come from the nest (see below). Sheet, offset and roll summaries carry finishing_timed ({part id: [{id, machine, units_in, time_s, cost, price, needs_rates}]}) for finishing timed on a machine.

curl -sS -H "$AUTH" -OJ "$HOST/a/acme/estimating/api/v1/estimates/42/production/roll-7/cutfile/?format=dxf"

A die-cut or litho-laminated box's plan names its die: die_type (the dies matched: rotary_die on a rotary die-cutter, else steel_rule_die), die_policy (the one in effect), die_options and die_vs. Each of die_options has key (tool:<id> or new:<ups>), kind (standing or new), tool, tool_number, ups, sheet_in, tier (exact, near or structural; empty for a new die), dist_mm, reasons (why a die isn't used by itself: sheet_differs, not_mountable, not_on_hand, customer_die …), usable, late, ready_on (a new die ordered today, from the rate card's lead time; a die at the die maker, its expected date), customer_owned, and the money at the part's quantity: die_cost / die_price (a die on hand: 0 plus its missing companions, re-rule and wear), line_cost / line_price (everything but the die row), total_cost / total_price (all-in); money is null on a die made for another sheet size when the board doesn't come in that size or the press or die-cutter can't take it, and on a die of more than one up on a made-to-size board (listed, never used). Exactly one option has chosen: true unless the box is blocked (die_sheet_stock: the picked die's sheet size isn't a size of the board, or the press or die-cutter can't take it). die_vs is the cheapest other option that could be used, as key, kind, ups, tool_number and delta_cost / delta_price (its all-in minus the chosen one's), or null. On a die on hand the plan's ups_basis is tool and notices has tool_reused, with die_cheaper_at when a new die would be cheaper all-in at the quantity or an alternate and die_life_exceeded when the quantity or an alternate passes the die's life. A die on hand whose extras need a rate card the team doesn't have (a missing companion, a re-rule) adds tool_rate to needs_rates. Each of alternates includes the die's extras at its own quantity (a re-rule or wear the main quantity doesn't need). Designer links never get plan.

Box dielines#

The box and carton generator has its own endpoints under /a/<team_slug>/dielines/api/v1/. Every call that makes a dieline takes a definition: the style, the three sizes and, optionally, the board and the style's options.

{"definition": {"style": "rte", "L": 2.5, "W": 1.5, "D": 6, "unit": "in", "basis": "inside",
                "board_id": "board.sbs_c1s_18pt", "params": {"tuck_len": 15}}}

GET styles/ lists the styles with their options, ranges and defaults, and GET boards/ lists the boards with your team's board materials (a board material with no catalogue board has board_id null). Option lengths are always millimetres, whatever unit says. A definition may carry allowances: carton_k (0.5 to 2) for carton boards; a_l_mm, a_w_mm and a_d_mm (all three, 0 to 50) and joint_mode for corrugated. Keys left out are the board's.

A definition with errors gets 400 with {"issues": [...]}: each issue has a code, a severity, the field it is about (L, board_id, params.tuck_len, allowances.carton_k…) and a readable message (every code is listed under Size and option messages). Warnings and notes come back with a successful preview and never block it.

The fold check folds the box in 3D and looks for clashes. Most sizes answer at once; a slow one answers 202 with {"status": "running", "hash"}, and you poll check/<hash>/ until the report arrives. Results are kept per size, so the same definition is checked once.

format is pdf (the dieline for the die maker or cutting table), template (the same lines plus bleed, glue areas and labels, for your designer), dxf, cf2 or svg. The PDF, DXF and CF2 wait for the fold check: a size that fails it gets 409 with {"code": "foldcheck_failed", "report"}, and 503 means the check is still running. The template and the SVG are always available. The same definition always gives the same bytes.

curl -sS -H "$AUTH" -H "Content-Type: application/json" -OJ \
  -d '{"definition": {"style": "fefco_0201", "L": 12, "W": 10, "D": 8, "unit": "in"}, "format": "cf2"}' \
  "$HOST/a/acme/dielines/api/v1/export/"

Saving stores the dieline PDF in Files with its style, size, board and generator. Send target_file to save a new version of a file you saved before.

A single-up from Tools & dies#

An imported single-up dieline (a shape from a die file you imported into Tools & dies) opens in the Box designer read-only. Send {"design": <id>} in place of a definition:

• open/ returns the read-only payload: the design, its drawing, the export formats and a link to the original file.
• structure/ folds it in 3D with its saved fold.
• export/ takes {"design": <id>, "format": "pdf" | "dxf" | "cf2" | "svg"} and returns the stored geometry as it was imported: nothing is regenerated, and there is no artwork template.
• save/ takes {"design": <id>, "fold": {"angles": {"<crease id>": 90}, "root_panel": "<panel id>"}} and returns {structure, scene}. "fold": null goes back to the default fold.

A fold that names creases the dieline doesn't have gets 400 with {"code": "invalid_fold"}, and a single-up with no panels to fold gets 409 with {"code": "no_structure"}.

Previews allow 600 requests a minute per user; checks, structures, downloads and saves 60.

Errors and limits#

Every estimating endpoint#

Materials (the price list the designer offers) are managed with the materials/ endpoints; deleting one archives it. The takeoff, snap-point and thumbnail endpoints serve the Takeoff workspace itself.

The takeoff sync. PUT takeoff/ replaces the whole drawing: {base_revision, scales, shapes, parts_scope}. With "parts_scope": "all" any part missing from shapes is deleted. Without it, as older integrations call it, only missing drawn parts and dimension lines are deleted: parts sized by hand and price-only items are kept. On a part that already exists, a quoting field you leave out (route, inks, finishing, other quantities, bleed, product, hand prices, shape and size) keeps its value, and null resets it.