https://api.finxa.store/api

{
  "success": true,
  "data": { ... },
  "message": "Product created"
}

{
  "success": false,
  "error": "Product not found"
}

curl https://api.finxa.store/api/products \
  -H "X-Finxa-Access-Token: fxat_your_secret_key_here"

curl -X POST https://api.finxa.store/api/products \
  -H "X-Finxa-Access-Token: fxat_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Premium T-Shirt",
    "status": "ACTIVE",
    "variants": [
      { "title": "Default", "price": 29.99, "inventory": 100 }
    ]
  }'

{
  "success": true,
  "data": {
    "products": [ ... ],
    "pagination": {
      "total": 156,
      "page": 1,
      "limit": 20,
      "totalPages": 8
    }
  }
}

{
  "success": false,
  "error": "Insufficient scopes. Required: write_products"
}

{
  "id": "evt_9f1c2b7a4d3e8f10aa11bb22",
  "topic": "orders/create",
  "api_version": "2026-09",
  "created_at": "2026-09-18T06:20:11.000Z",
  "store_id": "cmu6e4ndz0001…",
  "data": {
    "order": { "id": "cmu6e4nxq005k…", "orderNumber": 1042, "status": "PAID", "total": "24.690", "items": [ … ] }
  }
}

import { createHmac, timingSafeEqual } from "node:crypto";

app.post("/webhooks/finxa", express.raw({ type: "application/json" }), (req, res) => {
  const expected = createHmac("sha256", process.env.FINXA_WEBHOOK_SECRET)
    .update(req.body)              // the raw bytes, not a re-serialised object
    .digest("base64");
  const given = req.get("X-Finxa-Hmac-SHA256") ?? "";
  if (given.length !== expected.length || !timingSafeEqual(Buffer.from(given), Buffer.from(expected))) {
    return res.status(401).end();
  }
  const event = JSON.parse(req.body);
  // Store event.id and skip duplicates — retries redeliver the same id.
  res.status(200).end();           // answer fast; do the work in a queue
});

$raw = file_get_contents('php://input');
$expected = base64_encode(hash_hmac('sha256', $raw, $_ENV['FINXA_WEBHOOK_SECRET'], true));
if (!hash_equals($expected, $_SERVER['HTTP_X_FINXA_HMAC_SHA256'] ?? '')) {
    http_response_code(401);
    exit;
}
$event = json_decode($raw, true);

# On install, register the events your app needs — no dashboard visit required.
curl -X POST https://api.finxa.store/api/app/webhooks \
  -H "X-Finxa-Access-Token: fxat_…" \
  -H "Content-Type: application/json" \
  -d '{ "topic": "orders/paid", "address": "https://yourapp.com/hooks/finxa" }'

# 201 — the signing secret is in the response and is never shown again.
{ "success": true,
  "data": { "id": "…", "topic": "orders/paid", "address": "https://yourapp.com/hooks/finxa",
            "isActive": true, "secret": "9f86d0818…" },
  "warning": "Save the secret now — it signs every delivery (X-Finxa-Hmac-SHA256) and is only shown once." }

# Already subscribed to that topic? 409 with the existing id, so you can update it instead.
{ "success": false, "code": "topic_already_subscribed", "webhookId": "…" }

curl -X POST https://api.finxa.store/api/orders/draft \
  -H "X-Finxa-Access-Token: fxat_…" \
  -H "Idempotency-Key: order-sync-8842" \
  -H "Content-Type: application/json" \
  -d '{ "items": [{ "variantId": "cmu…", "quantity": 1 }], "customerEmail": "[email protected]" }'

# Same key again within 24 h → the stored response, plus:
# Idempotent-Replayed: true

curl https://api.finxa.store/api/products \
  -H "X-Finxa-Access-Token: fxat_…" \
  -H "X-Finxa-API-Version: 2026-09"

# Every response echoes the version it was served with:
# X-Finxa-API-Version: 2026-09

https://api.finxa.store/api/openapi.json

curl "https://api.finxa.store/api/storefront/products?limit=12&sort=created-desc" \
  -H "X-Finxa-Storefront-Token: fxst_…"

{
  "success": true,
  "data": [
    {
      "id": "cmu…", "title": "Racing Polo", "handle": "racing-polo",
      "available": true,
      "price_range": { "min": { "amount": "12.500", "currency": "BHD" }, "max": { "amount": "12.500", "currency": "BHD" } },
      "images": [{ "src": "https://…/polo.jpg", "alt": "Racing Polo", "width": 1600, "height": 1600 }],
      "options": [{ "name": "Size", "values": ["S", "M", "L"] }],
      "variants": [{ "id": "cmu…", "title": "S", "price": { "amount": "12.500", "currency": "BHD" }, "available": true, "options": { "Size": "S" } }]
    }
  ],
  "pagination": { "limit": 12, "has_more": true, "next_cursor": "cmu…" }
}

// 1. create a cart with a first line
const cart = await fetch("https://api.finxa.store/api/storefront/carts", {
  method: "POST",
  headers: { "X-Finxa-Storefront-Token": TOKEN, "Content-Type": "application/json" },
  body: JSON.stringify({ items: [{ variantId: "cmu…", quantity: 2 }] }),
}).then((r) => r.json());

// 2. add / change lines as the shopper browses
await fetch(`https://api.finxa.store/api/storefront/carts/${cart.data.id}/items`, {
  method: "POST", headers, body: JSON.stringify({ variantId: "cmu…", quantity: 1 }),
});

// 3. send the shopper to the hosted checkout
window.location.href = cart.data.checkout_url;
// → https://<your-store-domain>/cart/load?cart=…&token=…  → /checkout

// POST /api/storefront/carts/{id}/discount   { "code": "TEN" }
{
  "success": true,
  "data": {
    "id": "cart_…",
    "subtotal": { "amount": "45.000", "currency": "BHD" },
    "discount": { "code": "TEN", "title": "Ten off", "type": "PERCENTAGE", "value": 10,
                  "amount": { "amount": "4.500", "currency": "BHD" }, "free_shipping": false },
    "discount_error": null,
    "total": { "amount": "40.500", "currency": "BHD" },
    "checkout_url": "https://shop.example.com/cart/load?cart=…&token=…"
  }
}

curl -X POST https://api.finxa.store/api/storefront/shipping/rates \
  -H "X-Finxa-Storefront-Token: fxst_…" -H "Content-Type: application/json" \
  -d '{ "country_code": "BH", "cart_id": "cart_…" }'
# or without a cart: { "country_code": "SA", "subtotal": 40.5, "market_id": "…", "locale": "ar" }

// 1. ask for a code — the shopper gets a 6-digit code by e-mail (10 min, 3 per minute)
await sf("/customers/login/request", { method: "POST", body: JSON.stringify({ email }) });

// 2. exchange the code for a customer token (30 days)
const { data } = await (await sf("/customers/login/verify", {
  method: "POST", body: JSON.stringify({ email, code }) })).json();
localStorage.setItem("customer_token", data.customer_token);   // fxct_…

// 3. call account endpoints with the token
const me = await sf("/customers/me", { headers: { "X-Finxa-Customer-Token": data.customer_token } });
const orders = await sf("/customers/me/orders?limit=20", { headers: { "X-Finxa-Customer-Token": data.customer_token } });

https://api.finxa.store/api/oauth/authorize
  ?client_id=fxca_…
  &scope=read_orders,write_products
  &redirect_uri=https://yourapp.com/oauth/callback
  &state=8f3a…               # random, checked on return
  &code_challenge=…          # optional PKCE (S256)
  &code_challenge_method=S256

curl -X POST https://api.finxa.store/api/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "<code from the callback>",
    "client_id": "fxca_…",
    "client_secret": "fxcs_…",
    "redirect_uri": "https://yourapp.com/oauth/callback"
  }'

# {
#   "access_token": "fxat_…",
#   "token_type": "bearer",
#   "scope": "read_orders write_products",
#   "store": { "id": "cmu…", "handle": "sunglasses-bhr", "name": "Sunglasses BHR", "currency": "BHD" },
#   "app_id": "cmu…",
#   "api_version": "2026-09"
# }

# token response when the app has an access-token lifetime set
{ "access_token": "fxat_…", "token_type": "bearer", "expires_in": 3600,
  "refresh_token": "fxrt_…", "scope": "read_orders write_products", "store": { … }, "app_id": "…" }

# before expires_in runs out (or on a 401): rotate both tokens
curl -X POST https://api.finxa.store/api/oauth/token \
  -H "Content-Type: application/json" \
  -d '{ "grant_type": "refresh_token", "refresh_token": "fxrt_…",
        "client_id": "fxca_…", "client_secret": "fxcs_…" }'
# → a new access_token + refresh_token; the old pair stops working immediately

PUT /api/public-apps/{id}
{
  "listed": true,
  "installUrl": "https://yourapp.com/finxa/install",   // starts your OAuth flow
  "logoUrl": "https://yourapp.com/logo.png",
  "category": "shipping",
  "supportEmail": "[email protected]",
  "description": "Prints labels and syncs tracking numbers.",
  "accessTokenTtlSeconds": null                         // or e.g. 3600 for expiring tokens
}

curl "https://api.finxa.store/api/products?status=ACTIVE&limit=10" \
  -H "X-Finxa-Access-Token: fxat_your_secret_key"

{
  "success": true,
  "data": {
    "products": [
      {
        "id": "cmmm0ekmc0000ny1p7n1vdsbf",
        "title": "Premium T-Shirt",
        "handle": "premium-t-shirt",
        "status": "ACTIVE",
        "description": "A comfortable cotton t-shirt",
        "vendor": "Finxa Apparel",
        "productType": "Clothing",
        "tags": ["summer", "cotton"],
        "images": [],
        "options": [
          { "name": "Size", "position": 0, "values": ["S", "M", "L"] }
        ],
        "weight": null,
        "weightUnit": "kg",
        "isPhysical": true,
        "seoTitle": null,
        "seoDescription": null,
        "publishedAt": "2026-03-10T12:00:00.000Z",
        "createdAt": "2026-03-10T12:00:00.000Z",
        "updatedAt": "2026-03-10T12:30:00.000Z",
        "variants": [
          {
            "id": "clxyz123",
            "title": "Small",
            "sku": "TS-S",
            "barcode": null,
            "price": "29.990",
            "costPrice": "12.000",
            "compareAtPrice": null,
            "inventory": 50,
            "trackInventory": true,
            "taxable": true,
            "requiresShipping": true,
            "options": { "Size": "S" },
            "position": 0,
            "weight": null,
            "weightUnit": "kg"
          }
        ],
        "productImages": [],
        "_count": { "collections": 1 }
      }
    ],
    "pagination": {
      "total": 42,
      "page": 1,
      "limit": 10,
      "totalPages": 5
    }
  }
}

curl "https://api.finxa.store/api/products/cmmm0ekmc0000ny1p7n1vdsbf" \
  -H "X-Finxa-Access-Token: fxat_your_secret_key"

curl -X POST "https://api.finxa.store/api/products" \
  -H "X-Finxa-Access-Token: fxat_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Classic Polo Shirt",
    "description": "A timeless polo in premium cotton.",
    "status": "ACTIVE",
    "vendor": "Finxa Apparel",
    "productType": "Clothing",
    "tags": ["polo", "cotton", "casual"],
    "options": [
      { "name": "Size", "position": 0, "values": ["S", "M", "L", "XL"] }
    ],
    "variants": [
      { "title": "Small",  "price": 35.00, "sku": "POLO-S",  "inventory": 25, "options": { "Size": "S" } },
      { "title": "Medium", "price": 35.00, "sku": "POLO-M",  "inventory": 40, "options": { "Size": "M" } },
      { "title": "Large",  "price": 35.00, "sku": "POLO-L",  "inventory": 30, "options": { "Size": "L" } },
      { "title": "XL",     "price": 37.50, "sku": "POLO-XL", "inventory": 15, "options": { "Size": "XL" } }
    ]
  }'

curl -X PATCH "https://api.finxa.store/api/products/cmmm0ekmc0000ny1p7n1vdsbf" \
  -H "X-Finxa-Access-Token: fxat_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Premium Polo Shirt — Updated",
    "tags": ["polo", "premium", "new-arrival"]
  }'

curl -X DELETE "https://api.finxa.store/api/products/cmmm0ekmc0000ny1p7n1vdsbf" \
  -H "X-Finxa-Access-Token: fxat_your_secret_key"

curl -X POST "https://api.finxa.store/api/products/cmmm0ekmc0000ny1p7n1vdsbf/variants" \
  -H "X-Finxa-Access-Token: fxat_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "XXL",
    "price": 39.99,
    "sku": "POLO-XXL",
    "inventory": 10,
    "options": { "Size": "XXL" }
  }'

curl -X PATCH "https://api.finxa.store/api/products/cmmm0ekmc0000ny1p7n1vdsbf/variants/clxyz123" \
  -H "X-Finxa-Access-Token: fxat_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "price": 32.50,
    "inventory": 75,
    "costPrice": 14.00
  }'

curl -X PUT "https://api.finxa.store/api/products/cmmm0ekmc0000ny1p7n1vdsbf/variants/sync" \
  -H "X-Finxa-Access-Token: fxat_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "variants": [
      { "id": "existing_id_1", "title": "Small",  "price": 29.99, "inventory": 50 },
      { "id": "existing_id_2", "title": "Medium", "price": 29.99, "inventory": 40 },
      { "title": "Large",  "price": 29.99, "inventory": 30 },
      { "title": "XL",     "price": 34.99, "inventory": 20 }
    ]
  }'

curl "https://api.finxa.store/api/collections" \
  -H "X-Finxa-Access-Token: fxat_your_secret_key"

curl -X POST "https://api.finxa.store/api/collections" \
  -H "X-Finxa-Access-Token: fxat_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Summer Collection 2026",
    "description": "Lightweight essentials for the summer season.",
    "collectionType": "MANUAL",
    "sortOrder": "MANUAL"
  }'

curl -X POST "https://api.finxa.store/api/collections/col_abc123/products" \
  -H "X-Finxa-Access-Token: fxat_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "productIds": ["prod_id_1", "prod_id_2"]
  }'

curl "https://api.finxa.store/api/orders?status=PAID&limit=10" \
  -H "X-Finxa-Access-Token: fxat_your_secret_key"

curl -X POST "https://api.finxa.store/api/orders/draft" \
  -H "X-Finxa-Access-Token: fxat_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cust_abc123",
    "items": [
      { "variantId": "var_xyz789", "quantity": 2 }
    ],
    "shippingAddress": {
      "line1": "123 Main St",
      "city": "Manama",
      "country": "BH"
    }
  }'

curl -X PATCH "https://api.finxa.store/api/orders/order_abc123/status" \
  -H "X-Finxa-Access-Token: fxat_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{ "status": "FULFILLED" }'

curl -X PATCH "https://api.finxa.store/api/orders/order_abc123/notes" \
  -H "X-Finxa-Access-Token: fxat_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{ "notes": "Customer requested gift wrapping" }'

curl -X PATCH "https://api.finxa.store/api/orders/order_abc123/shipping" \
  -H "X-Finxa-Access-Token: fxat_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "trackingNumber": "1Z999AA10123456784",
    "trackingUrl": "https://track.example.com/1Z999AA10123456784",
    "trackingCarrier": "Aramex"
  }'

curl -X POST "https://api.finxa.store/api/customers" \
  -H "X-Finxa-Access-Token: fxat_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "firstName": "Ahmed",
    "lastName": "Al-Khalifa",
    "phone": "+97312345678",
    "address": {
      "line1": "Building 42, Road 3601",
      "city": "Manama",
      "country": "BH",
      "postalCode": "0360"
    }
  }'

curl -X POST "https://api.finxa.store/api/discounts" \
  -H "X-Finxa-Access-Token: fxat_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Summer Sale",
    "code": "SUMMER15",
    "type": "PERCENTAGE",
    "value": 15,
    "minimumOrderAmount": 20,
    "startsAt": "2026-06-01T00:00:00Z",
    "endsAt": "2026-08-31T23:59:59Z"
  }'

curl -X POST "https://api.finxa.store/api/shipping/zones" \
  -H "X-Finxa-Access-Token: fxat_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Bahrain Domestic",
    "countries": ["BH"],
    "rates": [
      { "name": "Standard Shipping", "price": 1.500, "minOrderAmount": 0 },
      { "name": "Free Shipping",     "price": 0,     "minOrderAmount": 25 }
    ]
  }'

curl -X POST "https://api.finxa.store/api/pages/YOUR_STORE_ID" \
  -H "X-Finxa-Access-Token: fxat_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "About Us",
    "body": "<h2>Our Story</h2><p>We started in 2024 with a mission to...</p>",
    "published": true
  }'

{ "value": { "code": "ERP-001", "bin": "A-12" }, "type": "json" }

// → 201 on create, 200 on update
{ "success": true, "data": { "id": "…", "namespace": "erp", "key": "sku",
  "value": { "code": "ERP-001", "bin": "A-12" }, "type": "json", "app_id": "app_…",
  "created_at": "2026-09-21T08:00:00.000Z", "updated_at": "2026-09-21T08:00:00.000Z" } }

// 1. ask for a signed upload URL
const { data } = await (await api("/uploads/presign", { method: "POST",
  body: JSON.stringify({ filename: "hero.png", contentType: "image/png" }) })).json();

// 2. PUT the bytes straight to storage (no token needed on this request)
await fetch(data.uploadUrl, { method: "PUT", headers: { "Content-Type": "image/png" }, body: fileBytes });

// 3. attach it to the product by URL
await api(`/products/${productId}/images`, { method: "POST",
  body: JSON.stringify({ src: data.fileUrl, alt: "Hero", position: 0 }) });

{ "name": "Sunglasses BHR", "seoTitle": "Sunglasses in Bahrain", "language": "ar", "ga4MeasurementId": "G-XXXX" }

{ "delta": -2, "reason": "Damaged in warehouse" }
// → { "success": true, "data": { "before": 5, "after": 3 } }  and an inventory_levels/update webhook

{ "title": "Summer drop", "handle": "summer-drop", "body": "<p>…</p>", "excerpt": "New frames.", "tags": ["news"],
  "isPublished": true, "publishedAt": "2026-09-22T09:00:00Z", "coverImage": "https://…/cover.jpg" }

// finxa.ts — a 30-line client: token, versioning, idempotency, pagination
const BASE = "https://api.finxa.store/api";
export class Finxa {
  constructor(private token: string) {}
  async request<T>(method: string, path: string, body?: unknown, idempotencyKey?: string): Promise<T> {
    const res = await fetch(BASE + path, {
      method,
      headers: {
        "X-Finxa-Access-Token": this.token,
        "X-Finxa-API-Version": "2026-09",
        ...(body ? { "Content-Type": "application/json" } : {}),
        ...(idempotencyKey ? { "Idempotency-Key": idempotencyKey } : {}),
      },
      body: body ? JSON.stringify(body) : undefined,
    });
    if (res.status === 429) {                       // rate limited: wait and retry once
      await new Promise((r) => setTimeout(r, Number(res.headers.get("Retry-After") ?? 1) * 1000));
      return this.request(method, path, body, idempotencyKey);
    }
    const json = await res.json();
    if (!res.ok || json.success === false) throw new Error(typeof json.error === "string" ? json.error : JSON.stringify(json.error));
    return json as T;
  }
  get = <T>(path: string) => this.request<T>("GET", path);
  post = <T>(path: string, body: unknown, key?: string) => this.request<T>("POST", path, body, key);
  patch = <T>(path: string, body: unknown) => this.request<T>("PATCH", path, body);
  /** Walk a page/limit list to the end. */
  async *pages<T>(path: string, limit = 100) {
    for (let page = 1; ; page++) {
      const { data } = await this.get<{ data: T[] }>(`${path}${path.includes("?") ? "&" : "?"}page=${page}&limit=${limit}`);
      yield* data;
      if (data.length < limit) return;
    }
  }
}

const finxa = new Finxa(process.env.FINXA_TOKEN!);
for await (const p of finxa.pages<{ id: string; title: string }>("/products?status=ACTIVE")) console.log(p.title);

import os, requests

BASE = "https://api.finxa.store/api"
H = {"X-Finxa-Access-Token": os.environ["FINXA_TOKEN"], "X-Finxa-API-Version": "2026-09"}

def get(path, **params):
    r = requests.get(BASE + path, headers=H, params=params, timeout=30)
    r.raise_for_status()
    return r.json()["data"]

def post(path, body, idempotency_key=None):
    h = {**H, "Content-Type": "application/json"}
    if idempotency_key: h["Idempotency-Key"] = idempotency_key
    r = requests.post(BASE + path, headers=h, json=body, timeout=30)
    r.raise_for_status()
    return r.json()["data"]

for order in get("/orders", status="PAID", limit=50):
    print(order["orderNumber"], order["total"])

# Import into Postman or Insomnia: File → Import → paste the URL
https://api.finxa.store/api/openapi.json

# Generate a typed client in any language (needs Java or Docker)
npx @openapitools/openapi-generator-cli generate \
  -i https://api.finxa.store/api/openapi.json -g typescript-fetch -o ./finxa-client
# other generators: python, go, java, csharp, php, ruby, kotlin, swift5, dart …

# TypeScript types only, no runtime
npx openapi-typescript https://api.finxa.store/api/openapi.json -o finxa-api.d.ts

https://api.finxa.store/api/openapi.json

const API_URL = "https://api.finxa.store/api";
const TOKEN = "fxat_your_secret_key_here";

const headers = {
  "X-Finxa-Access-Token": TOKEN,
  "Content-Type": "application/json",
};

// 1. Create a product
async function createProduct() {
  const res = await fetch(`${API_URL}/products`, {
    method: "POST",
    headers,
    body: JSON.stringify({
      title: "My First Product",
      status: "ACTIVE",
      variants: [
        { title: "Default", price: 19.99, inventory: 50 }
      ],
    }),
  });
  const data = await res.json();
  console.log("Created:", data.data.id);
  return data.data;
}

// 2. List all products
async function listProducts() {
  const res = await fetch(`${API_URL}/products`, { headers });
  const data = await res.json();
  console.log(`Found ${data.data.pagination.total} products`);
  return data.data.products;
}

// 3. Update a product
async function updateProduct(productId) {
  const res = await fetch(`${API_URL}/products/${productId}`, {
    method: "PATCH",
    headers,
    body: JSON.stringify({
      description: "Updated via the API!",
      tags: ["api-managed"],
    }),
  });
  const data = await res.json();
  console.log("Updated:", data.data.title);
}

// Run it
const product = await createProduct();
await updateProduct(product.id);
await listProducts();

import requests

API_URL = "https://api.finxa.store/api"
HEADERS = {
    "X-Finxa-Access-Token": "fxat_your_secret_key_here",
    "Content-Type": "application/json",
}

# Create a product
res = requests.post(f"{API_URL}/products", headers=HEADERS, json={
    "title": "My First Product",
    "status": "ACTIVE",
    "variants": [
        {"title": "Default", "price": 19.99, "inventory": 50}
    ],
})
product = res.json()["data"]
print(f"Created: {product['id']}")

# List all products
res = requests.get(f"{API_URL}/products", headers=HEADERS)
data = res.json()["data"]
print(f"Found {data['pagination']['total']} products")

# Update a product
res = requests.patch(f"{API_URL}/products/{product['id']}", headers=HEADERS, json={
    "description": "Updated via the API!",
    "tags": ["api-managed"],
})
print(f"Updated: {res.json()['data']['title']}")