Batches

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Batches",
  "description": "Batches help you track inventory items by batch numbers, manufacturing dates, and expiration dates.",
  "definitions": {
    "gendoc-attributes-schema": {
      "$ref": "#/components/schemas/batch-response"
    },
    "batch_id": {
      "description": "Unique identifier of the batch.",
      "type": "string",
      "example": "6780203000001066694"
    },
    "batch_in_id": {
      "description": "Unique identifier of the inward batch entry created when stock was received.",
      "type": "string",
      "example": "6780203000001003281"
    },
    "item_id": {
      "description": "Unique identifier of the item the batch belongs to.",
      "type": "string",
      "example": "6780203000001003147"
    },
    "batch_number": {
      "description": "Batch number.",
      "type": "string",
      "example": "BTC-8900"
    },
    "internal_batch_number": {
      "description": "Internal batch number generated by the system.",
      "type": "string",
      "example": ""
    },
    "manufacturer_batch_number": {
      "description": "Manufacturer-provided batch number.",
      "type": "string",
      "example": "MFR-BTC-8900"
    },
    "external_batch_number": {
      "description": "External batch number from the manufacturer.",
      "type": "string",
      "example": "MFR-BTC-8900"
    },
    "manufactured_date": {
      "description": "Manufacturing date of the batch.",
      "type": "string",
      "example": "2026-05-12"
    },
    "manufacturer_date": {
      "description": "Manufacturing date of the batch. Legacy alias retained for backward compatibility; prefer <code>manufactured_date</code>.",
      "type": "string",
      "example": "2026-05-12"
    },
    "expiry_date": {
      "description": "Expiration date of the batch.",
      "type": "string",
      "example": "2026-10-15"
    },
    "in_quantity": {
      "description": "Quantity received into the batch when stock was added.",
      "type": "number",
      "format": "float",
      "example": 0
    },
    "balance_quantity": {
      "description": "Quantity currently available in the batch.",
      "type": "number",
      "format": "float",
      "example": 0
    },
    "balance_quantity_unit": {
      "description": "Unit of measurement for the balance quantity.",
      "type": "string",
      "example": ""
    },
    "location_id": {
      "description": "Unique identifier of the location associated with the batch.",
      "type": "string",
      "example": "6780203000000093215"
    },
    "associated_locations": {
      "description": "Locations where stock for this batch is available, with the inward and balance quantity at each location.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "location_id": {
            "$ref": "#/components/schemas/location_id"
          },
          "in_quantity": {
            "$ref": "#/components/schemas/in_quantity"
          },
          "balance_quantity": {
            "$ref": "#/components/schemas/balance_quantity"
          }
        }
      }
    },
    "status": {
      "description": "Status of the batch. Allowed values <code>active</code> and <code>inactive</code>.",
      "type": "string",
      "example": "active"
    },
    "sales_rate": {
      "description": "Sales rate of the batch.",
      "type": "number",
      "format": "float",
      "example": 50.4,
      "x-node_available_in": [
        "Batch Price enabled"
      ]
    },
    "label_rate": {
      "description": "Label rate of the batch.",
      "type": "number",
      "format": "float",
      "example": 50,
      "x-node_available_in": [
        "Batch Price enabled"
      ]
    },
    "custom_field_id": {
      "description": "Unique identifier of the custom field.",
      "type": "string",
      "example": "6780203000000176175"
    },
    "label": {
      "description": "Label of the custom field.",
      "type": "string",
      "example": "Lot Code"
    },
    "value": {
      "description": "Value of the custom field.",
      "type": "string",
      "example": "LC-001"
    },
    "batch_custom_fields": {
      "description": "Custom fields configured for the batch.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "custom_field_id": {
            "$ref": "#/components/schemas/custom_field_id"
          },
          "label": {
            "$ref": "#/components/schemas/label"
          },
          "value": {
            "$ref": "#/components/schemas/value"
          }
        }
      }
    },
    "batch-response": {
      "description": "Details of a batch.",
      "type": "object",
      "properties": {
        "batch_id": {
          "$ref": "#/components/schemas/batch_id"
        },
        "item_id": {
          "$ref": "#/components/schemas/item_id"
        },
        "batch_number": {
          "$ref": "#/components/schemas/batch_number"
        },
        "manufacturer_batch_number": {
          "$ref": "#/components/schemas/manufacturer_batch_number"
        },
        "manufactured_date": {
          "$ref": "#/components/schemas/manufactured_date"
        },
        "expiry_date": {
          "$ref": "#/components/schemas/expiry_date"
        },
        "balance_quantity": {
          "$ref": "#/components/schemas/balance_quantity"
        },
        "status": {
          "$ref": "#/components/schemas/status"
        },
        "batch_custom_fields": {
          "$ref": "#/components/schemas/batch_custom_fields"
        }
      }
    },
    "list-batches-item": {
      "description": "Details of a batch as returned in the list batches response.",
      "type": "object",
      "properties": {
        "batch_id": {
          "$ref": "#/components/schemas/batch_id"
        },
        "batch_in_id": {
          "$ref": "#/components/schemas/batch_in_id"
        },
        "batch_number": {
          "$ref": "#/components/schemas/batch_number"
        },
        "internal_batch_number": {
          "$ref": "#/components/schemas/internal_batch_number"
        },
        "external_batch_number": {
          "$ref": "#/components/schemas/external_batch_number"
        },
        "manufacturer_batch_number": {
          "$ref": "#/components/schemas/manufacturer_batch_number"
        },
        "manufacturer_date": {
          "$ref": "#/components/schemas/manufacturer_date"
        },
        "manufactured_date": {
          "$ref": "#/components/schemas/manufactured_date"
        },
        "expiry_date": {
          "$ref": "#/components/schemas/expiry_date"
        },
        "in_quantity": {
          "$ref": "#/components/schemas/in_quantity"
        },
        "balance_quantity": {
          "$ref": "#/components/schemas/balance_quantity"
        },
        "balance_quantity_unit": {
          "$ref": "#/components/schemas/balance_quantity_unit"
        },
        "location_id": {
          "$ref": "#/components/schemas/location_id"
        },
        "associated_locations": {
          "$ref": "#/components/schemas/associated_locations"
        },
        "batch_custom_fields": {
          "$ref": "#/components/schemas/batch_custom_fields"
        },
        "status": {
          "$ref": "#/components/schemas/status"
        }
      }
    },
    "create-a-batch-request": {
      "required": [
        "item_id",
        "batch_number"
      ],
      "type": "object",
      "properties": {
        "item_id": {
          "$ref": "#/components/schemas/item_id"
        },
        "batch_number": {
          "$ref": "#/components/schemas/batch_number"
        },
        "manufacturer_batch_number": {
          "$ref": "#/components/schemas/manufacturer_batch_number"
        },
        "manufactured_date": {
          "$ref": "#/components/schemas/manufactured_date"
        },
        "expiry_date": {
          "$ref": "#/components/schemas/expiry_date"
        },
        "sales_rate": {
          "$ref": "#/components/schemas/sales_rate"
        },
        "label_rate": {
          "$ref": "#/components/schemas/label_rate"
        },
        "batch_custom_fields": {
          "$ref": "#/components/schemas/batch_custom_fields"
        }
      }
    },
    "create-a-batch-response": {
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "example": 0,
          "readOnly": true
        },
        "message": {
          "type": "string",
          "example": "The batch has been created.",
          "readOnly": true
        },
        "batch": {
          "$ref": "#/components/schemas/batch-response"
        }
      }
    },
    "list-all-batches-response": {
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "example": 0,
          "readOnly": true
        },
        "message": {
          "type": "string",
          "example": "success",
          "readOnly": true
        },
        "batches": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/list-batches-item"
          }
        }
      }
    },
    "retrieve-a-batch-response": {
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "example": 0,
          "readOnly": true
        },
        "message": {
          "type": "string",
          "example": "success",
          "readOnly": true
        },
        "batch": {
          "$ref": "#/components/schemas/batch-response"
        }
      }
    },
    "update-a-batch-request": {
      "type": "object",
      "properties": {
        "batch_number": {
          "$ref": "#/components/schemas/batch_number"
        },
        "manufacturer_batch_number": {
          "$ref": "#/components/schemas/manufacturer_batch_number"
        },
        "manufactured_date": {
          "$ref": "#/components/schemas/manufactured_date"
        },
        "expiry_date": {
          "$ref": "#/components/schemas/expiry_date"
        },
        "sales_rate": {
          "$ref": "#/components/schemas/sales_rate"
        },
        "label_rate": {
          "$ref": "#/components/schemas/label_rate"
        },
        "batch_custom_fields": {
          "$ref": "#/components/schemas/batch_custom_fields"
        }
      }
    },
    "update-a-batch-response": {
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "example": 0,
          "readOnly": true
        },
        "message": {
          "type": "string",
          "example": "The batch has been updated.",
          "readOnly": true
        },
        "batch": {
          "$ref": "#/components/schemas/batch-response"
        }
      }
    },
    "delete-a-batch-response": {
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "example": 0,
          "readOnly": true
        },
        "message": {
          "type": "string",
          "example": "The batch has been deleted.",
          "readOnly": true
        }
      }
    },
    "bulk-delete-batches-response": {
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "example": 0,
          "readOnly": true
        },
        "message": {
          "type": "string",
          "example": "The selected batches have been deleted.",
          "readOnly": true
        }
      }
    },
    "mark-a-batch-as-active-response": {
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "example": 0,
          "readOnly": true
        },
        "message": {
          "type": "string",
          "example": "The batch has been marked as active.",
          "readOnly": true
        }
      }
    },
    "mark-a-batch-as-inactive-response": {
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "example": 0,
          "readOnly": true
        },
        "message": {
          "type": "string",
          "example": "The batch has been marked as inactive.",
          "readOnly": true
        }
      }
    },
    "mark-batches-as-active-response": {
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "example": 0,
          "readOnly": true
        },
        "message": {
          "type": "string",
          "example": "The selected batches have been marked as active.",
          "readOnly": true
        }
      }
    },
    "mark-batches-as-inactive-response": {
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "example": 0,
          "readOnly": true
        },
        "message": {
          "type": "string",
          "example": "The selected batches have been marked as inactive.",
          "readOnly": true
        }
      }
    }
  }
}