페이지네이션

모든 목록 엔드포인트는 일관되고 성능 좋은 결과를 위해 커서 기반 페이지네이션을 사용합니다.

요청 파라미터

파라미터	타입	기본값	설명
`limit`	integer	20	페이지당 항목 수 (1–100)
`starting_after`	string	—	커서: 이 ID 이후의 항목 반환

응답 형식

{
  "data": [
    { "id": "prod_abc", "name": "Product A" },
    { "id": "prod_def", "name": "Product B" }
  ],
  "has_more": true,
  "next_cursor": "prod_def"
}

필드	타입	설명
`data`	array	항목 목록
`has_more`	boolean	이 페이지 이후에 더 많은 항목이 있는지 여부
`next_cursor`	string \| null	다음 페이지를 위해 `starting_after`로 전달할 ID

예시: 전체 상품 조회

let cursor: string | undefined;
const allProducts = [];

do {
  const params = new URLSearchParams({ limit: '100' });
  if (cursor) params.set('starting_after', cursor);

  const res = await fetch(
    `https://api.headlesscommerce.io/v1/storefront/products?${params}`,
    { headers: { Authorization: `Bearer ${apiKey}` } },
  );
  const body = await res.json();

  allProducts.push(...body.data);
  cursor = body.has_more ? body.next_cursor : undefined;
} while (cursor);

필터링 및 정렬

목록 엔드포인트는 필터링과 정렬을 위한 쿼리 파라미터도 지원합니다:

# 상태 필터 + 생성일 기준 정렬
GET /v1/admin/products?status=active&sort=created_at&order=desc&limit=50

지원되는 필터 파라미터는 리소스마다 다릅니다 — 각 엔드포인트의 문서를 참조하세요.