Blog

Every webshop, product configurator and quoting tool needs the same thing before it can show a price: the size of the packaging. The Dieline Dimensions API answers exactly that question. Send it a template and a set of variables — length, width, height, material thickness and your unit — and it returns the flat outside dimensions of the unfolded blank in milliseconds. No file is drawn or exported; you get only the sizes, ready to drop into your pricing logic. This post walks through your first request, the response you get back, the same call in Ruby, PHP and JavaScript, multi-part dielines, discovery, errors and how credits work.

The examples below use curl, which is a command you run in a terminal (Terminal on macOS or Linux, Command Prompt or PowerShell on Windows). curl is built into all modern versions of these operating systems. If you prefer a graphical client, paste the same URL, headers, and body into Postman or Insomnia. Both are free and friendlier for first-time API testing.

The Dieline Dimensions API gives you the flat outside dimensions of a packaging dieline — boxes, trays, bags, envelopes, separators, folders — as a list of parts, for any set of variables you send. Each part's size is the true assembled footprint: the exact measurement it takes to lay out and print one copy, computed from the real production template rather than estimated. It is built for the pricing and quoting step, so your customer sees an accurate price the moment they change a dimension.

Already using the Dielines API? These are two separate products. The Dielines API generates and exports actual dieline files and 3D mockups; the Dieline Dimensions API only computes sizes and produces no file. They use different keys and a different version header, and each is billed separately. If all you need is the size to calculate a price, this is the lighter, cheaper endpoint.

Every request is a single authenticated HTTPS call. You need three things:

• An API key. Generate one on the Dieline Dimensions API keys page after subscribing to a Dimensions credit pack. Dimensions keys start with dim_ and are distinct from Dielines API keys — one never authenticates the other.
• The base URL. Production is https://api.diecuttemplates.com; the sandbox at https://sandbox.api.diecuttemplates.com shares the same request shape, authentication and errors, and never consumes credits — so you can wire up and test your integration before you go live. One difference to know: on the sandbox only the free demo template (becf-11101) is sized from the dimensions you send; every other template returns its own default size, so validate real pricing numbers against production.
• Two headers on every request: Authorization: Bearer YOUR_API_KEY and Dimensions-Api-Version: 1.0.

You can try the whole thing without spending anything: the demo template becf-11101 accepts custom dimensions and is free on both the sandbox and the production API — no credit is consumed either way. Swap any template id in the examples below for becf-11101 to run them for free.

Send a POST to /dimensions/{template_id}/parts with your variables in the body. The example below sizes a tuck end box (becf-11a02) that is 200 × 100 × 40 mm on 0.5 mm board:

curl -X POST \
  https://api.diecuttemplates.com/dimensions/becf-11a02/parts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Dimensions-Api-Version: 1.0" \
  -d '{
    "variables": {
      "unit": "mm",
      "material": 0.5,
      "length": 200,
      "width": 100,
      "height": 40
    }
  }'

The response is a part_list — always an array of parts, each with its own bounding_box:

{
  "part_list": {
    "type": "part_list",
    "id": "dm_9f2a1c7b4e10",
    "dieline_template_id": "becf-11a02",
    "total": 1,
    "parts": [
      {
        "type": "part",
        "id": "default",
        "name": "default",
        "category": "carton",
        "bounding_box": { "unit": "mm", "width": 280.0, "height": 180.0 }
      }
    ]
  }
}

The part you care about is the bounding_box: this box folds up from a flat blank 280.0 mm wide by 180.0 mm tall in the unit you requested. That footprint is everything your quoting logic needs to work out material usage, imposition and a printing price. A simple dieline returns a single part named default; the category tells you the material family (for example carton or corrugated_cardboard).

Want to run this without spending a credit? Replace becf-11a02 with the free demo template becf-11101 and the same call works on the sandbox or production at no cost.

Pass "area": true alongside variables and each part also carries its flat material area — the true area of the cut shape, not width × height:

curl -X POST \
  https://api.diecuttemplates.com/dimensions/becf-11a02/parts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Dimensions-Api-Version: 1.0" \
  -d '{
    "variables": { "unit": "mm", "material": 0.5, "length": 200, "width": 100, "height": 40 },
    "area": true
  }'

{
  "type": "part",
  "id": "default",
  "name": "default",
  "category": "carton",
  "bounding_box": { "unit": "mm", "width": 280.0, "height": 180.0 },
  "area": { "value": 48847.29, "unit": "mm2" }
}

The area is returned in square units (mm2 or in2) and is available for every dieline except those in the Hard cardboards group, where it is simply omitted.

Set unit to "mm" or "in". The response echoes the unit you asked for on every bounding_box, so the numbers come back ready to display or feed straight into your pricing formula — no conversion on your side.

It is a plain REST call, so anything that speaks HTTP works — no client library required. Here is the same size request in three common stacks.

require 'uri'
require 'net/http'
require 'json'

uri  = URI('https://api.diecuttemplates.com/dimensions/becf-11a02/parts')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Content-Type']         = 'application/json'
request['Authorization']        = 'Bearer YOUR_API_KEY'
request['Dimensions-Api-Version'] = '1.0'
request.body = {
  variables: { unit: 'mm', material: 0.5, length: 200, width: 100, height: 40 },
  area: true
}.to_json

response = http.request(request)
part = JSON.parse(response.body).dig('part_list', 'parts', 0)
puts part['bounding_box'] # => {"unit"=>"mm", "width"=>280.0, "height"=>180.0}

$ch = curl_init('https://api.diecuttemplates.com/dimensions/becf-11a02/parts');

curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST           => true,
  CURLOPT_HTTPHEADER     => [
    'Content-Type: application/json',
    'Authorization: Bearer YOUR_API_KEY',
    'Dimensions-Api-Version: 1.0',
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'variables' => ['unit' => 'mm', 'material' => 0.5, 'length' => 200, 'width' => 100, 'height' => 40],
    'area'      => true,
  ]),
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

print_r($response['part_list']['parts'][0]['bounding_box']);

const res = await fetch('https://api.diecuttemplates.com/dimensions/becf-11a02/parts', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY',
    'Dimensions-Api-Version': '1.0',
  },
  body: JSON.stringify({
    variables: { unit: 'mm', material: 0.5, length: 200, width: 100, height: 40 },
    area: true,
  }),
});

const { part_list } = await res.json();
console.log(part_list.parts[0].bounding_box); // { unit: 'mm', width: 280, height: 180 }

Some dielines are made of several physical parts — say an inner tray and a sleeve cover. Those come back with the dimensions of each part on its own: nothing is flattened together and nothing is guessed. total tells you how many parts there are, and each entry has its own name, category and bounding_box:

{
  "part_list": {
    "type": "part_list",
    "dieline_template_id": "tray-and-sleeve-example",
    "total": 2,
    "parts": [
      {
        "type": "part",
        "name": "tray",
        "category": "carton",
        "bounding_box": { "unit": "mm", "width": 320.0, "height": 210.0 }
      },
      {
        "type": "part",
        "name": "sleeve",
        "category": "cover",
        "bounding_box": { "unit": "mm", "width": 540.0, "height": 180.0 }
      }
    ]
  }
}

Iterate over parts and price each one; the two entries above might sit on different substrates, so you can cost the tray and the sleeve separately and add them up. Because each part is measured for a single copy, multiplying by quantity and adding your imposition logic is straightforward.

To size a dieline you need its template id and the variables it accepts. Two discovery endpoints let you browse the shared catalog. First, list the groups:

curl -X GET \
  https://api.diecuttemplates.com/dimensions/template-groups \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Dimensions-Api-Version: 1.0"

Then fetch a single template to see exactly which variables to send. The unit is an optional query parameter (defaulting to mm):

curl -X GET \
  "https://api.diecuttemplates.com/dimensions/becf-11a02?unit=mm" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Dimensions-Api-Version: 1.0"

The response includes a variables array describing each input — its name, data type, whether it is required, and a default value. Anything marked required: true must be present in your POST body; the rest fall back to their defaults.

"variables": [
  { "name": "length",   "data_type": "length",  "required": true },
  { "name": "width",    "data_type": "length",  "required": true },
  { "name": "height",   "data_type": "length",  "required": true },
  { "name": "material", "data_type": "length",   "required": true }
]

Discovery requests share the same catalog as the Dielines API, so if you have already browsed templates there the ids line up.

Once the footprint is in hand, pricing is your own arithmetic. A minimal example: turn the flat blank into a material cost, add a setup fee, and you have a live quote.

const { width, height } = part_list.parts[0].bounding_box; // 280.0 x 180.0 mm
const blankArea = width * height;                          // flat footprint in mm2
const price = blankArea * PRICE_PER_MM2 + SETUP_FEE;       // your pricing rule

Because the API answers in milliseconds, you can call it on every change a customer makes to a dimension and re-price instantly — no spreadsheets, no manual measuring, no waiting.

Error responses use standard HTTP status codes with a message and, where relevant, an errors array. The most common ones:

• 400 — the variables object is missing, or a variable is invalid (a bad unit, a missing required variable). The body names what went wrong.
• 401 — missing or invalid API key: { "message": "Unauthorized" }.
• 403 — no Dimensions credits left: { "message": "Forbidden. Available Dieline Dimensions API credits count = 0", "errors": [] }.
• 404 — unknown template id.
• 429 — more than one request per second. The API is throttled to one call per second per account (a limit shared with the Dielines API); pace your requests and retry.

A validation error looks like this — worth handling explicitly so you can surface the message to whoever is configuring the dieline:

{
  "message": "Validation failed for one or more variables.",
  "errors": [
    { "message": "Invalid 'unit'. Valid 'unit' values are 'mm' and 'in'." }
  ]
}

Pricing is simple and predictable:

• The first time you ask for a particular size, it costs 1 credit.
• Ask for the same size again within seven days and the stored result comes straight back at no charge — so re-quoting, recalculating and refreshing a cart never costs anything extra.
• A different size is another credit.

On top of that, the sandbox is always free and the demo template becf-11101 never consumes credits on either environment, so you can build and verify your whole integration before subscribing.

Sizing a dieline for pricing is a single request:

1. GET /dimensions/template-groups and GET /dimensions/{id}?unit={mm|in} — browse the catalog and learn which variables a template accepts (optional, once per template).
2. POST /dimensions/{id}/parts — send the variables, get back the part_list with a bounding_box per part. Add "area": true for the flat material area.

Feed the footprint into your pricing logic and you have an accurate, instant quote on every change. Full reference documentation lives at Dieline Dimensions API — Getting Started, and pricing is at Dieline Dimensions API pricing.

If you hit anything unexpected while testing in the Sandbox, send us the request you are making and the response you are getting and we will take a look.