Loading...جاري التحميل...

Quickstart

Zero to first order in 10 minutes

Walk through signing up, minting a key, placing a sandbox order, and receiving a signed webhook. Every sample runs as-is.

Create an account

Self-serve signup takes about two minutes — email verification is instant, no manual approval needed.

Create developer account — free

Mint a test API key

In the developer dashboard (Developers → API Keys), mint a new key with the scopes "orders:read orders:write". The full secret is shown once — copy it immediately.

Test keys start with sk_test_ and never touch real inventory or real drivers.

Open API keys dashboard

Make your first call

Export your key and make a harmless list-orders call.

list-orders.sh

export VIA_API_KEY="sk_test_…"

curl https://sandbox.api.via-basket.com/v1/orders \
  -H "Authorization: Bearer $VIA_API_KEY"

Understand the response

List endpoints wrap their results in an envelope. Use `cursor` to paginate.

response.json

{
  "data": [
    {
      "id": "ord_01H9F…",
      "store_id": "store_01H…",
      "status": "created",
      "total_amount": "125.00",
      "currency": "AED",
      "created_at": "2026-04-17T09:12:30Z"
    }
  ],
  "cursor": null
}

Create a sandbox order

Create accepts a list of items and a delivery coordinate. Use an Idempotency-Key header so retries are safe.

create-order.sh

curl -X POST https://sandbox.api.via-basket.com/v1/orders \
  -H "Authorization: Bearer $VIA_API_KEY" \
  -H "Idempotency-Key: order-abc-123" \
  -H "Content-Type: application/json" \
  -d '{
    "store_id": "store_01H...",
    "items": [{"sku": "BRD-001", "qty": 2}],
    "delivery": {"lat": 30.0444, "lng": 31.2357}
  }'

Set up a webhook endpoint

Register your HTTPS endpoint and subscribe to the event types you care about. VIA returns the signing secret once — store it safely.

create-webhook.sh

curl -X POST https://sandbox.api.via-basket.com/v1/webhooks \
  -H "Authorization: Bearer $VIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/via",
    "events": ["order.created", "order.status_changed", "order.delivered"],
    "description": "Production dispatch integration"
  }'

Verify HMAC signatures

Every delivery carries an X-VIA-Signature header of the form t=<ts>,v1=<hex>. Verify before trusting the body.

verify.ts

import express from 'express';
import { verifySignature } from '@via/sdk';

const app = express();

app.post(
    '/hooks/via',
    express.raw({ type: 'application/json' }),  // raw body is load-bearing
    (req, res) => {
        const sig = req.header('X-VIA-Signature') ?? '';
        if (!verifySignature(req.body, sig, process.env.VIA_WEBHOOK_SECRET!)) {
            return res.status(400).end();
        }
        const event = JSON.parse(req.body.toString());
        // …fulfil event…
        res.status(204).end();
    },
);

Always pass the *raw* bytes — any JSON reformatting breaks the signature.

Go live

Back in the developer dashboard, mint a `sk_live_…` key. Swap the environment variable — no code change needed. The SDKs auto-detect the host from the key prefix.

Monitor usage

The Developers → Usage dashboard shows daily request counts, rate-limit hits, and billing period status. We email an alert at 80% of your monthly quota.

Open usage dashboard

Upgrade your plan

Approaching your limits? Upgrade in one click from your portal settings (Manage billing button).

Manage billing View plans

What next?

Dive into the full reference or browse every webhook event type.

API Reference Webhook catalogue