Documentation

Carton Pack Pro

One cartonization solver, reachable four ways, with one stored history behind all of them.

ConceptsThe domain model, drawn.SolverObjectives, search, determinism, speed.CSV importColumn reference and validation rules.REST APIEvery endpoint, with a verified example.MCP serverTools for an AI assistant.ERP integrationOrders in, plans out, a link back.NetSuiteSuiteScripts for the Sales Order.

Surfaces

A pack job created through any door is the same record, metered once.

Quickstart

1Create an organization at /signup; pick imperial or metric.
2Load cartons and SKUs under /import.
3Create a key with the write scope under /api-keys.
4Set CPP_URL and CPP_KEY, then run this.

Request

curl -X POST "$CPP_URL/api/v1/pack" \
  -H "Authorization: Bearer $CPP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "SO-10422",
    "objective": "MIN_CARTONS",
    "lines": [
      { "sku": "KTC-SKLT-12",  "quantity": 2 },
      { "sku": "GLS-TMBL-4PK", "quantity": 1 }
    ]
  }'

Response, abridged

200 OK

{
  "data": {
    "jobId": "clw3k1n2t0004v8hq7x1s9abc",
    "reference": "PJ-4F2A9C",
    "externalId": "SO-10422",
    "unknownSkus": [],
    "result": {
      "success": true,
      "objective": "MIN_CARTONS",
      "unitSystem": "IMPERIAL",
      "cartons": [ /* cartonSku, placements, weights, steps */ ],
      "unpacked": [],
      "summary": {
        "totalCartons": 1,
        "packedItems": 3,
        "averageUtilization": 0.7103,
        "computeMs": 37
      }
    }
  }
}

That call created a durable pack job: open it at /jobs/<jobId>, or find it again with GET /api/v1/jobs?externalId=SO-10422.

Conventions

Convention	Rule
Envelope	Success is `{ data, meta? }`, failure is `{ error }`, on every `/api/v1` route.
Units	Plain numbers in your own unit system. Nothing is converted; the response repeats the system so you can label it.
Axes	`length` on x, `height` on y (up), `width` on z. Positions are the item’s minimum corner.
Identifiers	SKUs are unique per organization. `externalId` is yours; `reference` (`PJ-…`) is ours.
Periods	Metering periods are `YYYY-MM` in UTC. Monthly allowances reset on the first.
Rate limits	Per key, per minute: 30 on Free, 300 on Pro. Over it is a 429 with Retry-After.
Determinism	The same request always yields the same plan. Only computeMs varies between runs.

Machine-readable

GET /api/v1/openapi.json   # OpenAPI 3.1, unauthenticated