USPS Priority Mail¶

The ext_usps_priority_mail extension adds USPS Priority Mail as a shipping carrier priced entirely from local rate tables — no USPS account, credentials, or API calls, so quotes are instant even for large wholesale carts. It registers a rate-quote strategy under the carrier code usps_priority_mail and quotes weight/zone-based domestic rates, flat-rate box rates, and Priority Mail International, all from seven extension-owned database tables (ported 1:1 from a proven WooCommerce plugin's wp_usps_pm_* schema). It supersedes the retired USPS Flat Rate extension.

What It Provides¶

• A ShippingCalculatorStrategy registered as usps_priority_mail (see Building Extensions for the strategy surface). It quotes up to three services:

  Method code	Service	Est. days
  usps_priority_mail	USPS Priority Mail (weight/zone)	1–3
  usps_priority_mail_flat_rate	USPS Priority Mail Flat Rate	1–3
  usps_priority_mail_international	USPS Priority Mail International	6–10

• Seven rate tables owned by the extension (own Alembic chain, revision usppm0001): ext_usps_priority_mail_boxes, _zones, _zone_exceptions, _pricing, _intl_countries, _intl_pricing, and _intl_flat_pricing.

• A table seeder — seed_from_woo copies a WooCommerce store's wp_usps_pm_* tables wholesale (see Setup).
• Quotes surface through the storefront shippingRatesForCheckout GraphQL query, which routes every zone-assigned method without a flat rate to the carrier strategy matching the provider's carrier code.

Rating algorithm¶

The math is pinned by unit tests to the source WooCommerce plugin's semantics:

• Zone resolution — the destination ZIP is matched against 5-digit exception ranges first, then 3-digit prefix ranges; exceptions win (e.g. an APO ZIP inside a stateside 3-digit range re-zones correctly). Fewer than 3 digits, or an uncovered prefix, means no zone and no weight/zone rate.
• Billable weight — ceil(actual) with a 1 lb floor; when the package volume exceeds 1,728 cu in, dimensional weight ceil(L×W×H / 166) applies and the higher of the two bills.
• Domestic weight/zone price — per package, the first (zone, weight_not_over) bracket the billable weight fits; a package with no bracket makes the whole weight/zone rate unserviceable. Geometry surcharges are added per box: longest dimension over 30″ ($21.00 default), over 22″ ($4.50 default), volume over 3,456 cu in ($35.00 default).
• Flat rate — per package, the cheapest enabled flat-rate box it fits, rotation-aware (a 9.5×12.5 mailer fits a 12.5×9.5 envelope) and weight-capped, at the commercial or retail price tier (commercial by default). Every package must fit some box or the flat rate is not offered. The flat-rate quote does not depend on zone resolution.
• International — the destination country maps to a Priority Mail International price group (pmi_group 0 = no service); each package prices by (group, weight_not_over) bracket, and any package over the country's hard max_weight limit suppresses the rate entirely.
• Handling fee — "" = none, "2.50" = fixed, "5%" = percent of cart value; added once per domestic rate (not to international).

Setup¶

1. Once installed (or dev-linked in development), the extension is discovered at startup via its usps_priority_mail entry point. Per-channel enablement is managed under Settings > Extensions.

2. Seed the rate tables — the tables ship empty, and empty tables quote nothing. Copy them from a WooCommerce store running the source plugin:

   docker exec vectis-api-1 python -m \
       vectis.extensions.ext_usps_priority_mail.seed_from_woo \
       "mysql+aiomysql://root:pw@host:3306/woo"
   

   The seeder is idempotent — each target table is truncated and re-filled, so re-running against a fresher dump replaces the data set wholesale.

3. Create a provider under Settings > Shipping > Providers with carrier code usps_priority_mail (requires the settings.edit permission). This extension seeds no methods — unlike UPS or the retired USPS Flat Rate, it has no seed_carrier_methods hook, so add the methods yourself.

4. Add live-rate methods (leave the flat rate field empty) whose codes exactly match the method codes in the table above — the checkout resolver matches returned rates to method rows by code and drops unmatched rates (unless a single live-rate method or a default-style catch-all exists).
5. Assign the methods to shipping zones under Settings > Shipping > Zones — only enabled methods assigned to an enabled zone are quoted.
6. Optionally scope the provider to specific channels, set per-method rate adjustments (fixed amount and/or percent), and configure the provider's packing engine. See Shipping & Fulfillment for the provider / zone / method model.

Configuration Reference¶

The manifest declares no config_schema; there are no extension-level settings. Carrier setup lives on the shipping provider and its methods under Settings > Shipping > Providers (method enablement, estimated days, rate adjustments, packing config).

The strategy class accepts a config dict with these keys, but no configuration path currently populates it — see the warning below:

Permissions¶

The manifest declares no permissions. Provider, method, and zone management in the admin enforces the core settings.edit permission at call time.

Operational Notes¶

• Seed before you quote — no zones seeded means no domestic weight/zone rate, no enabled flat-rate boxes means no flat rate, and no country rows means no international rate. There is no fallback table.
• Domestic vs international routing — destinations US, PR, VI, GU, AS, MP, UM, FM, MH, PW price as domestic; everything else goes through Priority Mail International.
• Packages come from core cubing — the strategy prices whatever the provider's configured packing engine hands it, including the opt-in large-cart volume-approximation fallback (engaged only when the provider's packing_config sets volume_approx_threshold > 0). If packing produces nothing, core falls back to a single 12×12×12 package at total cart weight.
• Rate adjustments apply per method: final = base + amount + base × percent / 100, floored at 0. Per-method estimated days, when set, override the strategy's 1–3 / 6–10 defaults.
• Some seeded columns are not consulted at quote time — the ext_usps_priority_mail_intl_flat_pricing table, box type values other than flat_rate, and the box restriction / box_weight / padding columns are seeded from the source store but not used by the current rating strategy.

Source: ext_usps_priority_mail/ — in the enterprise-extensions repo. (extension.py, strategy.py, calculator.py, models.py, seed_from_woo.py).