Storefront/Admin API
Shopify Storefront/Admin API — 전체 개요
Shopify의 API 생태계는 자사몰 운영·확장의 핵심이다. 앱·테마·헤드리스 스토어프론트가 모두 이 API 위에서 데이터를 읽고 쓴다. 아래는 수집된 로우데이터(2019~2026년)를 종합한 분류 전체 개요다.
1. API 종류 지도
Shopify 공식 문서 기준으로 API는 여러 종류로 나뉜다 [S16]:
- Admin API — 스토어 데이터(상품·주문·고객 등)를 읽고 쓰는 핵심 API. 앱이 머천트 데이터와 상호작용하는 통로 [S1][S16].
- Storefront API — 구매자 대면 스토어프론트(헤드리스 포함)를 구성하는 API. 채용 공고·서비스 소개에서 Admin API와 함께 "기능 확장"의 양대 축으로 명시됨 [S15][S22].
- Partner API / App API / Payment Gateway API — 그 외 영역 [S16].
Admin API는 다시 두 가지 구현으로 나뉜다 [S3][S8][S16]:
| 구분 | 특징 |
|------|------|
| REST Admin API | 엔드포인트(/admin/api/<버전>/products.json 등) 기반. POST/GET/PUT/DELETE로 CRUD [S17] |
| GraphQL Admin API | 쿼리/뮤테이션 기반. "더 강력하고 효율적"이라고 Shopify가 직접 안내 [S16] |
두 API는 상품 등 리소스를 공유하지만 필드가 완전히 동일하지는 않다. 예를 들어 REST의 product에는 body_html, created_at 같은 속성이 있고, GraphQL의 product 데이터 모델은 필드 구성이 다르다 [S3].
REST vs GraphQL — 관점(의견)의 병렬 제시
- 효율성 관점(2023~2024): GraphQL이 REST보다 효율적이며, 유연한 쿼리와 더 작은 페이로드를 제공한다. Shopify도 보안을 위해 access scope 최소화를 권고 [S8][S16].
- 입문 난이도 관점(2023): "Shopify API는 거대해서 처음엔 어떤 scope·모델이 필요한지 모르는 게 당연하다. 연결은 나중에 수정 가능하니 처음부터 완벽히 고를 필요 없다" [S3].
- 학습 경로 관점(2021): 앱 개발에는 GraphQL을 익혀 API 호출로 Shopify 시스템과 통신해야 한다 [S7].
⚠️ 시점 주의: 옛 튜토리얼(2019~2024)은 REST API(
products.json,custom_collections.json등)를 다수 사용한다 [S11][S12][S13][S17][S18]. 2024년 이후 Gadget·Remix 기반 앱은 내부적으로 GraphQL로 수렴한다 [S4][S9][S10][S23][S24]. Shopify 공식은 "오류·검색 순위 저하를 막으려면 최신 Shopify API로 작업하라"고 안내한다 [S25].
2. 인증(Authentication)과 권한(Scopes)
- 모든 Admin API 요청은 유효한 Shopify access token이 필요하다 [S8][S16][S17].
- 공개 앱은 OAuth로 인증하고, 필요한 범위(scope)만 요청해야 한다 [S8].
- 커스텀 앱은 파트너/개발 대시보드에서 생성 후 access token을 발급받아 헤더에 포함시켜 호출한다 [S16][S17][S19]. access token은 "스토어의 비밀번호와 같다"며 외부 노출·echo 금지가 반복 강조된다 [S11][S16].
- scope 예시:
read_products,write_products,read_orders등. 필요한 scope만 선택하는 것이 보안상 권장(good practice) [S16][S19]. scope 변경 시shopify app deploy로 설정을 덮어써야 반영됨 [S9]. - API 키/시크릿은 파트너 대시보드(또는 Dev Dashboard)에서 앱 생성 시 자동 발급되며, 재생성·관리 가능 [S2][S11][S25].
3. Rate Limit과 상태 코드 (사실형 — 검증 가능 값)
REST Admin API rate limit (2023-12 기준) [S17]:
- 앱당·스토어당·분당 40 요청. 초과 시 429 (Too Many Requests) 에러. 요청량을 늘리려면 두 번째 앱을 만드는 우회법 언급 [S17].
주요 HTTP 상태 코드 [S17]:
- 401 Unauthorized / 402 Payment Required / 403 Forbidden / 404 Not Found / 422 / 429 Too Many Requests / 5xx 서버 오류.
- 상품 생성 성공 시 201/202, 조회·취소 성공 시 200 응답 관찰 [S17][S18].
Gadget 같은 플랫폼은 이 rate limit과 대량 데이터 동기화를 자동 관리해 준다(상품·주문·고객 수와 무관하게 "가능한 빠르게" 동기화) [S3][S4][S5].
4. API 버전 관리 (사실형 — 변화 이력)
엔드포인트에 날짜형 버전을 넣는다 (/admin/api/<YYYY-MM>/...). 수집 자료에 나타난 버전 변천:
- 2019-10 — PHP 튜토리얼에서 사용 [S11][S12][S13]
- 2023-10 / 2023-01 계열 — "현재 stable"로 소개, 업그레이드 시 버전 문자열만 교체 [S17][S18]
- 2024-02 계열 — Remix 시리즈 시점 [S14]
Shopify 공식은 최신 API 사용을 권고하며, 불일치·오류는 shopify.dev의 .dev 어시스턴트 챗으로 해결 가능하다고 안내 [S25].
5. 리소스별 API 사용 패턴
상품(Products)
- 조회: REST
GET /products.json(limit으로 개수 제어) [S12][S17][S19] / GraphQLproducts(first: N)쿼리로 id·handle·status·images 등 fetch [S9][S24]. - 생성: REST
POST /products.json— title, body_html, vendor, product_type, status(active/draft/archived), tags, images[].src, variants(옵션·SKU·price) [S17][S20].status에publish는 허용 안 되고 active/draft/archived만 유효 [S17]. - 수정: GraphQL
productUpdate뮤테이션(제목·가격 변경) [S10] / RESTPUT[S17]. - 삭제: GraphQL
productDelete뮤테이션 또는 RESTDELETE(product ID 필요) [S10][S17]. - 변형(Variants): 옵션(color/size), SKU, price를 다차원 배열로 생성 [S17].
주문(Orders)
- 생성: REST
POST /orders.json— line_items(상품·price·quantity·grams), transactions, currency 등 [S18]. - 취소/조회/수정: order ID로 cancel 엔드포인트, status(paid/cancelled)별 조회, update [S18]. 주문 생성에는 여러 scope가 필요 [S18].
컬렉션 / 이미지
- 컬렉션은 custom_collections와 smart_collections 두 종류.
custom_collections.json→ collection ID 추출 →collects.json으로 컬렉션 내 상품 연결 조회 [S12][S13]. - 상품 이미지:
productAPI보다 product images API(/products/<id>/images.json)가 제어가 많아 권장. src URL, position, width/height, 사이즈 변형(파일명에_small등) [S13].
메타필드(Metafields)
- GraphQL
metafieldsSet뮤테이션으로 네임스페이스·키·타입(product reference 등)·값 지정. 체크아웃 익스텐션 입력값으로 활용 [S5].
테스트 도구
- REST API는 Postman으로 import(cURL/Node/PHP 등 코드 스니펫 제공)해 테스트 후 코드로 이식 가능. 브라우저에서 스토어 URL + 엔드포인트 직접 호출로도 JSON 확인 가능 [S12][S17][S18].
6. 앱 유형과 확장(Extensions)
앱 유형 (사실형)
- 커스텀 앱(Custom): 단일 머천트 전용. billing·멀티테넌시 부담이 없어 입문·프리랜스에 권장 [S2][S3][S25].
- 공개 앱(Public): 무제한 머천트 설치 가능, App Store 등재. 보통 일회성/월 구독 과금 [S1][S2][S3][S25].
확장 포인트 (의견·기능 진화 — 시점 병렬)
- Theme app extensions — 앱 콘텐츠를 온라인 스토어에 노출(리뷰 등) [S1][S3]. App block으로 테마와 상호작용(예: 위시리스트 버튼) [S14].
- Checkout UI extensions — 체크아웃에 pre-purchase offer 등 삽입 [S5].
- Admin UI extensions / Admin intents / Sidekick extensions (2026) — 앱을 어드민 워크플로에 통합하는 최신 흐름. 과거엔 앱이 어드민에서 "2등 시민"처럼 별도 화면으로 튕겨나갔으나, 이제 상품·고객 상세 페이지에 앱 조각을 삽입하고, 한 줄 코드로 Shopify 네이티브 UI(할인·상품 생성)를 호출하며, Sidekick이 앱 데이터에 직접 접근 [S6].
7. 개발 환경·툴체인
- Dev Dashboard(구 Partner Dashboard) — 앱 생성·관리·스토어·지표·매출·권한의 중앙 허브. 과거 파트너 대시보드 사용자는 마이그레이션 가이드 참조 [S25]. 개발 스토어(developer preview 선택 시 미출시 기능 미리 사용 가능, 단 소유권 이전 불가) 생성 [S2][S3].
- Shopify CLI — 앱 scaffolding·배포(
shopify create,shopify serve,shopify app deploy). Remix/Next.js 프론트 템플릿 제공. CLI는 Ruby 기반이라 Ruby 설치 필요(앱 자체는 Node+React) [S7][S8][S25]. - 클라이언트 라이브러리 — Node.js, PHP, Python, Ruby 등. Node는
@shopify/shopify-api등으로 상품 fetch/생성 [S17][S19][S20]. - App Bridge — iframe 임베드된 앱과 어드민 간 통신 [S7]. Polaris — 어드민과 일관된 느낌의 React 컴포넌트 라이브러리 [S3][S5][S7][S8][S15].
- 임베드 구조 — 앱은 실제론 별도 도메인(myapp.com) 웹사이트이며, Shopify가 어드민 안에 iframe으로 임베드. 스토어 밖에서 열면 인증 실패 [S7].
보일러플레이트 추상화 (의견 — 접근법 병렬)
- Gadget: OAuth·세션 토큰·웹훅 구독·히스토리컬 데이터 싱크·rate limit·Postgres·Node 백엔드·React 프론트·Polaris 설치를 자동 처리. 코드 없이 스토어에 앱 설치까지 가능하며 "가장 unique한 코드에만 집중" [S3][S4][S5].
- Remix(Shopify CLI 기본): 직접 loader/action에서
authenticate.admin으로 인증 후 GraphQL 호출 [S9][S10][S14][S23][S24]. - 순수 PHP(2019): 호스트·FTP·access token 수동 관리. 입문용이나 옛 방식 [S11][S12][S13].
- 순수 Node.js(2023): express +
@shopify/shopify-api로 직접 구현 [S19][S20].
8. 웹훅(Webhooks)
- 머천트가 어드민에서 상품을 변경하면 products create/update/delete 웹훅이 발화. 앱 데이터를 Shopify와 동기화하는 핵심 [S3][S4][S5].
- shop update/uninstall, GDPR request 웹훅도 제공(공개 앱 컴플라이언스에 중요) [S3][S4].
- 주의: 변경 여부와 무관하게 항상 쓰기를 하면 update 웹훅이 재발화해 무한 루프가 생길 수 있어, 변경 감지(change detection)로 실제 변경 시에만 로직 실행 [S4].
9. Storefront / 헤드리스 (Hydrogen)
- Hydrogen — Shopify의 React 기반 스토어프론트 프레임워크(2021 발표). 서버사이드 렌더링(Next.js 유사), 장바구니 등 사전 제작 컴포넌트/훅 제공. GraphQL Storefront API를 headless로 호출 [S21][S22].
useShopQuery훅으로 GraphQL 쿼리를 서버에서 실행 → SEO 친화적(이커머스에 중요). Vite 빌드, Tailwind 기본 [S21].- 전용 호스팅 Oxygen과 연계(Vercel+Next 모델과 유사) [S21].
- Hydrogen vs Liquid (의견): 성능 중요한 헤드리스·복잡 콘텐츠면 Hydrogen, 표준 테마에서 빠른 반복이면 Liquid. "대부분 머천트는 아직 Hydrogen 불필요" [S22].
- 실무 스택 예(채용/서비스): Liquid, Polaris, Hydrogen, Storefront API, GraphQL/REST, React [S15][S22].
10. 실무 맥락 (시장·역량)
- 채용 요건상 Shopify Admin·Storefront API 활용 기능 확장, 앱 개발/서드파티 연동, ERP/WMS/마케팅 툴 외부 연동(GraphQL·REST) 경험이 요구됨 [S15].
- 앱 비즈니스는 타깃이 "돈을 투자할 의향이 있는 머천트"라 수익화 유리하나, 앱 개발은 프리랜싱보다 난도가 높음(아이디어·백엔드·DB·보안·호스팅 필요) [S7][S8][S14].
출처
- [S1] ShopifyDevs — What is a Shopify App — https://youtu.be/UbAiY7RFlik (2021-11-16)
- [S2] ShopifyDevs — Partner Dashboard — https://youtu.be/6yNnwqjPtYA (2021-11-16)
- [S3] Gadget — Getting started building Shopify apps — https://youtu.be/bQWfJxVYktY (2023-12-01)
- [S4] Gadget — Build a full stack Shopify app (product tagger) — https://youtu.be/BerX6e8_u7s (2025-09-26)
- [S5] Gadget — Checkout UI extensions / pre-purchase offer — https://youtu.be/rCXC4tabpSE (2024-03-28)
- [S6] The Shopify App Show — Admin UI/intents/Sidekick extensions — https://youtu.be/yBj2-8nnbdw (2026-08-09)
- [S7] Coding with Jan — Fastest way to build a Shopify app — https://youtu.be/A8YCxBTgsbI (2021-05-12)
- [S8] kr.linkedin.com (Crest Infotech) — Building and Managing Shopify Apps — https://kr.linkedin.com/pulse/building-managing-shopify-apps-developers-guide-crest-infotech-eo7pf (게시일 미상)
- [S9] Fayyaz Ahmed — Fetch products in custom Node app — https://youtu.be/2X4xo9v8-Fk (2024-07-02)
- [S10] Fayyaz Ahmed — Update & delete products — https://youtu.be/GvlmukUw8Ns (2024-07-02)
- [S11] WeeklyHow — Create a Shopify app in PHP (install/token) — https://youtu.be/tX1E8fuesSE (2019-10-03)
- [S12] WeeklyHow — Display products with PHP & Shopify API — https://youtu.be/YMnouXWOyFw (2019-10-06)
- [S13] WeeklyHow — Display Shopify images — https://youtu.be/f2mQiULUm1o (2019-10-10)
- [S14] Code Inspire — Shopify app dev with Remix (wishlist) — https://youtu.be/FMVShSvAaAA (2024-02-09)
- [S15] www.wanted.co.kr — Concentrix 채용(Shopify 개발자) — https://www.wanted.co.kr/wd/315823 (게시일 미상)
- [S16] FineGap — Shopify REST Admin API intro / custom app — https://youtu.be/cy2dUXg5E-c (2023-12-26)
- [S17] FineGap — Create products via REST Admin API — https://youtu.be/et9CSd1xjUQ (2023-12-29)
- [S18] FineGap — Create orders via REST Admin API — https://youtu.be/inWrhRJNL8s (2024-01-01)
- [S19] Fayyaz Ahmed — Fetch products with Shopify Node API — https://youtu.be/VhT3dHg-jZ0 (2023-11-08)
- [S20] Fayyaz Ahmed — Create product via Node & Admin API — https://youtu.be/SAW_wd-1t4w (2023-11-09)
- [S21] Fireship — Shopify Hydrogen first look — https://youtu.be/mAsM9c2sGjA (2021-11-09)
- [S22] maeum.io — Shopify Development 서비스 소개 — https://maeum.io/services/shopify-development (게시일 미상)
- [S23] Lima Dev — Build app from zero pt.7 (save disabled products) — https://youtu.be/VZpdNNGKozU (2025-11-24)
- [S24] Lima Dev — Search input field (GraphQL query variables) — https://youtu.be/IVrQzw3lfe0 (2025-11-15)
- [S25] help.shopify.com — 빌드 및 통합 / Dev Dashboard — https://help.shopify.com/ko/partners/build-integrate (게시일 미상)