StoreCensus API Documentation

v1Base URL: https://www.storecensus.com

Introduction

The StoreCensus API provides programmatic access to comprehensive e-commerce intelligence data. Our RESTful API delivers structured, reliable data about online stores and businesses to power your applications, integrations, and workflows.

Whether you're building lead generation tools, enriching CRM data, conducting market research, or developing competitive analysis platforms, our API provides the foundation for data-driven e-commerce insights.

All API responses are returned in JSON format with consistent structure, comprehensive error handling, and enterprise-grade reliability. Authentication is handled via Bearer tokens with built-in rate limiting to ensure optimal performance for all users.

Authentication

The StoreCensus API uses Bearer Token Authentication. You must include your API key in the Authorization header of all requests.

Authentication Method

Authorization: Bearer your.api.key

API keys can be generated on the API page of your StoreCensus account after logging in.

Authentication Errors

Status Code	Error	Description
401	{'error': 'Missing API key'}	No API key was provided in the request
401	{'error': 'Invalid Authorization header format. Expected: Bearer your.api.key'}	The Authorization header format is incorrect
401	{'error': 'API key cannot be empty'}	An empty API key was provided
401	{'error': 'Invalid API key or inactive subscription'}	The API key is invalid or the subscription is not active

Rate Limits

The StoreCensus API implements rate limiting based on your subscription plan. Rate limits are applied on a per-API-key basis.

Rate Limit Plans

Plan	Rate Limit
Professional	6 requests per second
Enterprise	30 requests per second

Rate Limit Implementation

Rate limits are calculated using a 1-second sliding window
When rate limits are exceeded, the API returns a 429 Too Many Requests response
The response includes a Retry-After header indicating when you can make another request
Rate limit implementation uses in-memory caching for optimal performance

Rate Limit Exceeded Response:

{'error': 'Rate limit exceeded'}

Error Handling

The StoreCensus API uses standard HTTP status codes to indicate the success or failure of requests. All errors are returned in a consistent JSON format.

Status Code	Description
400 Bad Request	The request was malformed or missing required parameters
401 Unauthorized	Authentication failed or was not provided
429 Too Many Requests	Rate limit exceeded
500 Internal Server Error	An error occurred on the server

Error Response Format

All errors are returned in a consistent JSON format with an error field containing a description of the error:

{'error': 'Description of the error'}

The /website Endpoint

Endpoint Details

URL	`GET /api/v1/website/{domain}`
Description	Retrieve comprehensive e-commerce intelligence data for a specific website domain or lead_id.✨ Supports lead_id (integer) for direct lookup
Authentication	Required (Bearer token)
Rate Limited	Yes (based on subscription plan)

💡 Flexible Lookup: This endpoint intelligently detects the input type. Pass a domain name (e.g., "example-store.com") for domain-based search, or pass an integer (e.g., "12345") for direct lead_id lookup. No need for separate endpoints!

Path Parameters

Parameter	Description
`domain`required	The domain name to analyze (e.g., "example-store.com") or lead_id (e.g., "12345"). If the parameter is numeric, it will be treated as a lead_id for direct lookup.

Query Parameters

Parameter	Description
`sections`optional	Comma-separated list of sections to include in the response. Available sections:`basic_info`,`contact_info`,`location_info`,`social_media`,`ecommerce_info`,`financial_info`,`traffic_analytics`,`technical_info`,`apps_integrations`,`activity_signals`,`crm`,`data_metadata`,`payments_info` (Professional+),`shipping_info` (Professional+). If omitted, all sections are returned.

Request Examples

# Get all data for a domain
curl -X GET "https://www.storecensus.com/api/v1/website/example-store.com" \
  -H "Authorization: Bearer your.api.key" \
  -H "Content-Type: application/json"

# Get data by lead_id (direct lookup)
curl -X GET "https://www.storecensus.com/api/v1/website/12345" \
  -H "Authorization: Bearer your.api.key" \
  -H "Content-Type: application/json"

# Get only specific sections
curl -X GET "https://www.storecensus.com/api/v1/website/example-store.com?sections=basic_info,contact_info,crm" \
  -H "Authorization: Bearer your.api.key" \
  -H "Content-Type: application/json"

# Get specific sections by lead_id
curl -X GET "https://www.storecensus.com/api/v1/website/12345?sections=basic_info,crm" \
  -H "Authorization: Bearer your.api.key" \
  -H "Content-Type: application/json"

Response Format

The API returns comprehensive domain data organized into logical sections for enterprise-level consumption:

{
  "basic_info": {
    "domain": "string",
    "company_name": "string",
    "description": "string",
    "vertical": "string",
    "product_categories": "string",
    "employee_count": number,
    "website_created_at": "string",
    "language": "string",
    "password_protected": boolean
  },
  "contact_info": {
    "emails": [
      {
        "email": "string",
        "email_type": "string",
        "validated": boolean,
        "found_date": "string"
      }
    ],
    "phone": "string",
    "email_count": number,
    "phone_count": number,
    "contact_available": boolean
  },
  "location_info": {
    "address": "string",
    "city": "string",
    "state": "string",
    "country": "string",
    "zip_code": "string",
    "timezone": "string"
  },
  "social_media": {
    "facebook": "string",
    "twitter": "string",
    "instagram": "string",
    "linkedin": "string",
    "youtube": "string",
    "tiktok": "string",
    "pinterest": "string",
    "snapchat": "string",
    "whatsapp": "string",
    "telegram": "string",
    "discord": "string",
    "reddit": "string",
    "twitch": "string"
  },
  "ecommerce_info": {
    "platform": "string",
    "theme": "string",
    "currency": "string",
    "product_count": number,
    "variant_count": number,
    "average_product_price": number
  },
  "financial_info": {
    "estimated_monthly_revenue": number,
    "estimated_tech_spend": number,
    "estimated_app_spend": number,
    "estimated_technology_spend": number
  },
  "traffic_analytics": {
    "estimated_visits": number,
    "keywords": {
      "keyword": "string"
    },
    "sources": {
      "keyword": "string"
    },
    "bouncerate": {
      "num": number
    },
    "category": {
      "keyword": "string"
    },
    "globalrank": {
      "long": number
    },
    "pagepervisit": {
      "num": number
    },
    "screenshot": {
      "keyword": "string"
    },
    "timeonsite": {
      "num": number
    },
    "visits": {
      "long": number
    }
  },
  "technical_info": {
    "technologies": [
      {
        "technology_name": "string",
        "installed": boolean,
        "confidence": number,
        "effective_from": "string",
        "effective_to": "string",
        "observed_at": "string"
      }
    ],
    "last_crawled": "string"
  },
  "apps_integrations": {
    "shopify_apps": [
      {
        "app_id": number,
        "name": "string",
        "handle": "string",
        "installed": boolean,
        "last_detected": "string",
        "first_detected": "string"
      }
    ]
  },
  "activity_signals": {
    "freshness": {
      "last_activity_at": "string",
      "last_app_event_at": "string",
      "last_email_found_at": "string",
      "last_product_update_at": "string",
      "last_technology_change_at": "string",
      "last_theme_publish_at": "string"
    },
    "growth": {
      "product_page_count": {
        "delta_7d": number,
        "delta_30d": number,
        "current": number
      },
      "variant_count": {
        "delta_7d": number,
        "delta_30d": number,
        "current": number
      },
      "average_product_price": {
        "delta_7d": number,
        "delta_30d": number
      },
      "traffic_visits": {
        "delta_7d": number,
        "delta_30d": number
      },
      "email": {
        "new_7d": number,
        "new_30d": number
      },
      "technology": {
        "delta_7d": number,
        "delta_30d": number,
        "current": number
      },
      "spend_shopify_apps": {
        "delta_7d": number,
        "delta_30d": number
      },
      "spend_technology": {
        "delta_7d": number,
        "delta_30d": number
      },
      "app_events": {
        "installs_7d": number,
        "installs_30d": number,
        "uninstalls_7d": number,
        "uninstalls_30d": number
      }
    },
    "events": {
      "theme_changed_7d": boolean,
      "app_installed": boolean,
      "app_uninstalled": boolean,
      "tech_installed": boolean,
      "tech_uninstalled": boolean,
      "products_changed": boolean,
      "emails_changed": boolean
    },
    "changes": {
      "YYYY-MM-DD": [
        {
          "change_type": "string",
          "entity_type": "string",
          "entity_id": "string",
          "old_value": "any",
          "new_value": "any"
        }
      ]
    }
  },
  "crm": {
    "lists": ["string"],
    "note": "string",
    "note_updated_at": "string",
    "rating": number,
    "status": "string",
    "has_reminder": boolean,
    "exported": boolean,
    "exported_time": "string",
    "is_following": boolean
  },
  "data_metadata": {
    "lead_id": "string",
    "last_updated": "string",
    "data_source": "string",
    "api_version": "string"
  }
}

The /stores Endpoint

Endpoint Details

URL	`POST /api/v1/stores`
Description	Retrieve filtered lists of e-commerce stores (Shopify and WooCommerce) with comprehensive data and cursor-based pagination
Authentication	Required (Bearer token)
Rate Limited	Yes (based on subscription plan)

Request Body Parameters

Parameter	Type	Description
`filters`	object	Filter criteria (country, vertical, apps, traffic, etc.)
`sort`	object	Sort configuration with column and direction
`pageSize`	number	Results per page (50-500, default: 50)
`cursor`	string	Pagination cursor from previous response
`sections`	array	Data sections to include (null = all sections)
`selectionLogic`NEW	object	Controls how multi-value filters (apps, technology, payments, shipsTo, contact, shopifyPlan, platformFeatures) are combined. Shape: `{"mode": "include"\|"exclude", "operator": "or"\|"and"}`. Defaults to `{"mode":"include","operator":"and"}`. See the Selection Logic section for full details.
`historicalConstraints`NEW	object[]	Timing filters — filter by WHEN an attribute first appeared, changed, or was active. Each constraint is an object with `attribute`, `value`, `event`, `dateFrom`, `dateTo`. Multiple constraints are ANDed together. See the Timing Filters section for full details.

Complete Filters Reference

The endpoint supports 100+ filter parameters. Below is the complete reference with types, descriptions, and examples.

Shopify = Shopify stores onlyPro = Requires Professional plan or higher

Filter Parameter	Type	Description	Example
🎛️ Selection Logic — top-level body parameter (not inside filters)
`selectionLogic`NEW	object	Controls how multi-value filters are combined for eligible keys: `appstechnologypaymentsshipsTocontactshopifyPlanplatformFeatures` mode: `"include"` (default) — stores must match; `"exclude"` — stores must NOT match. operator: `"and"` (default) — all selected values must match; `"or"` — any one value must match.	`{"mode":"include","operator":"and"}{"mode":"exclude","operator":"or"}`
⏱️ Timing Filters — historicalConstraints — top-level body parameter (not inside filters)
`historicalConstraints`NEW	object[]	Filter by WHEN an attribute first appeared, changed, or was active. Multiple constraints are combined with AND logic. Each object has: attribute (required): `appstechnologiespayment_methodsshipping_countriesplatform_planmarkets_procheckout_extensions` value (required): specific value, `"any_selected"`, or `"__fixed__"` for boolean attrs. event (required): `first_became_truechanged_duringactive_duringremoved_during`(removed_during not available for `platform_plan` `markets_pro` `checkout_extensions`) dateFrom / dateTo (optional): ISO date YYYY-MM-DD — at least one required.	[{ "attribute": "apps", "value": "15", "event": "first_became_true", "dateFrom": "2024-01-01", "dateTo": "2024-12-31" }]
🖥️ Platform Filters
`platform`	string[]	Filter by ecommerce platform. Defaults to Shopify only if omitted. Values: `ShopifyWooCommerce`	`["Shopify", "WooCommerce"]`
📱 App Filters
`apps`	number[] \| string[]	Filter by installed app IDs (numeric). Use the top-level `selectionLogic` parameter to control include/exclude and AND/OR behaviour. Use the `/api/v1/apps` endpoint to look up app IDs by name.	`[15, 42, 89]`
`verifiedAppInstalls`	string[]	Filter for verified app installations only	`["true"]`
`uninstalledAppsOnly`	string[]	Filter for uninstalled apps only	`["true"]`
`installedDateFrom`	string	App first installed on or after this date (YYYY-MM-DD)	`"2024-01-01"`
`installedDateTo`	string	App first installed on or before this date (YYYY-MM-DD)	`"2024-12-31"`
`uninstalledDateFrom`	string	App uninstalled on or after this date (YYYY-MM-DD)	`"2025-01-01"`
`uninstalledDateTo`	string	App uninstalled on or before this date (YYYY-MM-DD)	`"2025-06-30"`
🏷️ Platform Attributes — Shopify only, Pro
`shopifyPlan`ShopifyPro	string[]	Filter by Shopify subscription plan. Pass one or more values — multiple values always use OR logic (a store can only have one plan at a time). Use the top-level `selectionLogic` parameter to control include/exclude mode only. Accepted values: `basicplus`	`["basic", "plus"]`
`platformFeatures`ShopifyPro	string[]	Filter by Shopify checkout capabilities and store type. Use the top-level `selectionLogic` parameter to control include/exclude. Store Type: `physical_productsdigital_products` Markets: `markets_produties_included` Checkout Features: `custom_brandingcustom_fontscustom_colorscheckout_rulescheckout_extensions`	`["physical_products", "checkout_extensions"]`
💳 Payment Filters — Shopify only, Pro
`payments`ShopifyPro	string[]	Filter by active payment methods. Use the top-level `selectionLogic` parameter to control include/exclude and AND/OR behaviour. Buy Now Pay Later: `klarnaaffirmafterpaysezzlezipbread_paykatapult` Processors: `shopify_paymentsstripeamazon_payglobal_e` Wallets: `shop_paypaypalapple_paygoogle_paycash_app`	`["shop_pay", "klarna"]`
🚚 Shipping Filters — Shopify only, Pro
`shippingScope`ShopifyPro	string[]	Filter by geographic shipping reach. Values: `domesticinternationalglobal`	`["international", "global"]`
`shipsTo`ShopifyPro	string[]	Filter by specific destination countries the store ships to. Use the top-level `selectionLogic` parameter to control include/exclude and AND/OR behaviour. Values: `uscagbaude`	`["us", "ca", "gb"]`
📍 Location Filters
`country`	string[]	Filter by country codes (ISO 3166-1 alpha-2)	`["US", "GB", "CA"]`
`state`	string[]	Filter by US state abbreviations (only applicable when country includes US)	`["CA", "NY", "TX"]`
📧 Communication Channel Filters
`contact`	string[]	Filter stores that have specific contact or social media channels. Use the top-level `selectionLogic` parameter to control include/exclude and AND/OR behaviour. Values: `emailphoneinstagramfacebooktiktoklinkedinyoutubepinterestxtwitterWhatsAppSnapchatyelpvimeo`	`["email", "instagram"]`
⚡ Activity Signals Filters — Pro
`activityDelta`Pro	string	Time window for growth metrics: "7" (last 7 days) or "30" (last 30 days)	`"7"`
`activity_events_app_installed`Pro	boolean	Store had an app installed in the last 7 days	`true`
`activity_events_app_uninstalled`Pro	boolean	Store had an app uninstalled in the last 7 days	`true`
`activity_events_tech_installed`Pro	boolean	Store had a technology installed in the last 7 days	`true`
`activity_events_tech_uninstalled`Pro	boolean	Store had a technology uninstalled in the last 7 days	`true`
`activity_events_products_changed`Pro	boolean	Store had product count changes in the last 7 days	`true`
`activity_events_emails_changed`Pro	boolean	Store had email changes in the last 7 days	`true`
`activity_events_theme_changed`Pro	boolean	Store changed its theme in the last 7 days	`true`
`activity_freshness_last_activity_at`Pro	object	Freshness filter for last activity date. Format: {preset: "7 days"} or {min, max}	`{"preset": "7 days"}`
`activity_freshness_last_app_event_at`Pro	object	Freshness filter for last app install/uninstall event	`{"preset": "30 days"}`
`activity_freshness_last_email_found_at`Pro	object	Freshness filter for when the last email was found	`{"preset": "90 days"}`
`activity_freshness_last_product_update_at`Pro	object	Freshness filter for last product update	`{"preset": "7 days"}`
`activity_freshness_last_technology_change_at`Pro	object	Freshness filter for last technology change	`{"preset": "30 days"}`
`activity_freshness_last_theme_publish_at`Pro	object	Freshness filter for last theme publish	`{"preset": "7 days"}`
`activity_growth_product_page_delta_min`Pro	number \| string	Minimum product page count change in the selected time window	`10`
`activity_growth_product_page_delta_max`Pro	number \| string	Maximum product page count change in the selected time window	`100`
`activity_growth_variant_delta_min`Pro	number \| string	Minimum variant count change	`50`
`activity_growth_variant_delta_max`Pro	number \| string	Maximum variant count change	`500`
`activity_growth_traffic_delta_min`Pro	number \| string	Minimum estimated visits change	`1000`
`activity_growth_traffic_delta_max`Pro	number \| string	Maximum estimated visits change	`50000`
`activity_growth_app_installs_delta_min`Pro	number \| string	Minimum number of app installs in the time window	`1`
`activity_growth_app_uninstalls_delta_min`Pro	number \| string	Minimum number of app uninstalls in the time window	`1`
`activity_growth_email_new_delta_min`Pro	number \| string	Minimum number of new emails found in the time window	`1`
`activity_growth_email_new_delta_max`Pro	number \| string	Maximum number of new emails found in the time window	`10`
📋 CRM Filters — Pro
`crm_status`Pro	string[]	Filter by CRM status	`["qualified", "contacted"]`
`crm_lists`Pro	number[]	Filter by CRM list IDs	`[1, 2, 3]`
`crm_has_note`Pro	boolean	Filter stores that have CRM notes	`true`
`crm_ratings`Pro	number[]	Filter by star ratings (1–5)	`[4, 5]`
`crm_has_reminder`Pro	boolean	Filter stores with active reminders	`true`
📤 Synced & Export History Filters
`show_exported`	boolean	Show only stores that have been synced or exported	`true`
`exclude_exported`	boolean	Exclude stores that have been synced or exported	`true`
`exported_date_range`	object	Filter by export date range: {enabled: true, startDate: "YYYY-MM-DD", endDate: "YYYY-MM-DD"}	`{enabled:true,startDate:"2024-01-01"}`
`website_following`	boolean	Filter stores you are following	`true`
💰 Financial Filters
`estimatedSales`	string[]	Monthly revenue range as [min, max] in USD (numeric strings)	`["10000", "100000"]`
`technologySpend`Pro	string[]	Monthly technology spend range as [min, max] in USD (numeric strings)	`["500", "5000"]`
📊 Traffic Filters
`estimatedVisits`	string[]	Monthly visit range as [min, max] (numeric strings)	`["10000", "500000"]`
`totalTrafficMin`	number \| string	Minimum total monthly traffic	`5000`
`totalTrafficMax`	number \| string	Maximum total monthly traffic	`500000`
`organicTrafficMin`	number \| string	Minimum monthly organic search traffic	`1000`
`organicTrafficMax`	number \| string	Maximum monthly organic search traffic	`100000`
📦 Product Filters
`productPagesMin`	number \| string	Minimum number of product pages	`100`
`productPagesMax`	number \| string	Maximum number of product pages	`1000`
`productVariantsMin`	number \| string	Minimum number of product variants	`500`
`productVariantsMax`	number \| string	Maximum number of product variants	`5000`
`avgProductPriceMin`	number \| string	Minimum average product price (USD)	`50`
`avgProductPriceMax`	number \| string	Maximum average product price (USD)	`200`
🏢 Business Filters
`vertical`	string[]	Filter by business vertical/industry. Example values: `Fashion & ApparelBeauty & Personal CareHealth & WellnessFood & BeverageElectronics & GadgetsHome & Garden` and more.	`["Fashion & Apparel", "Health & Wellness"]`
`language`	string[]	Filter by website language (language name, e.g. English, Spanish, French)	`["English", "Spanish"]`
`domainExtension`	string[]	Filter by top-level domain extension (with dot)	`[".com", ".co", ".io"]`
`websiteCreatedAt`	object	Filter by store creation date: {enabled: true, startDate: "YYYY-MM-DD", endDate: "YYYY-MM-DD"}	`{enabled:true,startDate:"2020-01-01"}`
`websiteUpdatedAt`	object	Filter by when the store was last crawled by StoreCensus	`{enabled:true,startDate:"2024-01-01"}`
🛍️ E-commerce Filters
`theme`	string[]	Filter by Shopify theme name (fetched dynamically from available themes)	`["Dawn", "Debut"]`
`technology`	string[]	Filter by tracking/analytics technologies detected on the store. Use the top-level `selectionLogic` parameter to control include/exclude and AND/OR behaviour. Example values: `Google AnalyticsFacebook PixelTikTok Pixel`	`["Google Analytics", "Facebook Pixel"]`
`currency`Shopify	string[]	Filter by store currency (ISO 4217 currency code)	`["USD", "EUR", "GBP"]`
📣 Marketing Signal Filters — Shopify only, Pro
`facebookCapi`ShopifyPro	boolean	Filter stores that have Facebook Conversions API enabled — a strong signal the store is running paid Meta/Facebook ads	`true`

Available Sections

Control which data sections are included in the response:

["basic_info", "contact_info", "location_info", "social_media", "ecommerce_info", "financial_info", "traffic_analytics", "technical_info", "apps_integrations", "activity_signals", "crm", "data_metadata", "payments_info", "shipping_info"]

payments_info and shipping_info require a Professional plan or above. Requesting these sections on a lower-tier plan will return them as null.

Getting App IDs

⚠️ Important: The apps filter requires numeric app IDs, not app names.

To get app IDs, either:

Call the /api/v1/apps endpoint to search for apps and get their IDs
Click on any app in the StoreCensus UI to view its App ID in the app info modal

Request Example

Step 1: Get app IDs from the /apps endpoint

curl -X GET "https://www.storecensus.com/api/v1/apps?search=klaviyo" \
  -H "Authorization: Bearer your.api.key"

# Response shows: "app_id": 15

Step 2: Use the app_id in your stores filter

curl -X POST "https://www.storecensus.com/api/v1/stores" \
  -H "Authorization: Bearer your.api.key" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "country": ["US", "GB"],
      "vertical": ["Fashion & Apparel"],
      "apps": ["15"],
      "estimatedVisits": ["10000", "999999999"]
    },
    "sort": {
      "column": "website_created_at",
      "direction": "desc"
    },
    "pageSize": 100,
    "sections": ["basic_info", "contact_info", "apps_integrations", "activity_signals"]
  }'

With Selection Logic (exclude stores that have Klaviyo OR Mailchimp):

curl -X POST "https://www.storecensus.com/api/v1/stores" \
  -H "Authorization: Bearer your.api.key" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "country": ["US"],
      "apps": ["15", "42"]
    },
    "selectionLogic": {
      "mode": "exclude",
      "operator": "or"
    },
    "pageSize": 100
  }'

With Timing Filters (stores that first installed Klaviyo in 2024):

curl -X POST "https://www.storecensus.com/api/v1/stores" \
  -H "Authorization: Bearer your.api.key" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "country": ["US"],
      "apps": ["15"]
    },
    "selectionLogic": {
      "mode": "include",
      "operator": "and"
    },
    "historicalConstraints": [
      {
        "attribute": "apps",
        "value": "15",
        "event": "first_became_true",
        "dateFrom": "2024-01-01",
        "dateTo": "2024-12-31"
      }
    ],
    "pageSize": 100
  }'

Response Format

{
  "data": [
    {
      "basic_info": { ... },
      "contact_info": { ... },
      "location_info": { ... },
      "social_media": { ... },
      "ecommerce_info": { ... },
      "financial_info": { ... },
      "traffic_analytics": { ... },
      "technical_info": { ... },
      "apps_integrations": { ... },
      "activity_signals": { ... },
      "crm": { ... },
      "data_metadata": { ... },
      "payments_info": { ... },   // Professional+ only
      "shipping_info": { ... }    // Professional+ only
    }
  ],
  "pagination": {
    "pageSize": 100,
    "hasMore": true,
    "nextCursor": "eyJwaXRJZCI6IjQ2VG9BNUlCQ3dqRjFWX...",
    "total": 1250,
    "returned": 100
  },
  "filters": { ... },
  "sort": { ... },
  "sections": [ ... ]
}

Pagination

This endpoint uses cursor-based pagination for efficient traversal of large result sets:

First request: Omit the cursor parameter
Subsequent requests: Include the nextCursor from the previous response
When hasMore is false, you've reached the end
Cursors are valid for 5 minutes

// Next page request
curl -X POST "https://www.storecensus.com/api/v1/stores" \
  -H "Authorization: Bearer your.api.key" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": { ... },
    "pageSize": 100,
    "cursor": "eyJwaXRJZCI6IjQ2VG9BNUlCQ3dqRjFWX..."
  }'

Best Practices

Use appropriate page sizes (50-100 for interactive use, up to 500 for bulk exports)
Request only needed sections using the sections parameter
Implement exponential backoff when receiving 429 rate limit responses
Store cursors to resume pagination if interrupted
Use specific filters to reduce result set size and improve performance

🎛️ Selection Logic

The selectionLogic parameter controls how multi-value filters are combined when querying stores. It is a top-level body parameter (not nested inside filters).

Shape

{
  "selectionLogic": {
    "mode": "include" | "exclude",
    "operator": "or" | "and"
  }
}

Eligible Filter Keys

Selection Logic applies to the following multi-value filter keys:

appstechnologypaymentsshipsTocontactshopifyPlanplatformFeatures

Behaviour Matrix

mode	operator	Meaning
`include`	`and`	Store must have all selected values (default)
`include`	`or`	Store must have at least one of the selected values
`exclude`	`or`	Store must have none of the selected values
`exclude`	`and`	Store must be missing all of the selected values

Example — Exclude stores using Klaviyo OR Mailchimp

curl -X POST "https://www.storecensus.com/api/v1/stores" \
  -H "Authorization: Bearer your.api.key" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "apps": [12345, 67890]
    },
    "selectionLogic": {
      "mode": "exclude",
      "operator": "or"
    },
    "pageSize": 50
  }'

Example — Stores using ALL of the selected payment methods

curl -X POST "https://www.storecensus.com/api/v1/stores" \
  -H "Authorization: Bearer your.api.key" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "payments": ["paypal", "stripe", "apple_pay"]
    },
    "selectionLogic": {
      "mode": "include",
      "operator": "and"
    },
    "pageSize": 50
  }'

⏱️ Timing Filters (historicalConstraints)

The historicalConstraints parameter lets you filter stores by when an attribute changed — not just whether it exists today. It is a top-level body parameter (not nested inside filters). Multiple constraints are ANDed together.

Constraint Shape

{
  "historicalConstraints": [
    {
      "attribute": string,   // Which attribute to track (see table below)
      "value": string,       // A single value to match (app ID, country code, payment key, etc.)
                             // Use "any_selected" to match any value currently in filters
                             // Use "__fixed__" for boolean attributes (markets_pro, checkout_extensions)
      "event": string,       // The timing event type (see table below)
      "dateFrom": string,    // ISO 8601 date — start of the window (optional)
      "dateTo": string       // ISO 8601 date — end of the window (optional)
    }
  ]
}

Supported Attributes

attribute	Tracks	value (single string)	removed_during?
`apps`	Shopify app installs	Numeric app ID string, e.g. `"12345"`	✓ Yes
`technologies`	Technology stack changes	Technology name string, e.g. `"Klaviyo"`	✓ Yes
`payment_methods`	Payment method additions/removals	Payment key, e.g. `"paypal"`, `"apple_pay"`	✓ Yes
`shipping_countries`	Shipping destination changes	ISO 3166-1 alpha-2 code, e.g. `"us"`, `"gb"`	✓ Yes
`platform_plan`	Shopify plan upgrades/downgrades	Plan name, e.g. `"shopify_plus"`, `"basic"`	✗ No
`markets_pro`	Shopify Markets Pro adoption	Use `"__fixed__"` (boolean attribute — no value selection)	✗ No
`checkout_extensions`	Checkout extension presence	Use `"__fixed__"` (boolean attribute — no value selection)	✗ No

Supported Events

event	Meaning
`first_became_true`	The attribute first appeared / was first detected within the date window
`changed_during`	The attribute changed (added or removed) at any point within the date window
`active_during`	The attribute was present / active at any point within the date window
`removed_during`	The attribute was removed / stopped being detected within the date window. Not available for `platform_plan`, `markets_pro`, `checkout_extensions`.

Example — Stores that first installed a specific app in Q1 2024

curl -X POST "https://www.storecensus.com/api/v1/stores" \
  -H "Authorization: Bearer your.api.key" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "apps": ["12345"]
    },
    "historicalConstraints": [
      {
        "attribute": "apps",
        "value": "12345",
        "event": "first_became_true",
        "dateFrom": "2024-01-01",
        "dateTo": "2024-03-31"
      }
    ],
    "pageSize": 50
  }'

Example — Stores that removed PayPal in the last 6 months

curl -X POST "https://www.storecensus.com/api/v1/stores" \
  -H "Authorization: Bearer your.api.key" \
  -H "Content-Type: application/json" \
  -d '{
    "historicalConstraints": [
      {
        "attribute": "payment_methods",
        "value": "paypal",
        "event": "removed_during",
        "dateFrom": "2024-07-01",
        "dateTo": "2025-01-01"
      }
    ],
    "pageSize": 50
  }'

Example — Combined: app installed AND plan upgraded in same window

curl -X POST "https://www.storecensus.com/api/v1/stores" \
  -H "Authorization: Bearer your.api.key" \
  -H "Content-Type: application/json" \
  -d '{
    "historicalConstraints": [
      {
        "attribute": "apps",
        "value": "12345",
        "event": "first_became_true",
        "dateFrom": "2024-01-01",
        "dateTo": "2024-12-31"
      },
      {
        "attribute": "platform_plan",
        "value": "shopify_plus",
        "event": "changed_during",
        "dateFrom": "2024-01-01",
        "dateTo": "2024-12-31"
      }
    ],
    "pageSize": 50
  }'

The /enrich Endpoint

Endpoint Details

URL	`POST /api/v1/enrich`
Description	Enrich lead data by retrieving contact information (emails and phone numbers) for specified lead_ids. Each email includes a deliverability score to help prioritize outreach. Credits are only deducted for leads that have contact information available. Optionally pass `decision_makers: true` to also unlock decision maker contacts (founders, CEOs, etc.) for each lead in the same request.
Authentication	Required (Bearer token)
Rate Limited	Yes (based on subscription plan)

💡 Smart Credit Usage: This endpoint only deducts credits for leads that contain contact information (at least one email or phone number). Leads without contact info are returned but don't consume credits, making this endpoint cost-effective for bulk enrichment.

Request Body Parameters

Parameter	Type	Description
`lead_ids`required	array of integers	Array of lead_ids to enrich. Maximum 1000 lead_ids per request. Each lead_id must be a positive integer.
`decision_makers`optional	boolean	Set to `true` to unlock decision maker contacts (founders, CEOs, etc.) for each lead. Results are returned in `results[].decision_makers`. Default: `false`.
`roles`optional	array of strings	Filter decision makers by preferred role(s). Only used when `decision_makers: true`. Accepted values: `"founder"`, `"co-founder"`, `"ceo"`, `"cto"`, `"cfo"`, `"coo"`, `"marketing"`, `"sales"`, `"operations"`, `"product"`, `"engineering"`, `"design"`. If omitted or empty, all available roles are returned.
`max_per_store`optional	integer	Maximum number of decision maker contacts to return per lead. Only used when `decision_makers: true`. Default: `1`.
`include_fallback`optional	boolean	When `decision_makers: true` and a `roles` filter is set, include the first available contact(s) (up to `max_per_store`) if no role match is found for a given lead. Default: `true`.

Request Examples

Store contact info only:

curl -X POST "https://www.storecensus.com/api/v1/enrich" \
  -H "Authorization: Bearer your.api.key" \
  -H "Content-Type: application/json" \
  -d '{
    "lead_ids": [12345, 67890, 11223, 44556]
  }'

With decision makers (role filter + fallback):

curl -X POST "https://www.storecensus.com/api/v1/enrich" \
  -H "Authorization: Bearer your.api.key" \
  -H "Content-Type: application/json" \
  -d '{
    "lead_ids": [12345, 67890, 11223, 44556],
    "decision_makers": true,
    "roles": ["founder", "ceo", "cto"],
    "include_fallback": true
  }'

Response Format

Store contact info only:

{
  "success": true,
  "results": [
    {
      "lead_id": 12345,
      "domain": "example-store.com",
      "emails": [
        {
          "email": "contact@example-store.com",
          "email_type": "general",
          "validated": true,
          "found_date": "2024-01-15",
          "email_deliverability": "good"
        }
      ],
      "phone": "+1-555-123-4567; +1-555-987-6543",
      "has_contact_info": true
    },
    {
      "lead_id": 67890,
      "domain": "another-store.com",
      "emails": null,
      "phone": null,
      "has_contact_info": false
    }
  ],
  "summary": {
    "total_requested": 4,
    "stores_with_contact_info": 2,
    "stores_without_contact_info": 2,
    "credits_deducted": 2
  }
}

With decision makers (decision_makers: true):

{
  "success": true,
  "results": [
    {
      "lead_id": 12345,
      "domain": "example-store.com",
      "emails": [...],
      "phone": "+1-555-123-4567",
      "has_contact_info": true,
      "decision_makers": [
        {
          "person_id": "storecensus_9871",
          "first_name": "Jane",
          "last_name": "Smith",
          "title": "CEO",
          "email": "jane@example-store.com",
          "phone": "+1-555-000-1234",
          "linkedin_url": "https://linkedin.com/in/janesmith"
        }
      ]
    },
    {
      "lead_id": 67890,
      "domain": "another-store.com",
      "emails": null,
      "phone": null,
      "has_contact_info": false,
      "decision_makers": null
    }
  ],
  "summary": {
    "total_requested": 4,
    "stores_with_contact_info": 2,
    "stores_without_contact_info": 2,
    "credits_deducted": 2,
    "decision_makers_unlocked": 1
  }
}

Response Fields

Field	Description
`success`	Boolean indicating if the request was successful
`results`	Array of enrichment results for each lead_id found
`results[].lead_id`	The lead ID
`results[].domain`	The store's domain name
`results[].emails`	Array of email objects or null if no emails found
`results[].phone`	Phone number(s) as semicolon-separated string, or null if no phones found
`results[].has_contact_info`	Boolean indicating if this lead has any contact information
`summary.total_requested`	Total number of lead_ids requested
`summary.stores_with_contact_info`	Number of stores that had contact information
`summary.stores_without_contact_info`	Number of stores without contact information
`summary.already_unlocked`	Number of stores that were already unlocked (no credit charged)
`summary.newly_unlocked`	Number of stores newly unlocked in this request
`summary.credits_deducted`	Number of credits deducted (1 per newly unlocked store only)
`summary.decision_makers_unlocked`	(Only present when `decision_makers: true`) Number of leads for which decision maker contacts were newly persisted. Re-requesting already-unlocked leads does not increment this count.
`results[].decision_makers`	(Only present when `decision_makers: true`) Array of decision maker contact objects for this lead, or `null` if none were found. Each object contains: `person_id`, `first_name`, `last_name`, `title`, `email`, `phone`, `linkedin_url`.
`credits.remaining`	Total credits remaining after this request
`credits.subscription`	Subscription credits remaining
`credits.addon`	Add-on credits remaining

Credit Deduction Logic

1 credit per lead is deducted only if the lead has at least one email OR one phone number
Already unlocked leads are FREE - if you've previously unlocked a lead, you can access it again without using credits
Leads without any contact information are returned but do not consume credits
The response includes your remaining credit balance (credits.remaining) so you can track usage
If you don't have enough credits, the request will fail with a 402 status code before any data is returned

💎 Decision Maker Credits

2 credits per decision maker unlocked — charged in addition to the 1 credit for store contact info
With max_per_store: 1 (default) → 2 credits per store with a decision maker
With max_per_store: 2 → up to 4 credits per store for decision makers
Already-unlocked leads are FREE — if decision makers were previously unlocked for a lead, they are returned at no charge
Unlimited plan users are not charged credits for decision maker unlocks

Error Responses

Status Code	Error	Description
400	lead_ids must be a non-empty array	The lead_ids parameter is missing or invalid
400	Maximum 1000 lead_ids per request	Too many lead_ids provided in a single request
402	Insufficient credits available	Not enough credits to complete the enrichment

The /apps Endpoint

The /api/v1/apps endpoint returns a paginated list of active Shopify apps from the shopify_apps table. This endpoint is perfect for building app directories, competitor analysis tools, or market research applications.

Endpoint Details

URL	`GET /api/v1/apps`
Description	Returns a paginated list of active Shopify apps with category information, ratings, and metadata.
Authentication	Required (Bearer token)
Rate Limited	Yes (based on subscription plan)

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number (1-indexed)
`pageSize`	integer	100	Records per page (1-500, max 500)
`app_id`	integer	null	Filter by specific app ID
`minRating`	float	null	Minimum app rating (0-5)
`search`	string	null	Search in name, description, or developer
`categoryId`	integer	null	Filter by category ID

💡 Maximum Page Size: You can retrieve up to 500 apps per request (maximum enforced by API). For optimal performance, we recommend using page sizes between 100-500 records.

Request Examples

Basic request - Get first 100 apps:

curl -X GET "https://www.storecensus.com/api/v1/apps?page=1&pageSize=100" \
  -H "Authorization: Bearer your.api.key"

Get specific app by ID:

curl -X GET "https://www.storecensus.com/api/v1/apps?app_id=12345" \
  -H "Authorization: Bearer your.api.key"

Filter by minimum rating:

curl -X GET "https://www.storecensus.com/api/v1/apps?minRating=4.0&pageSize=200" \
  -H "Authorization: Bearer your.api.key"

Search apps:

curl -X GET "https://www.storecensus.com/api/v1/apps?search=email&page=1" \
  -H "Authorization: Bearer your.api.key"

Get maximum records (500 per page):

curl -X GET "https://www.storecensus.com/api/v1/apps?pageSize=500" \
  -H "Authorization: Bearer your.api.key"

Response Format

{
  "data": [
    {
      "app_id": 1,
      "name": "Point of Sale",
      "handle": "shopify-pos",
      "description": "Shopify POS is the only point of sale...",
      "icon_url": "https://cdn.shopify.com/.../icon.png",
      "rating": 2.9,
      "developer": "apps.shopify.com",
      "active": true,
      "check_status": "done",
      "last_updated": "2026-02-02T13:42:04.000Z",
      "main_category": {
        "category_id": 12,
        "name": "Point of Sale",
        "slug": "point-of-sale"
      },
      "categories": [
        {
          "category_id": 12,
          "name": "Point of Sale",
          "slug": "point-of-sale",
          "is_main": true
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 100,
    "total": 11000,
    "totalPages": 110,
    "hasMore": true
  },
  "filters": {
    "categoryId": null,
    "minRating": null,
    "search": null
  }
}

Response Fields

Field	Description
`app_id`	Unique app identifier
`name`	App name
`handle`	URL-friendly app handle
`rating`	Average rating (0-5)
`main_category`	Primary category with id, name, and slug
`categories`	Array of all associated categories
`pagination.total`	Total number of apps matching filters
`pagination.hasMore`	Boolean indicating if more pages exist

Use Cases

App Directory: Build a searchable directory of Shopify apps with filtering and sorting
Competitor Analysis: Track competitor apps and their ratings over time
Market Research: Analyze app categories, pricing, and market trends
Integration Discovery: Help merchants find apps that integrate with your service
Data Enrichment: Enrich your database with comprehensive Shopify app information

The /app-categories Endpoint

The /api/v1/app-categories endpoint returns all Shopify app categories that have at least one active app. Use this endpoint to build category navigation, populate filter dropdowns, or discover available app categories.

Endpoint Details

URL	`GET /api/v1/app-categories`
Description	Returns all app categories with active apps, including app counts for each category.
Authentication	Required (Bearer token)
Rate Limited	Yes (based on subscription plan)

💡 Integration Tip: Use the category_id from this endpoint with the /apps endpoint to filter apps by category.

Request Example

curl -X GET "https://www.storecensus.com/api/v1/app-categories" \
  -H "Authorization: Bearer your.api.key"

Response Format

{
  "data": [
    {
      "category_id": 1,
      "name": "Marketing",
      "slug": "marketing",
      "app_count": 150
    },
    {
      "category_id": 2,
      "name": "Sales & Conversion",
      "slug": "sales-conversion",
      "app_count": 89
    }
  ],
  "total": 45
}

Integration Example

Combine with the /apps endpoint to build a category-filtered app directory:

# Step 1: Get all categories
curl -H "Authorization: Bearer your.api.key" \
  "https://www.storecensus.com/api/v1/app-categories"

# Step 2: Use category_id to filter apps
curl -H "Authorization: Bearer your.api.key" \
  "https://www.storecensus.com/api/v1/apps?categoryId=1&pageSize=100"

Use Cases

Category Navigation: Build a category menu for your app directory
Filter Dropdowns: Populate category filter options dynamically
Analytics: Track which categories have the most apps
Discovery: Help users discover apps by browsing categories

StoreCensus API Documentation

Introduction

Authentication

Authentication Method

Authentication Errors

Rate Limits

Rate Limit Plans

Rate Limit Implementation

Error Handling

Error Response Format

The /website Endpoint

Endpoint Details

Path Parameters

Query Parameters

Request Examples

Response Format

The /stores Endpoint

Endpoint Details

Request Body Parameters

Complete Filters Reference

Available Sections

Getting App IDs

Request Example

Response Format

Pagination

Best Practices

🎛️ Selection Logic

Shape

Eligible Filter Keys

Behaviour Matrix

Example — Exclude stores using Klaviyo OR Mailchimp

Example — Stores using ALL of the selected payment methods

⏱️ Timing Filters (historicalConstraints)

Constraint Shape

Supported Attributes

Supported Events

Example — Stores that first installed a specific app in Q1 2024

Example — Stores that removed PayPal in the last 6 months

Example — Combined: app installed AND plan upgraded in same window

The /enrich Endpoint

Endpoint Details

Request Body Parameters

Request Examples

Response Format

Response Fields

Credit Deduction Logic

Error Responses

The /apps Endpoint

Endpoint Details

Query Parameters

Request Examples

Response Format

Response Fields

Use Cases

The /app-categories Endpoint

Endpoint Details

Request Example

Response Format

Integration Example

Use Cases

Subscription Required