Admin REST API는 Shopify 스토어의 백엔드 데이터를 CRUD할 수 있는 API야. 상품 등록, 주문 조회, 고객 정보 수정 등 거의 모든 관리 기능을 API로 처리할 수 있음.

엔드포인트 형식은 이렇게 생겼어:

https://{store-name}.myshopify.com/admin/api/{version}/{resource}.json

예를 들어 상품 목록 가져오기:

GET https://my-store.myshopify.com/admin/api/2024-01/products.json

인증은 Access Token 방식을 사용함. 헤더에 X-Shopify-Access-Token을 넣어주면 됨.

API 버전 관리도 중요한데, Shopify는 분기마다 새 버전을 릴리즈하고 최소 12개월은 지원해줌. 2024-01, 2024-04 이런 식으로 버전이 붙어있어.

1. 출력 태그 (Output Tags) — 이중 중괄호 사용

{{ product.title }}
{{ product.price | money }}
{{ shop.name }}

2. 로직 태그 (Logic Tags) — 중괄호 + 퍼센트 사용

{% if product.available %}
  <button>장바구니 담기</button>
{% else %}
  <button disabled>품절</button>
{% endif %}

{% for product in collection.products %}
  <div>{{ product.title }}</div>
{% endfor %}

3. 필터 (Filters) — 파이프(|)로 데이터 변환

{{ product.price | money }}           → ₩15,000
{{ product.title | upcase }}          → PRODUCT NAME
{{ 'style.css' | asset_url | stylesheet_tag }}
{{ product.description | truncate: 100 }}

Shopify는 Shopify CLI라는 공식 개발 도구를 제공함. 이걸로 앱 프로젝트를 빠르게 세팅할 수 있어:

# Shopify CLI 설치
npm install -g @shopify/cli @shopify/theme

# 새 앱 프로젝트 생성
shopify app init

# 개발 서버 실행
shopify app dev

기본 앱 스택은 Node.js + Express + React 조합이 많이 쓰이고, 최근엔 Remix 프레임워크를 Shopify가 공식 지원하면서 Remix 기반 앱 개발이 트렌드임 ㅋㅋ

메타오브젝트(Metaobjects)는 2022년에 추가된 기능으로, 완전히 커스텀한 데이터 구조를 만들 수 있어. 예를 들어 "팀원 소개", "FAQ 항목", "브랜드 스토리" 같은 구조화된 콘텐츠를 만들 때 씀.

메타오브젝트는 타입 정의 → 인스턴스 생성 → 참조 순서로 사용해:

# 1. 메타오브젝트 타입 정의 (GraphQL)
mutation {
  metaobjectDefinitionCreate(definition: {
    name: "팀원"
    type: "team_member"
    fieldDefinitions: [
      { name: "이름", key: "name", type: "single_line_text_field" }
      { name: "직책", key: "role", type: "single_line_text_field" }
      { name: "사진", key: "photo", type: "file_reference" }
    ]
  }) {
    metaobjectDefinition { id }
  }
}

헤드리스에서 장바구니는 Storefront API의 Cart API로 구현함:

// 장바구니 생성
mutation cartCreate($input: CartInput!) {
  cartCreate(input: $input) {
    cart {
      id
      checkoutUrl
      lines(first: 10) {
        edges {
          node {
            id
            quantity
            merchandise {
              ... on ProductVariant {
                id
                title
                priceV2 { amount currencyCode }
              }
            }
          }
        }
      }
    }
  }
}

// 아이템 추가
mutation cartLinesAdd($cartId: ID!, $lines: [CartLineInput!]!) {
  cartLinesAdd(cartId: $cartId, lines: $lines) {
    cart {
      id
      totalQuantity
    }
  }
}

장바구니 ID는 localStorage에 저장해서 세션 간 유지하면 됨. 결제는 checkoutUrl로 리다이렉트하면 Shopify 기본 결제 페이지로 이동해.

Shopify는 자체 CDN을 통해 이미지를 제공하는데, Liquid에서 이미지 크기를 지정해서 불필요하게 큰 이미지 로딩을 막을 수 있어:

{% comment %} 나쁜 예 - 원본 이미지 그대로 로드 {% endcomment %}
<img src="{{ product.featured_image | img_url }}">

{% comment %} 좋은 예 - 크기 지정 + WebP 포맷 {% endcomment %}
<img
  src="{{ product.featured_image | image_url: width: 800 }}"
  srcset="{{ product.featured_image | image_url: width: 400 }} 400w,
          {{ product.featured_image | image_url: width: 800 }} 800w,
          {{ product.featured_image | image_url: width: 1200 }} 1200w"
  sizes="(max-width: 768px) 100vw, 50vw"
  loading="lazy"
  alt="{{ product.featured_image.alt }}"
>

Shopify CDN은 자동으로 WebP 변환을 지원하고, image_url 필터로 크기를 지정하면 서버에서 리사이징해서 줌.

Shopify의 기본 필터 기능을 커스터마이징하거나, Storefront API로 완전히 새로운 필터 UI를 만들 수 있어:

query getFilteredProducts(
  $handle: String!
  $filters: [ProductFilter!]
  $sortKey: ProductCollectionSortKeys
  $reverse: Boolean
) {
  collection(handle: $handle) {
    products(
      first: 20
      filters: $filters
      sortKey: $sortKey
      reverse: $reverse
    ) {
      filters {
        id
        label
        type
        values {
          id
          label
          count
          input
        }
      }
      edges {
        node {
          id
          title
          priceRange {
            minVariantPrice { amount }
          }
        }
      }
    }
  }
}

Shopify Markets를 활용하면 글로벌 판매가 훨씬 쉬워짐. Liquid에서 다국어 처리:

{% comment %} locales/ko.default.json {% endcomment %}
{
  "products": {
    "add_to_cart": "장바구니 담기",
    "sold_out": "품절",
    "sale": "세일"
  }
}

{% comment %} locales/en.default.json {% endcomment %}
{
  "products": {
    "add_to_cart": "Add to Cart",
    "sold_out": "Sold Out",
    "sale": "Sale"
  }
}

{% comment %} 템플릿에서 사용 {% endcomment %}
<button>{{ 'products.add_to_cart' | t }}</button>

통화 변환은 Shopify가 자동으로 처리해주는데, {{ product.price | money_with_currency }}로 현재 통화에 맞게 표시됨.

// GraphQL API의 비용 기반 Rate Limit 처리
async function shopifyGraphQL(query, variables) {
  const response = await fetch(endpoint, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify({ query, variables }),
  });

  const data = await response.json();

  // Rate Limit 정보 확인
  const cost = data.extensions?.cost;
  if (cost) {
    const { throttleStatus } = cost;
    const { currentlyAvailable, restoreRate } = throttleStatus;

    // 남은 포인트가 부족하면 대기
    if (currentlyAvailable < 100) {
      const waitTime = (100 - currentlyAvailable) / restoreRate * 1000;
      await new Promise(resolve => setTimeout(resolve, waitTime));
    }
  }

  return data;
}