Fayj API

Build your shipping workflow with Fayj.

Compose routes, create shipments and synchronise tracking with a REST API designed for commercial operations.

Base URLhttps://api.fayj.net/v1HTTPS

Authentication

Create an API key from the client portal. Keep it exclusively on your server and send it with every request using the Bearer scheme.

Authorization

Authorization: Bearer fj_live_your_key
Content-Type: application/json
Idempotency-Key: your-unique-operation-id

A complete key is displayed only once. Store it in a secrets manager.

Route configuration

Configure one active rule for every destination country. Fayj applies it to manual creation, API calls and integrations. You can provide a one-off override for a shipment.

POST /routing-profiles

{
  "destination_country": "FR",
  "selection_mode": "AUTOMATIC",
  "preference": "RECOMMENDED",
  "fallback_enabled": true
}

Quotes

Send the addresses and parcel characteristics. Response amounts are expressed in cents and route options expire after twenty minutes.

POST /quotes

curl https://api.fayj.net/v1/quotes \
  -H "Authorization: Bearer fj_live_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quote-order-24091" \
  -d '{
    "origin": { "country": "MA", "city": "Casablanca" },
    "destination": { "country": "FR", "postal_code": "75011", "city": "Paris" },
    "parcels": [{ "weight_kg": 5, "length_cm": 30, "width_cm": 20, "height_cm": 15 }]
  }'

200 OK

{
  "quote_id": "qt_01JFA8Q9K2",
  "currency": "EUR",
  "expires_at": "2026-09-14T16:40:00Z",
  "options": [{
    "route_option_id": "route_01JFA8V4G1",
    "service": "FAYJ_PRIORITY",
    "amount_minor": 2475,
    "estimated_days": 5
  }]
}

Shipments

Create the shipment with the selected option, customs information and your own references. The Idempotency-Key prevents duplicates during network retries.

POST /shipments

{
  "route_option_id": "route_01JFA8V4G1",
  "external_reference": "ORDER-24091",
  "recipient": {
    "name": "Maison Ardoise",
    "street": "18 rue Oberkampf",
    "postal_code": "75011",
    "city": "Paris",
    "country": "FR"
  },
  "customs": {
    "description": "Cotton clothing",
    "value": 120,
    "currency": "EUR",
    "country_of_origin": "MA"
  }
}

Tracking

Retrieve a normalised status and one consistent timeline, regardless of the partner executing each transport leg.

GET /shipments/{shipment_id}/tracking

{
  "shipment_id": "shp_01JFB2M6WQ",
  "status": "IN_TRANSIT",
  "events": [{
    "status": "LINEHAUL",
    "location": "Tangier, MA",
    "occurred_at": "2026-09-14T08:20:00Z"
  }]
}

Webhooks

Subscribe your system to shipment changes. Verify the HMAC signature before processing the event and respond within five seconds.

shipment.status_changedShipment status updated

shipment.deliveredDelivery confirmed

shipment.exceptionAction required

Integrations

E-commerce connectors turn a fulfilment-ready order into a Fayj draft, apply the country routing rule and send tracking updates back to the store.

Explore all integrations

Shopify

Admin API + webhooks

Create a custom app, grant read access to orders and write access to fulfilments, then enter the credentials in Fayj.

Authenticate the store
Map product and customs data
Test and enable synchronisation

WooCommerce

REST API

Generate a read/write REST key, configure the store URL and select the order status that triggers import.

Authenticate the store
Map product and customs data
Test and enable synchronisation

Magento

Adobe Commerce REST

Create an integration with order and shipment permissions, activate it and connect its access token.

Authenticate the store
Map product and customs data
Test and enable synchronisation

Etsy

OAuth 2.0

Authorise the Etsy shop, select which orders to import and enable automatic tracking-number updates.

Authenticate the store
Map product and customs data
Test and enable synchronisation