App data

​

Declare the keys

[[data.definitions]]
owner      = "product"   # business | store | product | order | customer
key        = "rating"    # [a-z][a-z0-9_]{0,63}, unique per owner
type       = "json"      # string | number | integer | boolean | json
visibility = "app"       # app | merchant | storefront

• The installation’s version decides. A key your new version adds can be written on an installation only once its merchant accepts that version.
• The type is checked on every write. The visibility comes from the declaration, never from the request.
• visibility: app values are read by your app only. merchant values are meant for the dashboard and storefront values for the store’s pages; neither is shown there yet, so declare them only for values you would be happy to see shown.
• A key a newer version drops keeps its values: still readable (declared: false) and deletable, never writable. A key whose type changes keeps its old values; the next write must match the new type.

​

Owners and scopes

​

Write, read, delete

const owner = {
  ownerType: 'product',
  ownerId: '741000000000000500',
  key: 'rating',
} as const;

// PUT writes the whole value: 201 when it is new, 200 when it replaced one.
await admin.put('/data/{ownerType}/{ownerId}/{key}', {
  path: owner,
  body: { value: { average: 4.5, count: 12 } },
});

const { data: rating } = await admin.get('/data/{ownerType}/{ownerId}/{key}', {
  path: owner,
});
console.log(rating.value, rating.visibility, rating.updatedAt);

await admin.delete('/data/{ownerType}/{ownerId}/{key}', { path: owner });

{
  "id": "9500000000000000001",
  "ownerType": "product",
  "ownerId": "741000000000000500",
  "key": "rating",
  "value": { "average": 4.5, "count": 12 },
  "visibility": "app",
  "declared": true,
  "createdAt": "2026-10-14T08:00:00.000Z",
  "updatedAt": "2026-10-14T09:30:00.000Z"
}

• The body is { "value": … } and nothing else. A value is never null: remove one with DELETE.
• A missing value answers 404 NOT_FOUND (its detail says whether the owner or the value is missing).
• GET /data lists your installation’s values, newest first. Filters: ownerType, ownerId (with ownerType), key. Values whose owner you can no longer read are left out, so a page can be shorter than limit while nextCursor is set: keep reading until it is null.

for await (const value of admin.paginate('/data', {
  query: { ownerType: 'product', key: 'rating' },
})) {
  console.log(value.ownerId, value.value);
}

​

Values

• At most 16,384 bytes of compact JSON in UTF-8 (an Arabic letter is two bytes): 400 APP_DATA_VALUE_TOO_LARGE.
• Refused with 400 APP_DATA_VALUE_INVALID and a reason: wrong_type, not_finite, nul_character, lone_surrogate, reserved_key (an object key __proto__, constructor or prototype), too_deep (more than 32 levels).
• An object’s keys come back in the order Tassyir stores them (shorter keys first), not the order you sent.
• A key the version does not declare for that owner is 400 APP_DATA_KEY_NOT_DECLARED.

​

Limits

​

When values go away

• Values stay when their owner is deleted, until you delete them; they drop out of lists and reads.
• When the merchant uninstalls your app, its values are deleted 48 hours later, and your app receives business/redact. A reinstall, even within those 48 hours, is a new installation that starts empty, and an uninstalled installation can no longer read its values: if a value must survive a reinstall, keep your own copy (Compliance and uninstall).