Skip to main content

Build a third-party logistics application

Use this roadmap when your third-party logistics (3PL) application quotes, accepts, and fulfills delivery jobs for Otter. A certification-ready 3PL flow supports quoting, delivery creation, live updates, update requests, cancellation, errors, and both successful and canceled terminal states.

Quote support is part of this baseline. Confirm the final requirements for your product with your Otter representative before you submit for certification.

Before you begin​

  • Complete the shared readiness baseline.
  • Configure signed delivery webhooks for your application.
  • Define how your delivery ids map to Otter delivery reference ids.
  • Map your courier lifecycle to ALLOCATED, PICKED_UP, COMPLETED, and CANCELED.
  • Define quote expiration, service-level, currency, and estimate behavior.

How it fits​

Quote and delivery creation​

Quote and create a delivery through webhooks and callbacks

Delivery updates and cancellation​

Update a delivery until it completes or is canceled

Implementation roadmap​

1. Quote every supported delivery​

Handle Request delivery quotes (delivery.request_quote). Return available options through POST /v1/delivery/{deliveryReferenceId}/quotes, including stable quote ids and valid estimates.

Make repeated quote requests safe and return explicit errors when your service cannot quote the delivery.

2. Accept and allocate the delivery​

Handle Accept delivery (delivery.accept). Reserve the selected service in your system, then call POST /v1/delivery/{deliveryReferenceId}/accept with committed estimates and status ALLOCATED.

Follow Create a delivery for the complete sequence.

3. Publish live updates​

Call PUT /v1/delivery/{deliveryReferenceId}/status whenever status, address, courier, vehicle, notes, or estimates change. Keep updates ordered and continue until the delivery reaches COMPLETED or CANCELED.

4. Handle update requests​

Process Update delivery request (delivery.update_request), apply supported changes, and reply through POST /v1/delivery/{deliveryReferenceId}/update. See Handle delivery update requests.

5. Handle cancellation​

Process Cancel delivery (delivery.cancel), stop the job when allowed, and reply through POST /v1/delivery/{deliveryReferenceId}/cancel. See Cancel a delivery.

6. Report failures​

When a webhook-triggered operation cannot complete, call POST /v1/delivery/callback/error with the matching delivery reference and actionable details. Follow Handle delivery errors.

Readiness checklist​

  • Quote requests return valid options, estimates, prices, currencies, and stable quote ids.
  • Repeated quote and accept events do not create duplicate reservations or delivery jobs.
  • Accepted deliveries enter ALLOCATED with committed pickup and drop-off estimates.
  • Status updates preserve the delivery reference and follow a valid lifecycle.
  • Courier, vehicle, address, notes, and estimate updates reach the correct delivery.
  • Update requests return a success callback or an explicit error callback.
  • Cancellation succeeds before completion and leaves both systems in CANCELED.
  • Successful delivery reaches COMPLETED in both systems.
  • Webhook signatures, duplicate delivery, rate limits, and retryable API failures are handled.

Test before certification​

  1. Receive a quote request and return at least one valid option.
  2. Replay the quote request and verify that the result remains safe and traceable.
  3. Accept a selected quote and verify that only one delivery job is allocated.
  4. Move the delivery through ALLOCATED, PICKED_UP, and COMPLETED, including courier and estimate updates.
  5. Create a second delivery, apply an update request, then cancel it before completion.
  6. Trigger one unsupported or invalid operation and verify that the error callback identifies the correct delivery.
  7. Replay an accept, update, and cancel event and verify that no duplicate action occurs.

Evidence to collect​

  • Delivery reference ids, quote ids, and provider delivery ids for every tested flow.
  • Quote and accept webhook ids with their callback responses.
  • Ordered status-update evidence for successful and canceled lifecycles.
  • Before-and-after evidence for one delivery update request.
  • Error callback evidence for one expected failure.
  • Signature-validation, duplicate-delivery, retry, and terminal-state logs.
  • The shared evidence listed in Scenarios.

Common failures​

SymptomLikely causeFix
Quote cannot be selectedQuote id expired, changed, or cannot be resolvedKeep quote ids stable for their advertised validity window
Duplicate courier job appearsAccept event was processed more than onceDeduplicate by delivery reference and selected quote before reserving a courier
Update targets the wrong jobProvider id is used without the Otter delivery reference mappingPersist and use both identifiers on every callback and update
Delivery remains in ALLOCATEDStatus publisher stopped or updates were rejectedRetry transient failures and monitor for stale non-terminal deliveries
Cancellation and completion raceTerminal transitions are not serializedApply one terminal state and treat later terminal events idempotently

Next​