🗂️ Overview

Everything a merchant can do in the NUMU dashboard, your code can do over HTTP. Predictable URLs, standard verbs, JSON in and out, and one token you mint yourself.

Quickstart

A token, a read, a safe write and a webhook — in order.

Authentication

Mint a scoped token and make your first call.

Webhooks

Receive order and product events, signed and retried.

Endpoint reference

Every endpoint, with snippets in four languages.

Errors & limits

What failures look like and how often you can call.

Partner apps

Build an app that many merchants install from the App Store.

Base URL

https://numueg.app/api/v1

https://api.numueg.app/api/v1 serves the same API. Every path in these docs is relative to that base, and every endpoint returns JSON.

Who can use it

API access is included in the Pro plan. On any other plan NUMU can switch it on for your store — ask, and we enable it per merchant without a plan change. GET /stores/{store_id}/access-tokens/access says where a store stands.

Your first call

Mint a token in the dashboard under Settings → API & webhooks, then ask the API who you are. If this returns your store, everything else will work.

cURL

JavaScript

Python

PHP

How responses are shaped

Every successful response is wrapped:

{
  "success": true,
  "data": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "Ceramic mug" },
  "message": "Product created"
}

Read data; treat message as human-readable text that may change. Lists add pagination alongside it — see Pagination.

Failures carry an error object and the HTTP status that matters:

{
  "success": false,
  "error": { "code": "HTTP_ERROR", "message": "Access token lacks the 'orders:write' scope" }
}

What is in the API

Area	Scope	Covers
Catalog	`catalog`	Products, variants, inventory, categories, bundles, gift cards
Orders & fulfillment	`orders`	Orders, shipments, waybills, returns, refunds, abandoned checkouts
Customers	`customers`	Customer records and addresses
Marketing	`marketing`	Coupons, promotions, campaigns, WhatsApp, inbox
Analytics	`analytics`	Store metrics, reports, dashboard figures
Online store	`themes`	Themes, pages, menus, the editor
Settings & money	`settings`	Store settings, locations, shipping, payments, invoices

Admin, staff and platform-billing endpoints are not part of the public API and are not reachable with a token.

Machine-readable contract

https://numueg.app/api/v1/public/openapi.json

OpenAPI 3.1, generated from the running API — point a client generator, Postman or Apidog at it. Each operation names the scope it needs in x-numu-scope.

Conventions worth knowing up front

Trailing slashes are load-bearing. Collection routes are written /orders/, item routes /orders/{order_id}. Send them exactly as documented; the API does not redirect between the two.

Money is minor units. Amounts are piasters (EGP ×100) unless a field says otherwise.

IDs are UUIDs. Store, order, product and customer ids are all UUID strings.

Times are UTC, ISO 8601.

A token belongs to one store. Working across several stores means one token per store.

Base URL#

Who can use it#

Your first call#

How responses are shaped#

What is in the API#

Machine-readable contract#