Open Mercato Shipping and Carrier Integration: Operations and Reconciliation Guide

Four manager choices

Record authority, capability state, evidence, owner, exception path, acceptance and mandatory stop.

Evidence snapshot and legend

Reviewed: 2026-07-14 · branch: develop · revision: 01911d00e28f44cf484d0b1d04860dcfef5370bf · describe: v0.6.5-1202-g01911d00e · root version: 0.6.5 · latest public tag: v0.6.5 · distance: 1,202 commits

Post-tag behavior is labeled current develop. Capability uses exactly four states; evidence uses six separate labels. Readiness has four separate outcomes: verified, conditional, unverified or stop.

• available
• configurable
• custom
• integration-required

• latest public release
• current develop
• current first-party documentation
• specification or plan
• external primary requirement
• editorial recommendation

Nine-record shipping chain

Do not collapse these records into one status. Every implementation must name the system of record, durable identity, status owner, timestamps, update mechanism, sensitive fields, reconciliation key, exception owner and evidence.

Two shipment ledgers need an explicit join

SalesShipment belongs to an order, has SalesShipmentItem quantities, and its sales command recalculates each order line fulfilled quantity. It can carry sales method, dictionary status, carrier name, tracking numbers, shipped and delivered timestamps, declared values, notes, address snapshot and adjustments.

CarrierShipment stores orderId, providerKey, carrierShipmentId, trackingNumber, unifiedStatus, raw carrierStatus, labelUrl or labelData, trackingEvents, lastWebhookAt, lastPolledAt, tenant and organization scope, and lifecycle timestamps. Current carrier creation calls the adapter and persists CarrierShipment; it does not create a SalesShipment or SalesShipmentItem rows and does not update fulfilled quantities.

CarrierShipment is order-linked and has no reviewed salesShipmentId field. The current response enricher chooses the latest carrier shipment per order when decorating sales shipment responses. Multiple sales shipments, parcels or carrier labels therefore require a durable deployment-specific correlation, cardinality, split/merge policy, reconciliation and exception queue. Latest per order provides presentation evidence. Reviewed evidence does not show a one-to-one invariant.

Two operator paths remain separate

The standalone wizard route is an implementation route. It provides no first-class shipping console or proof of pick, pack, address verification, manifest closure, pickup booking, customs, customer self-service, or delivery. Multiple parcels do not provide item-to-parcel mapping, cartonization, or packing enforcement.

Provider inventory records evidence. A listed provider is not confirmed carrier support.

A documentation example, provider key in a test, package name, old release, interface implementation or npm publication supplies no proof that a provider is installed, default, stable, supported, compatible, healthy or production-ready.

Provider-readiness scorecard

For each candidate, classify every row as verified, conditional, unverified or stop with evidence date, target version, owner, limitation and next test. Never average a mandatory stop into a marketing badge.

Outcome, evidence, owner, failure, recovery and acceptance required.

• 1. Package provenance
• 2. Version and peer compatibility
• 3. Install and build
• 4. Database migrations
• 5. Activation in the target app
• 6. Credential model
• 7. Health check
• 8. Carrier contract and account
• 9. Sandbox rates
• 10. Drop-off points
• 11. Shipment creation
• 12. Label formats and print path
• 13. Tracking mapping
• 14. Webhook verification
• 15. Polling recovery
• 16. Cancellation
• 17. Error redaction and support detail
• 18. Observability and alerts
• 19. Orphan and duplicate recovery
• 20. Privacy and retention
• 21. Maintenance ownership
• 22. Support and escalation

Adapter methods define a common integration seam

Verify the concrete provider implementation, credentials, errors, limits and business effect. A method signature does not prove account eligibility, coverage, timeliness or compliance.

• 1. calculateRates: provider services, amount, currency and optional timing signals
• 2. createShipment: provider shipment, tracking and label response
• 3. getTracking: current provider status and events
• 4. cancelShipment: provider cancellation result
• 5. verifyWebhook plus mapStatus: trusted provider event input and normalization
• 6. searchDropOffPoints, optional: provider point results

The create validator requires provider key, UUID-shaped order id, origin, destination, at least one positive-dimension package and service code, and permits label format, contacts, target point, sending method and optional idempotency key. These checks cover input shape. They do not prove carrier address validation, packing truth, dangerous-goods clearance, or service eligibility.

Keep seven shipping-cost records separate

• Provider rate quote
• Operator-selected rate
• Sales shipping adjustment
• Provider charge
• Carrier invoice
• Postage refund or credit
• Accounting posting

A provider rate supplies service code and name, amount, currency, optional estimated days and optional guaranteed-delivery flag for the submitted inputs. It provides no evidence of negotiated validity, taxes, fuel or remote-area surcharges, volumetric weight, duties, customs, insurance, cash on delivery, price expiry, final invoice, or availability at pickup. The selected rate is not stored on CarrierShipment, and no automatic sales shipping-cost adjustment is established.

Record input, expected source, expiry, discrepancy owner, prohibited assumption and reconciliation evidence.

• 1. Contract and account
• 2. Origin
• 3. Destination
• 4. Parcel dimensions and weight
• 5. Service code
• 6. Currency
• 7. Taxes and surcharges
• 8. Volumetric weight
• 9. Quote expiry
• 10. Unavailable service
• 11. Timeout and retry
• 12. Changed final price

Creation idempotency is local and bounded

A scoped unique claim binds idempotency key, provider key, request hash and eventual local shipment id. An equal same-key repeat can return the existing local record; conflicting payload reuse returns conflict; an unresolved concurrent claim conflicts. Selected failures release the claim only when the carrier was not successfully called. If the provider call succeeds and local persistence then fails, the claim is retained to discourage an upstream duplicate.

The reviewed adapter create input does not contain the idempotency key. Provider-side exactly-once behavior and automatic recovery of an upstream shipment without a resolved local row are not established. Require a provider request id or idempotency control where available, request/response correlation, orphan discovery, duplicate-label controls, daily reconciliation, manual recovery and named evidence owners.

Label lifecycle is an operating and data decision

Assign purpose, reader, writer, processor, evidence, incident path and stop condition.

• 1. Provider source and request
• 2. PDF, ZPL or PNG format
• 3. URL or inline data storage
• 4. Reader and download access
• 5. Printer and spool path
• 6. Reprint authorization
• 7. Void and replacement
• 8. Retention period and purpose
• 9. Deletion and export
• 10. Backup and recovery
• 11. Shared-device cleanup
• 12. Incident and evidence owner

CarrierShipment stores labelUrl or labelData directly. Reviewed shipping-carrier files contain no module-specific default encryption map, attachment migration, lawful retention, secure printer, automatic revocation, or deletion behavior. Verify generic platform, storage, infrastructure and provider controls separately.

Treat normalized status as a provider-reported state

Provider events may be delayed, duplicated, missing, out of order, incorrectly mapped or corrected later. Current transition rules permit failed_delivery recovery and guard selected terminal states. Local delivered records a normalized provider-reported state. Reviewed evidence does not show recipient identity, a proof-of-delivery document, customer acceptance, sales completion, revenue recognition, support closure, or accounting close.

GET, refresh, webhook and polling are different controls

Webhook support is provider-dependent and does not guarantee complete, ordered, timely or exactly-once delivery. Provider errors are logged server-side and exposed to callers as generic errors on reviewed paths. This provides bounded redaction. It does not guarantee observability or recovery. Webhook plus polling plus daily reconciliation plus manual recovery is the operating model.

Specify setup, provider event, expected local state, prohibited regression, queue evidence, replay, poll recovery and owner.

• 1. Invalid signature
• 2. Unknown provider
• 3. Unknown shipment
• 4. Duplicate event
• 5. Delayed event
• 6. Out-of-order event
• 7. Terminal-state regression
• 8. Queue outage
• 9. Worker failure
• 10. Replay after recovery
• 11. Polling recovery

Cancellation does not complete physical recall or financial reversal

The hub checks an allowed local transition, sends the provider request, writes the provider result and emits cancellation. Keep the cancellation request, provider acceptance, label void, pickup cutoff, parcel interception, local status, postage credit, SalesShipment reversal, fulfilled quantity, warehouse release, customer notice and accounting result as separate evidence.

Require provider and local evidence, operator outcome, recovery, cost result and reconciliation.

• 1. Before pickup
• 2. After pickup
• 3. After delivery
• 4. Duplicate request
• 5. Provider timeout
• 6. Ambiguous provider response
• 7. Reconciliation after failure

Drop-off points and parcels stay provider and warehouse dependent

Optional searchDropOffPoints can return provider points for query, type or postcode. A result does not prove freshness, geographic completeness, opening hours, accessibility, capacity, persisted selection identity, public checkout UX, or service availability. Persist and reconcile any selected point explicitly.

Pick, pack, stock movement, parcel composition, scans, dimensions, weight and physical handoff remain canonical to the inventory or WMS owner. SalesShipment, fulfilled quantity, SalesReturn, refund, credit memo and invoice remain canonical to sales and finance. Customer email, SMS, message delivery and public tracking UX remain canonical to communications or portal owners. Carrier returned creates none of those outcomes automatically.

Capability and evidence matrix

For every row record one capability state, one evidence label, current surface, provider dependency, limitation, owner, confidence and next test. The reviewed hub provides none of these common shipping-software outcomes by itself.

Default outcome: integration-required until refreshed compatible product or provider evidence proves otherwise.

• 1. Batch label creation
• 2. Wave picking
• 3. Cartonization
• 4. Packing station and scanner workflow
• 5. Printer agent
• 6. Manifests
• 7. Carrier pickup scheduling
• 8. Multi-carrier rate shopping in one request
• 9. Routing rules and service substitution
• 10. Address validation or correction
• 11. Dangerous-goods workflow
• 12. International customs documents
• 13. Duties and taxes
• 14. Insurance and claims
• 15. Cash on delivery
• 16. Proof of delivery
• 17. Branded tracking page
• 18. Proactive customer notifications
• 19. Carrier SLA analytics
• 20. Carrier invoice audit
• 21. Freight, LTL and pallet shipping
• 22. Return labels and customer return portal

Access vocabulary and responsibility matrix

Current features are shipping_carriers.view and shipping_carriers.manage. Default setup grants both to superadmin and admin, and view to employee. Rates, create, cancel and persisted refresh require manage; tracking and point lookup require view. Two feature ids do not provide least-privilege separation among rate shopping, label purchasing, cancellation, label and PII viewing, credential administration, exception recovery, refund approval and carrier-invoice reconciliation. Design and test denied combinations explicitly.

Assign responsible, accountable, consulted and informed roles, backup, segregation, evidence, exception authority and release sign-off.

• 1. Order release
• 2. Warehouse item and parcel truth
• 3. Provider selection
• 4. Credential administration
• 5. Rate policy
• 6. Label access and printing
• 7. Pickup and physical handoff
• 8. Tracking exceptions
• 9. Customer support and notices
• 10. Returns and inspection
• 11. Shipping cost reconciliation
• 12. Privacy and retention
• 13. Security and incident response
• 14. Release acceptance and rollback

Scope, security and sensitive-data register

Credentials resolve through the integration credential service in tenant and organization scope. Tracking lookups require an owned local shipment before provider access; webhook scope derives from stored candidates and verified scoped credentials. These reviewed controls cover the named paths. They do not provide universal assurance for isolation, secure configuration, privacy, retention or carrier compliance.

Assign purpose, minimum collection, reader, processor and transfer, retention, deletion and export, backup, search and log exposure, encryption evidence and incident owner.

• 1. Origin and destination addresses
• 2. Sender and receiver contacts
• 3. Tracking numbers and shipment ids
• 4. Tracking times and locations
• 5. Label data, URLs and barcodes
• 6. Provider credentials and account references
• 7. Application and provider logs
• 8. Provider-held shipment records
• 9. Customer messages and tracking links

Three synthetic architectures

Record ledgers, architecture choice, capability states, provider evidence, owners, failures, reconciliation, acceptance, stops and next step.

Poor fit without additional specialist systems

• Turnkey WMS: the reviewed hub lacks the complete domain workflow, controls, and evidence. Keep the specialist authority or verify an integration for the deployment.
• High-volume packing station: the reviewed hub lacks the complete domain workflow, controls, and evidence. Keep the specialist authority or verify an integration for the deployment.
• International customs: the reviewed hub lacks the complete domain workflow, controls, and evidence. Keep the specialist authority or verify an integration for the deployment.
• Dangerous goods: the reviewed hub lacks the complete domain workflow, controls, and evidence. Keep the specialist authority or verify an integration for the deployment.
• Freight or LTL: the reviewed hub lacks the complete domain workflow, controls, and evidence. Keep the specialist authority or verify an integration for the deployment.
• Route optimization: the reviewed hub lacks the complete domain workflow, controls, and evidence. Keep the specialist authority or verify an integration for the deployment.
• Carrier procurement: the reviewed hub lacks the complete domain workflow, controls, and evidence. Keep the specialist authority or verify an integration for the deployment.
• Customer returns portal: the reviewed hub lacks the complete domain workflow, controls, and evidence. Keep the specialist authority or verify an integration for the deployment.
• Carrier-invoice audit: the reviewed hub lacks the complete domain workflow, controls, and evidence. Keep the specialist authority or verify an integration for the deployment.

Stop or go table

Set verified evidence, owner, threshold, exception, recovery and mandatory stop. Unknown means stop.

• 1. Provider package compatibility
• 2. Carrier contract and credentials
• 3. Order and shipment mapping
• 4. Warehouse authority
• 5. Printer and label path
• 6. Webhook and poll recovery
• 7. Privacy and retention
• 8. Customer support ownership
• 9. Return handoff
• 10. Cost reconciliation
• 11. UAT and failure tests
• 12. Operating steward and backup

Acceptance pack

Specify setup, abstract ids, state sequence, provider and local evidence, failure injection, prohibited outcome, recovery, reconciliation, owner and pass criterion.

• 1. Draft route isolation
• 2. Default module activation
• 3. Official provider activation
• 4. SalesShipment fields
• 5. Shipment-item fulfilled quantity
• 6. CarrierShipment fields
• 7. No salesShipmentId correlation
• 8. Latest carrier per order enrichment
• 9. Manual sales path
• 10. Order-launched wizard
• 11. Destination prefill
• 12. Multiple parcels
• 13. Rate and service selection
• 14. Contacts and point
• 15. Label formats
• 16. Mock-only default provider
• 17. InPost provenance and npm tags
• 18. Target-app compatibility proof
• 19. Adapter methods
• 20. Rate contract cases
• 21. Selected-rate persistence gap
• 22. Address shape versus verification
• 23. Package truth
• 24. Same idempotency key retry
• 25. Conflicting idempotency payload
• 26. Concurrent unresolved claim
• 27. Provider call and local persist failure
• 28. Orphan discovery
• 29. Duplicate-label prevention
• 30. Label access and retention
• 31. Every normalized status
• 32. Allowed transitions
• 33. Terminal regression
• 34. Failed-delivery recovery
• 35. GET tracking read-only
• 36. POST refresh persists
• 37. Poller deployment decisions
• 38. Webhook invalid signature
• 39. Webhook duplicate and ordering
• 40. Queue and worker failure
• 41. Poll recovery
• 42. Cancellation boundaries
• 43. Drop-off point boundaries
• 44. Warehouse authority
• 45. Communications authority
• 46. Returned versus SalesReturn
• 47. ACL and denied combinations
• 48. Tenant and organization scope
• 49. Sensitive-data controls
• 50. Reconciliation and owner sign-off

Mandatory stop conditions

• No compatible and accepted provider adapter.
• No durable order, sales-shipment, parcel and carrier correlation.
• No warehouse handoff owner.
• No label access, print, retention or incident control.
• No webhook, poll and manual recovery path.
• No duplicate or orphan recovery.
• No return and customer-support handoff.
• No rate, invoice and accounting reconciliation.
• Real personal or credential data entered into this worksheet.
• Unknown safety, customs, dangerous-goods or regulatory requirement.

Source ledger and correction path

Claim surface, capability state, evidence label, revision or date, confidence, limitation, public suitability and review owner recorded on 2026-07-14.

• 1. Default app modules and empty official activation at reviewed revision
• 2. Carrier adapter contract and validator
• 3. Shipping service, idempotency and status transitions
• 4. Carrier entity, routes, webhook and workers
• 5. Sales shipment entities and fulfilled-quantity commands
• 6. Carrier response enricher
• 7. First-party shipping-carrier framework documentation
• 8. Latest public Open Mercato v0.6.5 release
• 9. Pinned public official-modules InPost source
• 10. npm metadata observed 2026-07-14
• 11. InPost primary API documentation
• 12. Live English and Polish search results 2026-07-14

Latest reviewed public release · Immutable carrier-hub source · Immutable sales-shipment source · Pinned InPost candidate source · InPost primary API documentation

Report a correction with the exact claim, replacement primary evidence, affected date or revision, operating impact and owner. Search results and package metadata were refreshed in English and Polish on 2026-07-14; they record buyer expectations and discoverability only.