Eekaam App Developer API Reference

The Eekaam App Ecosystem lets third-party developers build apps that merchants install from the Eekaam marketplace. Once installed, an app authenticates with an OAuth-style access token and calls the Admin API to read or write a store's products, orders, customers, themes, and more — all scoped to the merchant that installed it.

This document is the canonical reference for every endpoint an app developer can call.

1. Concepts

Hosts and base URLs

The platform is multi-tenanted by hostname. All API URLs in this document use the merchant store's host — for example, a merchant on acme.eekaam.com will hit https://acme.eekaam.com/admin/api/2026-05/.... The Admin API is also mirrored under /api/apps/admin/2026-05/... for compatibility, and the OAuth endpoints are mirrored under /api/admin/oauth/....

API version

The current Admin API version is 2026-05. It is embedded in the URL path:

https://{shop}.eekaam.com/admin/api/2026-05/{resource}

2. Registering an app

Apps are created from the developer portal (/dev/apps in the web app, backed by /api/developer/apps). When you create an app you get back:

• client_id — public identifier (UUID-shaped)
• client_secret — shown once, store it immediately
• redirect_urls — at least one HTTPS URL the OAuth flow will redirect to
• requested_scopes — the scope list merchants will be asked to approve

The developer-portal endpoints (auth: developer session cookie) are:

3. OAuth installation flow

Apps use a standard OAuth 2.0 authorization-code flow. There are two mirrored prefixes — pick one and stick with it:

• /admin/oauth/...
• /api/admin/oauth/...

3.1 Begin authorization

Redirect the merchant's browser to:

GET https://{shop}.eekaam.com/admin/oauth/authorize
  ?client_id={client_id}
  &redirect_uri={your_redirect_url}
  &state={opaque_csrf_token}

Eekaam validates the client_id, checks the app is approved, and verifies the redirect URI against the app's allow-list. If the merchant approves the install, the browser is redirected back to your redirect_uri with:

?code={authorization_code}
&state={same_state_you_sent}
&tenant={tenant_uuid}
&shop={shop_subdomain_or_domain}

Always verify the returned state matches what you sent. Authorization codes expire after 5 minutes and can be used once.

3.3 Verify embedded session (optional, for embedded apps)

If your app runs inside an iframe in the merchant dashboard, Eekaam mints a short-lived JWT that proves the calling user is logged in. Verify it server-side before trusting the request:

POST https://{shop}.eekaam.com/admin/oauth/session/verify
Content-Type: application/json

{
  "client_id":     "{client_id}",
  "client_secret": "{client_secret}",
  "session_token": "{jwt_from_the_iframe}"
}

Response includes app_id, install_id, tenant_id, user_id, shop, scopes, and expires_at.

4. Authentication

Every Admin API request must include the bearer access token:

Authorization: Bearer shpat_xxxxxxxxxxxxxxxxxxxx

On every request, the server:

1. Looks up the install by hashed token.
2. Confirms the install is active.
3. Confirms the install was granted the scope required by the route.

Failures return:

• 401 Unauthorized — missing/invalid token, install uninstalled
• 403 Forbidden — scope not granted, body includes "scope": "<required>"

Tenant ID is always derived from the install record; you cannot escape your tenant by sending a different tenant_id.

5. Rate limiting

The Admin API is rate-limited to 40 requests per second per access token.

When you exceed the limit Eekaam responds with:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{ "error": "API rate limit exceeded", "retry_after": "1s" }

Back off and retry. Bursts within the budget are fine.

6. Scope reference

The exact scope strings the API recognises:

Request only the scopes you need — fewer scopes means higher merchant install conversion and a smaller blast radius if the token leaks.

7. Admin API reference

Base URL: https://{shop}.eekaam.com/admin/api/2026-05 (or /api/apps/admin/2026-05). All endpoints require Authorization: Bearer.

Pagination convention for list endpoints:

• Query params: page (default 1), limit (default 50, max 250)
• Response: { "<resource>": [...], "pagination": { "page", "limit", "total", "pages" } }

7.1 Shop

7.3 Orders (read-only)

Preloads Items and ShippingAddress.

7.4 Customers (read-only)

Returns a PII-limited projection: id, tenant_id, first_name, last_name, email, phone, accepts_marketing, created_at, updated_at.

7.8 Discounts

Body fields match the Discount model — title is required; method defaults to "code"; starts_at defaults to now if omitted.

7.9 Markets

Responses preload ShippingZones and PaymentConfigs. On create, name is required; slug is auto-generated from name if omitted, and currency_code defaults to PKR.

7.11 Metaobjects

Create body requires definition_id and handle; status defaults to active.

7.13 Analytics

8. Webhooks

8.1 Supported topics

app/uninstalled       — the merchant uninstalled your app (always delivered, even after delete)
orders/create         — a new order was placed
orders/updated        — an order changed (fulfillment, status, line items, etc.)
products/create
products/update
products/delete
customers/create
customers/update

Trying to subscribe to anything else returns 400 Unsupported webhook topic.

8.3 Headers Eekaam sends

8.5 Retry policy

If the endpoint responds with a non-2xx status, or fails to respond within 10 seconds, Eekaam retries with exponential backoff up to 8 attempts over roughly a 16-hour window. Any 2xx response — including an empty body — counts as success. Payloads are retained for 72 hours; failed deliveries can be manually replayed from the dev portal's deliveries page.

A sustained-high failure rate auto-disables the subscription and fires the app/webhook_subscription_disabled event.