Task: CROP Source Identification for Delivery Orders

Target repo: CROP-delivery-services Priority: Medium Type: Feature

Summary

Add CROP source markers to delivery shipments so the team can identify orders made through CROP platform in UPS Dashboard and internal systems.

Context

Frontend (CROP-front) now sends CROP source markers in delivery requests. Backend needs to properly use these markers when creating shipments.

What Frontend Sends

Frontend injects the following fields into createShipment requests:

{
  "reference": "CROP-prod-ORD-abc123",
  "instructions": "CROP-prod | Customer notes here"
}

Format:

• reference: CROP-{env}-{orderId} or just CROP-{env} if no order ID
• instructions: CROP-{env} | {original_instructions} or just CROP-{env}

Where {env} is one of: dev, stage, prod, unknown

Required Backend Changes

1. UPS Provider (src/providers/ups.py)

File: src/providers/ups.py Method: create_shipment

Add at top of method:

import os
app_env = os.environ.get("APP_ENV", "unknown")
crop_marker = f"CROP-{app_env}"

CustomerContext (line ~397-398):

# Use frontend reference if provided, otherwise create with backend marker
# UPS limit: 512 characters
customer_context = request.reference or f"{crop_marker}-{datetime.now().strftime('%Y%m%d%H%M%S')}"
if len(customer_context) > 512:
    customer_context = customer_context[:512]

Description (line ~402):

# Use frontend instructions if provided, otherwise use backend marker
# UPS limit: 35 characters
description = request.instructions or f"{crop_marker} order"
if len(description) > 35:
    description = description[:35]

Shipper AttentionName (line ~405):

"AttentionName": "CROP",  # Changed from request.from_address.name

ShipFrom AttentionName (line ~462):

"AttentionName": "CROP",  # Changed from request.from_address.name

2. Clinton Tractor Provider (src/providers/clinton_tractor.py)

File: src/providers/clinton_tractor.py Method: create_shipment

Replace tracking number generation (line ~171):

import os

app_env = os.environ.get("APP_ENV", "unknown")
env_code_map = {"prod": "P", "dev": "D", "stage": "S", "unknown": "U"}
env_code = env_code_map.get(app_env, "U")

# Format: CT-CROP-{E}-XXXXXXXX (e.g., CT-CROP-P-12345678)
random_suffix = "".join([str(random.randint(0, 9)) for _ in range(8)])
tracking_number = f"CT-CROP-{env_code}-{random_suffix}"

3. Environment Variable (Cloud Run)

Add APP_ENV to GCP Cloud Run configuration:

Expected Results

UPS Dashboard will show:

Clinton Tractor tracking:

Acceptance Criteria

• UPS shipments contain CROP marker in CustomerContext
• UPS shipments contain CROP marker in Description
• UPS labels show "CROP" in AttentionName
• Clinton Tractor tracking numbers have format CT-CROP-{E}-XXXXXXXX
• APP_ENV environment variable configured in Cloud Run
• Field length limits respected (CustomerContext: 512, Description: 35)
• Add logging when creating shipment with CROP marker

Notes

• Frontend already sends CROP markers — backend should use them if present
• If reference/instructions are empty, backend should create its own CROP marker
• UPS tracking number generation unchanged (generated by UPS API)
• This does not affect rate queries, only shipment creation