# A store's current stack

`GET /v1/companies/{domain}`

Returns one Shopify store's current app stack, theme, country, industry and order-value band for **1 credit**.

- **Auth:** API key ([Authentication](https://installgraph.com/docs/authentication.md))
- **Scope:** `companies:read`
- **Cost:** 1 credit per store found; free again within 7 days. `include=history` costs 1 more.

Use it when you have a domain and want everything we know about that store. To find stores, start from an app with `GET /v1/apps/{slug}/companies`.

The apps a store ran at its latest healthy scan, with its theme, country and currency. `domain` is
normalized (scheme, `www.`, path and port are dropped), so `https://www.allbirds.com/` works.
Costs 1 credit, free again within 7 days. A 404 (no store found) is free up to 2 × your lookups
that found a store in the last 30 days + 100, then costs 1 credit (`X-Credits-Charged` on the 404;
a 402 when out of credits). Until your account has bought credits, a domain we know of but have not
scanned yet answers with the same 404 as one we have never heard of. `include=history` adds the store's install
and removal events (`history`, newest first, up to 500) for 1 credit more. Scope `companies:read`.

## Request

```bash
curl "https://api.installgraph.com/v1/companies/example.com" \
  -H "Authorization: Bearer $INSTALLGRAPH_API_KEY"
```

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `domain` | string | Yes | Example: `allbirds.com`. |

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `include` | string | No | One of `history`. |

## Response

`200`. The example's stores are fictional.

```json
{
  "data": {
    "domain": "example.com",
    "name": "Example Apparel Co.",
    "myshopifyDomain": "example-apparel.myshopify.com",
    "country": "US",
    "region": "north-america",
    "industry": {
      "category": "Apparel",
      "subcategory": "Footwear",
      "path": "/Apparel/Footwear",
      "confidence": "high"
    },
    "pricePoint": {
      "aovBand": "100-200",
      "label": "$100–200",
      "confidence": "medium",
      "medianProductPriceUsd": 128,
      "productPriceRangeUsd": [
        95,
        165
      ],
      "productPricesSeen": 24
    },
    "currency": "USD",
    "locale": "en",
    "status": "live",
    "theme": {
      "name": "Dawn",
      "version": "15.2.0",
      "themeStoreId": 887,
      "customName": "Dawn - spring",
      "since": "2026-03-02T04:11:09.000Z"
    },
    "lastScannedAt": "2026-11-02T03:40:12.000Z",
    "lastHealthyScanAt": "2026-11-02T03:40:12.000Z",
    "customPixelCount": 2,
    "apps": [
      {
        "slug": "klaviyo",
        "name": "Klaviyo",
        "category": "email-sms",
        "firstSeenAt": "2026-01-12T05:02:44.000Z",
        "lastSeenAt": "2026-11-02T03:40:12.000Z",
        "evidence": [
          "webPixel",
          "themeAppExtension"
        ]
      },
      {
        "slug": "judge-me",
        "name": "Judge.me",
        "category": "reviews",
        "firstSeenAt": "2026-01-12T05:02:44.000Z",
        "lastSeenAt": "2026-11-02T03:40:12.000Z",
        "evidence": [
          "themeAppExtension",
          "script"
        ]
      }
    ]
  },
  "meta": {
    "requestId": "6f1c2a9e-4b7d-4e2a-9c51-0d3b8e7f2a14",
    "creditsUsed": 1,
    "creditsCharged": 1,
    "creditsRemaining": 49,
    "freeRepulls": 0
  }
}
```

### Fields

| Field | Type | Description |
| --- | --- | --- |
| `data.domain` | string | Example: `allbirds.com`. |
| `data.name` | string \| null |  |
| `data.myshopifyDomain` | string \| null | Example: `allbirds.myshopify.com`. |
| `data.country` | string \| null | Example: `US`. |
| `data.region` | Region \| null | One of `north-america`, `latin-america`, `europe`, `middle-east-africa`, `asia-pacific`. |
| `data.industry` | Industry \| null | Our reading of what the store sells, from its homepage, in the Store Leads taxonomy. |
| `data.industry.category` | string | Example: `Apparel`. |
| `data.industry.subcategory` | string \| null | Null when the store fits a category but none of its subcategories (a general bookshop). Example: `Footwear`. |
| `data.industry.path` | string | `/Books & Literature` alone when there is no subcategory. Example: `/Apparel/Footwear`. |
| `data.industry.confidence` | string \| null | One of `high`, `medium`, `low`. |
| `data.pricePoint` | PricePoint \| null | The store's typical order value, in USD bands so it reads the same in every country. Our own reading of the homepage: the product prices shown there (converted from the store's currency), and what is sold. |
| `data.pricePoint.aovBand` | string | One of `under-25`, `25-50`, `50-100`, `100-200`, `200-500`, `500-1000`, `1000-plus`. |
| `data.pricePoint.label` | string | Example: `$100–200`. |
| `data.pricePoint.confidence` | string \| null | One of `high`, `medium`, `low`. |
| `data.pricePoint.medianProductPriceUsd` | integer \| null | Median product price on the homepage, in USD. |
| `data.pricePoint.productPriceRangeUsd` | integer[] \| null | Interquartile range of homepage product prices, in USD. |
| `data.pricePoint.productPricesSeen` | integer |  |
| `data.currency` | string \| null | Example: `USD`. |
| `data.locale` | string \| null | Example: `en`. |
| `data.status` | Status | The latest scan's verdict: `live`, `password` (behind a password page), `closed` (store unavailable), `not_shopify` (the domain no longer serves a Shopify store), or `unreachable` (we could not read the page this time). Apps are from the latest `live` scan (`lastHealthyScanAt`). One of `live`, `password`, `closed`, `not_shopify`, `unreachable`. |
| `data.theme` | object \| null |  |
| `data.theme.name` | string | The theme's own name (schema name), e.g. Dawn. |
| `data.theme.version` | string \| null |  |
| `data.theme.themeStoreId` | integer \| null | Shopify Theme Store id, for a store theme. |
| `data.theme.customName` | string \| null | What the merchant named their copy. |
| `data.theme.since` | string (date-time) \| null | First scan on this theme. |
| `data.lastScannedAt` | string (date-time) |  |
| `data.lastHealthyScanAt` | string (date-time) \| null |  |
| `data.customPixelCount` | integer \| null | Custom pixels in Shopify's Customer events. |
| `data.apps` | CompanyApp[] |  |
| `data.apps[].slug` | string | Example: `klaviyo`. |
| `data.apps[].name` | string | The catalogue's name: our own for apps we curate, else the App Store listing title as written. Example: `Klaviyo`. |
| `data.apps[].displayName` | string | What a merchant calls the app, read from its keyword-padded App Store title ("Preorder, Back In Stock ‑ STOQ" is `STOQ`). A developer's listings that share a brand keep the words that tell them apart (`Swym Wishlist Plus`). Equal to `name` until derived. Example: `Klaviyo`. |
| `data.apps[].category` | Category | One of 28 values (see [Data model](https://installgraph.com/docs/data-model.md)). |
| `data.apps[].kind` | string | `shopify-app`: an app installed from Shopify. `web`: a website technology installed outside Shopify, by pasting its tag into the theme or through a tag manager (Google Tag Manager, Meta Pixel, Hotjar). A vendor with both has one entry of each (`meta-pixel` and `meta-facebook-instagram-app`). One of `shopify-app`, `web`. |
| `data.apps[].firstSeenAt` | string (date-time) | First scan that found it. |
| `data.apps[].lastSeenAt` | string (date-time) | Latest scan that found it. |
| `data.apps[].evidence` | Evidence[] | One of `webPixel`, `themeAppExtension`, `appProxy`, `customPixel`, `script`, `html`. |

Every keyed response also carries `meta` (`requestId`, `creditsUsed`, `creditsRemaining`, `freeRepulls`) and the `X-Credits-*` and `X-RateLimit-*` headers. See [Credits](https://installgraph.com/docs/credits.md) and [Rate limits](https://installgraph.com/docs/rate-limits.md).

## Errors

| Status | Code | Meaning | What to do |
| --- | --- | --- | --- |
| 400 | `invalid_request` | A parameter or body field is missing or malformed. | Fix the request; `message` names the field. Do not retry unchanged. |
| 401 | `missing_api_key` | No key was sent. | Send `Authorization: Bearer sfs_…` or `X-API-Key: sfs_…`. |
| 401 | `invalid_api_key` | The key is not one we issued. | Check for truncation or whitespace; keys are `sfs_` plus 32 letters and digits. |
| 401 | `api_key_revoked` | The key was revoked. | Make a new key at installgraph.com/account. |
| 402 | `insufficient_credits` | The balance cannot cover one row or lookup. Nothing was charged. | Buy credits: `error.offers.pack.buyUrl`, or `POST /v1/billing/purchase` if agent purchases are on. |
| 402 | `usage_cap_reached` | The account unlocked 40,000 distinct stores in the last 30 days. | Wait for the window to roll, or Talk to us: `error.offers.talkToUs.url`. |
| 403 | `insufficient_scope` | The key lacks this endpoint's scope. | Use a key with the scope the endpoint lists (`GET /v1/usage` shows yours). |
| 403 | `api_key_suspended` | The key is suspended. | Talk to us, quoting `requestId`. |
| 404 | `not_found` | No such endpoint, app, or store (or not scanned yet). | Check the slug or domain. Store 404s are free within the lookup-miss allowance. |
| 429 | `rate_limited` | Too many requests this minute. | Wait `Retry-After` seconds, then retry. |

All codes: [Errors](https://installgraph.com/docs/errors.md).