Skip to content

AfterShip

Multi-carrier shipment tracking and delivery notifications via AfterShip. The extension ships an async client for the AfterShip Tracking API (v2024-10) and two Temporal workflows: an on-demand workflow that registers a tracking number with AfterShip, and a scheduled poll that walks active trackings for status updates. AfterShip covers 1,200+ carriers and acts as the external enrichment source for tracking state.

At a glance
Extension id aftership
Category fulfillment
Version 0.1.0
Provides Temporal workflows + scheduled tracking poll
External account AfterShip account with an API key

What It Provides

  • Tracking registration workflow — AfterShipRegisterTrackingWorkflow, an on-demand workflow that registers a single tracking number with AfterShip (POST /tracking/2024-10/trackings), with optional carrier slug, order id, customer name, and e-mail list. When the carrier slug is omitted, AfterShip auto-detects the carrier.
  • Scheduled tracking poll — AfterShipTrackingPollWorkflow, run by the Temporal schedule vectis-aftership-tracking-poll every 30 minutes. It pages through the account's trackings (100 per page), skips trackings tagged Delivered or Expired, and reports a checked count.
  • AfterShip API client — create / get / delete / list trackings, courier auto-detection (POST /tracking/2024-10/couriers/detect), webhook signature verification, and a test_connection helper that lists couriers (no admin action currently invokes it).
  • Admin settings link — the manifest contributes a Fulfillment settings page entry pointing at /settings/fulfillment.

The workflows, activities, and schedule are declared on the extension via the self-registration methods, so the Temporal worker picks them up without core edits. AfterShip registers no shipping-rate strategy — it is a tracking-only companion to rate-quote carriers; see Shipping & Fulfillment.

Setup

  1. Once installed (or dev-linked in development), the extension is discovered at startup; per-channel enablement is managed under Settings > Extensions. Configure the API key from your AfterShip dashboard.
  2. Set AFTERSHIP_API_KEY (and, if you use webhook verification, AFTERSHIP_WEBHOOK_SECRET) in the Temporal worker's environment. The activities build their API client from these environment variables and raise when AFTERSHIP_API_KEY is unset.
  3. The vectis-aftership-tracking-poll schedule is declared by the extension and created together with the core schedules by python -m vectis.schedules.

Admin config fields are not read by the worker

The configuration schema below renders in the admin, but the current workflow/activity code reads only the AFTERSHIP_API_KEY / AFTERSHIP_WEBHOOK_SECRET environment variables. The admin fields — including api_key, auto_register, tracking_poll_enabled, and poll_interval_minutes — are not consumed by the registration or polling code, and the poll interval is fixed at 30 minutes in the extension's schedule declaration.

Configuration Reference

Key Type Required Secret Description
api_key string Yes Yes AfterShip API key (Settings → API Keys in your AfterShip dashboard)
webhook_secret string No Yes HMAC secret for verifying inbound webhook signatures
auto_register boolean No No Automatically register tracking numbers with AfterShip when fulfillments are created. Default true.
tracking_poll_enabled boolean No No Poll AfterShip for tracking updates on a schedule (fallback when webhooks are unavailable). Default false.
poll_interval_minutes integer No No How often to poll AfterShip for tracking updates (minimum 15). Default 30.
custom_domain string No No Custom domain for branded tracking pages (e.g., track.yourstore.com)
notify_customer_on_update boolean No No Send Vectis notification emails when AfterShip detects a tracking status change. Default false.

Secret fields are stored Fernet-encrypted and masked in the admin.

Permissions

  • fulfillment.aftership.manage

Permissions are upserted at boot from the manifest; assigning them to roles is currently a manual step.

Operational Notes

  • API surface — all calls go to https://api.aftership.com on the versioned /tracking/2024-10/... paths, authenticated with the aftership-api-key header, with a 15-second request timeout.
  • Rate limiting — AfterShip allows 10 requests/second on tracking endpoints; the client retries up to 3 times on HTTP 429, honoring the Retry-After header (fallback backoff 1.5 s × attempt number), and raises once retries are exhausted.
  • The poll is read-only today — the poll activity counts and logs active trackings; it does not yet write tracking state back to Vectis fulfillment records.
  • Nothing auto-starts registration — AfterShipRegisterTrackingWorkflow is registered on the worker, but no core code currently starts it when a fulfillment is created.
  • Webhook verification helper only — the client can verify AfterShip's aftership-hmac-sha256 header (HMAC-SHA256 over the raw POST body), and skips verification — accepting the payload — when no webhook secret is configured. No inbound AfterShip webhook endpoint is mounted in the current backend, and no code currently calls the verification helper.
  • Retries and timeouts — both workflows run their activity with a retry policy of initial 10 s, maximum interval 5 min, maximum 5 attempts; the register activity has a 2-minute timeout, the poll a 10-minute timeout.
  • Tracking tags — tag values surfaced by the list endpoint: Pending, InTransit, OutForDelivery, Delivered, AvailableForPickup, AttemptFail, Exception, Expired, InfoReceived.

For the extension developer view, see Building Extensions.