shopify-api

Shopify API

Shopify는 전자상거래 플랫폼의 모든 면을 프로그램 방식으로 다루기 위한 다양한 API 세트를 제공해요. 스토어 데이터를 읽고 쓰는 Admin API, 구매자(고객)가 보는 스토어프런트를 직접 구축하는 Storefront API, 가격·결제·배송 등 백엔드 로직을 커스터마이즈하는 Shopify Functions, 그리고 이벤트를 구독해 실시간으로 반응하는 Webhooks까지, 우리의 아이디어를 실제 동작하는 통합(App)으로 만들 수 있어요. 모든 API는 인증·버전 관리·속도 제한(rate limit)을 따르고, Shopify에서 공식 지원하는 클라이언트 라이브러리(Node.js, Ruby, React Router 등)를 사용하면 안정적으로 빠르게 개발할 수 있어요.

출처: 문서

본문

핵심 기능

Admin API (GraphQL) — 상품(product), 고객(customer), 주문(order), 재고(inventory) 등 스토어 데이터를 읽고 쓰는 핵심 API예요. 새 통합을 만들 땐 REST보다 GraphQL Admin API를 쓰는 걸 권장해요. 실시간 변경에 대응하는 Events와 결제·환불을 다루는 Payments Apps API도 함께 제공돼요.

Storefront API (GraphQL) — 헤드리스 커머스(headless commerce)를 위한 API예요. 웹·모바일·게임 등 어디서든 나만의 구매 경험을 만들 수 있고, Liquid 테마, Ajax API, Hydrogen(React 기반 스토어프런트 프레임워크)과 함께 쓰여요.

Shopify Functions — 백엔드에서 할인(discount), 결제(payment), 배송(delivery) 같은 핵심 로직을 커스터마이즈해요. 상점 확인 없이도 스토어의 실제 동작을 바꿀 수 있어요.

Webhooks — 스토어에서 발생하는 이벤트(예: 주문 생성)를 구독하고, 우리 앱이 그 이벤트를 받아 우리만의 로직을 실행해요.

Webhooks의 이벤트 구독 예시 (GraphQL Admin):

mutation webhookSubscriptionCreate($topic: WebhookSubscriptionTopic!, $webhookSubscription: WebhookSubscriptionInput!) {
  webhookSubscriptionCreate(topic: $topic, webhookSubscription: $webhookSubscription) {
    userErrors {
      field
      message
    }
    webhookSubscription {
      id
      callbackUrl
    }
  }
}

클라이언트 라이브러리 설치

Shopify가 공식 지원하는 클라이언트 라이브러리로, 이미 알고 있는 언어·프레임워크로 빠르고 안정적인 앱을 만들 수 있어요.

Node.js:

npm install --save @shopify/shopify-api
# or
yarn add @shopify/shopify-api

Ruby:

bundle add shopify_api

React Router 앱 (CLI 스캐폴드):

npm install -g @shopify/cli@latest
shopify app init

인증 (Authentication)

모든 GraphQL Admin API 요청은 X-Shopify-Access-Token 헤더에 액세스 토큰을 담아 보내요. 대부분의 앱은 Shopify CLI 템플릿이나 Direct API Access가 요청마다 인증을 자동으로 처리하므로, 토큰을 직접 관리할 필요가 없어요. 보안을 위해 앱은 설치 과정에서 필요한 최소한의 access scope만 요청해야 해요.

Node.js로 쇼핑몰 이름 조회 (GraphQL Admin):

const client = new shopify.clients.Graphql({session});
const response = await client.query({data: 'query { shop { name } }'});

cURL로 직접 호출 (GraphQL Admin):

# Replace {SHOPIFY_ACCESS_TOKEN} with your actual access token
curl -X POST \
https://{shop}.myshopify.com/admin/api/2026-07/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {SHOPIFY_ACCESS_TOKEN}' \
-d '{
  "query": "query { shop { name } }"
}'

GraphQL 쿼리 실행

GraphQL 쿼리는 POST HTTP 요청으로 엔드포인트에 보내요. 쿼리는 QueryRoot 객체에서 시작하며, REST의 GET과 비슷한 역할을 해요. 아래 예시는 첫 3개 상품의 ID와 제목을 가져와요.

query getProducts {
  products(first: 3) {
    edges {
      node {
        id
        title
      }
    }
  }
}

cURL로 위 쿼리 실행:

curl -X POST https://{store_name}.myshopify.com/admin/api/2026-07/graphql.json \
  -H 'Content-Type: application/json' \
  -H 'X-Shopify-Access-Token: {access_token}' \
  -d '{
  "query": "{
    products(first: 3) {
      edges {
        node {
          id
          title
        }
      }
    }
  }"
}'

주요 엔드포인트:

Admin API: https://{store_name}.myshopify.com/admin/api/2026-07/graphql.json
Storefront API: https://{shop}.myshopify.com/api/2026-07/graphql.json

Storefront API 사용 예시

구매자 쪽 데이터를 읽을 땐 X-Shopify-Storefront-Access-Token 헤더를 사용해요.

curl -X POST \
  https://{shop}.myshopify.com/api/2026-07/graphql.json \
  -H 'Content-Type: application/json' \
  -H 'X-Shopify-Storefront-Access-Token: {storefront_access_token}' \
  -d '{ "query": "{ products(first: 3) { edges { node { title } } } }" }'

상태 코드와 오류

GraphQL API는 대부분의 오류를 HTTP 200 응답의 errors 배열로 돌려주므로, errors 필드를 반드시 확인해야 해요. 네트워크·계정·Shopify 서비스 문제는 4xx/5xx 상태 코드로 반환돼요.

HTTP/1.1 400 Bad Request
{
  "errors": {
    "query": "Required parameter missing or invalid"
  }
}

주요 상태 코드:

400 Bad Request — 서버가 요청을 처리하지 못해요.
402 Payment Required — 스토어가 동결(frozen) 상태예요.
403 Forbidden — 스토어가 사기로 표시되어 접근이 금지돼요.
404 Not Found — 리소스를 찾을 수 없어요(주로 삭제된 항목 조회 시).
423 Locked — 스토어를 사용할 수 없어요(반복적 속도 제한 초과·사기 위험).
5xx Errors — Shopify 내부 오류로, Shopify status page를 확인해요.

더 알아보기 (Learn more)

공식 문서