Bagster REST API

https://bagster.io/api/v1

All partner routes live under /api/v1/*. There is no /api/v2 today. Unversioned admin routes are not for partner integrations.

Send your API key on every partner request via the X-API-Key header. Bearer tokens are for Supabase user sessions (carrier dashboard / org seats), not for API keys.

• yk_live_… — production keys
• yk_test_… — sandbox keys (sandbox carriers only)
• bgst_… — legacy prefix (still accepted)

curl -H "X-API-Key: yk_live_…" \
  "https://bagster.io/api/v1/carriers/quote?origin_country=Turkey&destination_country=Nigeria&weight_kg=5"

Keys are issued by Bagster ops (Admin → API keys). Treat them like passwords; rotate if exposed.

Pass Idempotency-Key (UUID recommended) so retries do not double-create work.

• Required: cancel, bulk-create, carrier accept / claim
• Optional (honored when present): /orders/create, /shipments, update-status

curl -X POST "https://bagster.io/api/v1/orders/cancel" \
  -H "X-API-Key: yk_live_…" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{ "tracking_number": "BGT-…", "reason": "Customer cancelled" }'

Origin must be Turkey or China when provided. Destination must be an African country name supported by the platform. Provide weight_kg or packages[] with positive weight.

Required body

Optional

origin_country, carrier_id, service_tier, order_reference, external_reference_id, tracking_pin, dimensions, HS code, declared value, delivery instructions, quote_id.

curl -X POST "https://bagster.io/api/v1/orders/create" \
  -H "X-API-Key: yk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "origin_country": "Turkey",
    "destination_country": "Nigeria",
    "weight_kg": 5,
    "customer_name": "Ada Okonkwo",
    "customer_phone": "+234…",
    "customer_address": "Lagos, Nigeria",
    "order_reference": "ORD-12345"
  }'

There is no POST /api/v1/orders alias — use /orders/create.

Query parameters (all required): origin_country, destination_country, weight_kg.

GET /api/v1/carriers/quote?origin_country=Turkey&destination_country=Nigeria&weight_kg=5

Response includes quotes[] with carrier_id, name, price_per_kg, total_price, estimated_days, and markup_rate when applicable. For structured address-based rating use POST /rates.

Partner machine tracking requires your API key. Envelope shape: { success, data }. You can also use GET /orders/{tracking_number}.

Recipients use the public page /track with optional PIN unlock for PII via /api/public/track-unlock. There is no unauthenticated /api/v1/track/… route.

curl -H "X-API-Key: yk_live_…" \
  "https://bagster.io/api/v1/tracking/BGT-ABC123XYZ"

Outbound webhooks are configured on your API key (URL + signing secret). Payloads are signed with X-Webhook-Signature: sha256=<hex>. Monitor delivery via GET /webhooks/health or Partner → Webhooks health.

There is no POST /webhooks registration endpoint. Store intake uses connector routes (Shopify / WooCommerce HMAC) and /webhooks/inbound for registered partners.

Typical outbound events include order.created, order.assigned, order.status_changed, order.delivered, order.cancelled.

Bagster settles carrier payouts and partner invoicing through the admin payments desk (manual operator action). Partner APIs do not move funds.

• Cash-on-delivery (COD) is not supported
• Mobile-money / cash payout rails are not selectable
• POST /payments/retry returns 410 Gone

See /reliability for the honest production surface.

Carrier marketplace routes (available / accept / claim / reject) use a carrier session, not a partner API key. Interactive OpenAPI: /docs.

Canonical error envelope (newer routes): { success: false, error: { code, message, requestId? } }. Some older handlers may still return { error }.

• Partner API key: 1000 requests / hour
• Rates endpoints: 60 requests / minute
• Public tracking helpers: rate-limited separately (do not scrape)

API questions: api@bagster.io. General support: support@bagster.io.

Versioning policy lives in-repo at docs/API_VERSIONING.md. Partner honesty surface: /reliability.