Installations

App-installation endpoints used by marketplace apps via app_inst_* tokens. Write encrypted secrets and manage external-resource mappings tied to a specific installation. The route installationId must match the token; one app cannot read another app’s installation.

List mappings

List mappings for this installation. Paginated; filterable by resourceType, internalId, platformCode, and syncStatus.

Authorization

AuthorizationBearer <token>

App installation token (server-to-server, for marketplace apps). Format: Authorization: Bearer app_inst_xxxxxxxxx. Issued to each AppInstallation row when a merchant installs the app. Scopes are declared by the app manifest; the token cannot escalate beyond them. Used against /api/v1/installations/:installationId/* to read/write mappings and persist OAuth secrets.

In: header

Path Parameters

installationIdstring

Installation ID. Must match the installationId carried by the app_inst_* token.

Query Parameters

resourceType?string

Filter by Brainerce resource type.

internalId?string

Filter by internal Brainerce resource ID.

platformCode?string

Filter by external platform code.

syncStatus?string

Filter by sync status.

Value in"synced" | "pending" | "error" | "stale"

page?number

Page number (1-based).

Default1

Range1 <= value

limit?number

Page size (max 100).

Default20

Range1 <= value <= 100

curl -X GET "https://api.brainerce.com/api/v1/installations/inst_01HXYZ/mappings?resourceType=product&internalId=prod_01HXYZ&platformCode=shopify&syncStatus=synced&page=1&limit=20"

curl -X GET "https://api.brainerce.com/api/v1/installations/inst_01HXYZ/mappings?resourceType=product&internalId=prod_01HXYZ&platformCode=shopify&syncStatus=synced&page=1&limit=20"

{
  "data": [
    {
      "id": "clx1a2b3c4d5e6f7g8h9",
      "storeId": "string",
      "installationId": "clx1a2b3c4d5e6f7g8h9",
      "resourceType": "product",
      "internalId": "prod_01HXYZ",
      "externalId": "string",
      "externalUrl": "string",
      "platformCode": "shopify",
      "syncStatus": "synced",
      "lastSyncedAt": "2019-08-24T14:15:22Z",
      "lastSyncError": "string",
      "metadata": {},
      "createdAt": "2019-08-24T14:15:22Z",
      "updatedAt": "2019-08-24T14:15:22Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 137,
    "totalPages": 7
  }
}

{
  "statusCode": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid or expired credential",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/installations/{installationId}/mappings"
}

{
  "statusCode": 403,
  "code": "INSUFFICIENT_SCOPE",
  "message": "API key does not have the required scope: products:write",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/installations/{installationId}/mappings"
}

Create a mapping

Register that a Brainerce resource (product, order, customer, …) corresponds to a resource on the app’s external platform. The mapping is keyed by (installationId, resourceType, internalId, platformCode). Duplicates are rejected; use PUT /upsert instead.

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

installationIdstring

Installation ID. Must match the installationId carried by the app_inst_* token.

Request Body

resourceTypestring

Type of Brainerce resource being mapped.

internalIdstring

Internal Brainerce resource ID (e.g. product.id).

externalIdstring

External resource ID on the app’s platform.

externalUrl?string

Optional canonical URL to the resource on the external platform, surfaced in the dashboard UI.

platformCodestring

Platform code identifying the external platform (matches the App.platformCode field on the installed app).

syncStatus?string

Initial sync status. Defaults to synced.

Value in"synced" | "pending" | "error" | "stale"

metadata?object

Optional metadata JSON holding platform-specific data. Stored as-is.

Empty Object

curl -X POST "https://api.brainerce.com/api/v1/installations/inst_01HXYZ/mappings" \
  -H "Content-Type: application/json" \
  -d '{
    "resourceType": "product",
    "internalId": "prod_01HXYZ",
    "externalId": "7891234567890",
    "platformCode": "shopify"
  }'

curl -X POST "https://api.brainerce.com/api/v1/installations/inst_01HXYZ/mappings" \  -H "Content-Type: application/json" \  -d '{    "resourceType": "product",    "internalId": "prod_01HXYZ",    "externalId": "7891234567890",    "platformCode": "shopify"  }'

{
  "id": "clx1a2b3c4d5e6f7g8h9",
  "storeId": "string",
  "installationId": "clx1a2b3c4d5e6f7g8h9",
  "resourceType": "product",
  "internalId": "prod_01HXYZ",
  "externalId": "string",
  "externalUrl": "string",
  "platformCode": "shopify",
  "syncStatus": "synced",
  "lastSyncedAt": "2019-08-24T14:15:22Z",
  "lastSyncError": "string",
  "metadata": {},
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

{
  "statusCode": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid or expired credential",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/installations/{installationId}/mappings"
}

{
  "statusCode": 403,
  "code": "INSUFFICIENT_SCOPE",
  "message": "API key does not have the required scope: products:write",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/installations/{installationId}/mappings"
}

{
  "statusCode": 409,
  "code": "CONFLICT",
  "message": "The request conflicts with the current state of the resource",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/installations/{installationId}/mappings"
}

Get a mapping

Return one mapping by ID. 404 if the mapping does not belong to this installation.

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

installationIdstring

Installation ID. Must match the installationId carried by the app_inst_* token.

mappingIdstring

Mapping ID.

curl -X GET "https://api.brainerce.com/api/v1/installations/inst_01HXYZ/mappings/map_01HXYZ"

curl -X GET "https://api.brainerce.com/api/v1/installations/inst_01HXYZ/mappings/map_01HXYZ"

{
  "id": "clx1a2b3c4d5e6f7g8h9",
  "storeId": "string",
  "installationId": "clx1a2b3c4d5e6f7g8h9",
  "resourceType": "product",
  "internalId": "prod_01HXYZ",
  "externalId": "string",
  "externalUrl": "string",
  "platformCode": "shopify",
  "syncStatus": "synced",
  "lastSyncedAt": "2019-08-24T14:15:22Z",
  "lastSyncError": "string",
  "metadata": {},
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

{
  "statusCode": 404,
  "code": "RESOURCE_NOT_FOUND",
  "message": "Resource not found",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/installations/{installationId}/mappings/{mappingId}"
}

Update a mapping

Partial update: only the fields you provide are written. Useful for transitioning syncStatus and recording lastSyncedAt / lastSyncError.

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

installationIdstring

Installation ID. Must match the installationId carried by the app_inst_* token.

mappingIdstring

Mapping ID.

Request Body

externalId?string

Updated external resource ID.

externalUrl?string

Updated URL to the resource on the external platform.

syncStatus?string

Updated sync status.

Value in"synced" | "pending" | "error" | "stale"

lastSyncedAt?string

Timestamp of last successful sync (ISO 8601).

lastSyncError?string | null

Last sync error message. Pass null to clear the error.

metadata?object

Updated metadata JSON holding platform-specific data.

Empty Object

curl -X PATCH "https://api.brainerce.com/api/v1/installations/inst_01HXYZ/mappings/map_01HXYZ" \
  -H "Content-Type: application/json" \
  -d '{}'

curl -X PATCH "https://api.brainerce.com/api/v1/installations/inst_01HXYZ/mappings/map_01HXYZ" \  -H "Content-Type: application/json" \  -d '{}'

{
  "id": "clx1a2b3c4d5e6f7g8h9",
  "storeId": "string",
  "installationId": "clx1a2b3c4d5e6f7g8h9",
  "resourceType": "product",
  "internalId": "prod_01HXYZ",
  "externalId": "string",
  "externalUrl": "string",
  "platformCode": "shopify",
  "syncStatus": "synced",
  "lastSyncedAt": "2019-08-24T14:15:22Z",
  "lastSyncError": "string",
  "metadata": {},
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

{
  "statusCode": 404,
  "code": "RESOURCE_NOT_FOUND",
  "message": "Resource not found",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/installations/{installationId}/mappings/{mappingId}"
}

Delete a mapping

Remove a mapping. The Brainerce resource itself is untouched: this only unlinks the external counterpart.

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

installationIdstring

Installation ID. Must match the installationId carried by the app_inst_* token.

mappingIdstring

Mapping ID.

curl -X DELETE "https://api.brainerce.com/api/v1/installations/inst_01HXYZ/mappings/map_01HXYZ"

curl -X DELETE "https://api.brainerce.com/api/v1/installations/inst_01HXYZ/mappings/map_01HXYZ"

Empty

{
  "statusCode": 404,
  "code": "RESOURCE_NOT_FOUND",
  "message": "Resource not found",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/installations/{installationId}/mappings/{mappingId}"
}

Upsert a mapping

Create the mapping if it does not exist, otherwise update the existing row. Uniqueness key: (installationId, resourceType, internalId, platformCode). Idempotent, and recommended for sync loops.

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

installationIdstring

Installation ID. Must match the installationId carried by the app_inst_* token.

Request Body

resourceTypestring

Type of Brainerce resource being mapped.

internalIdstring

Internal Brainerce resource ID (e.g. product.id).

externalIdstring

External resource ID on the app’s platform.

externalUrl?string

Optional canonical URL to the resource on the external platform, surfaced in the dashboard UI.

platformCodestring

Platform code identifying the external platform (matches the App.platformCode field on the installed app).

syncStatus?string

Initial sync status. Defaults to synced.

Value in"synced" | "pending" | "error" | "stale"

metadata?object

Optional metadata JSON holding platform-specific data. Stored as-is.

Empty Object

curl -X PUT "https://api.brainerce.com/api/v1/installations/inst_01HXYZ/mappings/upsert" \
  -H "Content-Type: application/json" \
  -d '{
    "resourceType": "product",
    "internalId": "prod_01HXYZ",
    "externalId": "7891234567890",
    "platformCode": "shopify"
  }'

curl -X PUT "https://api.brainerce.com/api/v1/installations/inst_01HXYZ/mappings/upsert" \  -H "Content-Type: application/json" \  -d '{    "resourceType": "product",    "internalId": "prod_01HXYZ",    "externalId": "7891234567890",    "platformCode": "shopify"  }'

{
  "id": "clx1a2b3c4d5e6f7g8h9",
  "storeId": "string",
  "installationId": "clx1a2b3c4d5e6f7g8h9",
  "resourceType": "product",
  "internalId": "prod_01HXYZ",
  "externalId": "string",
  "externalUrl": "string",
  "platformCode": "shopify",
  "syncStatus": "synced",
  "lastSyncedAt": "2019-08-24T14:15:22Z",
  "lastSyncError": "string",
  "metadata": {},
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

Write installation secrets

Write or update the encrypted secrets bag attached to an installation. Used by marketplace apps to persist OAuth tokens, signing secrets, or provider-specific credentials after completing their setup flow. Secrets are encrypted at rest with AES-256-GCM.

Empty Object

curl -X PUT "https://api.brainerce.com/api/v1/installations/inst_01HXYZ/secrets" \
  -H "Content-Type: application/json" \
  -d '{
    "secrets": {
      "access_token": "shpat_xxx",
      "refresh_token": "rt_yyy"
    }
  }'

curl -X PUT "https://api.brainerce.com/api/v1/installations/inst_01HXYZ/secrets" \  -H "Content-Type: application/json" \  -d '{    "secrets": {      "access_token": "shpat_xxx",      "refresh_token": "rt_yyy"    }  }'

{
  "success": true
}

{
  "statusCode": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid or expired credential",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/installations/{installationId}/secrets"
}

{
  "statusCode": 403,
  "code": "INSUFFICIENT_SCOPE",
  "message": "API key does not have the required scope: products:write",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/installations/{installationId}/secrets"
}

Example default

Example default

Example default

Example default

Example default

Example default

Example default

Example default

Example default

Example default

On this page