StoreFleet API

1. StoreFleet switches the API on for your store. Ask us at jake@storefleet.com.
2. The store owner opens Settings > API in StoreFleet, creates a key, names it after the app that will use it, and ticks the permissions it needs.
3. Copy the key when it appears. It is shown once.
4. Make your first call. It answers with the store and what the key may do.

curl https://storefleet.com/api/v1/me \
  -H "Authorization: Bearer sf_live_your_key"

{
  "store": {
    "id": "8d3f0c3e-6c55-4d9b-9b0e-6a3f2a1b7c10",
    "name": "Luxury Box",
    "slug": "luxurybox",
    "timezone": "America/New_York"
  },
  "credential": {
    "id": "1b7e5d2a-0f43-4a3c-9a3b-2b1c9c4e8f01",
    "name": "Store dashboard",
    "kind": "key",
    "mode": "live"
  },
  "scopes": [
    "read:orders",
    "read:metrics"
  ]
}

Every address in this guide starts with https://storefleet.com/api/v1. The full list is in the endpoint reference and the OpenAPI file.

Send the key in the Authorization header of every request: Authorization: Bearer sf_live_.... Never put a key in a URL. A key belongs to one store, so you never pass a store id: the key decides which store you see.

A test key answers a write with 200 and { "dry_run": true, "operation", "result" }, where result shows what the call would have done. Build with a test key, then switch to a live one.

• Keep a key like a password. Anyone holding it can do what its permissions allow.
• The owner can revoke a key in Settings > API. It stops working on the very next call.
• A missing or wrong key answers 401 unauthorized. If the API is not switched on for the store, calls answer 403 api_disabled.
• An app that many stores connect to uses OAuth instead of keys. See Connect an app. Its access tokens go in the same header.

A key or app holds a list of permissions. Each endpoint needs one. A call without it answers 403 insufficient_scope with required_scope naming the one it needed.

Two permissions are never given by default. The owner ticks each one by name for each key or app: read:contact_info, which lets customer phone numbers and emails leave StoreFleet, and send:messages, which lets your program text customers from the store's number.

• HTTPS only. JSON in, JSON out.
• GET and DELETE take query parameters. POST, PUT and PATCH take a JSON body with Content-Type: application/json, up to 64 KB.
• Ids are StoreFleet ids. An id from another store answers 404, the same as one that does not exist.
• Every object carries an object field naming its kind, such as contact, order or message.
• Times are ISO 8601 strings.
• Customer phone numbers and emails are null unless the key holds read:contact_info.
• Every response carries an X-Request-Id header. Quote it when you ask us about a call.

List endpoints answer newest first, one page at a time: { "data": [...], "has_more": true, "next_cursor": "..." }. Ask for up to limit rows (50 by default, 200 at most). For the next page, send cursor set to the next_cursor you got. When has_more is false, next_cursor is null and you have every row.

Treat a cursor as opaque and pass it back as it came. Rows added between your calls never repeat or go missing.

let cursor = null;
do {
  const url = new URL("https://storefleet.com/api/v1/contacts");
  url.searchParams.set("limit", "200");
  if (cursor) url.searchParams.set("cursor", cursor);

  const res = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.STOREFLEET_KEY}` },
  });
  const page = await res.json();
  for (const customer of page.data) {
    // use the customer
  }
  cursor = page.has_more ? page.next_cursor : null;
} while (cursor);

A failure answers with an HTTP status and one shape. Branch on code; the message is for people and may change.

{
  "error": {
    "code": "insufficient_scope",
    "message": "this call needs the read:orders permission",
    "request_id": "req_Xz3k9QmW2pLr7TbV",
    "required_scope": "read:orders"
  }
}

Retry a 429 after Retry-After seconds, and a 500 or 503 after a growing wait. Other errors will answer the same way again until the request changes.

Every response reports the per-minute window in RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds until it resets). Past a limit, calls answer 429 rate_limited with a Retry-After header in seconds.

A write that times out leaves you unsure whether it happened. Send an Idempotency-Key header with any unique string for that action (1 to 255 letters, digits, or - _ : .). If you retry with the same key and the same request, StoreFleet answers with the first outcome instead of doing it again.

• The same key while the first request is still running answers 409 conflict. Try again shortly.
• The same key with a different request answers 409 idempotency_conflict.
• A server error (5xx) is not remembered, so a retry runs again.
• Keys are remembered for at least 48 hours.
• Required on: POST /messages. Accepted on every other write except these, which are never replayed: POST /webhook-endpoints, POST /webhook-endpoints/{id}/rotate-secret, POST /webhook-endpoints/{id}/test.

POST /api/v1/messages

Needs send:messages, which is off unless the owner ticks it, and an Idempotency-Key header. The text goes through the same checks as every text the store sends. Nothing about the API skips them:

• Customers who opted out, or who are kept out of automatic texts, are never texted.
• Quiet hours: texts go out only between 9am and 9pm, store time.
• The store's daily limit. It resets at midnight, store time.
• No repeating the same words to one customer within 24 hours.
• The customer needs a mobile number on file.

curl -X POST https://storefleet.com/api/v1/messages \
  -H "Authorization: Bearer sf_live_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: restock-4471-jordan-4" \
  -d '{
    "contact_id": "5b1e7c2a-3d4f-4a6b-8c9d-0e1f2a3b4c5d",
    "body": "Hi Sam, the Jordan 4 in size 10 you asked about just came in."
  }'

{
  "error": {
    "code": "send_refused",
    "message": "it is outside the store's texting hours (9am to 9pm store time)",
    "request_id": "req_Lq8vN2cR5sYw1HdK",
    "reason": "quiet_hours"
  }
}

A refusal is an answer, not a fault. Do not retry around it. With a test key the call checks the customer and their number and sends nothing.

StoreFleet can post an event to your server when something happens. Add an endpoint in Settings > API, or with POST /webhook-endpoints (permission manage:webhooks). Its signing secret, whsec_..., is shown once. Events arrive within about a minute.

An endpoint only receives events its creator's permissions can read. Each event names the row it is about, and data.object has the same shape the matching endpoint answers. If the row is gone, data.object is null and data.deleted is true. Phone numbers and emails appear only when the endpoint was set to include them, which needs read:contact_info.

{
  "id": "evt_5f0c2b8e9d4a4c1b8a7e6d5c4b3a2f10",
  "object": "event",
  "type": "inquiry.created",
  "created_at": "2026-10-04T15:02:11.000Z",
  "store_id": "8d3f0c3e-6c55-4d9b-9b0e-6a3f2a1b7c10",
  "data": {
    "object": {
      "id": "2c9a4e1b-7f3d-4b5a-9e8c-1d2f3a4b5c6d",
      "object": "inquiry",
      "contact_id": "5b1e7c2a-3d4f-4a6b-8c9d-0e1f2a3b4c5d",
      "first_name": "Sam",
      "last_name": null,
      "phone": null,
      "email": null,
      "product": "Jordan 4 Bred",
      "size": "10",
      "status": "open",
      "kind": "source",
      "source": "form",
      "match_preference": "similar",
      "matched_product": null,
      "matched_at": null,
      "notified_at": null,
      "closed_at": null,
      "close_reason": null,
      "converted": false,
      "converted_order_id": null,
      "submitted_at": "2026-10-04T15:01:58.000Z",
      "created_at": "2026-10-04T15:01:58.000Z"
    }
  }
}

Check the signature

Every delivery carries three headers, in the Standard Webhooks format: webhook-id (the event id), webhook-timestamp (unix seconds) and webhook-signature (v1, then a base64 HMAC-SHA256 of id.timestamp.body). The HMAC key is the part of your secret after whsec_, base64-decoded. Refuse any delivery more than five minutes old. Any Standard Webhooks library will do this for you; here it is in plain Node:

import crypto from "node:crypto";

// secret:  the endpoint's signing secret, whsec_...
// headers: the request's headers, with lowercase names
// rawBody: the body exactly as it arrived, before any JSON parsing
export function verifyStoreFleetWebhook(secret, headers, rawBody) {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  const signatures = headers["webhook-signature"];
  if (!id || !timestamp || !signatures) return false;

  // Refuse a delivery more than five minutes from now.
  const ts = Number(timestamp);
  const now = Math.floor(Date.now() / 1000);
  if (!Number.isInteger(ts) || Math.abs(now - ts) > 300) return false;

  // The key is the part after whsec_, base64-decoded.
  const key = Buffer.from(secret.slice("whsec_".length), "base64");
  const mac = crypto
    .createHmac("sha256", key)
    .update(`${id}.${ts}.${rawBody}`, "utf8")
    .digest("base64");
  const expected = Buffer.from(`v1,${mac}`);

  // The header may carry several signatures, separated by spaces.
  return signatures.split(" ").some((candidate) => {
    const got = Buffer.from(candidate);
    return got.length === expected.length && crypto.timingSafeEqual(got, expected);
  });
}

Answering and retries

• Answer with any 2xx within 10 seconds. Redirects are not followed.
• Anything else is a failure. The event is tried again after waits of 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours, 1 day, 1 day: 9 tries in all, over about three days.
• The same event can arrive twice. Use webhook-id to skip one you already handled.
• A retried event can arrive after a newer one. Order by created_at.
• An endpoint that fails every delivery for 3 days is switched off. The owner turns it back on in Settings, or you send PATCH /webhook-endpoints/{id} with active set to true.

If you build an app that many stores use, have each owner connect it instead of pasting a key. This is standard OAuth 2.1 with PKCE. The owner signs in to StoreFleet, sees your app's name and the permissions it asks for, and approves. The two sensitive permissions stay off unless the owner ticks them. The owner can disconnect your app at any time in Settings > API.

• Your client id can be the https address of a small JSON file you host describing your app (a client ID metadata document), or one you get by registering at the address above.
• PKCE with S256 is required. Redirect addresses must be https, or http on your own machine for local tools.
• Ask for permissions in scope, separated by spaces, using the names in the permissions table.
• Access tokens last 1 hour. Refresh tokens last 60 days and change every time you use one: keep the new one, the old one stops working.
• Send the access token as Authorization: Bearer ..., the same as a key.

StoreFleet runs an MCP server, so an AI assistant can read the store and act for the owner with the same permissions and rules as the API.

Server address: https://storefleet.com/api/mcp

• Assistants with a Connect button: add the address as a custom connector. The assistant sends the owner to StoreFleet to approve it, the same as connecting an app.
• Assistants that take a header: add the address and send a key as Authorization: Bearer .... Start with a test key, so anything the assistant writes or texts is a dry run.

{
  "mcpServers": {
    "storefleet": {
      "url": "https://storefleet.com/api/mcp",
      "headers": { "Authorization": "Bearer sf_test_your_key" }
    }
  }
}

Every endpoint, generated from the same list the API runs on. The same reference as a machine-readable file: /api/v1/openapi.json.

• Account
• Customers
• Team
• Orders
• Products
• Requests
• Texts
• Pricing
• Metrics
• Webhooks

{
  "store": {
    "id": "8d3f0c3e-6c55-4d9b-9b0e-6a3f2a1b7c10",
    "name": "Luxury Box",
    "slug": "luxurybox",
    "timezone": "America/New_York"
  },
  "credential": {
    "id": "1b7e5d2a-0f43-4a3c-9a3b-2b1c9c4e8f01",
    "name": "Store dashboard",
    "kind": "key",
    "mode": "live"
  },
  "scopes": [
    "read:orders",
    "read:metrics"
  ]
}

{
  "data": [
    {
      "id": "5a1f7c2e-3b8d-4e6a-9c0f-1d2e3f4a5b6c",
      "object": "team_member",
      "name": "Leah",
      "role": "Sales associate",
      "location": "buckhead",
      "active": true,
      "former_at": null,
      "created_at": "2026-08-01T15:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

{
  "range": {
    "from": "2026-09-01T00:00:00.000Z",
    "to": "2026-10-01T00:00:00.000Z"
  },
  "orders": 88,
  "revenue": 41200,
  "average_order": 468.18,
  "texts_sent": 640,
  "replies": 212,
  "requests": 37,
  "requests_converted": 9,
  "price_changes": 54
}