Create packages from a harvest in Metrc — the endpoint, the tag rules, and the 10-object cap

Metrc is the state-mandated cannabis track-and-trace system in 20+ U.S. jurisdictions, and turning a harvest batch into sellable packages is the single most common compliance write a cultivation integration makes. The API call itself is one POST — but it sits inside a lifecycle with a running weight ledger, a state-issued tag pool your software can't mint from, a separate endpoint for lab-sample packages that silently mislabels your package if you pick the wrong one, and a hard 10-objects-per-request cap. These are the documented steps and failure modes from Waymark's live route corpus, checked against Metrc's official state API documentation (the per-state /Documentation pages are public).

Why this call fails for integrations that treat it as a plain POST

Three structural facts drive most failures. First, a harvest batch tracks a running remaining weight: every package you create draws its Ingredients weight against that total, and requesting more than the harvest has left returns an error — sequencing matters if you create packages concurrently. Second, Metrc's v2 API enforces object limiting: any POST or PUT that accepts an array is capped at 10 objects per request, and an 11th gets you 413 Content Too Large — batch loops that page by 50 work on every other API you integrate and fail here. Third, package tags aren't yours to invent: they come from the physical RFID tag pool your facility bought from Metrc, and the API only lets you list what's available (GET /tags/v2/package/available), never order more. If the pool is empty, no API call fixes it.

Verified routes for this task

The procedure

1. Authenticate with HTTP Basic auth — your software integrator API key as the username and the facility user's user API key as the password. Everything your software can do is bounded by that user's permissions in Metrc, and every call targets your state's own instance (api-ca.metrc.com, api-or.metrc.com, …)
2. Find the source harvest: GET /harvests/v2/active?licenseNumber=<license>. Harvests can be referenced by ID or by name (name matching is case-insensitive). Note the remaining weight before you package
3. Get an available package tag: GET /tags/v2/package/available?licenseNumber=<license>
4. Confirm the item you're packaging into exists with a valid unit of measure: GET /items/v2/active?licenseNumber=<license>
5. Create the package(s): POST /harvests/v2/packages?licenseNumber=<license> with an array of at most 10 package objects (v1 path: POST /harvests/v1/create/packages)
6. Verify with GET /packages/v2/active; when the harvest's remaining weight hits zero, explicitly finish it with PUT /harvests/v2/finish — Metrc never auto-finishes a harvest

# Create one package from a harvest (California instance shown — use your state's host)
curl -X POST "https://api-ca.metrc.com/harvests/v2/packages?licenseNumber=C11-0000000-LIC" \
  -u "$SOFTWARE_API_KEY:$USER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[{
    "Tag": "1A4FF0100000022000000123",
    "Location": "Packaging Room",
    "Item": "Shake",
    "UnitOfWeight": "Grams",
    "IsProductionBatch": false,
    "ProductRequiresRemediation": false,
    "ActualDate": "2026-07-12",
    "Ingredients": [{
      "HarvestId": 1234,
      "HarvestName": null,
      "Weight": 453.6,
      "UnitOfWeight": "Grams"
    }]
  }]'
# Lab-sample package? DIFFERENT endpoint: POST /harvests/v2/packages/testing
# The exact accepted field set can vary by state — confirm against
# https://api-<state>.metrc.com/Documentation before shipping.

The lab-sample trap

Metrc exposes two parallel creation endpoints: POST /harvests/v2/packages for standard packages and POST /harvests/v2/packages/testing for lab-sample packages destined for a testing facility. Both accept near-identical bodies, both succeed — but the endpoint you choose is the package's declared purpose in the state's ledger. Create a lab sample through the standard endpoint and it's recorded as ordinary sellable inventory; the mistake surfaces later as a compliance discrepancy, not as an API error at write time.

Rate limits and the 10-object cap

Metrc's v2 documentation states that any call accepting an array of objects is limited to 10 objects per request — exceeding it returns 413 Content Too Large. Rate limiting is enforced per facility (per API key for the few endpoints without a license number), and a 429 Too Many Requests response may carry a Retry-After header with the seconds to wait. Exact limits depend on your Metrc agreement tier, so build backoff around the headers rather than hard-coding a rate. One more v2 note: list endpoints like /harvests/v2/active are paginated — don't assume one page is the whole facility.

Before any of this works in production

Metrc production API access is gated: integrators go through Metrc's vetting process (sandbox testing and approval) before production keys are issued, and each facility user generates their own user API key that they hand to your software. Feature availability also genuinely differs between state instances — the v1 endpoints are still documented alongside v2, and states migrate on their own schedules. The per-state documentation at https://api-<state>.metrc.com/Documentation is public and is the source of truth for what your state supports.

How agents avoid this automatically

Agents wired to Waymark's MCP server pull these routes (the remaining-weight ledger, the testing-endpoint split, the tag-pool rule, the 10-object cap) at plan time instead of reconstructing Metrc's lifecycle rules from bulletins and forum posts — and instead of learning about 413 Content Too Large in production. Reads are free and keyless.

# Any MCP client — one call, no key:
waymark_query({ "task": "metrc create packages from harvest" })

# Or plain HTTP:
curl -s "https://mcp.waymark.network/search?q=metrc%20create%20packages%20from%20harvest"