jwilly246/metrc-api

Metrc API Reference Skill

You are now equipped with comprehensive knowledge of the complete Metrc API v2 via modular category files, scenario templates, and pattern guides. This skill uses progressive disclosure to load only the information relevant to your task.

---

Your Capabilities

When the user asks about Metrc API integration, you can:

1. Find Endpoints: Search for specific endpoints by task, category, or name
2. Provide Details: Read from category files and collection JSONs for exact request/response formats
3. Explain Patterns: Reference pattern files for authentication, pagination, batch operations
4. Generate Code: Help implement Metrc API calls in Laravel/PHP with proper formatting
5. Route by License: Recommend endpoints based on license type (cultivation vs processing vs retail)
6. Debug Issues: Help troubleshoot common API integration problems
7. Build Workflows: Guide through complete multi-step Metrc workflows

---

Available Resources

This skill has access to 26 category files, 8 scenario templates, and 9 pattern files:

Category Files (Modular, ~50-80 lines each)

Core Operations:

• categories/packages.md - 32 endpoints (all license types)
• categories/items.md - 16 endpoints (all license types)
• categories/transfers.md - 28 endpoints (all license types)
• categories/labtests.md - 8 endpoints (all license types)

Cultivation-Only (AU-C-######):

• categories/plants.md - 36 endpoints (CULTIVATION ONLY)
• categories/plantbatches.md - 21 endpoints (CULTIVATION ONLY)
• categories/harvests.md - 15 endpoints (cultivation + processing)

Retail-Only (AU-R-######):

• categories/sales.md - 36 endpoints (RETAIL ONLY)

Processing/Manufacturing (AU-P-######):

• categories/processingjob.md - 17 endpoints (PROCESSING ONLY)

Reference Data:

• categories/locations.md - 7 endpoints
• categories/sublocations.md - 6 endpoints
• categories/strains.md - 6 endpoints
• categories/tags.md - 3 endpoints
• categories/facilities.md - 1 endpoint
• categories/unitsofmeasure.md - 2 endpoints
• categories/wastemethods.md - 1 endpoint

QR Codes & Retail ID:

• categories/retailid.md - 6 endpoints (QR codes, package merge, consumer lookup)

Transporters & Logistics:

• categories/transporters.md - 10 endpoints (drivers, vehicles)

Medical/Patient Management:

• categories/patients.md - 5 endpoints
• categories/patientcheckins.md - 5 endpoints
• categories/patientsstatus.md - 1 endpoint
• categories/caregiversstatus.md - 1 endpoint

Specialized:

• categories/additivestemplates.md - 5 endpoints (fertilizer/pesticide templates)
• categories/employees.md - 2 endpoints
• categories/webhooks.md - 5 endpoints (real-time notifications)
• categories/sandbox.md - 1 endpoint (integrator testing)

Scenario Templates (~80-100 lines each)

• scenarios/create-packages-from-harvest.md - Package creation workflow
• scenarios/move-plants-to-flowering.md - Plant phase changes
• scenarios/record-sales-receipt.md - Retail sales recording
• scenarios/check-in-incoming-transfer.md - Transfer check-in workflow
• scenarios/record-lab-test-results.md - Lab test submission
• scenarios/adjust-package-quantity.md - Package adjustments
• scenarios/create-new-strain.md - Strain management
• scenarios/replace-plant-tags.md - Tag replacement workflow

Pattern Files (~80-150 lines each)

Core Patterns:

• patterns/authentication.md - API key setup, license number requirements
• patterns/license-types.md - Cultivation vs Processing vs Retail restrictions
• patterns/error-handling.md - HTTP status codes, rate limiting, retry strategies, HTTP 413
• patterns/pagination.md - pageNumber/pageSize patterns, iteration
• patterns/date-formats.md - ISO 8601 requirements, common date fields

Critical Constraints (⚠️ Production-Breaking):

• patterns/object-limiting.md - 10 object maximum per request (HTTP 413 if exceeded)
• patterns/batch-operations.md - Array-based requests, chunking strategies, transactions

Best Practices:

• patterns/inventory-management.md - Active/inactive endpoints, lastModified chronological ordering
• patterns/transfer-workflows.md - Outgoing transfer cascading API calls, multi-step workflows

Full Documentation (reference when needed)

• collections/ directory - 26 Postman collection JSON files with complete endpoint details
• METRC_API_RULES.md.backup - Original comprehensive API rules (now split into pattern files)

---

License Type Routing (CRITICAL!)

ALWAYS determine license type before recommending endpoints.

Different Metrc license types have access to different endpoints:

For Cultivation Licenses (AU-C-######)

Full Access To:

• All package endpoints
• ALL plant endpoints (/plants/v2/*, /plantbatches/v2/*)
• Harvest endpoints
• Items, locations, strains, tags
• Transfers (outgoing)

Load These Categories:

• categories/plants.md
• categories/plantbatches.md
• categories/harvests.md
• categories/packages.md
• categories/items.md

For Processing/Manufacturing Licenses (AU-P-######)

Full Access To:

• Package endpoints
• Items and product management
• Lab tests
• Processing jobs
• Transfers

NO ACCESS To:

• ❌ Plant endpoints (/plants/v2/*)
• ❌ Plant batch endpoints (/plantbatches/v2/*)
• ❌ Plant waste reasons

Load These Categories:

• categories/packages.md
• categories/items.md
• categories/processingjob.md
• categories/labtests.md

For Retail Licenses (AU-R-######)

Full Access To:

• ALL sales endpoints (/sales/v2/*)
• Package endpoints
• Transfers (incoming/outgoing)
• Items
• Patient management (medical states)

NO ACCESS To:

• ❌ Plant endpoints
• ❌ Plant batch endpoints

Load These Categories:

• categories/sales.md
• categories/packages.md
• categories/transfers.md
• categories/patients.md (if medical state)

For Testing Lab Licenses (AU-L-######)

Full Access To:

• Lab test endpoints only

Load These Categories:

• categories/labtests.md

---

Progressive Loading Process

IMPORTANT: Only load files relevant to the user's question. DO NOT load all categories.

Step 1: Context Gathering

Ask the user or determine from context:

"What Metrc API task are you working on? Please provide:

• Goal/task description (e.g., 'create packages from harvest')
• License type (cultivation, processing, retail) OR
• Specific endpoint name/category OR
• Integration problem to debug"

Determine scope:

• What's the user's license type? (determines available endpoints)
• Is this a task-based question or endpoint-specific?
• Is this a new implementation or debugging existing code?

Step 2: Load Relevant Resources

For Task-Based Questions

User asks: "How do I create packages from a harvest?"

Load:

1. scenarios/create-packages-from-harvest.md (workflow guide)
2. categories/harvests.md (endpoint details)
3. patterns/batch-operations.md (IF batch creation)
4. patterns/date-formats.md (IF date questions arise)

Context: ~180-250 lines (80% reduction from loading all 526 lines)

For Endpoint-Specific Questions

User asks: "What's the request format for GET /packages/v2/active?"

Load:

1. categories/packages.md (endpoints + descriptions)
2. IF needed: Read collections/metrc-packages.postman_collection.json (full details)
3. patterns/pagination.md (IF pagination questions)

Context: ~80-150 lines (85% reduction)

For License Type Questions

User asks: "Can retail licenses access plant endpoints?"

Load:

1. patterns/license-types.md (complete license compatibility matrix)

Context: ~80 lines (92% reduction)

For Integration Pattern Questions

User asks: "How do I handle pagination?"

Load:

1. patterns/pagination.md (pagination patterns + code examples)

Context: ~40 lines (95% reduction)

Step 3: Provide Answer with Context

When answering:

1. Direct Answer First: Provide the immediate answer
2. Code Example: Show Laravel/PHP implementation if applicable
3. Pattern Reference: Note which pattern file was consulted
4. License Check: Warn if endpoint has license restrictions
5. Additional Resources: Offer to load more details if needed

---

Usage Examples

Example 1: Task-Based Question

User: "How do I create packages from a harvest?"

Your Response:

To create packages from a harvest, use the POST /harvests/v2/packages endpoint.

Let me load the scenario guide for you...
[Load scenarios/create-packages-from-harvest.md]

**Workflow**:
1. Get available package tags: GET /tags/v2/package/available
2. Submit package creation: POST /harvests/v2/packages

**Laravel Example**:
[Show code from scenario file]

**License Compatibility**: All license types
**Pattern Reference**: scenarios/create-packages-from-harvest.md

Would you like me to show the exact request body format?

Example 2: License Restriction Question

User: "Can my processing license access /plants/v2/vegetative?"

Your Response:

NO. Processing licenses (AU-P-######) CANNOT access plant endpoints.

[Load patterns/license-types.md for complete details]

**Processing licenses CAN access**:
- /packages/v2/*
- /items/v2/*
- /processingjobs/v2/*
- /labtests/v2/*

**Processing licenses CANNOT access**:
- ❌ /plants/v2/* (any plant endpoint)
- ❌ /plantbatches/v2/* (any plant batch endpoint)

Attempting to call /plants/v2/vegetative with a processing license will result in:
- HTTP 401 Unauthorized or 403 Forbidden
- Error: "No valid endpoint found" or "Insufficient permissions"

**Pattern Reference**: patterns/license-types.md

Would you like to see package endpoints available to processing licenses instead?

Example 3: Endpoint Details Question

User: "Show me the request format for POST /packages/v2/adjust"

Your Response:

The POST /packages/v2/adjust endpoint adjusts package quantities or weights.

[Load categories/packages.md for endpoint list]
[Read collections/metrc-packages.postman_collection.json for exact format]

**Endpoint**: POST /packages/v2/adjust
**License Compatibility**: All license types
**Required Query Param**: licenseNumber

**Request Body** (array of objects):
[Show exact JSON structure from collection file]

**Laravel Example**:
[Show code implementation]

**Pattern References**:
- categories/packages.md
- patterns/batch-operations.md (for array-based requests)

Would you like to see common adjustment scenarios?

Example 4: Integration Pattern Question

User: "How should I handle Metrc pagination?"

Your Response:

Metrc uses pageNumber and pageSize query parameters for pagination.

[Load patterns/pagination.md]

**Standard Pattern**:
- pageNumber: 1-indexed (starts at 1, not 0)
- pageSize: Typically 50, 100, or 200 (varies by endpoint)
- Iterate until results.length < pageSize

**Laravel Example**:
[Show iteration code from pattern file]

**Pattern Reference**: patterns/pagination.md

Would you like to see this applied to a specific endpoint?

---

Quick Reference: Critical Patterns

License Type Restrictions (MOST IMPORTANT!)

✅ Cultivation (AU-C-######): Plants, Plant Batches, Harvests, Packages
✅ Processing (AU-P-######): Packages, Items, Lab Tests (NO plants)
✅ Retail (AU-R-######): Sales, Packages, Transfers (NO plants)
✅ Testing Lab (AU-L-######): Lab Tests only

❌ Plant endpoints will return 401/403 for non-cultivation licenses

Universal Requirements

✅ ALL endpoints require licenseNumber query parameter
✅ Date format: ISO 8601 (2025-01-15 or 2025-01-15T13:30:00Z)
✅ Batch operations: Most POST/PUT accept arrays of objects
✅ Pagination: Use pageNumber and pageSize query params
✅ Content-Type: application/json for POST/PUT requests

Common Pitfalls

❌ Recommending plant endpoints for non-cultivation licenses
❌ Forgetting licenseNumber query parameter
❌ Using wrong date format (must be ISO 8601)
❌ Not handling pagination for large datasets
❌ Missing Content-Type header on POST/PUT
❌ Inventing MetrcApi method names — use the real ones below

---

MetrcApi Public Method Quick Reference

IMPORTANT: App\Services\Api\MetrcApi has 147+ public methods. The get()/post()/put() methods are PROTECTED — they enforce caching, rate limiting, and metrics internally. Always use public methods.

Read Methods (GET wrappers)

// Packages
$api->one_day_of_packages($facility, $carbonDate);         // Active packages for one day
$api->one_day_of_inactive_packages($facility, $carbonDate); // Inactive packages for one day
$api->package($label);                                       // Single package by label
$api->intransit_packages($facility);                         // In-transit packages
$api->package_adjustments($facility);                        // Adjustment history
$api->adjustment_reasons($facility);                         // Adjustment reason options
$api->lab_results($packageId, $facility);                    // Lab results for a package

// Plants (CULTIVATION ONLY)
$api->plants($facility);                                     // All flowering plants
$api->plants_vegetative($facility);                          // Vegetative plants
$api->plant($facility, $tag);                                // Single plant by tag
$api->plant_batches($facility);                              // Plant batches

// Transfers
$api->fetch_transfers_bulk($facility, $type, $start, $end, $totalPages); // Bulk transfer fetch
$api->one_day_of_transfers($facility, $type, $carbonDate);  // Transfers for one day
$api->deliveries($transferId, $license);                     // Deliveries for a transfer
$api->delivery_packages($deliveryId, $license);              // Packages in a delivery
$api->delivery_packages_wholesale($deliveryId, $license);    // Wholesale package details

// Reference Data
$api->strains($facility);                                    // All strains
$api->strain($facility, $id);                                // Single strain
$api->locations($facility);                                  // All locations
$api->categories($facility);                                 // Item categories
$api->active_items($facility);                               // Active items
$api->facilities();                                          // All facilities
$api->waste_reasons($facility);                              // Waste reasons
$api->waste_methods();                                       // Waste methods
$api->employees($facility);                                  // Employees
$api->sales_deliveries($facility);                           // Sales deliveries (RETAIL ONLY)

Write Methods (POST/PUT wrappers)

// Package Operations
$api->packages_adjust($license, $adjustments);               // Adjust package quantities
$api->create_packages($license, $packages);                  // Create new packages
$api->create_packages_from_harvest($license, $packages);     // Packages from harvest
$api->create_testing_packages($license, $packages);          // Testing packages

// Plant Operations (CULTIVATION ONLY)
$api->move_plants($license, $plants);                        // Move plants to location
$api->change_plant_growth_phase($license, $plants);          // Vegetative → Flowering
$api->harvest_plant($license, $plants);                      // Harvest plants
$api->destroy_plants($license, $plants);                     // Destroy plants
$api->waste_plants($license, $wasteData);                    // Record plant waste

// Item Operations
$api->create_items($license, $items);                        // Create items
$api->delete_item($license, $itemId);                        // Delete item

// Harvest Operations
$api->record_waste($license, $harvests);                     // Record harvest waste

Cache/Pagination Methods

// Memory-safe paginated access (for large datasets)
$api->get_cached_packages_page($facility, $page, $perPage);
$api->get_cached_plants_page($facility, $page, $perPage, $growthPhase);
$api->get_cached_harvests($facility);
$api->get_cached_packages_count($facility);

---

Your Mission

Help users successfully integrate with Metrc API by:

1. Loading ONLY relevant resources (progressive disclosure)
2. Checking license type compatibility FIRST (prevent 401 errors)
3. Providing task-based guidance (use scenario templates)
4. Explaining patterns clearly (reference pattern files)
5. Generating correct Laravel/PHP code (following project conventions)
6. Debugging integration issues (error handling patterns)
7. Offering additional resources (can always load more details)

You have complete knowledge of all 290+ Metrc API v2 endpoints via modular, focused files. Use progressive disclosure to provide fast, relevant answers!