⚡Developer Documentation

AMANA ERP API

Build integrations, automate workflows, and extend AMANA with our REST and GraphQL APIs. Full GCC data residency. Rate limited, versioned, and production-ready.

OpenAPI Spec (JSON)Quick start

Quick start

Get your API token from Settings → API & Integrations in your AMANA dashboard, then make your first request:

bash
curl https://api.amana.io/products \
  -H "Authorization: Bearer YOUR_API_TOKEN"
json
{
  "items": [
    {
      "id": "a1b2c3...",
      "name": "Classic Polo Shirt",
      "brandId": "f0e1d2c3-...",
      "brand": { "id": "f0e1d2c3-...", "name": "Al Noor", "slug": "al-noor" },
      "status": "active",
      "createdAt": "2025-01-15T10:00:00Z"
    }
  ],
  "total": 84,
  "page": 1,
  "limit": 20
}

Authentication

All requests must include a Bearer token in the Authorization header. Tokens are scoped to a single tenant and can be revoked at any time.

bash
Authorization: Bearer amana_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
⚠️ Never expose your API token in client-side code or public repositories. Use environment variables and server-side requests only.

Rate limits

The API enforces rate limits per tenant to ensure fair usage:

LimitValue
Per minute60 requests
Burst30 req/second
Exceeded response429 Too Many Requests

GraphQL

AMANA exposes a read-optimized GraphQL endpoint alongside REST. Use the same Bearer token. In development, GraphiQL is available at /graphql on your API host (e.g. http://localhost:3001/graphql).

bash
curl http://localhost:3001/graphql \
  -H "Authorization: Bearer YOUR_JWT_OR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ tenant { id name } products(limit: 5) { total items { id name sku } } }"}'
graphql
query WorkflowStatus($id: ID!) {
  workflowInstance(id: $id) {
    id
    businessKey
    status
    currentNodeId
    processKey
  }
  workflowInstances(status: "running") {
    id
    businessKey
    status
  }
}

MVP queries: tenant, products, customers, salesOrders, workflowInstances, formDefinition. Manage API keys under Settings → Integrations or /developer/api-keys.

Webhooks

Subscribe to events and receive real-time HTTP POST notifications to your endpoint. Each delivery is signed with HMAC-SHA256 using your endpoint secret.

Available events

order.createdorder.status_changedorder.deliveredinventory.low_stockinventory.adjustedpayment.receivedpayment.failedcustomer.createdgrn.confirmedreturn.completedpos.transaction.completedemployee.hiredemployee.terminated

Verify signature

typescript
import crypto from 'crypto'

function verifyWebhook(payload: string, signature: string, secret: string): boolean {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex')
  return `sha256=${expected}` === signature
}

// In your Express/Fastify handler:
app.post('/webhooks/amana', (req, res) => {
  const signature = req.headers['x-amana-signature'] as string
  const isValid = verifyWebhook(req.rawBody, signature, process.env.WEBHOOK_SECRET)
  if (!isValid) return res.status(400).send('Invalid signature')

  const { event, data } = req.body
  console.log('Received event:', event, data)
  res.send({ received: true })
})

TypeScript SDK

Use the official @amana/sdk package for typed API access:

bash
npm install @amana/sdk
typescript
import { createClient } from '@amana/sdk'

const amana = createClient({ apiKey: 'amana_live_...' })

// List products
const { items } = await amana.products.list({ status: 'active' })

// Create customer
const customer = await amana.customers.create({
  name: 'Fatima Al Mansouri',
  email: 'fatima@example.ae',
  countryCode: 'AE',
})

// Check low stock
const stock = await amana.inventory.getStock({ lowStock: true })

// Subscribe to webhook events
const webhook = await amana.webhooks.createEndpoint({
  name: 'My integration',
  url: 'https://myapp.com/webhooks',
  events: ['order.created', 'inventory.low_stock'],
})

Zapier Integration

Connect AMANA to 6,000+ apps through Zapier without writing code.

Triggers

  • • New POS sale completed
  • • New customer created
  • • Low stock alert
  • • New sales order

Actions

  • • Create customer
  • • Create CRM task
  • • Adjust inventory

Endpoint reference

GET/productsList all products
POST/productsCreate a product
GET/inventory/stockGet stock levels
GET/customersList customers
POST/customersCreate a customer
GET/sales-ordersList sales orders
GET/pos/transactionsList POS transactions
POST/webhooks/endpointsRegister webhook
GET/marketplace/appsList marketplace apps
GET/zapier/auth/testZapier auth test

Full endpoint reference available in the OpenAPI spec.