App Bridge
Embed your application directly in the Cartly merchant admin using iframe-based integration.
Architecture
App Bridge apps run inside an iframe within the Cartly admin panel. Communication between your app and the Cartly admin happens via postMessage.
Session Tokens
When your app loads in the iframe, the Cartly admin posts an APP_BRIDGE_INIT message to it with a short-lived access token scoped to your app and the shop, and the API base URL (apiUrl). Check that the message comes from window.parent on a Cartly admin origin, answer APP_BRIDGE_READY right away (the admin shows a handshake error if it hasn't arrived 5 seconds after opening your app), and send the token as Authorization: Bearer to apiUrl — there is no token in the URL and no exchange step.
Origins
The merchant admin runs on https://cartly.pro, https://*.cartly.pro or https://*.mycartly.pro; accept APP_BRIDGE_INIT only from window.parent on such an origin (regional deployments add their own admin host). *.mycartly.pro also serves storefronts, so the origin alone is no proof: treat the token as the credential and check the shop it belongs to with GET /apps/api/me. The admin talks only to your app's registered origin (the origin of its Website URL), so that URL must load your app directly — a redirect to another origin breaks the handshake. When the token expires (1 hour), post APP_BRIDGE_TOKEN_REQUEST: the admin answers APP_BRIDGE_TOKEN with a fresh accessToken, or APP_BRIDGE_ERROR with code token_refresh_failed or token_refresh_throttled (at most one refresh a minute).
App API Endpoints
Available endpoints for OAuth-authenticated apps
| Name | Type | Required | Description |
|---|---|---|---|
| GET /apps/api/shop | shop:read | No | Get current shop info |
| GET /apps/api/products | products:read | No | List shop products |
| GET /apps/api/orders | orders:read | No | List shop orders |
| GET /apps/api/customers | customers:read | No | List shop customers |
| PUT /apps/api/metafields/:owner_type/:owner_id/:namespace/:key | metafields:write | No | Create or update a metafield in your namespace (app:<app id>) |
| GET /apps/api/metafields/:owner_type/:owner_id | metafields:read | No | List your app's metafields of a resource |