Priority1 LTL Freight¶

Priority1 LTL freight rate quotes with pallet calculation, carrier filtering, per-product freight class, hazmat, and NMFC support. Priority1 is a freight broker: one quote request returns competing carrier quotes identified by SCAC code, and Vectis maps each valid quote to a checkout rate option. Use this extension when you ship heavy or palletized orders that need live less-than-truckload freight pricing at checkout.

What It Provides¶

• Live LTL rate quotes — registers a ShippingCalculatorStrategy named priority1 that calls the Priority1 v2 API (POST /v2/ltl/quotes/rates, X-API-KEY auth) and returns one rate per valid broker carrier quote, sorted by price. Rate names render as <Carrier> LTL (<n> days) when transit days are known.
• Pallet calculation — converts cart items into Priority1 pallet line items in three modes: simple (aggregate by weight with volume-based stack height), per_product_dims (also splits when an item exceeds the pallet footprint), and cubbing (3D bin-packing via the platform cubing engines, falling back to simple mode on failure).
• Per-product freight data via traits — on activation the extension seeds four product trait definitions: LTL Freight Class (enum, NMFC classes 50–500), LTL Hazardous Material (boolean), NMFC Item Code, and NMFC Sub Code. Values assigned to products flow into the pallet line items.
• Suggested freight class — an optional freight_class_strategy mode that calls POST /v2/ltl/quotes/suggestedclass per item, using weight and dimensions.
• Accessorial services — liftgate, residential, limited-access, and appointment delivery (API codes LGDEL, RESDEL, LTDDEL, APPT) are forwarded when the quote request carries accessorial codes, and the priority1AccessorialPricing GraphQL query computes the per-accessorial price delta against a base quote.
• GraphQL admin operations — queries priority1Status and priority1AccessorialPricing; mutations testPriority1Connection (single test quote) and discoverPriority1Carriers (test quotes across 7 US routes to collect available carrier SCAC codes, merged with the built-in KNOWN_LTL_CARRIERS registry).
• Carrier-method seeding — a seed_carrier_methods hook runs on every provider save: it creates one ShippingMethod per SCAC in allowed_carriers (display name from KNOWN_LTL_CARRIERS), re-enables previously disabled ones, and disables — rather than deletes — methods whose SCAC was removed, preserving zone assignments and audit trail.

Setup¶

1. Create (or edit) a shipping provider with carrier code priority1 under Settings > Shipping > Providers & Methods.
2. Enter the API key from your Priority1 account representative and choose the environment (dev = https://dev-api.priority1.com, live = https://api.priority1.com).
3. Click Test Connection — this runs the testPriority1Connection mutation, which validates the key with a single test quote.
4. Click Discover Carriers to run discoverPriority1Carriers, then pick the SCACs you want offered via the allowed_carriers checkbox picker (blank = all carriers).
5. Optionally assign the LTL Freight Class, LTL Hazardous Material, and NMFC traits to individual products; products without a freight class trait use the configured default_freight_class.

See Shipping & Fulfillment for how carrier strategies, zones, and methods fit together.

Configuration Reference¶

This extension declares no manifest config_schema. All settings live in the shipping provider's config (the ShippingProvider.config column for the provider whose carrier code is priority1), edited from Settings > Shipping > Providers & Methods. The keys read by the extension:

When pallet_mode is cubbing, the provider's packing configuration (ShippingProvider.packing_config, e.g. engine: vectis_3d) is merged in and drives the bin-packing engine.

For local development the extension falls back to the PRIORITY1_API_KEY and PRIORITY1_ENVIRONMENT environment variables when no enabled provider row carries an api_key.

Operational Notes¶

• Response caching — successful API responses are cached in Valkey for 10 minutes, keyed on a hash of the request path and body, to reduce API calls during checkout rate recalculation. If Valkey is unavailable, calls go straight to the API.
• Pickup date — computed as the next business day in the America/Phoenix timezone: a weekday before 3 PM quotes same-day pickup, otherwise the next weekday.
• Fallback behaviour — API errors (including 401 invalid key, 403, and 429 rate-limit responses), empty quote lists, and fully filtered carrier lists all fall back to the single flat rate when fallback_enabled is set and fallback_rate is greater than 0; otherwise no LTL rates are offered.
• Freight class aggregation — when multiple items share a pallet, the pallet is quoted at the highest (most expensive) freight class among its items; a pallet containing any hazmat-flagged item is quoted as hazardous.
• Zero-weight items — items without weight log a warning and make the pallet estimate inaccurate; give LTL products real weights.
• transit_days_padding only changes the displayed method name (e.g. "3 days" becomes "5 days"); the underlying estimate fields keep the carrier's transit days.
• suggested freight-class strategy cost — it makes one suggestedclass API call per cart item that has no per-product freight class trait (responses are cached like rate calls).