Store and user context - Salesive Docs

Overview

GET /api/v1/app/context returns the identity of the store your app is installed on and the merchant who installed it. It is default-granted to every installation: no OAuth scope is required, because it exposes only the store profile an app needs to render its own header. Call it first, before any scoped endpoint, to display the store’s name, logo, currency, country and storefront domain, and to learn whether the installing user is the owner or a staff member.

GET /api/v1/app/context
Authorization: Bearer app_<your-app-access-token>

Authentication

Send your app_ access token as a Bearer header. This endpoint accepts an app token only. A merchant session is refused with 403, because the response is the store the app is installed on, not the store a person happens to be browsing. The store comes from the installation bound to your token, never from a header or query parameter. There is no x-shop-id here: a token can only ever read the one store it was installed on.

Response

{
  "status": 200,
  "success": true,
  "message": "Context retrieved",
  "data": {
    "app": {
      "id": "66f0aabbccddeeff00112233",
      "clientId": "app_7d1f0c2b9a4e4f6c8b3d2a1e0f9c8b7a",
      "installationId": "66f1bbccddeeff00112233445",
      "name": "Acme Analytics",
      "slug": "acme-analytics"
    },
    "store": {
      "id": "6680aabbccddeeff00112200",
      "name": "Acme Store",
      "type": "restaurant",
      "domain": "acme.store",
      "url": "https://acme.store",
      "logo": "https://cdn.salesive.com/stores/acme/logo.png",
      "favicon": "https://cdn.salesive.com/stores/acme/favicon.png",
      "tagline": "Best jollof in town",
      "description": "Lagos kitchen, open every day",
      "currency": { "code": "NGN", "symbol": "₦", "name": "Nigerian Naira" },
      "country": { "name": "Nigeria", "code": "NG", "flag": "https://cdn.salesive.com/flags/ng.svg" },
      "state": "Lagos",
      "location": {
        "address": "12 Lekki Phase 1",
        "city": "Lagos",
        "state": "Lagos",
        "country": "Nigeria",
        "phone": "+2348012345678",
        "email": "hello@acme.com",
        "zipCode": "106104",
        "coordinates": { "lat": 6.4474, "lng": 3.4735 }
      },
      "business": {
        "name": "Acme Ltd",
        "phone": "+2348012345678",
        "email": "billing@acme.com"
      },
      "socialMedia": {
        "facebook": "https://facebook.com/acmestore",
        "instagram": "https://instagram.com/acmestore",
        "x": "https://x.com/acmestore",
        "tiktok": "https://tiktok.com/@acmestore"
      }
    },
    "user": {
      "id": "66b1f0a3c2d4e5f6a7b8c9d0",
      "name": "Amara Okonkwo",
      "email": "amara@acme.com",
      "phone": "+2348012345678",
      "avatar": "https://cdn.salesive.com/avatars/amara.png",
      "storeRole": "owner"
    }
  }
}

app

Field	Type	Description
`id`	string	Your app’s registration id. It is the same on every store, and it is the id in the developer console URL, `/apps/developer/<id>`.
`clientId`	string or `null`	Your OAuth client id, `app_<hex>`.
`installationId`	string	This store’s installation id. Use it when you need the per-store record.
`name`	string	Your app’s name.
`slug`	string or `null`	Your marketplace slug, when set.

id and clientId are stable across every store. installationId changes with each install. The app id is the value the scripts API accepts as integration, so an app never has to hardcode or guess it. See Create a script.

store

Field	Type	Description
`id`	string	The store id. The same value as `shopId` on every webhook.
`name`	string	The store’s display name.
`type`	string	`ecommerce`, `restaurant`, `business` or `digital`. Use it to decide which catalog your app should read.
`domain`	string or `null`	The storefront host, for example `acme.store`. `null` when the store has no domain.
`url`	string or `null`	The storefront URL: `https://` plus `domain`, with no trailing slash. `null` when the store has no domain.
`logo`	string	Store logo URL.
`favicon`	string	Store favicon URL.
`tagline`	string or `null`	Short store tagline, when set.
`description`	string or `null`	Longer store description, when set.
`currency`	object or `null`	The store’s currency as `{ code, symbol, name }`, when one is set.
`country`	object or `null`	The store’s country as `{ name, code, flag }`, where `flag` is the flag image when the country record carries one.
`state`	string or `null`	The store’s state or region, when set.
`location`	object or `null`	The store’s address block, or `null` when no location is recorded.
`location.address`	string or `null`	Street address.
`location.city`	string or `null`	City.
`location.state`	string or `null`	State or region.
`location.country`	string or `null`	Country name, as recorded on the address.
`location.phone`	string or `null`	Contact phone.
`location.email`	string or `null`	Contact email.
`location.zipCode`	string or `null`	Postal code.
`location.coordinates`	object or `null`	`{ lat, lng }`, or `null` when no latitude is recorded.
`business`	object or `null`	Business details as `{ name, phone, email }`, each a string or `null`.
`socialMedia`	object or `null`	The store’s social links. The object can carry `facebook`, `instagram`, `x` and `tiktok`, each a string.

The storefront domain is resolved from the store’s own domains in this order: the default domain first, then an active custom domain, then any other active domain. When none of those is available it falls back to the store’s legacy domain field. domain and url are both null when the store has no domain at all. Use store.url to build product links, emails and canonical URLs. Do not ask the merchant to type a domain: this is the storefront they have already set up, and a hardcoded value goes stale when they change it. Every field inside location and business is returned as null when it is not set, so the object shape stays stable. socialMedia is the store’s own object and its keys vary by store.

user

Field	Type	Description
`id`	string	The Salesive user who installed your app.
`name`	string	Their name.
`email`	string	Their email.
`phone`	string or `null`	Their phone, when set.
`avatar`	string or `null`	Their avatar URL, when set.
`storeRole`	string	`owner` when the installing user owns the store, otherwise `staff`.

user is the person who completed the install, not necessarily the person viewing your app right now. Use user.id to bind your own session to that person, and compare it with the ?user= value the dashboard appends to your iframe URL. See Install your app.

This endpoint is for identity, not for store data. It carries no orders, customers, products, financial balances or credentials. Read those from their own endpoints with the matching scope.

When to call it

On first load, to render the store’s name, logo, currency, country and storefront domain without asking the merchant for a scope.
When you need a link, to build product links, emails and canonical URLs from store.url rather than asking the merchant to type a domain.
After a shop/updated webhook, to pick up a change to the profile, business details, location or app info. The event carries a section field naming the part that changed and no values, so re-fetch them here. See Webhooks.
When binding a session, to record which user installed the app and whether they are the owner or staff.
When you need your own id, read app.id instead of hardcoding it. The scripts API and any support or billing link can use it.

Errors

Status	Meaning
`401`	The token is missing, expired or revoked, or the app is no longer installed on the store.
`403`	The caller is not an app token. The message is `This endpoint requires an app token.`
`404`	The store bound to the installation no longer exists.

Next steps

Scopes & permissions

The default grant and every scope an app can request.

Webhooks

The shop/updated topic and the rest of the event list.

Install your app

Exchange the install for a token and bind your session to user.id.

Apps API overview

Authentication, the response envelope and money units.

​Overview

​Authentication

​Response

​app

​store

​user

​When to call it

​Errors

​Next steps

Scopes & permissions

Webhooks

Install your app

Apps API overview

Overview

Authentication

Response

app

store

user

When to call it

Errors

Next steps