Admin API conventions

​

Calling it

curl https://api.tassyir.io/apps/2026-10/business \
  -H "Authorization: Bearer $TASSYIR_ACCESS_TOKEN"

{
  "data": {
    "id": "741939488313319175",
    "name": "Dar Amina",
    "currency": "DZD",
    "country": "DZ",
    "timezone": "Africa/Algiers",
    "createdAt": "2026-01-02T03:04:05.000Z"
  }
}

const { data: business } = await admin.get('/business');
const { data: order } = await admin.get('/orders/{id}', {
  path: { id: '741000000000000001' },
  query: { fields: ['orderNumber', 'status', 'total', 'currency'] },
});
console.log(business.timezone, order.status, order.total);

​

Versions

​

Values

• JSON fields are camelCase. Ids are strings: never parse them as numbers. Times are ISO 8601 in UTC (2026-10-11T09:12:44.120Z).
• Money is a decimal string with two decimals ("2500.00") next to a currency field (DZD today), never a number. Keep it a string; for arithmetic, use a decimal library or integer cents, never parseFloat. An amount Tassyir does not know is null, never "0.00". When you send money (a product’s price), send a decimal string too.
• Open vocabularies (an order’s status, a carrier’s status) are strings, not enums: a merchant or a carrier can add values.
• Contact fields (a buyer’s name, phones, email, address, an order’s notes) are present only with read_customer_contact. Without it the keys are absent, not null (Customers and contact data).

​

One resource, and lists

• Lists are newest first and keyset-paged: a row added while you walk a list never shifts the pages to come, and no row is repeated or skipped. New rows appear on a new walk from the first page.
• nextCursor is opaque: never build or edit one. It belongs to its list and its filters; with another list or other filters it is 400 INVALID_CURSOR. nextCursor: null is the last page.
• A page can hold fewer than limit items while nextCursor is set (app data drops values whose owner you can no longer read). Stop on null, not on a short page.
• Unknown parameters are refused (400 VALIDATION_FAILED, naming them): a misspelt filter never silently returns everything.

let pending = 0;
for await (const order of admin.paginate('/orders', {
  query: { status: 'pending', limit: 100, fields: ['id'] },
})) {
  pending += 1;
}
console.log(`${pending} pending orders`);

​

Fields

​

Idempotent writes

await admin.post('/orders/{id}/confirm', {
  path: { id: '741000000000000001' },
  idempotencyKey: 'confirm-741000000000000001',
});

​

Errors

{
  "type": "https://developers.tassyir.io/errors/permission-denied",
  "title": "Permission denied",
  "status": 403,
  "detail": "You do not have permission: orders:read",
  "code": "PERMISSION_DENIED",
  "permission": "orders:read",
  "fix": "Request the read_orders scope in the app's manifest; it applies once the merchant consents to the new version.",
  "requestId": "a1b2c3"
}

• Act on code, never on detail or title: code is stable.
• fix is one sentence saying what to do, when there is one.
• Other members name what was refused: permission, storeId, limit, errors, allowedFields, …
• requestId (also the X-Request-Id header) names the request: quote it when you ask Tassyir for help.
• A 5xx never carries an internal message: retry with backoff.

import { TassyirApiError, type AdminApiErrorCode } from '@tassyir/app';

type ConfirmError = AdminApiErrorCode<'post', '/orders/{id}/confirm'>;

export async function confirm(
  id: string,
): Promise<'confirmed' | 'waiting' | ConfirmError> {
  try {
    await admin.post('/orders/{id}/confirm', { path: { id } });
    return 'confirmed';
  } catch (error) {
    if (!(error instanceof TassyirApiError)) throw error;
    if (error.code === 'ORDER_LIMIT_REACHED') return 'waiting'; // past the plan's allowance
    console.warn(error.code, error.fix, error.requestId);
    return error.code as ConfirmError;
  }
}

​

Stores: 460, and 404

​

Rate limits

• Your installation’s bucket: by default 40 requests at once, refilled at 4 a second. Past it: 429 RATE_LIMITED, with Retry-After (seconds until one more request fits). Online and offline tokens of an installation share one bucket.
• The business’s ceiling: all the apps of one business share, by default, 20 requests at once and 20 a second. Past it: 429 BUSINESS_RATE_LIMITED, with Retry-After; then other apps of the business are using the room, so spread your calls out.
• A busy API: when the API is already running its maximum of app requests, it answers 503 API_BUSY with Retry-After: 1, having done nothing: any call, a write included, can be retried as it was.
• Image uploads have their own daily quota (Products and collections).

​

Plans

​

Masking

• Without read_customer_contact, contact fields are absent.
• When the merchant’s plan hides phones (no active subscription, or a billing grace that hides them), phones read **********.
• A waiting order (past the plan’s order allowance, waiting: true) is masked whatever your scopes: phones ********** and notes null, until it unlocks (orders/updated with waiting).

​

Caching