DIdistru
Batch

Create or update a batch

Changed on

Create or update a single batch. Omit id to create a new batch; pass the id of an existing batch to update it. Either way the whole operation is atomic — if any field is rejected, nothing is written and the batch is left unchanged.

A batch is Distru's lot for a batch-tracked product: it is the unit that inventory quantity, cost, test results, and (optionally) bins hang off of. You can only create a batch under a product whose inventory-tracking method is batch-tracked; pointing product_id at any other product is rejected. Products that track inventory as compliance packages are managed through their package endpoints, not here.

On create, the batch's inventory records are initialized so quantity and cost can begin accumulating against it (a brand-new batch starts with no on-hand quantity — receive a purchase, run an assembly, or adjust stock to add inventory). The write is recorded to the batch's activity history. This endpoint does not push to or pull from any state traceability system (Metrc / BioTrack); a 200 reflects the Distru batch record only.

Update is a targeted patch, not a full replace: only the fields you send are changed, and any field you omit keeps its current value. product_id is fixed after creation — a batch cannot be moved to a different product. See each field below for its create-time default and its null-vs-omit behavior (notably bin_ids).

Required permission: products_permissions_create to create, products_permissions_edit to update.

post/public/v1/batches

Request

  • Base URL
    https://app.distru.com
  • Auth
    HTTP bearer

Request body

idstring

The Distru batch ID to update. Omit to create a new batch. When present, it must reference a batch in your company or the request is rejected.

product_idstring

The Distru product ID this batch belongs to. Required on create, and the product must be a batch-tracked product in your company (pointing at a product tracked any other way is rejected). Immutable once the batch exists — on update, omit it or resend the batch's current product; sending a different product id is rejected rather than silently ignored, and a batch can never be moved to another product.

batch_numberstring

The user-facing lot / batch number label (e.g. LOT-1241291). This is where your own batch identifier belongs. Free-form and not required to be unique. Nullable; leave omitted or null if the batch has no external lot number.

thcstring

A free-form THC label for the batch, as displayed in Distru (e.g. "18.5%"). This is a static value stored on the batch record; it does not set or derive from any lab result — the batch's primary test result tracks potency separately.

cbdstring

A free-form CBD label for the batch, as displayed in Distru (e.g. "0.3%"). This is a static value stored on the batch record; it does not set or derive from any lab result — the batch's primary test result tracks potency separately.

expiration_datetimestring

When the batch expires, as an ISO 8601 datetime (e.g. 2026-01-31T00:00:00Z). Nullable; omit or send null if the batch has no expiration.

harvest_datetimestring

When the batch's material was harvested, as an ISO 8601 datetime (e.g. 2025-09-15T00:00:00Z). Nullable and optional; surfaced in the response as harvest_datetime.

manufactured_datetimestring

When the batch was manufactured, as an ISO 8601 datetime (e.g. 2025-09-20T00:00:00Z). If omitted on create, defaults to the time the batch is created. Surfaced in the response as manufactured_datetime.

owner_idstring

The Distru user ID of the batch's designated owner. Must be an active user in your company that the authenticated user is allowed to assign to, otherwise the request is rejected. Nullable; omit or send null for no owner.

descriptionstring

Free-form notes about the batch. Nullable and optional.

custom_dataobject

A map of custom field IDs to their values. Use GET /public/v1/custom-fields?parent_object=batch to retrieve available custom fields, their IDs, and their types. The value format depends on the field's type: a text field takes a string, a date field takes a full ISO8601 datetime, and a checkbox field takes an array of its selected options.

bin_idsstring[]

The IDs of the bins this batch is stored in. Behaviour: omit bin_ids to leave the batch's bins unchanged; pass null or an empty array to clear all bins; pass a non-empty array to replace the batch's bins with exactly those. Ignored unless bin inventory tracking is enabled for your company.

Response

A single batch

Example response

{
  "data": {
    "product": {
      "batches_with_active_quantity_by_location": [
        {
          "location": {
            "address": "1234 Warehouse Street, Oakland, CA",
            "company_id": "02c88a3f-d759-4973-88f9-60049d682524",
            "id": "02c88a3f-d759-4973-88f9-60049d682524",
            "license_id": "02c88a3f-d759-4973-88f9-60049d682524",
            "name": "Warehouse 1"
          }
        }
      ],
      "brand": {
        "id": "3f128a34-cc59-4b49-8883-23bf10e59c6c",
        "name": "Retailer 1"
      },
      "packages_with_active_quantity_by_location": [
        {
          "location": {
            "address": "1234 Warehouse Street, Oakland, CA",
            "company_id": "02c88a3f-d759-4973-88f9-60049d682524",
            "id": "02c88a3f-d759-4973-88f9-60049d682524",
            "license_id": "02c88a3f-d759-4973-88f9-60049d682524",
            "name": "Warehouse 1"
          }
        }
      ],
      "quantity_active_by_location": [
        {
          "location": {
            "address": "1234 Warehouse Street, Oakland, CA",
            "company_id": "02c88a3f-d759-4973-88f9-60049d682524",
            "id": "02c88a3f-d759-4973-88f9-60049d682524",
            "license_id": "02c88a3f-d759-4973-88f9-60049d682524",
            "name": "Warehouse 1"
          }
        }
      ],
      "vendor": {
        "id": "3f128a34-cc59-4b49-8883-23bf10e59c6c",
        "name": "Retailer 1"
      }
    },
    "quantity_active_by_location": [
      {
        "location": {
          "address": "1234 Warehouse Street, Oakland, CA",
          "company_id": "02c88a3f-d759-4973-88f9-60049d682524",
          "id": "02c88a3f-d759-4973-88f9-60049d682524",
          "license_id": "02c88a3f-d759-4973-88f9-60049d682524",
          "name": "Warehouse 1"
        }
      }
    ]
  }
}

Changes

  • e8b3a3d07ad5Revision changes
    • info

      added the required property // to the response with the status

    • info

      added the required property /// to the response with the status

    • info

      added the required property /// to the response with the status

  • 421cc4d0838bRevision changes
    • warning

      removed the request property