Shopify API 개요

Shopify는 커머스 플랫폼의 거의 모든 측면을 읽고, 쓰고, 확장할 수 있는 풍부한 API 세트를 제공합니다. 각 작업에 적합한 API를 선택하는 것은 Shopify 개발에서 가장 중요한 기술 중 하나입니다. 이 강의에서는 인증, 버전 관리, 레이트 리밋, 각 API의 구체적인 사용 사례를 포함한 API 환경의 전체 지도를 제공합니다.

API 환경

Admin API (GraphQL 및 REST)

Admin API는 Shopify 생태계에서 가장 포괄적인 API입니다. 스토어 데이터에 대한 전체 CRUD 접근을 제공하며, 앱이 대부분의 백엔드 작업에 사용하는 API입니다.

GraphQL vs REST

Shopify는 Admin API의 GraphQL과 REST 버전을 모두 유지하고 있지만, GraphQL이 향후 주력 API입니다. 새로운 기능은 GraphQL에 먼저 추가되며, 일부 기능은 GraphQL에서만 사용할 수 있습니다.

항목	GraphQL	REST
데이터 조회	필요한 데이터만 정확히 요청	고정된 응답 형태
레이트 리밋	비용 기반 (1,000 포인트/초)	요청 기반 (40 요청/초)
새로운 기능	먼저 추가	지연되거나 추가되지 않을 수 있음
대량 작업	지원	미지원
뮤테이션	단일 엔드포인트	리소스별 엔드포인트
학습 곡선	가파름	완만함

GraphQL을 선호하세요

Shopify는 GraphQL이 API 플랫폼의 미래라고 명시적으로 밝혔습니다. metaobjects, markets, fulfillment orders 같은 새로운 리소스는 REST 지원이 제한적이거나 없습니다. 새 프로젝트에서는 항상 GraphQL을 사용하세요.

Admin API 인증

앱은 OAuth 2.0을 통해 Admin API에 인증합니다. 흐름은 다음과 같습니다:

액세스 토큰은 특정 스토어에 범위가 지정되며, 판매자가 승인한 권한(스코프)만 가집니다. 일반적인 스코프는 다음과 같습니다:

read_products / write_products -- 상품 카탈로그 접근
read_orders / write_orders -- 주문 관리
read_customers / write_customers -- 고객 데이터
read_inventory / write_inventory -- 재고 수준
read_content / write_content -- 메타오브젝트 및 콘텐츠

최소한의 스코프를 요청하세요

앱에 실제로 필요한 스코프만 요청하세요. 과도한 스코프 요청은 설치율을 낮춥니다 -- 판매자는 모든 것에 접근을 원하는 앱을 당연히 의심합니다. 나중에 재인증 흐름을 통해 추가 스코프를 요청할 수 있습니다.

Storefront API

Storefront API는 고객 대면 애플리케이션을 위해 설계되었습니다. Admin API와 달리, 클라이언트 측 코드에 안전하게 포함할 수 있는 공개 액세스 토큰을 사용합니다.

사용 사례

Hydrogen 스토어프론트: 헤드리스 스토어프론트의 모든 데이터 조회
커스텀 상품 선택기: 스토어프론트의 JavaScript 위젯
모바일 앱: 네이티브 iOS/Android 쇼핑 앱
Buy Button: 외부 웹사이트에 상품 임베딩
장바구니 작업: 상품 추가, 할인 코드 적용, 장바구니 관리

Admin API와의 주요 차이점

기능	Admin API	Storefront API
인증	비공개 액세스 토큰	공개 액세스 토큰
데이터 접근	전체 읽기/쓰기	읽기 전용 + 장바구니 뮤테이션
대상	앱 백엔드	고객 대면 클라이언트
레이트 리밋	스토어별	앱별, 스토어별
고객 데이터	전체 접근	인증된 고객만

# Storefront API: 컬렉션 페이지용 상품 조회
query CollectionProducts($handle: String!, $first: Int!) {
  collection(handle: $handle) {
    title
    products(first: $first) {
      edges {
        node {
          id
          title
          priceRange {
            minVariantPrice {
              amount
              currencyCode
            }
          }
          images(first: 1) {
            edges {
              node {
                url
                altText
              }
            }
          }
        }
      }
    }
  }
}

Payments Apps API

Payments Apps API를 사용하면 Shopify Checkout에 직접 통합되는 결제 게이트웨이를 구축할 수 있습니다. 이것은 결제 서비스 제공업체를 위한 특수 API입니다.

신용카드, 외부 결제, 커스텀 온사이트 결제 방법을 지원합니다
신용카드 처리에는 PCI DSS 규정 준수가 필요합니다
결제 세션에 Webhook 기반 흐름을 사용합니다
Partner Dashboard를 통해 추가 심사와 함께 등록됩니다

Payments Apps는 특수 목적입니다

대부분의 개발자는 이 API가 필요하지 않습니다. 결제 게이트웨이 또는 대체 결제 방법을 구축하는 경우에만 관련이 있습니다. 결제를 받기만 하면 된다면 Shopify Payments 또는 기존 결제 게이트웨이 앱 중 하나를 사용하세요.

Customer Account API

Customer Account API는 새로운 Customer Account 환경(2024년 도입)에서 고객 셀프서비스 기능을 가능하게 합니다. 인증된 고객이 다음을 할 수 있습니다:

주문 조회 및 관리
프로필 정보 업데이트
주소 관리
로열티 및 리워드 프로그램 접근
B2B 회사 정보 조회

이 API는 Shopify의 새로운 고객 인증 시스템을 통해 얻은 고객 액세스 토큰을 사용합니다.

Functions API

Functions API는 Shopify Functions가 입력 데이터를 수신하고 출력을 반환하는 방법을 정의합니다. 이것은 전통적인 HTTP API가 아니라, WebAssembly 모듈과 Shopify 런타임 간의 계약입니다.

각 Function 확장 대상에는 특정 입력/출력 스키마가 있습니다:

# 할인 Function의 입력 쿼리
query Input {
  cart {
    lines {
      merchandise {
        ... on ProductVariant {
          product {
            hasAnyTag(tags: ["vip-discount"])
          }
        }
      }
      cost {
        totalAmount {
          amount
        }
      }
    }
  }
}

// 출력: VIP 상품에 10% 할인 적용
{
  "discounts": [
    {
      "value": {
        "percentage": {
          "value": "10.0"
        }
      },
      "targets": [
        {
          "productVariant": {
            "id": "gid://shopify/ProductVariant/123"
          }
        }
      ],
      "message": "VIP 10% Off"
    }
  ]
}

Checkout Extensions API

Checkout Extensions API를 사용하면 Shopify 결제 내에서 렌더링되는 React 기반 UI 컴포넌트를 구축할 수 있습니다. Extension 대상은 UI가 표시되는 위치를 정의합니다:

purchase.checkout.block.render -- 메인 결제 영역의 블록
purchase.checkout.header.render-after -- 결제 헤더 뒤
purchase.checkout.footer.render-before -- 결제 푸터 앞
purchase.thank-you.block.render -- 감사 페이지
purchase.checkout.shipping-option-item.render-after -- 각 배송 옵션 뒤

Extension은 Checkout UI Extensions 라이브러리의 제한된 UI 컴포넌트 세트를 사용합니다(Polaris가 아님).

Flow Triggers and Actions API

Shopify Flow는 판매자를 위한 시각적 자동화 플랫폼입니다. 앱은 다음을 제공하여 Flow와 통합할 수 있습니다:

Trigger: Flow 워크플로우를 시작하는 이벤트 (예: "새 리뷰 제출됨")
Action: Flow가 앱에서 호출할 수 있는 작업 (예: "로열티 포인트 발송")

이것은 전체 자동화 UI를 직접 구축하지 않고도 앱을 더 유용하게 만드는 강력한 방법입니다.

API 버전 관리

Shopify는 캘린더 기반 버전 관리 시스템을 사용합니다. 새로운 API 버전은 분기별로 릴리스됩니다:

버전	릴리스	상태
`2025-07`	2025년 7월	지원 중
`2025-10`	2025년 10월	지원 중
`2026-01`	2026년 1월	현재 안정 버전
`2026-04`	2026년 4월	릴리스 후보

버전 관리 규칙

각 버전은 릴리스 후 12개월 동안 지원됩니다
호환성을 깨는 변경은 버전 사이에서만 발생하며, 버전 내에서는 발생하지 않습니다
API 요청에 버전을 지정합니다:
- GraphQL: X-Shopify-API-Version: 2026-01 헤더
- REST: /admin/api/2026-01/products.json URL 경로
폐기 예정 알림은 제거 9개월 전에 API 응답에 나타납니다

# 명시적 버전이 있는 GraphQL 요청
curl -X POST "https://your-store.myshopify.com/admin/api/2026-01/graphql.json" \
  -H "Content-Type: application/json" \
  -H "X-Shopify-Access-Token: your-token" \
  -d '{"query": "{ shop { name } }"}'

최신 버전을 유지하세요

매 분기마다 API 버전을 업데이트하는 캘린더 알림을 설정하세요. 버전이 뒤처지면 새로운 기능을 놓치고 결국 폐기 장벽에 부딪힙니다. Shopify CLI와 Partner Dashboard는 오래된 버전을 사용할 때 경고를 표시합니다.

레이트 리밋

레이트 리밋은 플랫폼을 보호하고 스토어의 모든 앱에 대한 공정한 접근을 보장합니다.

GraphQL 레이트 리밋

GraphQL은 비용 기반 시스템을 사용합니다:

각 스토어는 앱에 초당 1,000 비용 포인트를 부여합니다
포인트는 초당 50포인트씩 재생성됩니다(Leaky Bucket 알고리즘)
간단한 쿼리는 1-10포인트, 연결이 있는 복잡한 쿼리는 더 높은 비용이 듭니다
응답에는 남은 예산을 보여주는 throttleStatus 객체가 포함됩니다

{
  "extensions": {
    "cost": {
      "requestedQueryCost": 12,
      "actualQueryCost": 8,
      "throttleStatus": {
        "maximumAvailable": 1000,
        "currentlyAvailable": 992,
        "restoreRate": 50
      }
    }
  }
}

REST 레이트 리밋

REST는 더 단순한 요청 기반 모델을 사용합니다:

표준 플랜: 스토어당 초당 40개 요청
Shopify Plus: 스토어당 초당 80개 요청 (일부 엔드포인트는 더 높음)
X-Shopify-Shop-Api-Call-Limit 응답 헤더로 추적됩니다

레이트 리밋 처리

// 지수 백오프를 사용한 재시도
async function shopifyRequest(query, retries = 3) {
  for (let attempt = 0; attempt < retries; attempt++) {
    const response = await admin.graphql(query);

    if (response.status === 429) {
      const retryAfter = parseFloat(
        response.headers.get("Retry-After") || "1"
      );
      await new Promise(r => setTimeout(r, retryAfter * 1000));
      continue;
    }

    return response.json();
  }
  throw new Error("Rate limit exceeded after retries");
}

커서 기반 페이지네이션

GraphQL과 REST 모두 목록 엔드포인트에 커서 기반 페이지네이션을 사용합니다. 이는 동시 데이터 변경을 올바르게 처리하기 때문에 오프셋 기반 페이지네이션보다 더 안정적입니다.

GraphQL 페이지네이션

query Products($first: Int!, $after: String) {
  products(first: $first, after: $after) {
    edges {
      cursor
      node {
        id
        title
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

다음 페이지를 가져오려면 endCursor 값을 after 변수로 전달하세요. hasNextPage가 false가 될 때까지 계속합니다.

REST 페이지네이션

REST API는 Link 헤더에 페이지네이션 링크를 반환합니다:

Link: <https://store.myshopify.com/admin/api/2026-01/products.json?page_info=abc123&limit=50>; rel="next"

rel="next" URL을 파싱하고 다음 요청에 사용하세요.

페이지 번호를 사용하지 마세요

Shopify는 수년 전에 페이지 번호 페이지네이션을 폐기했습니다. 항상 커서 기반 페이지네이션을 사용하세요. ?page=2를 사용하는 오래된 튜토리얼을 발견하면 그것은 구식이며 작동하지 않습니다.

올바른 API 선택하기

하고 싶은 작업	사용할 API
앱 백엔드에서 상품, 주문, 고객 관리	Admin API (GraphQL)
커스텀 스토어프론트에 상품 표시	Storefront API
Hydrogen으로 헤드리스 스토어프론트 구축	Storefront API
결제 시 할인 로직 커스터마이징	Functions API (discount target)
결제 페이지에 UI 추가	Checkout Extensions API
게이트웨이로서 결제 처리	Payments Apps API
고객이 자신의 계정 관리	Customer Account API
Shopify Flow 자동화와 통합	Flow Triggers & Actions API
대규모 데이터셋 내보내기/가져오기	Admin API Bulk Operations

다음 강의에서는 가장 중요한 Shopify API를 구동하는 쿼리 언어인 GraphQL에 대해 깊이 다루겠습니다.

API 환경​

Admin API (GraphQL 및 REST)​

GraphQL vs REST​

Admin API 인증​

Storefront API​

사용 사례​

Admin API와의 주요 차이점​

Payments Apps API​

Customer Account API​

Functions API​

Checkout Extensions API​

Flow Triggers and Actions API​

API 버전 관리​

버전 관리 규칙​

레이트 리밋​

GraphQL 레이트 리밋​

REST 레이트 리밋​

레이트 리밋 처리​

커서 기반 페이지네이션​

GraphQL 페이지네이션​

REST 페이지네이션​

올바른 API 선택하기​