Copy page

Hyperlocal

Quickstart

Get a Marketplace delivery order live on staging in under 10 minutes.

Authentication

Shadowfax Hyperlocal supports two authentication methods. Staging and production API keys are shared by the Shadowfax team via automated email.

Token Authentication — pass your API token in the Authorization header:

Code
Authorization: Token your_api_token

OAuth2 Authentication — exchange client credentials for a Bearer token (valid 24 hours):

Code
Authorization: Bearer your_access_token

To obtain an OAuth token:

Code
curl -X POST https://hlbackend.staging.shadowfax.in/oauth/token/ \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=your_client_id&client_secret=your_client_secret&grant_type=client_credentials"

IP Whitelisting

Share your IP address list with Shadowfax to access production APIs.

Environments

Environment	Base URL	Purpose
Staging	https://hlbackend.staging.shadowfax.in	Integration testing, development
Production	https://api.shadowfax.in	Live operations

Staging and production use separate credentials. All examples below use the staging base URL.

1. Check Serviceability

Verify that Shadowfax can serve the order before placement. Place the order within a couple of minutes of a successful check.

Code
curl -X PUT https://hlbackend.staging.shadowfax.in/api/v1/order-serviceability/ \
  -H "Authorization: Token your_api_token" \
  -H "Content-Type: application/json" \
  -d '{
    "pickup_latitude": "12.9276526",
    "pickup_longitude": "77.5620661",
    "drop_latitude": "12.897338",
    "drop_longitude": "77.552905",
    "paid": "false",
    "order_value": 250
  }'

See Serviceability for field details.

2. Place an Order

Code
curl -X POST https://hlbackend.staging.shadowfax.in/api/v2/orders/ \
  -H "Authorization: Token your_api_token" \
  -H "Content-Type: application/json" \
  -d '{
    "client_code": "merchant001",
    "order_details": {
      "order_value": 248,
      "paid": "false",
      "client_order_id": "TEST-001"
    },
    "pickup_details": {
      "city": "Delhi",
      "contact_number": "9876543210",
      "name": "Store name",
      "address": "Store address in plain text",
      "latitude": 28.5833332,
      "longitude": 77.0563207
    },
    "drop_details": {
      "city": "Delhi",
      "contact_number": "9987654321",
      "name": "Customer name",
      "address": "Customer address in plain text",
      "latitude": 28.588891,
      "longitude": 77.037531
    },
    "order_items": [
      {
        "id": "29656019",
        "name": "Item name",
        "price": 259,
        "quantity": 1
      }
    ]
  }'

Save the sfx_order_id from the response.

3. Get Order Status

Poll order status or rely on callbacks for updates. Rider location in the response updates every 60 seconds.

Code
curl https://hlbackend.staging.shadowfax.in/api/v2/orders/{sfx_order_id}/status/ \
  -H "Authorization: Token your_api_token"

4. Set Up Callbacks

Share your callback URL with the Shadowfax team for production. In staging, use the Sandbox Testing APIs to simulate status transitions and verify your webhook handler.

See Callbacks for payload formats and best practices.

Next Steps

• Order Lifecycle — understand order states
• Onboarding — staging to production checklist
• API Reference — full endpoint documentation