Shopify 리서치 허브 · 문서/위키형 둘러보기 분류 관리 자동 조사
앱·툴(서드파티) /Shopify 개발·커스터마이징 /Storefront/Admin API

Storefront/Admin API

근거 22건 · v3 · 2026-08-14 · claude-opus-4-8

Storefront/Admin API — 전체 개요 써머리

Shopify의 API 생태계는 자사몰(스토어) 데이터를 프로그래밍으로 읽고 쓰는 인터페이스로, 앱 개발·헤드리스 스토어프론트·외부 시스템 연동의 기반이다. 이 분류의 자료들은 크게 ① Admin API(REST/GraphQL), ② Storefront API 및 헤드리스(Hydrogen), ③ 인증·권한·레이트리밋, ④ 실전 구현 패턴(언어·프레임워크별) 로 나뉜다.

1. Shopify API 종류 개요

  • Shopify는 앱이 API·웹훅·플랫폼 확장 지점을 통해 머천트와 고객을 위한 새 기능을 확장·생성하도록 서드파티 개발자에게 권한을 준다 [S1].
  • 공식 문서상 API에는 Admin API, Partner API, App API, Payment Gateway API 등이 있으며, 이 자료들의 초점은 Admin API다 [S16].
  • Admin API는 두 가지 형태로 제공된다: REST Admin API와 GraphQL Admin API [S3][S16]. 두 API는 동일 리소스를 공유하지만 필드 구조가 서로 다르다 — 예를 들어 REST의 product에는 body HTML, created at 같은 속성이 있는데 GraphQL의 product 데이터 모델과 필드가 동일하지 않다 [S3].
  • Shopify 공식 입장 및 다수 자료는 GraphQL이 REST보다 더 강력하고 효율적이라고 안내한다 [S8][S16]. GraphQL은 유연한 쿼리와 더 작은 페이로드를 제공한다 [S8]. (단, 자료 시점 유의: 아래 "시점" 절 참고)

2. Admin API — REST vs GraphQL

REST Admin API

  • 엔드포인트 형식: {store}.myshopify.com/admin/api/{version}/{resource}.json [S17][S18]. API 버전은 2023-10, 2024-01(2024-01은 20240-1 표기 오독 가능) 같은 연-월 형식으로 지정하며, 버전을 바꾸면 API를 업그레이드할 수 있다 [S17][S18].
  • HTTP 메서드 매핑: POST=생성, GET=조회, PUT=업데이트, DELETE=삭제 [S17][S18]. (S17에서 "업데이트에 POST"라 말한 부분과 "PUT" 언급이 혼재 — 실제로는 PUT/POST 모두 등장)
  • 주요 리소스: product, product image, product variant, collect, custom collection, smart collection, order [S13][S16][S17][S18].
    • custom collection과 smart collection 두 종류의 컬렉션이 존재한다 [S13].
    • product image API는 product API보다 이미지에 대한 더 세밀한 제어(위치/순서, src URL, 사이즈 조정 등)를 제공한다 [S13].
  • 상태 코드: 401 unauthorized, 402 payment required, 403 forbidden, 404 not found, 422, 429 too many requests, 5xx 서버 오류 [S17]. 상품 생성 성공 시 201/202가 반환된다 [S17][S18].
  • 테스트 도구로 Postman에 cURL 코드를 임포트해 엔드포인트를 검증하고, 이후 원하는 언어(PHP, Node.js, Python, Ruby, Java 등) 코드로 내보내는 워크플로가 소개된다 [S17][S18].

GraphQL Admin API

  • Remix/Node 앱에서 authenticate.admin(request)으로 요청을 인증한 뒤 admin 객체로 GraphQL 쿼리/뮤테이션을 실행한다 [S9][S10].
  • 상품 조회: products(first: N) 쿼리로 ID·handle·status·이미지·가격 등을 페치 [S9]. 상품 수정/삭제는 product update mutation, product delete mutation을 사용하며 변수로 ID·title·price를 전달한다 [S10].
  • 메타필드 저장은 metafieldSet GraphQL 뮤테이션을 Shopify 문서 그대로 사용할 수 있다 [S5].

3. 인증·권한·레이트리밋

OAuth & Access Token

  • 모든 앱은 OAuth로 인증하고, 저장 데이터에 안전하게 접근하기 위해 적절한 스코프(scope)를 요청해야 한다 [S8].
  • 커스텀 앱을 만들면 Admin access token이 발급되며, 이 토큰을 API 요청 헤더에 포함해 인증한다 [S16][S17]. 이 토큰은 스토어의 비밀번호와 같아 노출/커밋 금지이며, PHP 예제에서도 access token을 echo하지 말고 안전히 저장하라고 강조된다 [S11][S16][S19].
  • 스코프 예: read_products, write_products, read_orders 등. 필요한 스코프만 선택하는 것이 보안상 좋은 관행이다 [S16][S19]. 스코프 변경 후에는 shopify app deploy로 설정을 덮어써야 반영된다 [S9].
  • Node.js 공식 모듈(shopify-api-node 등)에서는 shop name, API key, password(access token)를 인스턴스에 전달해 사용하며, 자격증명은 .env로 관리한다 [S19].
  • 커스텀 액션/커스텀 모델은 기본적으로 머천트가 호출할 수 없고, Access Control에서 shopify app users 역할을 명시적으로 허용해야 프런트엔드에서 호출 가능하다(멀티테넌시·보안 목적) [S5].

Rate Limits

  • REST Admin API 레이트리밋: 앱·스토어당 분당 40 요청 [S17]. 초과 시 429 (too many requests) 오류가 발생하며, 요청량을 늘리려면 두 번째 앱을 만드는 방식이 소개된다 [S17].
  • Gadget 같은 플랫폼은 이 레이트리밋을 자동 관리해, 상품/주문/고객이 아무리 많아도 가능한 빠르게 동기화하고 개발자가 직접 처리하지 않게 해준다 [S3][S4][S5]. 백엔드에서 Shopify로 다시 쓸 때는 백그라운드 잡 큐(api.enqueue, temporal 기반)로 동시성을 제어해 레이트리밋에 대응한다 [S4].

4. Storefront API 및 헤드리스(Hydrogen)

  • Storefront API는 Admin API와 별개로, 스토어프론트(구매자 화면) 데이터를 헤드리스 방식으로 다루는 데 쓰인다. 채용/서비스 자료에서 "Shopify Admin 및 Storefront API를 활용한 기능 확장"이 실무 요구사항으로 명시된다 [S15][S22].
  • Hydrogen은 2021년 발표된, Shopify용 React 기반 서버사이드 렌더링 프레임워크다 [S21]. Next.js와 유사하게 SSR 중심이며, 스토어프론트 데이터/UI 관리를 위한 사전 정의 컴포넌트·훅을 제공한다 [S21].
    • Shopify의 GraphQL API를 headless로 사용할 수 있다는 점이 핵심이며, useShopQuery 훅으로 Storefront GraphQL 데이터를 서버에서 페치한다 [S21].
    • 빌드 도구로 Vite, 기본 스타일로 Tailwind, .client/.server 컴포넌트(React Server Components) 구조를 채택. 서버 렌더링으로 SEO에 유리하다 [S21].
    • Shopify는 Hydrogen 앱을 위한 자체 호스팅 서비스 Oxygen을 계획한다(Vercel 유사 모델) [S21].
  • 현업 관점(2026년 서비스 자료): Hydrogen + Remix 헤드리스 스토어프론트, GraphQL Admin + Storefront API가 프로덕션 개발 범위에 포함된다 [S22]. 다만 "대부분의 머천트는 아직 Hydrogen이 필요 없다" — 성능이 중요한 헤드리스·복잡한 콘텐츠라면 Hydrogen, 표준 테마에서 빠른 반복이면 Liquid를 권한다 [S22].
  • 관련 기술 스택으로 Liquid, Polaris, Hydrogen, Storefront API가 실무 요구로 함께 언급된다 [S15].

5. 앱 개발 컨텍스트 (API를 쓰는 환경)

앱 종류 & 파트너 대시보드

  • 앱 유형: Public 앱(앱스토어 등재, 무제한 머천트 설치, 일회성/구독 과금)과 Custom 앱(단일 머천트 전용) [S2][S3]. 초보자에게는 빌링 API·멀티테넌시를 다룰 필요가 없는 Custom 앱으로 시작을 권장하는 관점이 있다 [S3].
  • Partner Dashboard(shopify.com/partners)에서 개발 스토어 생성, 앱 생성, API 키 발급, 스코프·웹훅·앱 확장 관리를 한다 [S2][S3]. 앱 생성 시 API 키가 자동 생성된다 [S2].
  • 개발/프로덕션 환경은 별도의 앱이 필요하다(각각 client ID/secret 발급) [S3][S4].

웹훅 & 확장

  • 앱은 웹훅을 구독해 상품 생성/업데이트/삭제, 앱 설치/제거 등 이벤트에 반응한다 [S3][S4][S5]. Gadget은 선택한 데이터 모델에 대해 웹훅을 자동 구독하고, 무한 루프 방지를 위한 변경 감지(change detection)를 제공한다 [S4].
  • 앱 확장(App Extensions): 어드민·체크아웃·온라인 스토어에 콘텐츠를 노출. Theme app extension(테마에 기능 삽입), Checkout UI extension(프리퍼체이스 오퍼 등), Admin UI extension(상품·고객 상세 페이지에 앱 조각 삽입) [S1][S3][S5][S6].
  • Admin intents: 할인/상품 생성 시 자체 UI를 만들 필요 없이 한 줄로 Shopify 네이티브 UI를 호출 [S6]. Sidekick extensions: Sidekick이 앱 데이터에 직접 접근(2026년 최신 방향) [S6].

프레임워크·툴체인

  • Shopify CLI: 앱 스캐폴딩, 개발 서버, 배포 자동화. Remix 템플릿을 제공한다 [S2][S3][S8][S14]. (초기 CLI는 Ruby 기반이라 Ruby 설치가 필요했으나 빌드 대상은 Node.js+React였다 — 2021년 정보 [S7].)
  • Polaris: Shopify 어드민과 어우러지는 네이티브 느낌의 React 컴포넌트 라이브러리 [S3][S5][S7][S8].
  • App Bridge: iframe으로 임베드된 앱과 어드민 간 통신 및 세션 토큰 처리 [S5][S7].
  • Gadget: OAuth·세션 토큰·웹훅·히스토리컬 데이터 싱크·레이트리밋을 대신 처리하는 풀스택 호스팅 플랫폼(Postgres + Node 백엔드 + React/Remix). Shopify 보일러플레이트를 추상화한다 [S3][S4][S5].

6. 실전 구현 패턴 (언어·프레임워크별)

| 접근 | 스택 | 대표 작업 | 자료 | |---|---|---|---| | PHP + REST | 순수 PHP, cURL 함수 | 상품/컬렉션/이미지 표시, access token 발급 | [S11][S12][S13] | | Node.js + REST 모듈 | Express + shopify-api-node | 상품 조회(limit), 상품 생성 | [S19][S20] | | Remix + GraphQL | Shopify CLI Remix 템플릿 | 상품 fetch/수정/삭제, Polaris UI | [S9][S10][S14] | | REST 원본 테스트 | Postman + cURL | product/order/collection/image CRUD | [S16][S17][S18] | | 풀스택 추상화 | Gadget | 상품 태거, 프리퍼체이스 오퍼 | [S3][S4][S5] | | 헤드리스 | Hydrogen + Storefront GraphQL | 커스텀 스토어프론트 | [S21][S22] |

  • 대표 CRUD 예: Node에서 Shopify.product.create({title, body_html, vendor, product_type, tags, images})로 상품 생성 [S20]; Remix GraphQL에서 첫 10개 상품 페치 후 Polaris DataTable 렌더 [S9], 수정·삭제 뮤테이션 [S10].
  • PHP 예제는 custom_collections → collection ID → collects → product → product image로 API를 연쇄 호출하는 패턴을 보여준다 [S12][S13].

7. 정보 시점(연도별) 유의사항

이 분류는 2019~2026년에 걸친 자료가 섞여 있어, 특히 REST/GraphQL 권장이나 툴체인 안내는 시점 차이가 크다.

  • 2019년: PHP + REST Admin API로 앱을 밑바닥부터 구현(WeeklyHow) — 웹호스트·FTP·수동 OAuth 스크립트 중심 [S11][S12][S13]. 오늘날 권장 흐름과 다름(구식).
  • 2021년: Shopify CLI가 Ruby 의존, Node.js+React 앱 생성; Hydrogen 최초 발표(개발자 프리뷰) [S1][S2][S7][S21].
  • 2023~2024년: REST Admin API(버전 2023-10)로 Postman 실습이 여전히 활발 [S16][S17][S18][S19][S20]; 동시에 Remix + GraphQL이 "PHP에서 업그레이드된 새 방식"으로 제시됨 [S14]. GraphQL이 REST보다 효율적이라는 안내 [S8][S16].
  • 2025~2026년: Gadget Remix 풀스택 튜토리얼 [S4]; Admin UI extensions·Admin intents·Sidekick extensions 등 앱을 어드민 워크플로에 깊게 통합하는 방향 [S6]; 실무에서는 Hydrogen+Remix 헤드리스와 Admin/Storefront GraphQL이 프로덕션 범위 [S22].

관점 병렬(대체 아님): "REST로 시작해 배우기 쉽다"(2023~2024, Postman 실습 [S16][S17]) vs "GraphQL이 더 효율적이고 최신 권장"(공식·서비스 [S8][S16][S22]) vs "대부분 머천트는 Hydrogen 불필요, Liquid로 충분"(2026 [S22]) — 목적(단일 머천트 학습/헤드리스 성능/빠른 반복)에 따라 선택이 갈린다.

8. 핵심 정리

  • Shopify Admin API는 REST와 GraphQL 두 갈래, 리소스는 공유하되 필드가 다름 [S3][S16].
  • 인증은 OAuth + access token + 최소 스코프, REST는 분당 40요청 레이트리밋(429) [S8][S16][S17].
  • 스토어프론트는 Storefront API + Hydrogen(React SSR, Oxygen 호스팅) 으로 헤드리스 구현, 단 필요성은 머천트마다 다름 [S21][S22].
  • 실전은 PHP/Node REST(입문·CRUD) → Remix GraphQL / Gadget(현대적 풀스택) 으로 이동하는 흐름 [S9][S10][S14][S4].
  • 채용 시장에서 Admin + Storefront API, GraphQL/REST, Liquid, Polaris, Hydrogen 경험이 실무 요구로 명시된다 [S15][S22].

출처

  • [S1] ShopifyDevs — "What is a Shopify App?" (2021-11-16) — https://youtu.be/UbAiY7RFlik
  • [S2] ShopifyDevs — Partner Dashboard 소개 (2021-11-16) — https://youtu.be/6yNnwqjPtYA
  • [S3] Gadget — Getting started building Shopify apps (2023-12-01) — https://youtu.be/bQWfJxVYktY
  • [S4] Gadget — Build a full stack Shopify app / product tagger (2025-09-26) — https://youtu.be/BerX6e8_u7s
  • [S5] Gadget — Checkout UI extension pre-purchase offer (2024-03-28) — https://youtu.be/rCXC4tabpSE
  • [S6] The Shopify App Show — Admin UI extensions·intents·Sidekick (2026-08-09) — https://youtu.be/yBj2-8nnbdw
  • [S7] Coding with Jan — Fastest way to build a Shopify app (2021-05-12) — https://youtu.be/A8YCxBTgsbI
  • [S8] kr.linkedin.com (Crest Infotech) — Building & Managing Shopify Apps: A Developer's Guide — https://kr.linkedin.com/pulse/building-managing-shopify-apps-developers-guide-crest-infotech-eo7pf
  • [S9] Fayyaz Ahmed — Fetch products in custom Node.js/Remix app (2024-07-02) — https://youtu.be/2X4xo9v8-Fk
  • [S10] Fayyaz Ahmed — Update & delete products (2024-07-02) — https://youtu.be/GvlmukUw8Ns
  • [S11] WeeklyHow — Create a Shopify app from scratch in PHP (2019-10-03) — https://youtu.be/tX1E8fuesSE
  • [S12] WeeklyHow — Display Shopify products with pure PHP (2019-10-06) — https://youtu.be/YMnouXWOyFw
  • [S13] WeeklyHow — Display Shopify images via API (2019-10-10) — https://youtu.be/f2mQiULUm1o
  • [S14] Code Inspire — Shopify app development with Remix (2024-02-09) — https://youtu.be/FMVShSvAaAA
  • [S15] www.wanted.co.kr — 콘센트릭스 Shopify 개발 채용공고 — https://www.wanted.co.kr/wd/315823
  • [S16] FineGap — Shopify REST Admin API 소개 & 커스텀 앱 생성 (2023-12-26) — https://youtu.be/cy2dUXg5E-c
  • [S17] FineGap — Create products via REST Admin API (2023-12-29) — https://youtu.be/et9CSd1xjUQ
  • [S18] FineGap — Create orders via REST Admin API (2024-01-01) — https://youtu.be/inWrhRJNL8s
  • [S19] Fayyaz Ahmed — Fetch products with Node API module (2023-11-08) — https://youtu.be/VhT3dHg-jZ0
  • [S20] Fayyaz Ahmed — Create a product via Admin API in Node.js (2023-11-09) — https://youtu.be/SAW_wd-1t4w
  • [S21] Fireship — Hydrogen (Shopify React framework) 소개 (2021-11-09) — https://youtu.be/mAsM9c2sGjA
  • [S22] maeum.io — Shopify Development 서비스 소개 — https://maeum.io/services/shopify-development