Refills the sandbox wallet back to ₦1,000,000. Requires an amg_test_ token — live tokens get 403 live_token_not_allowed.

curl -X POST "https://amigo.ng/api/commerce/sandbox/reset-balance/" \
  -H "X-API-Key: $TEST_TOKEN"

# → { "success": true, "data": { "test_balance": 1000000, "display": "₦1,000,000", "livemode": false } }

Body:

{
  "network":       1,              // 1=MTN, 2=Glo, 4=Airtel, 3=9mobile
  "mobile_number": "09012345678",
  "plan":          1001,           // from /plans_catalog.php
  "Ported_number": true            // if MNP'd
}

<?php
$ch = curl_init('https://amigo.ng/api/data/');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'X-API-Key: YOUR_API_TOKEN',
    'Content-Type: application/json',
    'Idempotency-Key: '.bin2hex(random_bytes(16))
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'network'       => 1,
    'mobile_number' => '09012345678',
    'plan'          => 1001,
    'Ported_number' => true
  ])
]);
echo curl_exec($ch);

fetch('https://amigo.ng/api/data/', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_TOKEN',
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({
    network: 1,
    mobile_number: '09012345678',
    plan: 1001,
    Ported_number: true
  })
}).then(r => r.json()).then(console.log);

curl -X POST https://amigo.ng/api/data/ \
  -H "X-API-Key: $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  --data '{"network":1,"mobile_number":"09012345678","plan":1001,"Ported_number":true}'

Paginated product listing with filters.

curl "https://amigo.ng/api/commerce/products/?category=power-banks&in_stock=true&limit=5" \
  -H "X-API-Key: $TOKEN"

{
  "success": true,
  "data": [
    {
      "id": 42,
      "slug": "oraimo-traveler-3-10000mah-power-bank",
      "brand": "oraimo",
      "name": "Oraimo Traveler 3 10000mAh Power Bank",
      "description": "Slim aluminum body with 22.5W fast charge…",
      "price":    { "amount": 14500, "display": "₦14,500", "currency": "NGN", "market": {…} },
      "category": { "id": 5, "slug": "power-banks", "name": "Power Banks" },
      "stock":    { "in_stock": true, "count": 27 },
      "rating":   { "value": 4.6, "count": 312 },
      "images":   [ { "position": 1, "url": "https://res.cloudinary.com/…/traveler-3.jpg" } ],
      "updated_at": "2026-05-16T18:32:11+01:00"
    }
  ],
  "pagination": { "total": 142, "limit": 5, "offset": 0, "has_more": true }
}

Single product. Same shape as a list entry. Use slug for stable URLs in your storefront — slugs don't change when IDs are renumbered.

curl "https://amigo.ng/api/commerce/products/?slug=oraimo-traveler-3-10000mah-power-bank" \
  -H "X-API-Key: $TOKEN"

All 14 consolidated categories with product counts. Useful for rendering a nav or filter sidebar in your storefront.

{
  "success": true,
  "data": [
    { "id": 1, "slug": "charging-accessories", "name": "Charging Accessories", "product_count": 183 },
    { "id": 2, "slug": "power-banks",          "name": "Power Banks",          "product_count": 142 }
  ]
}

Admin-curated product lists for your storefront — "Featured", "New arrivals", "Bestsellers", "Deals", plus any custom lists Amigo's catalog team adds. Use them to populate your home page, category banners, and discover-style surfaces.

The same admin-curated pool is shared across all developer apps, but the products returned to your token are token-seeded random — so two apps built on Amigo's catalog don't show identical home pages. The order is stable per token: same token + same list = same order every call (cache-friendly, consistent customer UX). Different tokens see different subsets.

Discover available lists

Call with no type param to enumerate what's currently active:

curl 'https://amigo.ng/api/commerce/curation/' \
  -H "X-API-Key: $TOKEN"

{
  "success": true,
  "data": [
    { "slug": "featured",    "name": "Featured",     "source_type": "manual",     "description": "Admin-picked highlights.",       "default_limit": 8, "pool_size": 50, "product_count": 12 },
    { "slug": "new",         "name": "New arrivals", "source_type": "new",        "description": "Recently added products.",        "default_limit": 8, "pool_size": 50, "product_count": 23 },
    { "slug": "bestsellers", "name": "Bestsellers",  "source_type": "bestseller", "description": "Top sellers, last 90 days.",      "default_limit": 8, "pool_size": 50, "product_count":  9 },
    { "slug": "deals",       "name": "Deals",        "source_type": "deals",      "description": "Products with market discount.", "default_limit": 8, "pool_size": 50, "product_count": 17 }
  ]
}

Fetch a list's products

Pass type=<slug> (or slug=<slug> — alias) to get the token-seeded subset:

curl 'https://amigo.ng/api/commerce/curation/?type=featured&limit=8' \
  -H "X-API-Key: $TOKEN"

Query params:

type   = slug of the list (required for products; omit to discover)
slug   = alias of `type`
limit  = optional override of the list's default_limit
         (capped server-side at the list's pool_size)

Response (200):

{
  "success": true,
  "data": {
    "list": {
      "slug": "featured",
      "name": "Featured",
      "source_type": "manual",
      "description": "Admin-picked highlights.",
      "default_limit": 8,
      "pool_size": 50
    },
    "products": [
      // Same shape as GET /api/commerce/products/ — id, slug, brand, name,
      // description, price, category, stock, rating, images, updated_at
      { "id": 42, "slug": "...", "name": "...", "brand": "oraimo", "price": {...}, "images": [...], … }
    ]
  }
}

Eligibility filters (server-side):

• List must not be archived.
• If the list has an active_from / active_until window, the current time must be inside it (lets the team schedule "Black Friday picks" etc.).
• Only in_stock = true products surface.
• Pool is capped at the list's pool_size before shuffle; limit is then applied to the shuffle result.

Errors:

404 list_not_found     // slug doesn't exist or list is outside its active window
405 method_not_allowed // only GET is supported
401 invalid_token      // missing or bad X-API-Key

Empty pool (no in-stock products in the list) is 200 with products: [], not a 404 — the list itself exists, it just has nothing to show right now.

Master catalog of the 36 Nigerian states + FCT and their 774 Local Government Areas (called cities in the storefront). Public, no auth, cached 5 minutes — safe to call from a browser checkout flow.

Query parameters:

type        = "states" (default) | "lgas"
state_id    = int                   // optional, when type=lgas
state_code  = "LA" | "KD" | "FCT"   // optional, when type=lgas
search      = "lagos"               // typeahead across both — returns {states:[…], lgas:[…]}

List states:

curl 'https://amigo.ng/api/commerce/locations.php?type=states'

{
  "success": true,
  "data": [
    { "id": 25, "code": "LA", "name": "Lagos",  "capital": "Ikeja",   "region": "South-West",    "sort_order": 250 },
    { "id": 19, "code": "KD", "name": "Kaduna", "capital": "Kaduna",  "region": "North-West",    "sort_order": 190 }
    // …35 more rows
  ],
  "count": 37
}

List cities in a state:

curl 'https://amigo.ng/api/commerce/locations.php?type=lgas&state_code=KD'

{
  "success": true,
  "data": [
    { "id": 142, "state_id": 19, "name": "Kaduna North", "slug": "kaduna-north", "is_capital": 1, "state_code": "KD", "state_name": "Kaduna" },
    { "id": 155, "state_id": 19, "name": "Zaria",        "slug": "zaria",        "is_capital": 0, "state_code": "KD", "state_name": "Kaduna" }
    // …21 more rows
  ],
  "count": 23
}

Typeahead search:

curl 'https://amigo.ng/api/commerce/locations.php?search=zar'

{
  "success": true,
  "query":   "zar",
  "states":  [],
  "lgas":    [
    { "id": 155, "name": "Zaria", "state_code": "KD", "state_name": "Kaduna" }
  ]
}

Quote shipping for a cart at a specific address. Returns prices for both Standard and Home delivery (premium) tiers plus an ETA range, so your checkout can show the customer their options before they commit. Same resolver as create order — the quote you show is what they'll be charged.

Body:

{
  "state_code": "KD",          // or "state_id": 19
  "lga_name":   "Zaria",       // optional · or "lga_id": 155
  "items": [
    { "product_id": 1, "quantity": 2 },
    { "product_id": 5, "quantity": 1 }
  ]
}

Up to 100 line items. quantity isn't used for pricing (delivery is per scheme, not per unit) but is required for shape consistency with /orders/.

curl -X POST https://amigo.ng/api/commerce/delivery/quote/ \
  -H "Content-Type: application/json" \
  --data @quote.json

Success (200):

{
  "success": true,
  "data": {
    "location": {
      "state_id":   19,
      "state_code": "KD",
      "state_name": "Kaduna",
      "lga_id":     155,
      "lga_name":   "Zaria"
    },
    "serviceable": true,
    "schemes": [
      {
        "scheme_id":       1,
        "scheme_name":     "Default Domestic",
        "product_ids":     [1, 5],
        "product_count":   2,
        "all_free":        true,
        "serviceable":     true,
        "tier_resolution": "state",    // 'lga' | 'state' | 'fallback' | 'free'
        "standard": { "price": 1500, "free_for_customer": true,  "eta_min": 0, "eta_max": 2 },
        "premium":  { "price": 5000,                              "eta_min": 0, "eta_max": 2 }
      }
    ],
    "totals":   { "standard": 0, "premium": 5000 },
    "eta":      { "min": 0, "max": 2 },
    "warnings": []
  }
}

Resolution chain — for each unique scheme in the cart, the resolver walks:

1. LGA-specific scheme group covering the customer's LGA   →  tier_resolution: "lga"
2. State-level scheme group covering the customer's state  →  tier_resolution: "state"
3. The scheme's "rest of Nigeria" fallback row             →  tier_resolution: "fallback"
4. No match found                                          →  serviceable: false

Products with no scheme assigned aggregate into a single scheme_id: null bucket and are always free (tier_resolution: "free").

Unserviceable (200 with serviceable=false): when a scheme in the cart doesn't ship to the customer's area, the quote still returns 200 so the UI can show which scheme failed. Order create returns 422 unserviceable_delivery for the same cart — see below.

Create a paid order. Your wallet is debited inline; if the balance is short, the order is not created and you get 422 insufficient_balance. Prices are snapshotted from the catalog at order time, so you can't be surprised by a price change between read and write.

Body:

{
  "customer": {
    "name":  "Aisha Bello",       // required, ≤ 120 chars
    "phone": "08012345678",       // required, ≤ 20 chars
    "email": "aisha@example.com"  // optional
  },
  "delivery": {
    "address":    "Plot 12, Sabon Gari, off PZ Road",  // required
    "state_code": "KD",                 // optional · or "state_id": 19
    "lga_name":   "Zaria",              // optional · or "lga_id": 155
    "tier":       "standard",           // optional · "standard" (default) or "premium"
    "city":       "Zaria",              // optional legacy free-text — auto-filled from lga_name
    "state":      "Kaduna",             // optional legacy free-text — auto-filled from the resolved state
    "notes":      "Call on arrival"
  },
  "items": [
    { "product_id": 42, "quantity": 1 },
    { "product_id": 8,  "quantity": 2 }
  ]
}

Up to 50 distinct line items per order; quantities 1–1000.

Success (201):

{
  "success": true,
  "data": {
    "id":            1037,
    "reference":     "AMG-COM-20260520-AB12CD",
    "status":        "paid",
    "payment_state": "paid",
    "subtotal":     { "amount": 29000, "display": "₦29,000" },
    "delivery_fee": { "amount":     0, "display": "₦0" },
    "total":        { "amount": 29000, "display": "₦29,000" },
    "customer":     { "name": "Aisha Bello", "phone": "08012345678", "email": "aisha@example.com" },
    "delivery": {
      "address":      "Plot 12, Sabon Gari, off PZ Road",
      "city":         "Zaria",
      "state":        "Kaduna",
      "state_id":     19,
      "lga_id":       155,
      "scheme_id":    1,
      "scheme_name":  "Default Domestic",
      "tier":         "standard",
      "was_free":     true,
      "eta_min_days": 0,
      "eta_max_days": 2,
      "breakdown": [
        { "scheme_id": 1, "scheme_name": "Default Domestic", "tier": "standard", "price": { "amount": 0, "display": "₦0" }, "eta_min_days": 0, "eta_max_days": 2, "product_count": 2 }
      ],
      "notes":        "Call on arrival"
    },
    "items":        [ { "product_id": 42, "name": "Oraimo Traveler 3 …", "quantity": 1, "unit_price": {…}, "line_total": {…} }, … ],
    "created_at":   "2026-05-20 03:12:08",
    "paid_at":      "2026-05-20 03:12:08"
  }
}

On legacy orders (no state_id/lga_id sent), delivery.scheme_id, delivery.tier, delivery.was_free, and delivery.eta_* are all null and breakdown is an empty array.

Unserviceable delivery (422): the cart resolves to a scheme that doesn't ship to the given area, and the scheme has no "rest of Nigeria" fallback configured.

{
  "success":  false,
  "error":    "unserviceable_delivery",
  "message":  "One or more products in the cart can't ship to Zaria, Kaduna. Call POST /api/commerce/delivery/quote/ first to see which.",
  "warnings": ["Scheme 'Lagos Metro Only' does not ship to this area."]
}

Invalid delivery location (422): bad state_id / state_code / lga_id. The response carries a field hint pointing at the offending key.

{
  "success": false,
  "error":   "invalid_delivery_location",
  "field":   "state_code",
  "message": "state_code 'XYZ' is not recognised"
}

Insufficient balance (422):

{
  "success":  false,
  "error":    "insufficient_balance",
  "message":  "Wallet balance is below the order total.",
  "required": 29000,
  "balance":  12500
}

Fetch one of your own orders. Another merchant's reference returns 404 not_found.

Paginated list of YOUR orders, newest first.

curl "https://amigo.ng/api/commerce/orders/?status=shipped&limit=10" \
  -H "X-API-Key: $TOKEN"

Register a URL that should receive event POSTs. The plaintext signing secret is returned once in this response — store it then; later GETs will never include it.

{
  "url":    "https://your-app.com/amigo/webhook",  // required, http(s), ≤ 512 chars
  "events": "*"                                    // "*" all, "order.*" prefix, or "order.shipped,order.delivered"
}

{
  "success": true,
  "data": {
    "id":     12,
    "url":    "https://your-app.com/amigo/webhook",
    "events": "*",
    "status": "active",
    "secret": "a3f1…64-char hex…"     // ← save this NOW
  },
  "message": "Save this secret now — it will not be shown again."
}

List your registered endpoints (no secrets). Pass ?id=N for one endpoint plus its 20 most recent delivery attempts (status, attempts, response code, scheduled retry).

Update url, events, or status (active/disabled). Disabled endpoints stop receiving new events but keep their delivery history.

Permanently remove the endpoint and its delivery history (FK cascade).