Productions

Production runs, what they plan to consume and what they consumed, lot by lot.

manufacturing:readmanufacturing:writehttps://public-api.nutrasoft.ca/v1

Links toProductsproduct_id Production linesproduction_line_id Product lotsconsumed_steps[].lot_id Product lotsoutput.lot_id

The Production object

idinteger
consumed_stepsarray of objectsnullable
What the run consumed, lot by lot. On GET /productions/{production_id} only; null elsewhere.
ShowHide 3 fields of consumed_steps
- lot_idintegernullable
  Set on consumption only, not on a plan.
- product_idintegernullable
- quantity_basenumbernullable
  In the component product's base unit.
end_datestringnullable
- UTC timestamp
expiration_datestringnullable
- UTC timestamp
location_idintegernullable
Where the run's output goes. Planned until the run is COMPLETED, then the location it was closed into.
lot_numberstringnullable
The lot number of the run's output. Planned until the run is COMPLETED, then the one it was closed under, unless the lot number was cleared at close: output always names the exact lot.
outputobjectnullable
Where the finished product went: the lot and location chosen when the run was closed, and with cost:read, what it cost. Null until the run is COMPLETED. On GET /productions/{production_id} only; null elsewhere.
ShowHide 10 fields of output
- ingredient_costnumbernullable
  What the ingredients, packaging and other materials the run consumed cost, at the costs recorded on the run. Requires cost:read; null means redacted, not zero.
- location_codestringnullable
- location_idintegernullable
  Where the lot is now. Null when it has no location.
- location_namestringnullable
- lot_idinteger
  Fetch it with GET /product-lots/{lot_id}.
- lot_numberstringnullable
  Null when the run was closed without a lot number.
- operations_costnumbernullable
  What the run's operations, such as labour and overhead, cost. Requires cost:read; null means redacted, not zero.
- quantity_basenumbernullable
  What this run added to the lot, in the product's base unit. The lot holds more when the output joined an existing lot.
- total_costnumbernullable
  ingredient_cost plus operations_cost: the full cost of the run. Requires cost:read; null means redacted, not zero.
- unit_cost_basenumbernullable
  The unit cost, per base unit, that NutraSoft recorded on the output when the run was completed: the value the finished stock is carried at. A run completed now records total_cost less any by-product credit, divided by quantity_base, or the product's cost before the close when the run recorded no ingredient cost. Older runs carry the value recorded for them, which may not follow that rule, or null. Requires cost:read; null also means redacted.
planned_stepsarray of objectsnullable
What the run intends to consume. On GET /productions/{production_id} only; null elsewhere.
ShowHide 3 fields of planned_steps
- lot_idintegernullable
  Set on consumption only, not on a plan.
- product_idintegernullable
- quantity_basenumbernullable
  In the component product's base unit.
produced_qty_display_unitsnumbernullable
What was produced, in the product's display unit.
product_idintegernullable

Show 6 more attributes

production_line_idintegernullable
production_nointegernullable
The run number, unique within your account.
production_numberstringnullable
The number as printed on the document.
production_qty_display_unitsnumbernullable
The planned quantity, in the product's display unit. Step quantities are in base units.
start_datestringnullable
- UTC timestamp
statusstring
- one ofPLANNEDIN_PROGRESSIN_PROGRESS_TRANSFORMATIONCOMPLETEDCANCELLEDON_HOLDQUARANTINE

Operations

List production runs

get/productionsmanufacturing:read

planned_steps, consumed_steps and output are null here: retrieve a run for them.

Query parameters

statusarray of stringnullable
Repeat the parameter to match any of several statuses.
- one ofPLANNEDIN_PROGRESSIN_PROGRESS_TRANSFORMATIONCOMPLETEDCANCELLEDON_HOLDQUARANTINE
product_idintegernullable
- > 0
production_line_idintegernullable
- > 0
lot_numberstringnullable
searchstringnullable
Free-text match.
sortstringnullable
Comma-separated field:direction pairs, e.g. id:desc. Sortable: end_date, id, production_no, start_date, status. id is always added last, so paging is stable.
limitinteger
Rows to return. Maximum 200.
- >= 1
- <= 200
- default 50
offsetinteger
Rows to skip. Maximum 10000: to read further, narrow the filters or page with updated_since.
- >= 0
- <= 10000
- default 0

Returns

200 A page of Production objects in data, with pagination.

Errors

400 401 403 429 500 503

GET /productions

curl "https://public-api.nutrasoft.ca/v1/productions?limit=50" \
  -H "Authorization: Bearer $NUTRASOFT_API_KEY"

Response200

{
  "data": [
    {
      "id": 123,
      "consumed_steps": [
        {
          "lot_id": 123,
          "product_id": 123,
          "quantity_base": 12.5
        }
      ],
      "end_date": "2026-09-10T14:30:00Z",
      "expiration_date": "2026-09-10T14:30:00Z",
      "location_id": 123,
      "lot_number": "LOT-2026-0142",
      "output": {
        "ingredient_cost": 12.5,
        "location_code": "SAMPLE-01",
        "location_id": 123,
        "location_name": "Sample name",
        "lot_id": 123,
        "lot_number": "LOT-2026-0142",
        "operations_cost": 12.5,
        "quantity_base": 12.5,
        "total_cost": 12.5,
        "unit_cost_base": 12.5
      },
      "planned_steps": [
        {
          "lot_id": 123,
          "product_id": 123,
          "quantity_base": 12.5
        }
      ],
      "produced_qty_display_units": 12.5,
      "product_id": 123,
      "production_line_id": 123,
      "production_no": 10,
      "production_number": "string",
      "production_qty_display_units": 12.5,
      "start_date": "2026-09-10T14:30:00Z",
      "status": "PLANNED"
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 1,
    "has_more": false
  },
  "order": "id:asc"
}

Retrieve a production run

get/productions/{production_id}manufacturing:read

Includes planned_steps, what the run intends to consume, and consumed_steps, what it consumed lot by lot, both in base units. Once the run is COMPLETED, output names the lot and location the finished product went into and, with cost:read, its ingredient, operations and total cost and the unit cost it was valued at.

Path parameters

production_idintegerrequired
The run's id.
- > 0

Returns

200 One Production object in data.

Errors

400 401 403 404 429 500 503

GET /productions/{production_id}

curl "https://public-api.nutrasoft.ca/v1/productions/123" \
  -H "Authorization: Bearer $NUTRASOFT_API_KEY"

Response200

{
  "data": {
    "id": 123,
    "consumed_steps": [
      {
        "lot_id": 123,
        "product_id": 123,
        "quantity_base": 12.5
      }
    ],
    "end_date": "2026-09-10T14:30:00Z",
    "expiration_date": "2026-09-10T14:30:00Z",
    "location_id": 123,
    "lot_number": "LOT-2026-0142",
    "output": {
      "ingredient_cost": 12.5,
      "location_code": "SAMPLE-01",
      "location_id": 123,
      "location_name": "Sample name",
      "lot_id": 123,
      "lot_number": "LOT-2026-0142",
      "operations_cost": 12.5,
      "quantity_base": 12.5,
      "total_cost": 12.5,
      "unit_cost_base": 12.5
    },
    "planned_steps": [
      {
        "lot_id": 123,
        "product_id": 123,
        "quantity_base": 12.5
      }
    ],
    "produced_qty_display_units": 12.5,
    "product_id": 123,
    "production_line_id": 123,
    "production_no": 10,
    "production_number": "string",
    "production_qty_display_units": 12.5,
    "start_date": "2026-09-10T14:30:00Z",
    "status": "PLANNED"
  }
}

Change a production run's status

post/productions/{production_id}/statusmanufacturing:write· idempotent with Idempotency-Key

Moves a run between PLANNED, ON_HOLD, QUARANTINE and CANCELLED. Starting and completing a run happen on the production floor, so IN_PROGRESS, IN_PROGRESS_TRANSFORMATION and COMPLETED are refused with 409, as are runs already COMPLETED or CANCELLED and signed, locked records. The response carries no steps.

Path parameters

production_idintegerrequired
The run's id.
- > 0

Headers

Idempotency-Keystring
Your own unique string for this request, up to 200 characters. A retry with the same key returns the first response instead of running again.
- max 200 chars

Request body

statusstringrequired
PLANNED, ON_HOLD, QUARANTINE or CANCELLED. IN_PROGRESS, IN_PROGRESS_TRANSFORMATION and COMPLETED are refused with 409: starting and completing a run happen on the production floor.
- one ofPLANNEDIN_PROGRESSIN_PROGRESS_TRANSFORMATIONCOMPLETEDCANCELLEDON_HOLDQUARANTINE

Returns

200 One Production object in data.

Errors

400 401 403 404 409 429 500 503

POST /productions/{production_id}/status

curl -X POST "https://public-api.nutrasoft.ca/v1/productions/123/status" \
  -H "Authorization: Bearer $NUTRASOFT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f1c6a52-8d0e-4b7a-9c2f-5e8d1b4a7c90" \
  -d '{
  "status": "ON_HOLD"
}'

Response200

{
  "data": {
    "id": 123,
    "consumed_steps": [
      {
        "lot_id": 123,
        "product_id": 123,
        "quantity_base": 12.5
      }
    ],
    "end_date": "2026-09-10T14:30:00Z",
    "expiration_date": "2026-09-10T14:30:00Z",
    "location_id": 123,
    "lot_number": "LOT-2026-0142",
    "output": {
      "ingredient_cost": 12.5,
      "location_code": "SAMPLE-01",
      "location_id": 123,
      "location_name": "Sample name",
      "lot_id": 123,
      "lot_number": "LOT-2026-0142",
      "operations_cost": 12.5,
      "quantity_base": 12.5,
      "total_cost": 12.5,
      "unit_cost_base": 12.5
    },
    "planned_steps": [
      {
        "lot_id": 123,
        "product_id": 123,
        "quantity_base": 12.5
      }
    ],
    "produced_qty_display_units": 12.5,
    "product_id": 123,
    "production_line_id": 123,
    "production_no": 10,
    "production_number": "string",
    "production_qty_display_units": 12.5,
    "start_date": "2026-09-10T14:30:00Z",
    "status": "PLANNED"
  }
}