Amazon Influencer Program에 참여하는 크리에이터는 amazon.com/shop/<name>에서 스토어프런트를 운영합니다. 상품을 아이디어 리스트와 큐레이션 게시물로 묶고, 소셜 계정을 연결하고, 트렌딩 픽을 강조해 보여 줍니다. 제휴 마케팅팀이나 인플루언서팀에게 이 페이지는 실질적인 질문에 답해 줍니다. 크리에이터가 누구인지, 다른 어디에 게시하는지, 이번 시즌에 무엇을 추천하는지, 각 리스트의 규모가 어느 정도인지입니다.
2026-11-17에 SocQ는 스토어프런트 하나를 구조화된 레코드 하나로 반환하는 Amazon Storefront API를 추가했습니다. 이 가이드에서는 요청 방법, 필드, 가격, 그리고 크리에이터 리서치 워크플로에 적용하는 방법을 다룹니다.
빠른 답변: 스토어프런트 URL 하나를
url에 담아POST /v1/amazon/shop으로 보내세요. 작업이 성공할 때까지GET /v1/tasks/{task_id}를 폴링한 뒤data.results.items에서 크리에이터 프로필,social_urls,lists,curations,trending_picks가 담긴 행 하나를 읽으면 됩니다. 요청당 비용은 0.5 크레딧($0.0025)입니다.
엔드포인트 반환 내용
1 SocQ 크레딧 = $0.005입니다.
| 엔드포인트 | 반환 내용 | 가격 |
|---|---|---|
| Amazon Storefront API | 스토어프런트당 한 행: 크리에이터 이름, 소개, 아바타, 톱 크리에이터 여부, 연결된 소셜 프로필, 상품 수가 포함된 아이디어 리스트, 상품 수가 포함된 큐레이션 게시물, 가격이 포함된 트렌딩 픽 | 호출당 0.5 크레딧($0.0025) |
이 행은 스토어프런트의 리스트, 큐레이션, 트렌딩 픽 중 첫 페이지에 표시되는 항목을 담습니다. 존재하지 않는 스토어프런트는 실패 처리되고 환불되므로, 없는 URL에는 비용이 들지 않습니다.
인증과 비동기 작업 흐름
모든 SocQ 요청은 API 키로 인증하며, 작업 제출, 작업 상태 조회, 결과 요청에 같은 헤더를 사용합니다.
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
모든 수집은 백그라운드 작업으로 실행됩니다.
submit -> task_id -> queued -> running -> succeeded
\-> failed
제출 응답에는 data.task_id와 data.status가 들어 있습니다. 이 ID로 작업을 폴링하세요.
curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=50" \
-H "Authorization: Bearer $SOCQ_API_KEY"
status가 succeeded이면 응답의 data.results.items에 정규화된 레코드의 첫 페이지가 포함됩니다. limit의 기본값은 50이고 최대 500까지 지정할 수 있으며, has_more가 true이면 results.next_cursor를 cursor로 넘기세요. 작업이 queued, running, failed 상태인 동안에는 results 없이 작업 메타데이터만 반환됩니다.
제출 본문에 선택 항목인 callback_url을 넣으면 작업이 끝났을 때 SocQ가 작업 요약을 담은 POST를 한 번 보내며, 레코드는 GET /v1/tasks/{task_id}로 읽으면 됩니다. 클라이언트 측 타임아웃이 발생해도 작업은 취소되지 않으므로, 중복 비용을 내지 말고 같은 작업 ID로 조회를 이어가세요. 402는 크레딧이 부족하다는 뜻이고, 429는 키가 속도 또는 크레딧 한도에 도달했다는 뜻입니다.
스토어프런트 요청하기
입력은 amazon.com/shop/<name> 형식의 스토어프런트 하나를 가리키는 url뿐입니다. 다른 Amazon 마켓플레이스도 같은 방식으로 동작합니다.
curl -X POST "https://api.socq.ai/v1/amazon/shop" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://www.amazon.com/shop/sydneydelrey"
}'
이 엔드포인트는 요청당 URL 하나를 받습니다. 여러 스토어프런트를 읽으려면 URL마다 작업을 하나씩 제출하고, 각 task_id를 입력값과 함께 저장한 뒤 개별적으로 폴링하세요.
스토어프런트 레코드 이해하기
문서 예시의 결과를 일부 줄이면 다음과 같습니다.
{
"id": "sydneydelrey",
"platform": "amazon",
"resource": "shop",
"type": "storefront",
"url": "https://www.amazon.com/shop/sydneydelrey",
"name": "sydney del rey",
"is_top_creator": true,
"social_urls": [
"https://vm.tiktok.com/ZTFrowSpg/",
"https://www.youtube.com/channel/UCWvW1JOQ-nsAinO1jLFgrVA",
"https://www.pinterest.com/sydneydelrey"
],
"lists": [
{
"title": "Holiday home goods",
"url": "https://www.amazon.com/shop/sydneydelrey/list/XYAIGEFWJGML?tag=sydneybertonc-20",
"items_count": 107
}
],
"curations": [
{
"title": "f/w fit try ons",
"url": "https://www.amazon.com/shop/sydneydelrey/curation/71fad634-5787-4ee1-bc3c-6e3ca23e5eae",
"posts_count": 109
}
],
"trending_picks": [
{
"url": "https://www.amazon.com/shop/sydneydelrey/getProductDetails/B0FCLQD6BN?showRelatedPost=true&tag_override=sydneybertonc-20",
"price": 24.99,
"discount": null
}
]
}
필드를 용도별로 묶으면 다음과 같습니다.
- 크리에이터 정보:
id(URL의 스토어프런트 이름),name,text(크리에이터가 작성한 소개),avatar_url, 그리고 Amazon이 해당 크리에이터를 톱 크리에이터로 표시하는지 알려 주는is_top_creator. - 크로스 플랫폼 도달 범위: 스토어프런트에 연결된 소셜 프로필인
social_urls. - 카탈로그 구조:
title,url,image_url,items_count가 포함된lists, 그리고title,url,image_url,posts_count(큐레이션 게시물의 상품 수)가 포함된curations. - 현재 프로모션:
url,image_url, 마켓플레이스 통화 기준price, 표시되는 경우discount가 포함된trending_picks.
모든 행에는 SocQ가 수집한 시각인 collected_at도 들어 있습니다. 가격은 바뀌므로, 가격을 저장할 때는 이 타임스탬프도 함께 저장하세요. 전체 필드 표는 Amazon Storefront 문서에 있습니다.
언제 사용하나요?
제휴 파트너 발굴. is_top_creator, 리스트 개수, 각 리스트의 items_count를 보면 팀원 누군가가 스토어프런트를 직접 열어 보기 전에 얼마나 활발한지 빠르게 파악할 수 있습니다.
크리에이터의 추천 상품 추적. 일정 주기로 스토어프런트를 다시 읽고 실행 간 리스트 제목, 개수, 트렌딩 픽을 비교하면 크리에이터가 이번 시즌에 무엇을 밀고 있는지 알 수 있습니다.
스토어프런트와 크리에이터의 소셜 계정 연결. social_urls에는 크리에이터가 연결한 TikTok, YouTube, Pinterest 프로필이 담깁니다. 이를 Creator API에 넣어 공개된 비즈니스 이메일을 찾거나, 플랫폼별 프로필 엔드포인트에 넣어 팔로워 수를 확인하세요.
상품 리서치. 트렌딩 픽은 상품으로 이어집니다. 전체 상품 데이터, 리뷰, 카테고리 순위가 필요하면 Amazon Product Details API와 Amazon Best Sellers API 같은 SocQ의 다른 Amazon 엔드포인트를 사용하세요. 이들이 Amazon 자체 API와 어떻게 다른지는 Amazon Product Advertising API 대안을 참고하세요.
프로덕션 팁
- URL을 정규화하세요. 크리에이터마다
amazon.com/shop/<name>형식의 정규 URL 하나만 유지하면 같은 스토어프런트에 두 번 비용을 내지 않습니다. - 첫 페이지 스냅샷이라는 점을 감안하세요. 리스트, 큐레이션, 트렌딩 픽은 스토어프런트 첫 페이지에 표시되는 항목입니다. 개수는
collected_at시점의 스냅샷으로 다루세요. - 실패는 따로 처리하세요. 존재하지 않는 스토어프런트는 실패 처리되고 환불됩니다. 재시도하지 말고 사라진 것으로 표시하세요.
- 예산은 간단하게 잡으세요. 스토어프런트당 0.5 크레딧이므로 스토어프런트 1,000개는 500 크레딧, 즉 $2.50입니다.
자주 묻는 질문(FAQ)
Amazon Storefront API란 무엇인가요?
Amazon 크리에이터 스토어프런트(amazon.com/shop/<name>) 하나를 읽어 크리에이터 프로필, 연결된 소셜 계정, 아이디어 리스트, 큐레이션 게시물, 트렌딩 픽을 구조화된 레코드 하나로 반환하는 SocQ 엔드포인트입니다.
amazon.com 이외의 마켓플레이스에서도 동작하나요?
네. 문서에 따르면 다른 Amazon 마켓플레이스도 같은 방식으로 동작하며, 해당 마켓플레이스의 스토어프런트 URL을 url에 담아 보내면 됩니다. trending_picks의 가격은 해당 마켓플레이스의 통화로 표시됩니다.
모든 리스트의 모든 상품을 반환하나요?
아니요. 이 행은 스토어프런트의 첫 페이지를 담습니다. 각 리스트의 제목, URL, 커버 이미지, items_count, 각 큐레이션 게시물의 상품 수, 현재 트렌딩 픽이 포함되며, 리스트의 모든 항목을 펼쳐서 반환하지는 않습니다.
스토어프런트가 존재하지 않아도 과금되나요?
아니요. 존재하지 않는 스토어프런트는 실패 처리되고 환불됩니다. 성공한 요청은 0.5 크레딧($0.0025)입니다.
한 요청에 여러 스토어프런트를 보낼 수 있나요?
요청은 url 하나만 받습니다. 스토어프런트마다 작업을 하나씩 제출하고 각 task_id를 추적하세요.
AMAZON API
공개 Amazon URL로 워크플로를 테스트하세요
공개 데이터 입력을 제출하면 출처를 추적할 수 있는 컨텍스트가 포함된 정규화된 레코드를 받을 수 있습니다.
Amazon API 살펴보기