Shipping providers

Openfront's ShippingProvider model and features/keystone/utils/shippingProviderAdapter.ts support:

• local modules such as shippo, shipengine, and manual;
• independently deployed HTTP adapter apps configured per operation.

The five operation fields cover rate lookup, address validation, label creation, tracking, and cancellation. When a field begins with http, Openfront sends that route a JSON POST containing the provider and operation arguments. Otherwise, it imports the matching local file under features/integrations/shipping.

This configuration-driven route selection is intentional. It allows a merchant to connect a carrier, warehouse, aggregator, local courier, or custom shipping service without changing Openfront source.

Data boundary

Shipping profiles and options define store policy. Fulfillment providers, methods, labels, fulfillments, and fulfillment items record execution. The adapter translates the selected order, address, parcel, rate, or tracking context to its external service and returns a provider-neutral result.

The current callers query accessToken and send the selected provider object to the adapter. For an HTTP adapter, that means the configured app becomes a trusted credential and customer-data processor. Restrict route configuration, authenticate Openfront to the app, minimize forwarded fields, redact logs, validate responses, and apply outbound destination controls appropriate to the deployment.

Current source gaps

The backend operation fields are usable through a trusted administrative path, but both custom-provider UI paths are incomplete:

• the order-level form collects an API URL and stores it under metadata.apiUrl without assigning the operation fields;
• the provider drawer assigns the local token custom, but no matching features/integrations/shipping/custom.ts exists.

Do not claim a custom provider is connected merely because one of those forms creates a record. Verify the actual operation fields and execute each intended route.

Verification before enabling a provider

1. Confirm each configured operation destination and payload from current source.
2. Prove only an authorized operator can read credentials or change routes.
3. authenticate Openfront-to-adapter calls and reject replay where relevant.
4. validate order, address, parcel, line-item, rate, and provider relationships.
5. validate adapter JSON before writing fulfillment or label records.
6. make label purchase and cancellation idempotent.
7. reconcile uncertain provider outcomes before retrying.
8. deduplicate tracking updates and preserve operator recovery.

Manual fulfillment

Manual shipping can record an operator-managed fulfillment without a carrier API. It should remain explicit and must not fabricate carrier tracking events.

Start with Add a shipping adapter.