카탈로그 API2026-11프리뷰

옵션

상품의 옵션 하나(사이즈, 색상, 휴대폰 기종 등). 저희가 구매하는 판매자 SKU와 내 스토어가 판매하는 옵션에 연결돼요.

옵션은 주문 항목이 지정하는 대상이에요. 그 재고 수준이 판매 가능한 수량을 나타내요.

엔드포인트

GET/v1/products/{id}/variants상품의 옵션 목록
GET/v1/variants/{id}옵션 조회
PATCH/v1/variants/{id}옵션 수정

Variant 객체

idstring: var_로 시작해요.
skustring: 저희가 읽은 판매자 SKU. 저희가 구매하는 것.
label, options: 옵션 값, 라벨 하나로 그리고 옵션 이름별로.
costmoney: 판매자의 1개 가격(CN¥, 마지막으로 읽은 기준).
pricemoney: 내 판매 가격.
in_stockboolean: 판매자가 판매할 수 있는지(마지막으로 읽은 기준).
unitsinteger: 1개 팔릴 때마다 구매하는 수량: 내 스토어의 3개 묶음이면 3개를 구매해요.
weight_ginteger: 배송비 견적에 쓰는, 내가 입력한 1개의 포장 후 무게.
external_variant_idstring|null: 스토어의 옵션. 그 주문은 이 SKU를 구매하며, 연결되지 않은 옵션의 주문은 거절돼요.

variant

{
  "id": "var_41hz",
  "product": "prd_8f2k",
  "sku": "5187209554",
  "label": "Black / M",
  "options": { "Color": "Black", "Size": "M" },
  "image": "https://media.ninjabuy.com/listings/weidian-7750970856/sku-black.webp",
  "cost": { "amount": "38.00", "currency": "CNY" },
  "price": { "amount": "49.99", "currency": "USD" },
  "in_stock": true,
  "units": 1,
  "weight_g": 180,
  "external_variant_id": "gid://shopify/ProductVariant/44100231",
  "updated_at": "2026-11-04T09:20:03Z"
}

상품의 옵션 목록

GET/v1/products/{id}/variants

모든 옵션의 비용, 내 가격, 재고, 연결.

범위products:read

경로 매개변수

idstring필수: 상품 ID.

쿼리 매개변수

limit, cursor: Pagination

오류

상태	유형	시점
404	not-found	이 계정에 해당 상품이 없어요.

curl "https://www.ninjabuy.com/api/v1/products/prd_8f2k/variants" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"

Response 200

HTTP/2 200 OK

{
  "data": [
    {
      "id": "var_41hz",
      "product": "prd_8f2k",
      "sku": "5187209554",
      "label": "Black / M",
      "options": { "Color": "Black", "Size": "M" },
      "image": "https://media.ninjabuy.com/listings/weidian-7750970856/sku-black.webp",
      "cost": { "amount": "38.00", "currency": "CNY" },
      "price": { "amount": "49.99", "currency": "USD" },
      "in_stock": true,
      "units": 1,
      "weight_g": 180,
      "external_variant_id": "gid://shopify/ProductVariant/44100231",
      "updated_at": "2026-11-04T09:20:03Z"
    },
    {
      "id": "var_41j0",
      "product": "prd_8f2k",
      "sku": "5187209555",
      "label": "Black / L",
      "options": { "Color": "Black", "Size": "M" },
      "image": "https://media.ninjabuy.com/listings/weidian-7750970856/sku-black.webp",
      "cost": { "amount": "38.00", "currency": "CNY" },
      "price": { "amount": "49.99", "currency": "USD" },
      "in_stock": false,
      "units": 1,
      "weight_g": 180,
      "external_variant_id": null,
      "updated_at": "2026-11-04T09:20:03Z"
    }
  ],
  "has_more": false,
  "cursor": null
}

옵션 조회

GET/v1/variants/{id}

옵션 하나.

범위products:read

경로 매개변수

idstring필수: 옵션 ID.

오류

상태	유형	시점
404	not-found	이 계정에 해당 옵션이 없어요.

curl "https://www.ninjabuy.com/api/v1/variants/var_41hz" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"

Response 200

HTTP/2 200 OK

{
  "id": "var_41hz",
  "product": "prd_8f2k",
  "sku": "5187209554",
  "label": "Black / M",
  "options": { "Color": "Black", "Size": "M" },
  "image": "https://media.ninjabuy.com/listings/weidian-7750970856/sku-black.webp",
  "cost": { "amount": "38.00", "currency": "CNY" },
  "price": { "amount": "49.99", "currency": "USD" },
  "in_stock": true,
  "units": 1,
  "weight_g": 180,
  "external_variant_id": "gid://shopify/ProductVariant/44100231",
  "updated_at": "2026-11-04T09:20:03Z"
}

옵션 수정

PATCH/v1/variants/{id}

가격, 판매당 구매 수량, 무게, 대응하는 스토어 옵션을 설정해요. 바뀌는 것만 보내세요.

범위products:write

경로 매개변수

idstring필수: 옵션 ID.

본문

pricemoney: 선택 사항. 내 판매 가격.
unitsinteger: 선택 사항. 1~50.
weight_ginteger: 선택 사항. 1개의 포장 후 무게(그램).
external_variant_idstring|null: 선택 사항. 스토어의 옵션에 연결하거나 null로 연결 해제.

오류

상태	유형	시점
404	not-found	이 계정에 해당 옵션이 없어요.
409	invalid-state	그 스토어 옵션은 이미 다른 SKU에 대응해요.

curl -X PATCH "https://www.ninjabuy.com/api/v1/variants/var_41hz" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Content-Type: application/json" \
  -d '{
    "units": 2,
    "price": { "amount": "89.99", "currency": "USD" }
  }'

Response 200

HTTP/2 200 OK

{
  "id": "var_41hz",
  "product": "prd_8f2k",
  "sku": "5187209554",
  "label": "Black / M",
  "options": { "Color": "Black", "Size": "M" },
  "image": "https://media.ninjabuy.com/listings/weidian-7750970856/sku-black.webp",
  "cost": { "amount": "38.00", "currency": "CNY" },
  "price": { "amount": "89.99", "currency": "USD" },
  "in_stock": true,
  "units": 2,
  "weight_g": 180,
  "external_variant_id": "gid://shopify/ProductVariant/44100231",
  "updated_at": "2026-11-04T09:20:03Z"
}