Formula imports

Import reviewed production formulas with ingredients, outputs, substitute products, and process steps, then keep a separate result for each formula.

Access and preparation

Use POST /formulas/batch with formulas:write and the acting person's current Work Order update permission. The organization's Work Orders must be enabled for that person. GET /me reports scope and permission availability; the import request also checks Work Order availability.

Prepare the products in ShelfCycle first. Formula lines use exact product codes, matched case-insensitively within the organization. The first code on each line is the preferred product; later codes are substitutes in priority order.

Preview an import

Send 1 to 50 items, each with a unique, stable clientItemId and a payload. Preview with dryRun=true to receive ordered ready or failed results without saving formulas. A preview does not require an Idempotency-Key.

Replace the example product codes with existing active products appropriate to your formula.

curl "$SHELFCYCLE_API_BASE_URL/formulas/batch?dryRun=true" \
  -X POST \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "clientItemId": "formula-001",
        "payload": {
          "name": "Northstar cleaning blend",
          "description": "Reviewed standard blend",
          "ingredients": [
            { "label": "Base", "quantity": "80", "unit": "kg", "productCodes": ["BASE-A", "BASE-B"] },
            { "label": "Additive", "quantity": "20", "unit": "kg", "productCodes": ["ADDITIVE-A"] }
          ],
          "outputs": [
            { "label": "Finished blend", "quantity": "100", "unit": "kg", "productCodes": ["BLEND-A"], "kind": "PRODUCT" }
          ],
          "processSteps": [
            { "name": "Blend", "attrs": [{ "key": "Instruction", "value": "Mix until uniform." }] }
          ]
        }
      }
    ]
  }'

Describe the formula

Each payload requires name, ingredients, and outputs. Optional fields are description, autotag, and processSteps.

• Every ingredient or output has label, quantity, unit, and at least one productCodes value.
• Units are g, kg, lb, ml, L, gal, or each. Quantities must satisfy the formula's normal save rules.
• Ingredients can set isPackage; outputs can set kind to PRODUCT or WASTE.
• Process steps have a name and attrs, with each attribute expressed as key and value.

Each formula can contain up to 100 product-code entries across ingredients and outputs, counting repeats. The name after trimming and the optional description each support up to 2400 UTF-8 bytes; count bytes rather than characters for non-ASCII text. Keep the complete request at or below 2 MB.

Save and retain results

After reviewing the preview, submit the same body without dryRun=true and add a stable Idempotency-Key, such as formula-library:approved-import-001. Execution returns data.results in input order with clientItemId, mode: "createFormula", and status: "succeeded" or "failed". A saved item includes data.id, name, number, and resultAction: "created"; data.counts summarizes the results.

A failed formula does not undo successful formulas. Its failures and error explain what to correct, including unknown or archived products, unsuitable quantities or units, an existing formula name, or oversized content. Missing or repeated item IDs, missing names, or duplicate trimmed names within a request are request-level errors, so correct those before submission.

This endpoint saves reusable formulas. It does not start a work order or receive, consume, or produce inventory.

Resume safely

If a request is interrupted, repeat the identical body, item order, clientItemId values, and Idempotency-Key. Recorded outcomes are returned and only pending items continue. A completed retry reports idempotencyStatus: "replayed". Correcting a failed formula is a new intended request and uses a new stable key; omit already successful formulas from that corrected request.

X-RateLimit-Cost reports the submitted item count. Divide larger approved libraries into requests of at most 50 formulas and keep each request's identity and results together.