Developer platformBearer API keys/api/v1

Developers

REST APIs and outgoing webhooks for banks, ERP vendors, logistics partners, and third-party apps integrating with urutiMall.

Get API keys Reference OpenAPI

Base path

/api/v1

Auth

Bearer sk_live_…

Events

Webhooks

Rate limit

60 req/min

Overview

What you can build with /api/v1.

The urutiMall API is a RESTful HTTP API versioned under /api/v1. It enables:

ERP / inventory sync

Push stock counts by SKU. Pull order queues in real time.

Logistics integration

Fetch orders ready for pickup. Push tracking and delivery status.

Banking & fintech

Query transaction history, settlements, and payout schedules.

Event-driven workflows

Receive order.paid, order.shipped, and inventory.low events.

Authentication

Bearer tokens from your vendor dashboard.

All API requests must include a Bearer token in the Authorization header. Generate keys from Vendor Dashboard → Developer API.

curl https://urutiMall.com/api/v1/orders \
  -H "Authorization: Bearer sk_live_your_key_here"

Security: API keys are shown only once at creation. Store them in environment secrets, never in source code. Keys can be revoked instantly from the dashboard.

Scopes

Least-privilege access per key.

Each API key is issued with a specific set of scopes. A key with * has full access.

Scope	Grants access to
`read:orders`	GET /api/v1/orders, GET /api/v1/orders/:id
`read:products`	GET /api/v1/products
`write:inventory`	POST /api/v1/products (stock sync)
`write:fulfillment`	PATCH /api/v1/orders/:id (tracking + status)
`read:analytics`	Reserved: analytics endpoints (coming soon)
`*`	All of the above

API reference

Core partner endpoints.

GET/api/v1/ordersread:ordersList orders (paginated)

GET/api/v1/orders/:idread:ordersFetch a single order with items

PATCH/api/v1/orders/:idwrite:fulfillmentPush tracking number / status

GET/api/v1/productsread:productsList products with variant inventory

POST/api/v1/productswrite:inventorySync stock count by SKU

GET /api/v1/orders

Returns a paginated list of orders for the authenticated vendor.

Query params

Param	Default	Description
`status`	-	Filter by PENDING, PAID, SHIPPED, DELIVERED, CANCELLED
`page`	1	Page number
`limit`	50	Per page (max 100)

# Example response
{
  "data": [
    {
      "id": "clx...",
      "status": "PAID",
      "total": 49.99,
      "customerEmail": "buyer@example.com",
      "items": [{ "product": { "name": "Solar Lamp", "sku": "SL-001" }, "quantity": 2 }],
      "createdAt": "2025-06-01T09:00:00Z"
    }
  ],
  "meta": { "page": 1, "limit": 50, "total": 142, "pages": 3 }
}

PATCH /api/v1/orders/:id

Logistics partners use this to push tracking info and update delivery status.

curl -X PATCH https://urutiMall.com/api/v1/orders/clx... \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "status": "SHIPPED", "trackingNumber": "RW123456789", "carrier": "Aramex" }'

POST /api/v1/products

ERP systems use this to sync stock counts. Pass variantSku to target a specific variant.

# Update a variant
curl -X POST https://urutiMall.com/api/v1/products \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "sku": "LAMP-001", "variantSku": "LAMP-001-RED", "stockCount": 45 }'

# Update product-level inStock (no variant)
curl -X POST https://urutiMall.com/api/v1/products \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "sku": "LAMP-001", "stockCount": 0 }'

Webhooks

Signed HTTPS callbacks for subscribed events.

Register an HTTPS endpoint in your Vendor Dashboard. We POST a signed JSON payload to your URL whenever a subscribed event occurs.

Available events

order.paidOrder confirmed and payment received.

order.shippedStatus updated to SHIPPED.

order.deliveredOrder marked as delivered.

order.cancelledCancelled (payment failed or refunded).

order.return_requestedCustomer requested a return.

inventory.lowA variant dropped to low stock.

settlement.completedVendor payout completed.

Payload structure

{
  "event": "order.paid",
  "timestamp": "2025-06-01T09:00:00.000Z",
  "data": {
    "orderId": "clx...",
    "checkoutRef": "uruti_1234567_abc",
    "total": 49.99,
    "customerEmail": "buyer@example.com"
  }
}

Verifying signatures

Every request includes an X-Uruti-Signature header: an HMAC-SHA256 hex digest of the raw body using your endpoint signing secret.

// Node.js verification example
import { createHmac, timingSafeEqual } from "crypto";

function verifyWebhook(rawBody: string, signature: string, secret: string): boolean {
  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
  try {
    return timingSafeEqual(Buffer.from(expected, "hex"), Buffer.from(signature, "hex"));
  } catch {
    return false; // length mismatch = invalid
  }
}

Errors

Standard HTTP codes with JSON bodies.

The API uses standard HTTP status codes and returns JSON error objects.

Code	Meaning
401	Missing or invalid API key
403	API key lacks the required scope
404	Resource not found or not owned by your vendor account
400	Validation error. Check the error message.
422	Business rule violation (e.g. invalid state transition)
429	Rate limit exceeded. Wait Retry-After seconds.
500	Internal server error. Contact support.

{ "error": "Insufficient scope. Required: write:inventory" }

Rate limits

Shared limit across /api/v1.

All /api/v1/* endpoints share a limit of 60 requests per minute per IP. When exceeded, you receive a 429 with a Retry-After header.

HTTP/1.1 429 Too Many Requests
Retry-After: 23

{ "error": "Too Many Requests" }

Need higher limits? Contact api@urutiMall.com.

SDKs

Official clients are on the roadmap.

Official SDKs are coming. Until then, call the API with any HTTP client.

Node.js / TypeScript

Coming soon

Python

Coming soon

PHP

Coming soon

Questions? Email api@urutiMall.com or open a support ticket from your dashboard.

Contact

Welcome back

Loading the marketplace for you…

Scope

Grants access to

read:orders

GET /api/v1/orders, GET /api/v1/orders/:id

read:products

GET /api/v1/products

write:inventory

POST /api/v1/products (stock sync)

write:fulfillment

PATCH /api/v1/orders/:id (tracking + status)

read:analytics

Reserved: analytics endpoints (coming soon)

*

All of the above

Param

Default

Description

status

Filter by PENDING, PAID, SHIPPED, DELIVERED, CANCELLED

page

Page number

limit

Per page (max 100)

# Example response { "data": [ { "id": "clx...", "status": "PAID", "total": 49.99, "customerEmail": "buyer@example.com", "items": [{ "product": { "name": "Solar Lamp", "sku": "SL-001" }, "quantity": 2 }], "createdAt": "2025-06-01T09:00:00Z" } ], "meta": { "page": 1, "limit": 50, "total": 142, "pages": 3 } }

curl -X PATCH https://urutiMall.com/api/v1/orders/clx... \ -H "Authorization: Bearer sk_live_..." \ -H "Content-Type: application/json" \ -d '{ "status": "SHIPPED", "trackingNumber": "RW123456789", "carrier": "Aramex" }'

# Update a variant curl -X POST https://urutiMall.com/api/v1/products \ -H "Authorization: Bearer sk_live_..." \ -H "Content-Type: application/json" \ -d '{ "sku": "LAMP-001", "variantSku": "LAMP-001-RED", "stockCount": 45 }' # Update product-level inStock (no variant) curl -X POST https://urutiMall.com/api/v1/products \ -H "Authorization: Bearer sk_live_..." \ -H "Content-Type: application/json" \ -d '{ "sku": "LAMP-001", "stockCount": 0 }'

{ "event": "order.paid", "timestamp": "2025-06-01T09:00:00.000Z", "data": { "orderId": "clx...", "checkoutRef": "uruti_1234567_abc", "total": 49.99, "customerEmail": "buyer@example.com" } }

// Node.js verification example import { createHmac, timingSafeEqual } from "crypto"; function verifyWebhook(rawBody: string, signature: string, secret: string): boolean { const expected = createHmac("sha256", secret).update(rawBody).digest("hex"); try { return timingSafeEqual(Buffer.from(expected, "hex"), Buffer.from(signature, "hex")); } catch { return false; // length mismatch = invalid } }

Code

Meaning

401

Missing or invalid API key

403

API key lacks the required scope

404

Resource not found or not owned by your vendor account

400

Validation error. Check the error message.

422

Business rule violation (e.g. invalid state transition)

429

Rate limit exceeded. Wait Retry-After seconds.

500

Internal server error. Contact support.