Shopify 리서치 허브 · 문서/위키형 둘러보기 분류 관리 자동 조사

Storefront/Admin API

근거 27건 · v6 · 2026-10-28 · claude-opus-4-8

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] / GraphQL products(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] / REST PUT [S17].
  • 삭제: GraphQL productDelete 뮤테이션 또는 REST DELETE (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].
  • 상품 이미지: product API보다 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 (게시일 미상)