Auth Codes & QR Assignment

Learn how to assign authentication codes (auth codes) to products, enabling customers to scan QR codes to verify authenticity and earn loyalty points.

Overview

Auth codes are unique identifiers that:

• ✅ Verify product authenticity (anti-counterfeiting)
• ✅ Enable customer engagement through QR scanning
• ✅ Reward loyalty points when scanned
• ✅ Track product journey from production to customer
• ✅ Provide valuable scan analytics

Prerequisites

Before assigning auth codes, ensure:

1. ✅ Auth codes have been pre-generated (by Batch team or batch range creation)
2. ✅ Products exist in your catalog
3. ✅ Loyalty program is configured (if using points rewards)

---

Auth Code Generation

How Auth Codes Are Created

Auth codes are generated in batch ranges which create sequential unique codes.

Navigate to: Admin Portal > Products > Batch Ranges

Creating a Batch Range

Step 1: Click Create Batch Range

Step 2: Fill in details

Range Name: Purple Haze Spring 2024
Product: Purple Haze - 3.5g
Quantity: 10,000 codes
Prefix: PH2024-
Starting Number: 00001
Loyalty Points per Scan: 50
Campaign Association: Spring Launch Campaign (optional)

Step 3: Click Generate

The system creates 10,000 unique codes:

PH2024-00001
PH2024-00002
PH2024-00003
...
PH2024-10000

Each code gets a unique QR code image generated.

Batch Range Settings

Setting	Description	Example
Range Name	Internal identifier	"Purple Haze Spring 2024"
Product	Which product these codes belong to	Purple Haze - 3.5g
Quantity	How many codes to generate	10,000
Prefix	Code prefix for organization	PH2024-
Starting Number	First sequential number	00001
Points per Scan	Loyalty points awarded	50
Scan Limit	How many times code can be scanned	1 (default) or unlimited
Expiration Date	When codes become invalid	2024-12-31
Campaign	Link to loyalty campaign	Spring Launch

---

Assigning Auth Codes to Products

There are three methods to assign auth codes to products:

Method 1: Auto-Assignment (Recommended)

Auth codes are automatically assigned when batch range is created.

When to use: Most common scenario - codes are for a specific product

How it works:

1. Create batch range and select product
2. Codes are automatically linked to that product
3. Scan any code → system knows which product it belongs to

Example:

Product: Purple Haze - 3.5g
Batch Range: PH2024-00001 to PH2024-10000
Status: 10,000 codes auto-assigned to Purple Haze

Method 2: Manual Assignment

Assign specific codes to specific product units/inventory.

When to use:

• Tracking individual units
• High-value products requiring detailed tracking
• Products with serial numbers

Navigate to: Admin Portal > Products > [Select Product] > Auth Codes

Steps:

1. Select product
2. Click Assign Auth Codes
3. Choose assignment method:
   • Range: Assign codes PH2024-00001 through PH2024-01000
   • List: Upload CSV with specific codes
   • Individual: Manually enter codes one by one

Example CSV:

auth_code,inventory_location,notes
PH2024-00001,Downtown Hub,Batch A
PH2024-00002,Downtown Hub,Batch A
PH2024-00003,Westside Hub,Batch B

Method 3: Bulk Assignment via Import

Assign codes in bulk using CSV import.

Navigate to: Admin Portal > Products > Import > Auth Code Assignment

CSV Format:

product_sku,auth_code_start,auth_code_end,location,points_per_scan
PH-35-001,PH2024-00001,PH2024-05000,Main Warehouse,50
BD-7G-001,BD2024-00001,BD2024-03000,Downtown Hub,75
GG-14G-001,GG2024-00001,GG2024-02000,Westside Hub,100

Steps:

1. Download CSV template
2. Fill in product SKUs and auth code ranges
3. Upload CSV
4. Review preview
5. Click Import

---

Physical QR Code Printing

Once auth codes are generated and assigned, you need to print QR codes for physical products.

Downloading QR Codes

Navigate to: Admin Portal > Products > Batch Ranges > [Select Range]

Options:

1. Download All as ZIP

Click: Download QR Codes (ZIP)
Format: Individual PNG files for each code
Resolution: 300 DPI (print quality)
Size: 2" x 2" (customizable)

2. Download as PDF Sheet

Click: Download QR Sheet (PDF)
Layout: 30 codes per page (customizable)
Labels: Avery 5160 compatible
Includes: Code number below each QR

3. API Download for Integration

GET /api/v1/batch-ranges/{id}/qr-codes
Response: Array of QR code image URLs

Printing Best Practices

Print Quality:

• ✅ Minimum 300 DPI resolution
• ✅ High contrast (black on white)
• ✅ No distortion or stretching
• ✅ Test scan before mass printing

Materials:

• Stickers/Labels: Waterproof, durable adhesive
• Packaging: Printed directly on packaging
• Tags: Hang tags with QR code
• Inserts: Info cards inserted in product

Size Guidelines:

Minimum QR Code Size: 0.8" x 0.8" (2cm x 2cm)
Recommended: 1.5" x 1.5" (4cm x 4cm)
Large Format: 2" x 2" (5cm x 5cm)

Testing:

1. Print test sheet
2. Scan with multiple devices (iOS, Android)
3. Verify correct product link
4. Check points award correctly
5. Approve for mass production

---

QR Code Scanning Flow

Customer Experience

1. Customer receives product with QR code

2. Customer scans QR with phone camera or Batch app

3. System validates auth code

4. Product details shown:

   • Product name and description
   • Authenticity verification
   • Batch information
   • Lab test results (if available)

5. Loyalty points awarded (if logged in)

6. Scan recorded for analytics

Scan Validation Rules

The system checks:

✅ Is code valid? (exists in database)
✅ Is code active? (not expired or deactivated)
✅ Has product been assigned? (knows which product)
✅ Scan limit reached? (if limit is 1, can only scan once)
✅ Is customer logged in? (for points award)
✅ Is loyalty campaign active? (if code is part of campaign)

Scan Outcomes

Successful Scan:

{
  "status": "success",
  "product": "Purple Haze - 3.5g",
  "points_awarded": 50,
  "message": "Authentic product verified! 50 points added to your account.",
  "scan_count": 1,
  "first_scan": true
}

Already Scanned:

{
  "status": "warning",
  "product": "Purple Haze - 3.5g",
  "message": "This product has already been verified.",
  "first_scan_date": "2024-01-15",
  "first_scan_location": "Los Angeles, CA"
}

Invalid Code:

{
  "status": "error",
  "message": "Invalid code. This may be a counterfeit product. Please contact support.",
  "support_email": "support@yourbrand.com"
}

---

Managing Assigned Codes

Viewing Code Status

Navigate to: Admin Portal > Products > [Select Product] > Auth Codes

Status Dashboard:

Total Codes Assigned: 10,000
Scanned: 3,247 (32.47%)
Unscanned: 6,753 (67.53%)
Points Awarded: 162,350
Unique Scanners: 2,891

Filtering and Searching

Filter Options:

• Status: Scanned / Unscanned / Expired / Deactivated
• Date Range: Codes created between X and Y
• Location: Scanned in specific location
• Campaign: Associated with campaign

Search:

• By code: PH2024-00123
• By product: Purple Haze
• By customer: john@example.com

Exporting Scan Data

Navigate to: Admin Portal > Products > Auth Codes > Export

Export Options:

1. Scan Report CSV:

auth_code,product,scan_date,customer_email,location,points_awarded
PH2024-00001,Purple Haze - 3.5g,2024-01-15 14:23:11,john@example.com,"Los Angeles, CA",50
PH2024-00002,Purple Haze - 3.5g,2024-01-15 15:47:22,jane@example.com,"San Francisco, CA",50

2. Unscanned Codes CSV:

auth_code,product,created_date,expiration_date,status
PH2024-06754,Purple Haze - 3.5g,2024-01-01,2024-12-31,active
PH2024-06755,Purple Haze - 3.5g,2024-01-01,2024-12-31,active

---

Advanced Use Cases

Use Case 1: Product Authenticity Verification

Scenario: High-value products need anti-counterfeiting protection

Solution:

1. Generate unique codes for each unit
2. Print QR on tamper-evident labels
3. Set scan limit to 1
4. First scan registers product as authentic
5. Subsequent scans show "already verified" warning

Benefits:

• Customers verify they bought genuine product
• Counterfeiters cannot replicate unique codes
• Scan data shows distribution patterns

Use Case 2: Loyalty Points on Purchase

Scenario: Reward customers for buying products

Solution:

1. Include QR code inside product packaging
2. Customer scans after purchase
3. Points awarded automatically
4. Points can be redeemed for discounts/rewards

Configuration:

Product: Premium Flower - 3.5g
Price: $45
Points per Scan: 50 points
Point Value: $0.10 per point
Reward: $5 off next purchase

Use Case 3: Campaign Progress Tracking

Scenario: "Scan 10 different products, get a free item"

Solution:

1. Create campaign with step: 10 unique scans
2. Assign auth codes to products in campaign
3. Track customer progress via scan dashboard
4. Auto-reward when step reached

Example:

Campaign: Spring Collection Challenge
Goal: Scan 10 different Spring products
Reward: Free pre-roll
Customer Progress: 7/10 scans (3 more to go!)

Use Case 4: Batch Recall Management

Scenario: Need to recall specific batch due to quality issue

Solution:

1. Identify batch range with issue: PH2024-05001 to PH2024-05500
2. Mark batch as "Recalled" in system
3. When customers scan codes from this batch:

   ⚠️ PRODUCT RECALL NOTICE
   This product is part of a voluntary recall.
   Please return to place of purchase for full refund.
   Recall ID: RC-2024-03
   Contact: recalls@yourbrand.com

4. Track how many recalled products have been scanned
5. Contact customers who scanned (if they're registered)

Use Case 5: Supply Chain Tracking

Scenario: Track product journey from production to customer

Configuration:

Scan Point 1: Manufacturing (internal scan)
Scan Point 2: Quality Control (internal scan)
Scan Point 3: Distribution Center (internal scan)
Scan Point 4: Dispensary Receipt (internal scan)
Scan Point 5: Customer Purchase (customer scan)

Tracking Data:

Auth Code: PH2024-00123
Manufactured: 2024-01-10 (Location: Production Facility A)
QC Passed: 2024-01-11 (Inspector: Jane Doe)
Shipped: 2024-01-12 (To: Downtown Hub)
Received: 2024-01-13 (By: Hub Manager)
Sold: 2024-01-15 (Customer: John Smith)
Total Journey Time: 5 days

---

Troubleshooting

Issue: QR Code Not Scanning

Possible Causes:

1. Low print quality / damaged QR code
2. Poor lighting when scanning
3. QR code too small
4. Camera focus issues

Solutions:

• ✅ Reprint at higher quality (300+ DPI)
• ✅ Ensure minimum 0.8" x 0.8" size
• ✅ Use high contrast (black on white)
• ✅ Test with multiple devices before mass printing
• ✅ Add backup manual code entry option

Issue: "Code Already Scanned" Error

Cause: Code has reached scan limit (usually 1)

Solutions:

• If legitimate re-scan needed: Increase scan limit in batch range settings
• If suspicious (potential fraud): Investigate scan history
• Provide customer with alternative verification method

Issue: Points Not Awarded After Scan

Check:

1. ✅ Customer is logged in (guest scans don't award points)
2. ✅ Loyalty program is active
3. ✅ Code is associated with points value
4. ✅ Customer hasn't exceeded daily/monthly point limits
5. ✅ Campaign hasn't expired

Admin Action:

• Manually award points: Admin > Customers > [Select Customer] > Loyalty > Add Points

Issue: Bulk Import Failed

Common Errors:

Error: "Product SKU not found"
Solution: Verify SKU exists and matches exactly (case-sensitive)

Error: "Auth code range already assigned"
Solution: Check if codes are already in use for another product

Error: "Invalid CSV format"
Solution: Download template and ensure columns match exactly

---

Best Practices

1. Code Organization

Use Meaningful Prefixes:

✅ Good:
PH2024-Q1-00001 (Purple Haze, 2024, Q1)
BD-SPRING-00001 (Blue Dream, Spring batch)

❌ Bad:
00001 (no context)
ABC123 (unclear meaning)

2. Scan Limits

Set Appropriate Limits:

Consumer Products: 1 scan (authenticity verification)
Promotional Items: Unlimited (for repeat engagement)
Limited Edition: 1 scan (prevent point farming)
Rewards Program: 5 scans (allow some flexibility)

3. Security

Protect Against Fraud:

• ✅ Don't publish code lists publicly
• ✅ Monitor for suspicious scan patterns
• ✅ Use tamper-evident packaging
• ✅ Implement rate limiting on API
• ✅ Alert on mass scanning from single IP

4. Customer Experience

Make Scanning Easy:

• ✅ Clear instructions on packaging
• ✅ QR code in accessible location
• ✅ Large enough to scan easily
• ✅ Provide manual code entry option
• ✅ Explain benefits (points, verification)

5. Analytics Usage

Leverage Scan Data:

• Track which products are scanned most
• Identify geographic distribution
• Measure campaign effectiveness
• Detect counterfeit patterns
• Optimize marketing based on engagement

---

API Integration

For developers integrating auth code scanning:

Validate Auth Code

POST /api/v1/auth-codes/validate
{
  "code": "PH2024-00123",
  "customer_id": "cust_abc123" // optional
}

Response:
{
  "valid": true,
  "product": {
    "id": "prod_123",
    "name": "Purple Haze - 3.5g",
    "sku": "PH-35-001"
  },
  "points_awarded": 50,
  "scan_count": 1,
  "first_scan": true
}

Record Scan

POST /api/v1/auth-codes/scan
{
  "code": "PH2024-00123",
  "customer_id": "cust_abc123",
  "location": {
    "latitude": 34.0522,
    "longitude": -118.2437
  },
  "device": "iPhone 14 Pro",
  "app_version": "1.2.0"
}

Get Scan History

GET /api/v1/auth-codes/PH2024-00123/scans

Response:
{
  "code": "PH2024-00123",
  "product": "Purple Haze - 3.5g",
  "total_scans": 1,
  "scans": [
    {
      "scan_id": "scan_xyz789",
      "customer_email": "john@example.com",
      "timestamp": "2024-01-15T14:23:11Z",
      "location": "Los Angeles, CA",
      "points_awarded": 50
    }
  ]
}

---

Related Guides

• Product Batches
• Batch Range Creation
• Loyalty Points Management
• Scan Reports & Analytics