DEVELOPER REFERENCE / V1

Build on better data.

Search stores, unlock the right businesses and work with lists through the same API that powers MerchTrace.

Start with a scoped API key

A paid plan is required. Create a key in your account, grant only the scopes you need, then send it in the x-api-key header. Keep keys on your server or in your local environment.

curl -G https://api.merchtrace.com/api/v1/stores \
  -H "x-api-key: $MERCHTRACE_API_KEY" \
  --data-urlencode "countries=US" \
  --data-urlencode "limit=10"

Array filters accept comma-separated values. Follow next_cursor for the next page; keep filters and sort unchanged. The API returns root store URLs.

Credits, retries and errors

Catalog searches do not spend unlock credits. Unlocking a new store spends one credit. Write operations need the documented scopes, and credit-spending requests include a maximum credit budget.

For mutations that require Idempotency-Key, keep the same key and body when retrying. Use a new key for a different action. Rate limits are weighted and depend on your plan.

400: invalid request · 401: missing or invalid credentials · 403: insufficient permission or entitlement · 404: missing resource · 409: conflicting mutation · 429: rate limit. Inspect the error response and request ID when troubleshooting.

Generated from backend controllers, validated request DTOs and TypeScript response types. Examples use placeholders; replace path IDs and provide your JSON body where required.

26 of 26 operations

Store catalog

post`/stores/ai-filters`

Use POST /stores/ai-filters.

Required scope: stores:read

curl -X POST 'https://api.merchtrace.com/api/v1/stores/ai-filters' \
  -H "x-api-key: $MERCHTRACE_API_KEY" \
  -H "Content-Type: application/json" \
  --data @request.json

JSON request body required

prompt string required

minLength: 3maxLength: 500

Responses

200 A complete, validated store filter set generated from text.

application/json

filters object required

View structure

q string required

platforms string[] required

View structure

Array items

string

technologies_any string[] required

View structure

Array items

string

countries string[] required

View structure

Array items

string

languages string[] required

View structure

Array items

string

domain_suffixes string[] required

View structure

Array items

string

ownership union required

View structure

Variant 1: string

string

Allowed: all

Variant 2: string

string

Allowed: owned

Variant 3: string

string

Allowed: not_owned

has_email union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

has_phone union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

has_social union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

sort union required

View structure

Variant 1: string

string

Allowed: newest

Variant 2: string

string

Allowed: relevance

Variant 3: string

string

Allowed:

summary string required

unsupported string[] required

View structure

Array items

string

Store catalog

get`/stores`

Use GET /stores.

Required scope: stores:read

curl 'https://api.merchtrace.com/api/v1/stores' \
  -H "x-api-key: $MERCHTRACE_API_KEY"

Parameters 47

q query · string

minLength: 1maxLength: 100

platforms query · string[]

minLength: 1maxLength: 64maxItems: 20

exclude_platforms query · string[]

minLength: 1maxLength: 64maxItems: 20

technologies_any query · string[]

minLength: 1maxLength: 100maxItems: 50

technologies_all query · string[]

minLength: 1maxLength: 100maxItems: 20

exclude_technologies query · string[]

minLength: 1maxLength: 100maxItems: 50

countries query · string[]

minLength: 2maxLength: 2maxItems: 50

languages query · string[]

minLength: 2maxLength: 20maxItems: 20

currencies query · string[]

minLength: 3maxLength: 3maxItems: 20

categories query · string[]

Item values: fashion_apparel, jewelry_watches_accessories, beauty_personal_care, health_wellness, home_furniture_garden, food_beverage, sports_fitness_outdoors, electronics_computers, baby_kids_maternity, pets_animal_supplies, automotive_motorcycle_marine, toys_games_hobbies, arts_crafts_collectibles, books_stationery_media, gifts_flowers_special_events, travel_luggage, tools_hardware_home_improvement, business_industrial_wholesale, office_school_supplies, education_learning, software_digital_products, services_experiences_rentals, religious_ceremonial, adult_products, alcohol, tobacco_vape_cannabis, weapons_tactical_survival, general_merchandise_multi_category, othermaxItems: 29

business_models query · string[]

Item values: direct_to_consumer, marketplace, retailer, manufacturer, wholesale_b2b, subscription, services, digital, mixed, unknownmaxItems: 10

customer_focuses query · string[]

Item values: consumer, business, both, unknownmaxItems: 4

price_positionings query · string[]

Item values: budget, mid_market, premium, luxury, unknownmaxItems: 5

market_scopes query · string[]

Item values: local, national, international, unknownmaxItems: 4

content_qualities query · string[]

Item values: low, medium, highmaxItems: 3

product_types query · string[]

minLength: 1maxLength: 100maxItems: 20

audiences query · string[]

minLength: 1maxLength: 100maxItems: 20

payment_methods query · string[]

minLength: 1maxLength: 64maxItems: 20

social_platforms query · string[]

Item values: instagram, facebook, tiktok, pinterest, youtube, x, linkedin, threads, whatsapp, telegrammaxItems: 10

domain_suffixes query · string[]

minLength: 2maxLength: 64maxItems: 20

has_email query · boolean

has_phone query · boolean

has_social query · boolean

sells_physical_products query · boolean

offers_services query · boolean

free_shipping query · boolean

multi_language query · boolean

multi_currency query · boolean

local_pickup query · boolean

local_delivery query · boolean

ships_internationally query · boolean

first_order_discount query · boolean

gift_cards_available query · boolean

subscription_available query · boolean

wholesale_available query · boolean

physical_store_available query · boolean

newsletter_signup query · boolean

cart_detected query · boolean

account_detected query · boolean

search_detected query · boolean

has_logo query · boolean

has_favicon query · boolean

has_social_image query · boolean

ownership query · string

Allowed: all, owned, not_owned

sort query · string

Allowed: newest, relevance

limit query · number

minimum: 1maximum: 100

cursor query · string

minLength: 40maxLength: 2048

Responses

200 A cursor-paginated collection of locked or previously unlocked stores.

application/json

data union[] required

View structure

Array items

Variant 1: object

locked boolean required

Allowed: true

social_links_available union[] required

View structure

Array items

Variant 1: string

string

Allowed: instagram

Variant 2: string

string

Allowed: facebook

Variant 3: string

string

Allowed: tiktok

Variant 4: string

string

Allowed: pinterest

Variant 5: string

string

Allowed: youtube

Variant 6: string

string

Allowed: x

Variant 7: string

string

Allowed: linkedin

Variant 8: string

string

Allowed: threads

Variant 9: string

string

Allowed: whatsapp

Variant 10: string

string

Allowed: telegram

technologies object[] required

View structure

Array items

slug string required

name string

category string

kind string

contact_availability object required

View structure

email union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

phone union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

enrichment object | null required

View structure

description string required

category union required

View structure

Variant 1: string

string

Allowed: fashion_apparel

Variant 2: string

string

Allowed: jewelry_watches_accessories

Variant 3: string

string

Allowed: beauty_personal_care

Variant 4: string

string

Allowed: health_wellness

Variant 5: string

string

Allowed: home_furniture_garden

Variant 6: string

string

Allowed: food_beverage

Variant 7: string

string

Allowed: sports_fitness_outdoors

Variant 8: string

string

Allowed: electronics_computers

Variant 9: string

string

Allowed: baby_kids_maternity

Variant 10: string

string

Allowed: pets_animal_supplies

Variant 11: string

string

Allowed: automotive_motorcycle_marine

Variant 12: string

string

Allowed: toys_games_hobbies

Variant 13: string

string

Allowed: arts_crafts_collectibles

Variant 14: string

string

Allowed: books_stationery_media

Variant 15: string

string

Allowed: gifts_flowers_special_events

Variant 16: string

string

Allowed: travel_luggage

Variant 17: string

string

Allowed: tools_hardware_home_improvement

Variant 18: string

string

Allowed: business_industrial_wholesale

Variant 19: string

string

Allowed: office_school_supplies

Variant 20: string

string

Allowed: education_learning

Variant 21: string

string

Allowed: software_digital_products

Variant 22: string

string

Allowed: services_experiences_rentals

Variant 23: string

string

Allowed: religious_ceremonial

Variant 24: string

string

Allowed: adult_products

Variant 25: string

string

Allowed: alcohol

Variant 26: string

string

Allowed: tobacco_vape_cannabis

Variant 27: string

string

Allowed: weapons_tactical_survival

Variant 28: string

string

Allowed: general_merchandise_multi_category

Variant 29: string

string

Allowed: other

product_types string[] required

View structure

Array items

string

audience string[] required

View structure

Array items

string

business_model union required

View structure

Variant 1: string

string

Allowed: direct_to_consumer

Variant 2: string

string

Allowed: marketplace

Variant 3: string

string

Allowed: retailer

Variant 4: string

string

Allowed: manufacturer

Variant 5: string

string

Allowed: wholesale_b2b

Variant 6: string

string

Allowed: subscription

Variant 7: string

string

Allowed: services

Variant 8: string

string

Allowed: digital

Variant 9: string

string

Allowed: mixed

Variant 10: string

string

Allowed: unknown

customer_focus union required

View structure

Variant 1: string

string

Allowed: unknown

Variant 2: string

string

Allowed: consumer

Variant 3: string

string

Allowed: business

Variant 4: string

string

Allowed: both

price_positioning union required

View structure

Variant 1: string

string

Allowed: unknown

Variant 2: string

string

Allowed: budget

Variant 3: string

string

Allowed: mid_market

Variant 4: string

string

Allowed: premium

Variant 5: string

string

Allowed: luxury

primary_language string required

sells_physical_products union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

offers_services union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

market_scope union required

View structure

Variant 1: string

string

Allowed: unknown

Variant 2: string

string

Allowed: local

Variant 3: string

string

Allowed: national

Variant 4: string

string

Allowed: international

content_quality union required

View structure

Variant 1: string

string

Allowed: low

Variant 2: string

string

Allowed: medium

Variant 3: string

string

Allowed: high

free_shipping union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

free_shipping_threshold string required

multi_language union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

languages_available string[] required

View structure

Array items

string

multi_currency union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

currencies_available string[] required

View structure

Array items

string

local_pickup union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

local_delivery union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

ships_internationally union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

first_order_discount union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

discount_details string required

gift_cards_available union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

subscription_available union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

wholesale_available union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

physical_store_available union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

evidence string[] required

View structure

Array items

string

id string required

platform string required

country_code string | null required

primary_language string | null required

currencies object required

View structure

shop string | null required

presentment string | null required

Variant 2: object

contacts object required

View structure

emails object[] required

View structure

Array items

object

phone_numbers object[] required

View structure

Array items

object

idn object required

View structure

status string required

risk_level string required

homepage_signals object | null required

View structure

deterministic_version string | null

themes object[]

View structure

Array items

name string | null required

schema_name string | null required

schema_version string | null required

id string | null required

theme_store_id string | null required

role string | null required

theme_ids string[]

View structure

Array items

string

theme_evidence_strength string | null

extension_handles string[]

View structure

Array items

string

app_proxy_paths string[]

View structure

Array items

string

technology_coverage object

View structure

checked number required

not_checked number required

detected number required

source string required

Allowed: homepage_html

logo_url string | null required

favicon_url string | null required

social_image_url string | null required

languages_detected string[] required

View structure

Array items

string

currencies_detected string[] required

View structure

Array items

string

free_shipping_mentions string[] required

View structure

Array items

string

payment_methods string[] required

View structure

Array items

string

social_links object required

View structure

newsletter_signup union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

cart_detected union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

account_detected union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

search_detected union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

locked boolean required

Allowed: false

domain string required

display_domain string required

canonical_url string | null required

store_name string | null required

technologies object[] required

View structure

Array items

slug string required

name string

category string

kind string

contact_availability object required

View structure

email union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

phone union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

enrichment object | null required

View structure

description string required

category union required

View structure

Variant 1: string

string

Allowed: fashion_apparel

Variant 2: string

string

Allowed: jewelry_watches_accessories

Variant 3: string

string

Allowed: beauty_personal_care

Variant 4: string

string

Allowed: health_wellness

Variant 5: string

string

Allowed: home_furniture_garden

Variant 6: string

string

Allowed: food_beverage

Variant 7: string

string

Allowed: sports_fitness_outdoors

Variant 8: string

string

Allowed: electronics_computers

Variant 9: string

string

Allowed: baby_kids_maternity

Variant 10: string

string

Allowed: pets_animal_supplies

Variant 11: string

string

Allowed: automotive_motorcycle_marine

Variant 12: string

string

Allowed: toys_games_hobbies

Variant 13: string

string

Allowed: arts_crafts_collectibles

Variant 14: string

string

Allowed: books_stationery_media

Variant 15: string

string

Allowed: gifts_flowers_special_events

Variant 16: string

string

Allowed: travel_luggage

Variant 17: string

string

Allowed: tools_hardware_home_improvement

Variant 18: string

string

Allowed: business_industrial_wholesale

Variant 19: string

string

Allowed: office_school_supplies

Variant 20: string

string

Allowed: education_learning

Variant 21: string

string

Allowed: software_digital_products

Variant 22: string

string

Allowed: services_experiences_rentals

Variant 23: string

string

Allowed: religious_ceremonial

Variant 24: string

string

Allowed: adult_products

Variant 25: string

string

Allowed: alcohol

Variant 26: string

string

Allowed: tobacco_vape_cannabis

Variant 27: string

string

Allowed: weapons_tactical_survival

Variant 28: string

string

Allowed: general_merchandise_multi_category

Variant 29: string

string

Allowed: other

product_types string[] required

View structure

Array items

string

audience string[] required

View structure

Array items

string

business_model union required

View structure

Variant 1: string

string

Allowed: direct_to_consumer

Variant 2: string

string

Allowed: marketplace

Variant 3: string

string

Allowed: retailer

Variant 4: string

string

Allowed: manufacturer

Variant 5: string

string

Allowed: wholesale_b2b

Variant 6: string

string

Allowed: subscription

Variant 7: string

string

Allowed: services

Variant 8: string

string

Allowed: digital

Variant 9: string

string

Allowed: mixed

Variant 10: string

string

Allowed: unknown

customer_focus union required

View structure

Variant 1: string

string

Allowed: unknown

Variant 2: string

string

Allowed: consumer

Variant 3: string

string

Allowed: business

Variant 4: string

string

Allowed: both

price_positioning union required

View structure

Variant 1: string

string

Allowed: unknown

Variant 2: string

string

Allowed: budget

Variant 3: string

string

Allowed: mid_market

Variant 4: string

string

Allowed: premium

Variant 5: string

string

Allowed: luxury

primary_language string required

sells_physical_products union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

offers_services union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

market_scope union required

View structure

Variant 1: string

string

Allowed: unknown

Variant 2: string

string

Allowed: local

Variant 3: string

string

Allowed: national

Variant 4: string

string

Allowed: international

content_quality union required

View structure

Variant 1: string

string

Allowed: low

Variant 2: string

string

Allowed: medium

Variant 3: string

string

Allowed: high

free_shipping union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

free_shipping_threshold string required

multi_language union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

languages_available string[] required

View structure

Array items

string

multi_currency union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

currencies_available string[] required

View structure

Array items

string

local_pickup union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

local_delivery union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

ships_internationally union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

first_order_discount union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

discount_details string required

gift_cards_available union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

subscription_available union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

wholesale_available union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

physical_store_available union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

evidence string[] required

View structure

Array items

string

id string required

platform string required

country_code string | null required

primary_language string | null required

currencies object required

View structure

shop string | null required

presentment string | null required

next_cursor string | null required

has_more union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

Store catalog

get`/stores/{storeId}`

Use GET /stores/{storeId}.

Required scope: stores:read

curl 'https://api.merchtrace.com/api/v1/stores/{storeId}' \
  -H "x-api-key: $MERCHTRACE_API_KEY"

Parameters 1

storeId path · string required

format: uuid

Responses

200

application/json

Variant 1: object

locked boolean required

Allowed: true

social_links_available union[] required

View structure

Array items

Variant 1: string

string

Allowed: instagram

Variant 2: string

string

Allowed: facebook

Variant 3: string

string

Allowed: tiktok

Variant 4: string

string

Allowed: pinterest

Variant 5: string

string

Allowed: youtube

Variant 6: string

string

Allowed: x

Variant 7: string

string

Allowed: linkedin

Variant 8: string

string

Allowed: threads

Variant 9: string

string

Allowed: whatsapp

Variant 10: string

string

Allowed: telegram

technologies object[] required

View structure

Array items

slug string required

name string

category string

kind string

contact_availability object required

View structure

email union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

phone union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

enrichment object | null required

View structure

description string required

category union required

View structure

Variant 1: string

string

Allowed: fashion_apparel

Variant 2: string

string

Allowed: jewelry_watches_accessories

Variant 3: string

string

Allowed: beauty_personal_care

Variant 4: string

string

Allowed: health_wellness

Variant 5: string

string

Allowed: home_furniture_garden

Variant 6: string

string

Allowed: food_beverage

Variant 7: string

string

Allowed: sports_fitness_outdoors

Variant 8: string

string

Allowed: electronics_computers

Variant 9: string

string

Allowed: baby_kids_maternity

Variant 10: string

string

Allowed: pets_animal_supplies

Variant 11: string

string

Allowed: automotive_motorcycle_marine

Variant 12: string

string

Allowed: toys_games_hobbies

Variant 13: string

string

Allowed: arts_crafts_collectibles

Variant 14: string

string

Allowed: books_stationery_media

Variant 15: string

string

Allowed: gifts_flowers_special_events

Variant 16: string

string

Allowed: travel_luggage

Variant 17: string

string

Allowed: tools_hardware_home_improvement

Variant 18: string

string

Allowed: business_industrial_wholesale

Variant 19: string

string

Allowed: office_school_supplies

Variant 20: string

string

Allowed: education_learning

Variant 21: string

string

Allowed: software_digital_products

Variant 22: string

string

Allowed: services_experiences_rentals

Variant 23: string

string

Allowed: religious_ceremonial

Variant 24: string

string

Allowed: adult_products

Variant 25: string

string

Allowed: alcohol

Variant 26: string

string

Allowed: tobacco_vape_cannabis

Variant 27: string

string

Allowed: weapons_tactical_survival

Variant 28: string

string

Allowed: general_merchandise_multi_category

Variant 29: string

string

Allowed: other

product_types string[] required

View structure

Array items

string

audience string[] required

View structure

Array items

string

business_model union required

View structure

Variant 1: string

string

Allowed: direct_to_consumer

Variant 2: string

string

Allowed: marketplace

Variant 3: string

string

Allowed: retailer

Variant 4: string

string

Allowed: manufacturer

Variant 5: string

string

Allowed: wholesale_b2b

Variant 6: string

string

Allowed: subscription

Variant 7: string

string

Allowed: services

Variant 8: string

string

Allowed: digital

Variant 9: string

string

Allowed: mixed

Variant 10: string

string

Allowed: unknown

customer_focus union required

View structure

Variant 1: string

string

Allowed: unknown

Variant 2: string

string

Allowed: consumer

Variant 3: string

string

Allowed: business

Variant 4: string

string

Allowed: both

price_positioning union required

View structure

Variant 1: string

string

Allowed: unknown

Variant 2: string

string

Allowed: budget

Variant 3: string

string

Allowed: mid_market

Variant 4: string

string

Allowed: premium

Variant 5: string

string

Allowed: luxury

primary_language string required

sells_physical_products union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

offers_services union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

market_scope union required

View structure

Variant 1: string

string

Allowed: unknown

Variant 2: string

string

Allowed: local

Variant 3: string

string

Allowed: national

Variant 4: string

string

Allowed: international

content_quality union required

View structure

Variant 1: string

string

Allowed: low

Variant 2: string

string

Allowed: medium

Variant 3: string

string

Allowed: high

free_shipping union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

free_shipping_threshold string required

multi_language union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

languages_available string[] required

View structure

Array items

string

multi_currency union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

currencies_available string[] required

View structure

Array items

string

local_pickup union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

local_delivery union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

ships_internationally union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

first_order_discount union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

discount_details string required

gift_cards_available union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

subscription_available union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

wholesale_available union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

physical_store_available union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

evidence string[] required

View structure

Array items

string

id string required

platform string required

country_code string | null required

primary_language string | null required

currencies object required

View structure

shop string | null required

presentment string | null required

Variant 2: object

contacts object required

View structure

emails object[] required

View structure

Array items

object

phone_numbers object[] required

View structure

Array items

object

idn object required

View structure

status string required

risk_level string required

homepage_signals object | null required

View structure

deterministic_version string | null

themes object[]

View structure

Array items

name string | null required

schema_name string | null required

schema_version string | null required

id string | null required

theme_store_id string | null required

role string | null required

theme_ids string[]

View structure

Array items

string

theme_evidence_strength string | null

extension_handles string[]

View structure

Array items

string

app_proxy_paths string[]

View structure

Array items

string

technology_coverage object

View structure

checked number required

not_checked number required

detected number required

source string required

Allowed: homepage_html

logo_url string | null required

favicon_url string | null required

social_image_url string | null required

languages_detected string[] required

View structure

Array items

string

currencies_detected string[] required

View structure

Array items

string

free_shipping_mentions string[] required

View structure

Array items

string

payment_methods string[] required

View structure

Array items

string

social_links object required

View structure

newsletter_signup union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

cart_detected union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

account_detected union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

search_detected union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

locked boolean required

Allowed: false

domain string required

display_domain string required

canonical_url string | null required

store_name string | null required

technologies object[] required

View structure

Array items

slug string required

name string

category string

kind string

contact_availability object required

View structure

email union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

phone union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

enrichment object | null required

View structure

description string required

category union required

View structure

Variant 1: string

string

Allowed: fashion_apparel

Variant 2: string

string

Allowed: jewelry_watches_accessories

Variant 3: string

string

Allowed: beauty_personal_care

Variant 4: string

string

Allowed: health_wellness

Variant 5: string

string

Allowed: home_furniture_garden

Variant 6: string

string

Allowed: food_beverage

Variant 7: string

string

Allowed: sports_fitness_outdoors

Variant 8: string

string

Allowed: electronics_computers

Variant 9: string

string

Allowed: baby_kids_maternity

Variant 10: string

string

Allowed: pets_animal_supplies

Variant 11: string

string

Allowed: automotive_motorcycle_marine

Variant 12: string

string

Allowed: toys_games_hobbies

Variant 13: string

string

Allowed: arts_crafts_collectibles

Variant 14: string

string

Allowed: books_stationery_media

Variant 15: string

string

Allowed: gifts_flowers_special_events

Variant 16: string

string

Allowed: travel_luggage

Variant 17: string

string

Allowed: tools_hardware_home_improvement

Variant 18: string

string

Allowed: business_industrial_wholesale

Variant 19: string

string

Allowed: office_school_supplies

Variant 20: string

string

Allowed: education_learning

Variant 21: string

string

Allowed: software_digital_products

Variant 22: string

string

Allowed: services_experiences_rentals

Variant 23: string

string

Allowed: religious_ceremonial

Variant 24: string

string

Allowed: adult_products

Variant 25: string

string

Allowed: alcohol

Variant 26: string

string

Allowed: tobacco_vape_cannabis

Variant 27: string

string

Allowed: weapons_tactical_survival

Variant 28: string

string

Allowed: general_merchandise_multi_category

Variant 29: string

string

Allowed: other

product_types string[] required

View structure

Array items

string

audience string[] required

View structure

Array items

string

business_model union required

View structure

Variant 1: string

string

Allowed: direct_to_consumer

Variant 2: string

string

Allowed: marketplace

Variant 3: string

string

Allowed: retailer

Variant 4: string

string

Allowed: manufacturer

Variant 5: string

string

Allowed: wholesale_b2b

Variant 6: string

string

Allowed: subscription

Variant 7: string

string

Allowed: services

Variant 8: string

string

Allowed: digital

Variant 9: string

string

Allowed: mixed

Variant 10: string

string

Allowed: unknown

customer_focus union required

View structure

Variant 1: string

string

Allowed: unknown

Variant 2: string

string

Allowed: consumer

Variant 3: string

string

Allowed: business

Variant 4: string

string

Allowed: both

price_positioning union required

View structure

Variant 1: string

string

Allowed: unknown

Variant 2: string

string

Allowed: budget

Variant 3: string

string

Allowed: mid_market

Variant 4: string

string

Allowed: premium

Variant 5: string

string

Allowed: luxury

primary_language string required

sells_physical_products union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

offers_services union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

market_scope union required

View structure

Variant 1: string

string

Allowed: unknown

Variant 2: string

string

Allowed: local

Variant 3: string

string

Allowed: national

Variant 4: string

string

Allowed: international

content_quality union required

View structure

Variant 1: string

string

Allowed: low

Variant 2: string

string

Allowed: medium

Variant 3: string

string

Allowed: high

free_shipping union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

free_shipping_threshold string required

multi_language union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

languages_available string[] required

View structure

Array items

string

multi_currency union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

currencies_available string[] required

View structure

Array items

string

local_pickup union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

local_delivery union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

ships_internationally union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

first_order_discount union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

discount_details string required

gift_cards_available union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

subscription_available union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

wholesale_available union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

physical_store_available union required

View structure

Variant 1: boolean

boolean

Allowed: false

Variant 2: boolean

boolean

Allowed: true

evidence string[] required

View structure

Array items

string

id string required

platform string required

country_code string | null required

primary_language string | null required

currencies object required

View structure

shop string | null required

presentment string | null required

Store catalog

get`/platforms`

Use GET /platforms.

Required scope: stores:read

curl 'https://api.merchtrace.com/api/v1/platforms' \
  -H "x-api-key: $MERCHTRACE_API_KEY"

Responses

200

application/json

data object[] required

View structure

Array items

slug string required

store_count number required

Store catalog

get`/technologies`

Use GET /technologies.

Required scope: stores:read

curl 'https://api.merchtrace.com/api/v1/technologies' \
  -H "x-api-key: $MERCHTRACE_API_KEY"

Parameters 4

q query · string

minLength: 1maxLength: 100

category query · string

minLength: 1maxLength: 100

kind query · string

Allowed: shopify_app, web_technology

limit query · number

minimum: 1maximum: 100

Responses

200

application/json

data object[] required

View structure

Array items

slug string required

name string required

category string required

kind string required

observability_tier string required

store_count number required

Store catalog

get`/technologies/{slug}`

Use GET /technologies/{slug}.

Required scope: stores:read

curl 'https://api.merchtrace.com/api/v1/technologies/{slug}' \
  -H "x-api-key: $MERCHTRACE_API_KEY"

Parameters 1

slug path · string required

Responses

200

application/json

slug string required

name string required

category string required

kind string required

observability_tier string required

store_count number required

Store catalog

get`/store-count`

Use GET /store-count.

Required scope: stores:read

curl 'https://api.merchtrace.com/api/v1/store-count' \
  -H "x-api-key: $MERCHTRACE_API_KEY"

Parameters 47

q query · string

minLength: 1maxLength: 100

platforms query · string[]

minLength: 1maxLength: 64maxItems: 20

exclude_platforms query · string[]

minLength: 1maxLength: 64maxItems: 20

technologies_any query · string[]

minLength: 1maxLength: 100maxItems: 50

technologies_all query · string[]

minLength: 1maxLength: 100maxItems: 20

exclude_technologies query · string[]

minLength: 1maxLength: 100maxItems: 50

countries query · string[]

minLength: 2maxLength: 2maxItems: 50

languages query · string[]

minLength: 2maxLength: 20maxItems: 20

currencies query · string[]

minLength: 3maxLength: 3maxItems: 20

categories query · string[]

business_models query · string[]

Item values: direct_to_consumer, marketplace, retailer, manufacturer, wholesale_b2b, subscription, services, digital, mixed, unknownmaxItems: 10

customer_focuses query · string[]

Item values: consumer, business, both, unknownmaxItems: 4

price_positionings query · string[]

Item values: budget, mid_market, premium, luxury, unknownmaxItems: 5

market_scopes query · string[]

Item values: local, national, international, unknownmaxItems: 4

content_qualities query · string[]

Item values: low, medium, highmaxItems: 3

product_types query · string[]

minLength: 1maxLength: 100maxItems: 20

audiences query · string[]

minLength: 1maxLength: 100maxItems: 20

payment_methods query · string[]

minLength: 1maxLength: 64maxItems: 20

social_platforms query · string[]

Item values: instagram, facebook, tiktok, pinterest, youtube, x, linkedin, threads, whatsapp, telegrammaxItems: 10

domain_suffixes query · string[]

minLength: 2maxLength: 64maxItems: 20

has_email query · boolean

has_phone query · boolean

has_social query · boolean

sells_physical_products query · boolean

offers_services query · boolean

free_shipping query · boolean

multi_language query · boolean

multi_currency query · boolean

local_pickup query · boolean

local_delivery query · boolean

ships_internationally query · boolean

first_order_discount query · boolean

gift_cards_available query · boolean

subscription_available query · boolean

wholesale_available query · boolean

physical_store_available query · boolean

newsletter_signup query · boolean

cart_detected query · boolean

account_detected query · boolean

search_detected query · boolean

has_logo query · boolean

has_favicon query · boolean

has_social_image query · boolean

ownership query · string

Allowed: all, owned, not_owned

sort query · string

Allowed: newest, relevance

limit query · number

minimum: 1maximum: 100

cursor query · string

minLength: 40maxLength: 2048

Responses

200 The exact number of stores matching the supplied filters.

application/json

total number required

Store catalog

get`/store-facets`

Use GET /store-facets.

Required scope: stores:read

curl 'https://api.merchtrace.com/api/v1/store-facets' \
  -H "x-api-key: $MERCHTRACE_API_KEY"

Parameters 47

q query · string

minLength: 1maxLength: 100

platforms query · string[]

minLength: 1maxLength: 64maxItems: 20

exclude_platforms query · string[]

minLength: 1maxLength: 64maxItems: 20

technologies_any query · string[]

minLength: 1maxLength: 100maxItems: 50

technologies_all query · string[]

minLength: 1maxLength: 100maxItems: 20

exclude_technologies query · string[]

minLength: 1maxLength: 100maxItems: 50

countries query · string[]

minLength: 2maxLength: 2maxItems: 50

languages query · string[]

minLength: 2maxLength: 20maxItems: 20

currencies query · string[]

minLength: 3maxLength: 3maxItems: 20

categories query · string[]

business_models query · string[]

Item values: direct_to_consumer, marketplace, retailer, manufacturer, wholesale_b2b, subscription, services, digital, mixed, unknownmaxItems: 10

customer_focuses query · string[]

Item values: consumer, business, both, unknownmaxItems: 4

price_positionings query · string[]

Item values: budget, mid_market, premium, luxury, unknownmaxItems: 5

market_scopes query · string[]

Item values: local, national, international, unknownmaxItems: 4

content_qualities query · string[]

Item values: low, medium, highmaxItems: 3

product_types query · string[]

minLength: 1maxLength: 100maxItems: 20

audiences query · string[]

minLength: 1maxLength: 100maxItems: 20

payment_methods query · string[]

minLength: 1maxLength: 64maxItems: 20

social_platforms query · string[]

Item values: instagram, facebook, tiktok, pinterest, youtube, x, linkedin, threads, whatsapp, telegrammaxItems: 10

domain_suffixes query · string[]

minLength: 2maxLength: 64maxItems: 20

has_email query · boolean

has_phone query · boolean

has_social query · boolean

sells_physical_products query · boolean

offers_services query · boolean

free_shipping query · boolean

multi_language query · boolean

multi_currency query · boolean

local_pickup query · boolean

local_delivery query · boolean

ships_internationally query · boolean

first_order_discount query · boolean

gift_cards_available query · boolean

subscription_available query · boolean

wholesale_available query · boolean

physical_store_available query · boolean

newsletter_signup query · boolean

cart_detected query · boolean

account_detected query · boolean

search_detected query · boolean

has_logo query · boolean

has_favicon query · boolean

has_social_image query · boolean

ownership query · string

Allowed: all, owned, not_owned

sort query · string

Allowed: newest, relevance

limit query · number

minimum: 1maximum: 100

cursor query · string

minLength: 40maxLength: 2048

Responses

200

application/json

total number required

facets object required

View structure

Store catalog

get`/store-facet-options`

Use GET /store-facet-options.

Required scope: stores:read

curl 'https://api.merchtrace.com/api/v1/store-facet-options' \
  -H "x-api-key: $MERCHTRACE_API_KEY"

Parameters 4

facet query · string required

Allowed: platform, technology, country, language, currency, domain_suffix, product_type, audience, payment_method, social_platform, category, business_model, customer_focus, price_positioning, market_scope, content_quality

q query · string

maxLength: 100

after query · string

maxLength: 1000

limit query · object required

minimum: 1maximum: 100Default: 50

Responses

200

application/json

data object[] required

View structure

Array items

value string required

label string

store_count number required

next_cursor string | null required

Store unlocks

post`/store-unlocks`

Use POST /store-unlocks.

Required scope: stores:write

curl -X POST 'https://api.merchtrace.com/api/v1/store-unlocks' \
  -H "x-api-key: $MERCHTRACE_API_KEY" \
  -H "Idempotency-Key: $UNIQUE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  --data @request.json

Parameters 1

Idempotency-Key header · string required

Use a unique key per mutation. Reuse it only when retrying the same request.

minLength: 8maxLength: 255

JSON request body required

store_ids string[] required

minItems: 1maxItems: 100

View structure

Array items

string

maximum_credits number required

minimum: 1maximum: 100

Responses

201

application/json

requested_count number required

newly_unlocked_count number required

already_unlocked_count number required

credits_charged number required

store_ids string[] required

View structure

Array items

string

balance object required

View structure

balance number required

reserved number required

available number required

updated_at string required

Exports

get`/exports/{id}`

Use GET /exports/{id}.

Required scope: lists:read

curl 'https://api.merchtrace.com/api/v1/exports/{id}' \
  -H "x-api-key: $MERCHTRACE_API_KEY"

Parameters 1

id path · string required

Responses

200

application/json

status union required

View structure

Variant 1: string

string

Allowed: queued

Variant 2: string

string

Allowed: running

Variant 3: string

string

Allowed: succeeded

Variant 4: string

string

Allowed: failed

Variant 5: string

string

Allowed: cancelled

error_code string | null required

id string required

job_id string required

list_id string required

format string required

fields string[] required

View structure

Array items

string

row_count number | null required

file_size_bytes string | null required

ready_at string | null required

expires_at string | null required

download_url string | null required

created_at string required

Exports

get`/exports/{id}/download`

Use GET /exports/{id}/download.

Required scope: lists:read

curl 'https://api.merchtrace.com/api/v1/exports/{id}/download' \
  -H "x-api-key: $MERCHTRACE_API_KEY"

Parameters 1

id path · string required

Responses

200

text/csv

string

Jobs

get`/jobs`

Use GET /jobs.

Required scope: lists:read

curl 'https://api.merchtrace.com/api/v1/jobs' \
  -H "x-api-key: $MERCHTRACE_API_KEY"

Parameters 4

limit query · object required

minimum: 1maximum: 100Default: 50

cursor query · string

type query · string

Allowed: population, export

status query · string

Allowed: queued, running, succeeded, failed, cancelled

Responses

200

application/json

data object[] required

View structure

Array items

id string required

list_id string required

type union required

View structure

Variant 1: string

string

Allowed: population

Variant 2: string

string

Allowed: export

status union required

View structure

Variant 1: string

string

Allowed: queued

Variant 2: string

string

Allowed: running

Variant 3: string

string

Allowed: succeeded

Variant 4: string

string

Allowed: failed

Variant 5: string

string

Allowed: cancelled

progress object required

View structure

current number required

total number required

output object | null required

View structure

error_code string | null required

created_at string required

started_at string | null required

completed_at string | null required

next_cursor string | null required

Jobs

get`/jobs/{id}`

Use GET /jobs/{id}.

Required scope: lists:read

curl 'https://api.merchtrace.com/api/v1/jobs/{id}' \
  -H "x-api-key: $MERCHTRACE_API_KEY"

Parameters 1

id path · string required

Responses

200

application/json

id string required

list_id string required

type union required

View structure

Variant 1: string

string

Allowed: population

Variant 2: string

string

Allowed: export

status union required

View structure

Variant 1: string

string

Allowed: queued

Variant 2: string

string

Allowed: running

Variant 3: string

string

Allowed: succeeded

Variant 4: string

string

Allowed: failed

Variant 5: string

string

Allowed: cancelled

progress object required

View structure

current number required

total number required

output object | null required

View structure

error_code string | null required

created_at string required

started_at string | null required

completed_at string | null required

Jobs

post`/jobs/{id}/cancel`

Use POST /jobs/{id}/cancel.

Required scope: lists:write

curl -X POST 'https://api.merchtrace.com/api/v1/jobs/{id}/cancel' \
  -H "x-api-key: $MERCHTRACE_API_KEY"

Parameters 1

id path · string required

Responses

202

application/json

id string required

list_id string required

type union required

View structure

Variant 1: string

string

Allowed: population

Variant 2: string

string

Allowed: export

status union required

View structure

Variant 1: string

string

Allowed: queued

Variant 2: string

string

Allowed: running

Variant 3: string

string

Allowed: succeeded

Variant 4: string

string

Allowed: failed

Variant 5: string

string

Allowed: cancelled

progress object required

View structure

current number required

total number required

output object | null required

View structure

error_code string | null required

created_at string required

started_at string | null required

completed_at string | null required

Lists

get`/lists`

Use GET /lists.

Required scope: lists:read

curl 'https://api.merchtrace.com/api/v1/lists' \
  -H "x-api-key: $MERCHTRACE_API_KEY"

Parameters 2

limit query · object required

minimum: 1maximum: 200Default: 50

cursor query · string

Responses

200

application/json

data object[] required

View structure

Array items

id string required

name string required

description string | null required

store_count number required

created_at string required

updated_at string required

next_cursor string | null required

Lists

post`/lists`

Use POST /lists.

Required scope: lists:write

curl -X POST 'https://api.merchtrace.com/api/v1/lists' \
  -H "x-api-key: $MERCHTRACE_API_KEY" \
  -H "Content-Type: application/json" \
  --data @request.json

JSON request body required

name string required

minLength: 1maxLength: 120

description string | null

maxLength: 500

Responses

201

application/json

id string required

name string required

description string | null required

store_count number required

created_at string required

updated_at string required

Lists

get`/lists/{id}`

Use GET /lists/{id}.

Required scope: lists:read

curl 'https://api.merchtrace.com/api/v1/lists/{id}' \
  -H "x-api-key: $MERCHTRACE_API_KEY"

Parameters 1

id path · string required

Responses

200

application/json

id string required

name string required

description string | null required

store_count number required

created_at string required

updated_at string required

Lists

patch`/lists/{id}`

Use PATCH /lists/{id}.

Required scope: lists:write

curl -X PATCH 'https://api.merchtrace.com/api/v1/lists/{id}' \
  -H "x-api-key: $MERCHTRACE_API_KEY" \
  -H "Content-Type: application/json" \
  --data @request.json

Parameters 1

id path · string required

JSON request body required

name string

minLength: 1maxLength: 120

description string | null

maxLength: 500

Responses

200

application/json

id string required

name string required

description string | null required

store_count number required

created_at string required

updated_at string required

Lists

delete`/lists/{id}`

Use DELETE /lists/{id}.

Required scope: lists:write

curl -X DELETE 'https://api.merchtrace.com/api/v1/lists/{id}' \
  -H "x-api-key: $MERCHTRACE_API_KEY"

Parameters 1

id path · string required

Responses

204

No response body.

Lists

get`/lists/{id}/stores`

Use GET /lists/{id}/stores.

Required scope: lists:read

curl 'https://api.merchtrace.com/api/v1/lists/{id}/stores' \
  -H "x-api-key: $MERCHTRACE_API_KEY"

Parameters 3

id path · string required

limit query · object required

minimum: 1maximum: 200Default: 50

cursor query · string

Responses

200

application/json

data object[] required

View structure

Array items

store object required

store_id string required

source union required

View structure

Variant 1: string

string

Allowed: manual

Variant 2: string

string

Allowed: population

added_at string required

next_cursor string | null required

Lists

post`/lists/{id}/stores`

Use POST /lists/{id}/stores.

Required scope: lists:write

curl -X POST 'https://api.merchtrace.com/api/v1/lists/{id}/stores' \
  -H "x-api-key: $MERCHTRACE_API_KEY" \
  -H "Idempotency-Key: $UNIQUE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  --data @request.json

Parameters 2

id path · string required

Idempotency-Key header · string required

Use a unique key per mutation. Reuse it only when retrying the same request.

minLength: 8maxLength: 255

JSON request body required

store_ids string[] required

minItems: 1maxItems: 1000

View structure

Array items

string

Responses

201

application/json

list_id string required

requested_count number required

added_count number required

duplicate_count number required

newly_unlocked_count number required

credits_charged number required

Lists

delete`/lists/{id}/stores/{storeId}`

Use DELETE /lists/{id}/stores/{storeId}.

Required scope: lists:write

curl -X DELETE 'https://api.merchtrace.com/api/v1/lists/{id}/stores/{storeId}' \
  -H "x-api-key: $MERCHTRACE_API_KEY"

Parameters 2

id path · string required

storeId path · string required

Responses

204

No response body.

Lists

post`/lists/{id}/population-jobs`

Use POST /lists/{id}/population-jobs.

Required scope: lists:write

curl -X POST 'https://api.merchtrace.com/api/v1/lists/{id}/population-jobs' \
  -H "x-api-key: $MERCHTRACE_API_KEY" \
  -H "Idempotency-Key: $UNIQUE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  --data @request.json

Parameters 2

id path · string required

Idempotency-Key header · string required

Use a unique key per mutation. Reuse it only when retrying the same request.

minLength: 8maxLength: 255

JSON request body required

quote_id string required

format: uuid

Responses

202

application/json

id string required

list_id string required

type union required

View structure

Variant 1: string

string

Allowed: population

Variant 2: string

string

Allowed: export

status union required

View structure

Variant 1: string

string

Allowed: queued

Variant 2: string

string

Allowed: running

Variant 3: string

string

Allowed: succeeded

Variant 4: string

string

Allowed: failed

Variant 5: string

string

Allowed: cancelled

progress object required

View structure

current number required

total number required

output object | null required

View structure

error_code string | null required

created_at string required

started_at string | null required

completed_at string | null required

Lists

post`/lists/{id}/export-jobs`

Use POST /lists/{id}/export-jobs.

Required scope: lists:write

curl -X POST 'https://api.merchtrace.com/api/v1/lists/{id}/export-jobs' \
  -H "x-api-key: $MERCHTRACE_API_KEY" \
  -H "Idempotency-Key: $UNIQUE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  --data @request.json

Parameters 2

id path · string required

Idempotency-Key header · string required

Use a unique key per mutation. Reuse it only when retrying the same request.

minLength: 8maxLength: 255

JSON request body required

fields string[]

Item values: store_id, domain, name, platform, country, technologies, email, phone, description, category, product_types, audience, business_model, customer_focus, price_positioning, primary_language, sells_physical_products, offers_services, market_scope, content_quality, free_shipping, free_shipping_threshold, multi_language, languages_available, multi_currency, currencies_available, local_pickup, local_delivery, ships_internationally, first_order_discount, discount_details, gift_cards_available, subscription_available, wholesale_available, physical_store_available, evidence, logo_url, favicon_url, social_image_url, html_languages_detected, html_currencies_detected, free_shipping_mentions, payment_methods, social_links, newsletter_signup, cart_detected, account_detected, search_detectedminItems: 1

View structure

Array items

string

Allowed: store_id, domain, name, platform, country, technologies, email, phone, description, category, product_types, audience, business_model, customer_focus, price_positioning, primary_language, sells_physical_products, offers_services, market_scope, content_quality, free_shipping, free_shipping_threshold, multi_language, languages_available, multi_currency, currencies_available, local_pickup, local_delivery, ships_internationally, first_order_discount, discount_details, gift_cards_available, subscription_available, wholesale_available, physical_store_available, evidence, logo_url, favicon_url, social_image_url, html_languages_detected, html_currencies_detected, free_shipping_mentions, payment_methods, social_links, newsletter_signup, cart_detected, account_detected, search_detected

Responses

202

application/json

id string required

list_id string required

type union required

View structure

Variant 1: string

string

Allowed: population

Variant 2: string

string

Allowed: export

status union required

View structure

Variant 1: string

string

Allowed: queued

Variant 2: string

string

Allowed: running

Variant 3: string

string

Allowed: succeeded

Variant 4: string

string

Allowed: failed

Variant 5: string

string

Allowed: cancelled

progress object required

View structure

current number required

total number required

output object | null required

View structure

error_code string | null required

created_at string required

started_at string | null required

completed_at string | null required

Lists

post`/list-population-quotes`

Use POST /list-population-quotes.

Required scope: lists:write

curl -X POST 'https://api.merchtrace.com/api/v1/list-population-quotes' \
  -H "x-api-key: $MERCHTRACE_API_KEY" \
  -H "Content-Type: application/json" \
  --data @request.json

JSON request body required

list_id string required

format: uuid

filters object required

max_results number required

minimum: 1maximum: 10000

Responses

201

application/json

id string required

list_id string required

filter_hash string required

matched_count number required

selected_count number required

new_item_count number required

already_in_list_count number required

already_unlocked_count number required

credits_required number required

expires_at string required

created_at string required

Build on better data.

post/stores/ai-filters

200 A complete, validated store filter set generated from text.

get/stores

200 A cursor-paginated collection of locked or previously unlocked stores.

get/stores/{storeId}

200

get/platforms

200

get/technologies

200

get/technologies/{slug}

200

get/store-count

200 The exact number of stores matching the supplied filters.

get/store-facets

200

get/store-facet-options

200

post/store-unlocks

201

get/exports/{id}

200

get/exports/{id}/download

200

get/jobs

200

get/jobs/{id}

200

post/jobs/{id}/cancel

202

get/lists

200

post/lists

201

get/lists/{id}

200

patch/lists/{id}

200

delete/lists/{id}

204

get/lists/{id}/stores

200

post/lists/{id}/stores

201

delete/lists/{id}/stores/{storeId}

204

post/lists/{id}/population-jobs

202

post/lists/{id}/export-jobs

202

post/list-population-quotes

201

post`/stores/ai-filters`

get`/stores`

get`/stores/{storeId}`

get`/platforms`

get`/technologies`

get`/technologies/{slug}`

get`/store-count`

get`/store-facets`

get`/store-facet-options`

post`/store-unlocks`

get`/exports/{id}`

get`/exports/{id}/download`

get`/jobs`

get`/jobs/{id}`

post`/jobs/{id}/cancel`

get`/lists`

post`/lists`

get`/lists/{id}`

patch`/lists/{id}`

delete`/lists/{id}`

get`/lists/{id}/stores`

post`/lists/{id}/stores`

delete`/lists/{id}/stores/{storeId}`

post`/lists/{id}/population-jobs`

post`/lists/{id}/export-jobs`

post`/list-population-quotes`