Skip to content

Supercollections

T3 API Supercollections

With Metrc data, users frequently encounter these sorts of problems:

  • "I want to load my packages, but also need test results for each"
  • "I want to load my transfers, but also want all the packages"
  • "I want to load my items, but I also want all the images and ingredients"

Enter supercollections

What is a Supercollection?

The best way to understand supercollections is to compare them to T3 collections:

  • T3 collection endpoints are designed to send exactly one request to Metrc per request to T3.
  • Examples: Active Packages, Incoming Transfers, Active Items.
  • This ensures the endpoints are fast, have generous rate limits, and are flexible to use.
  • If you want to load metadata for a collection, you need to explicitly request it per row.
  • T3 supercollection endpoints are designed to eagerly load all metadata for each collection object.
  • Examples: Active Superpackages, Incoming Supertransfers, Superitems.
  • They extend existing collection endpoint behavior.
  • This allows the endpoint to efficiently load, organize, and analyze the metadata for you.
  • Endpoints have lower rate limits, and are slower to use.
  • Metadata is loaded declaratively. For example, you'd specify you want lab results and history for an active superpackages request.

Available Supercollection Endpoints

Supercollection Path include options
Superitems /v2/items/super notes, history, ingredients, images
Active Superpackages /v2/packages/active/super labResults, labResultBatches, sourceHarvests, history, coaFiles¹
Inactive Superpackages /v2/packages/inactive/super labResults, labResultBatches, sourceHarvests, history, coaFiles¹
In Transit Superpackages /v2/packages/intransit/super labResults, labResultBatches, sourceHarvests, history, coaFiles¹
Incoming Active Supertransfers /v2/transfers/incoming/active/super packages, transporters
Outgoing Active Supertransfers /v2/transfers/outgoing/active/super packages, transporters

¹ coaFiles is reserved — not yet supported.

The include Parameter

The include parameter controls which additional data is fetched and attached to each object in the response. Without it, a supercollection request behaves like a regular collection request.

Each include value does two things:

  1. Attaches raw Metrc data as a new array on each object (e.g. labResults, sourceHarvests).
  2. Populates fields on the metadata object with extracted, cleaned-up values derived from that raw data.

You can combine multiple include values by repeating the parameter: include=labResults&include=sourceHarvests.

A few metadata fields are populated unconditionally (no include required), when the underlying data is available:

  • Superpackages: netWeightOrVolume, netWeightOrVolumeUnitOfMeasure
  • Superitems: approvalNumber, itemImages

Superpackage includes

include Raw data attached metadata fields populated
labResults labResults[] extractedLabResults, testSamplePackageLabels, labResultPdfs, indexedLabResults
labResultBatches labResultBatches[] extractedLabResults, testSamplePackageLabels, labResultPdfs, indexedLabResults
sourceHarvests sourceHarvests[] harvestDates
history history[] initialQuantity, initialQuantityUnitOfMeasure, manifestNumber², destinationFacilityLicenseNumber², destinationFacilityName², transferType²
coaFiles (reserved, not yet supported) extractedLabResults

² Only present for in-transit packages.

indexedLabResults is a simplified dictionary intended for templating (e.g. on a label). Example access:

{{ package.metadata.indexedLabResults.totalThc.name }}    → "Total THC"
{{ package.metadata.indexedLabResults.totalThc.value }}   → 12.5
{{ package.metadata.indexedLabResults.totalThc.unit }}    → "%"
{{ package.metadata.indexedLabResults.totalThc.full }}    → "Total THC: 12.5 %"

Also indexed: totalCbd, topTerpene1, topTerpene2, etc.

Superitem includes

include Raw data attached metadata fields populated
notes notes[] (none)
history history[] (none)
ingredients ingredients[] (none)
images images[] itemImages

approvalNumber and itemImages are populated on every superitem when the data is available — you don't need include=images to get image metadata, only the raw base64/image records themselves.

Supertransfer includes

include Raw data attached metadata fields populated
packages packages[] (none)
transporters transporters[] (none)

Superpackages Example

This is the most commonly used supercollection. Below is an example that loads all active superpackages with lab results for packages in the "Buds" product category:

#!/usr/bin/env python3
# /// script
# requires-python = ">=3.8"
# dependencies = [
#     "t3api-utils",
# ]
# ///


from t3api_utils.api.parallel import load_all_data_sync
from t3api_utils.main.utils import (get_authenticated_client_or_error,
                                    interactive_collection_handler,
                                    pick_license)


def main():
    api_client = get_authenticated_client_or_error()

    license_number = pick_license(api_client=api_client)

    all_packages = load_all_data_sync(
        client=api_client,
        path="/v2/packages/active/super",
        license_number=license_number["licenseNumber"],
        page_size=50,
        include="labResults",
        filter="item.productCategoryName__eq:Buds"
    )

    interactive_collection_handler(data=all_packages)

if __name__ == "__main__":
    main()

Each object in the response will contain:

  • All the standard package fields (label, item, quantity, etc.).
  • A labResults array with the raw Metrc lab result data.
  • A metadata object with extractedLabResults, testSamplePackageLabels, labResultPdfs, indexedLabResults, plus the unconditional netWeightOrVolume / netWeightOrVolumeUnitOfMeasure.

You can find more supercollection examples in the T3 API examples repository.

Next Steps