카탈로그 API2026-11프리뷰

상품

가져오기에서 저장한 상품. 내 상품명과 가격, 판매 중인 스토어가 포함돼요.

상품은 Shopify로 보내요. Shopify 스토어가 판매하는 마켓플레이스의 주문도 Shopify를 통해 저희에게 와요: 스토어 연결.
WooCommerce나 Wix 스토어는 자체 상품을 관리하고 주문 생성으로 주문을 보내요.

엔드포인트

GET/v1/products상품 목록
GET/v1/products/{id}상품 조회
PATCH/v1/products/{id}상품 수정
POST/v1/products/{id}/pushShopify로 보내기
DELETE/v1/products/{id}상품 삭제

Product 객체

idstring: prd_로 시작해요.
titlestring: 내 상품명. 판매자 상품명은 가져오기에 남아요.
statusstring: active 또는 paused(내가 중지했거나, 비용이 너무 오르거나 판매자가 품절되어 동기화 규칙이 중지한 경우).
sourceobject: 마켓플레이스, 상품 링크, 중국 판매자.
options[]array: 옵션 이름, 최대 세 개, 스토어에 표시되는 대로.
price_range, cost_rangeobject: 옵션별 내 가격과 판매자 가격.
channels[]array: 등록된 곳: 스토어, 그곳의 상품 ID, 그곳에서의 상태.
syncobject: 따르는 동기화 규칙과 상품을 마지막으로 읽은 시각.
importstring: 저장된 원본 가져오기.

product

{
  "id": "prd_8f2k",
  "title": "Heavyweight Washed Hoodie",
  "status": "active",
  "source": {
    "marketplace": "weidian",
    "url": "https://weidian.com/item.html?itemID=7750970856",
    "seller": "Ruoyi Studio"
  },
  "options": ["Color", "Size"],
  "variants_count": 6,
  "price_range": {
    "min": { "amount": "49.99", "currency": "USD" },
    "max": { "amount": "54.99", "currency": "USD" }
  },
  "cost_range": {
    "min": { "amount": "38.00", "currency": "CNY" },
    "max": { "amount": "42.00", "currency": "CNY" }
  },
  "channels": [
    {
      "channel": "shopify",
      "shop": "acme-goods.myshopify.com",
      "external_id": "gid://shopify/Product/8812042",
      "status": "draft",
      "pushed_at": "2026-11-04T09:20:03Z"
    }
  ],
  "sync": {
    "rule": "rule_default",
    "last_checked_at": "2026-11-04T09:12:40Z"
  },
  "import": "imp_2c9d",
  "created_at": "2026-11-04T09:20:01Z",
  "updated_at": "2026-11-04T09:20:03Z"
}

상품 목록

GET/v1/products

내 상품, 최신순.

범위products:read

쿼리 매개변수

statusstring: 선택 사항. active 또는 paused.
channelstring: 선택 사항. shopify(그곳에 등록된 것).
changed_sincestring: 선택 사항. 시각: 그 이후 비용이나 재고가 바뀐 상품만.
limit, cursor: Pagination

curl "https://www.ninjabuy.com/api/v1/products?status=active&limit=2" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"

Response 200

HTTP/2 200 OK

{
  "data": [
    {
      "id": "prd_8f2k",
      "title": "Heavyweight Washed Hoodie",
      "status": "active",
      "variants_count": 6
    },
    {
      "id": "prd_1x0a",
      "title": "Canvas Tote",
      "status": "active",
      "variants_count": 3
    }
  ],
  "has_more": true,
  "cursor": "c_1x0a"
}

상품 조회

GET/v1/products/{id}

공급처, 채널, 동기화 상태가 포함된 상품 하나. 옵션은 별도 경로예요.

범위products:read

경로 매개변수

idstring필수: 상품 ID.

오류

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

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

Response 200

HTTP/2 200 OK

{
  "id": "prd_8f2k",
  "title": "Heavyweight Washed Hoodie",
  "status": "active",
  "source": {
    "marketplace": "weidian",
    "url": "https://weidian.com/item.html?itemID=7750970856",
    "seller": "Ruoyi Studio"
  },
  "options": ["Color", "Size"],
  "variants_count": 6,
  "price_range": {
    "min": { "amount": "49.99", "currency": "USD" },
    "max": { "amount": "54.99", "currency": "USD" }
  },
  "cost_range": {
    "min": { "amount": "38.00", "currency": "CNY" },
    "max": { "amount": "42.00", "currency": "CNY" }
  },
  "channels": [
    {
      "channel": "shopify",
      "shop": "acme-goods.myshopify.com",
      "external_id": "gid://shopify/Product/8812042",
      "status": "draft",
      "pushed_at": "2026-11-04T09:20:03Z"
    }
  ],
  "sync": {
    "rule": "rule_default",
    "last_checked_at": "2026-11-04T09:12:40Z"
  },
  "import": "imp_2c9d",
  "created_at": "2026-11-04T09:20:01Z",
  "updated_at": "2026-11-04T09:20:03Z"
}

상품 수정

PATCH/v1/products/{id}

상품명이나 설명을 변경하거나 일시 중지·재개해요. 바뀌는 것만 보내세요. 가격은 옵션별이에요(옵션). 보낸 상품은 다음 보내기 때 변경 사항이 스토어에 반영돼요.

범위products:write

경로 매개변수

idstring필수: 상품 ID.

본문

titlestring: 선택 사항.
descriptionstring: 선택 사항. 스토어에 표시되는 HTML.
statusstring: 선택 사항. active 또는 paused. paused로 하면 채널 재고가 0이 돼요.
sync_rulestring: 선택 사항. 동기화 규칙 ID. null이면 기본 규칙.

오류

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

curl -X PATCH "https://www.ninjabuy.com/api/v1/products/prd_8f2k" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Content-Type: application/json" \
  -d '{ "status": "paused" }'

Response 200

HTTP/2 200 OK

{
  "id": "prd_8f2k",
  "title": "Heavyweight Washed Hoodie",
  "status": "paused",
  "source": {
    "marketplace": "weidian",
    "url": "https://weidian.com/item.html?itemID=7750970856",
    "seller": "Ruoyi Studio"
  },
  "options": ["Color", "Size"],
  "variants_count": 6,
  "price_range": {
    "min": { "amount": "49.99", "currency": "USD" },
    "max": { "amount": "54.99", "currency": "USD" }
  },
  "cost_range": {
    "min": { "amount": "38.00", "currency": "CNY" },
    "max": { "amount": "42.00", "currency": "CNY" }
  },
  "channels": [
    {
      "channel": "shopify",
      "shop": "acme-goods.myshopify.com",
      "external_id": "gid://shopify/Product/8812042",
      "status": "draft",
      "pushed_at": "2026-11-04T09:20:03Z"
    }
  ],
  "sync": {
    "rule": "rule_default",
    "last_checked_at": "2026-11-04T09:12:40Z"
  },
  "import": "imp_2c9d",
  "created_at": "2026-11-04T09:20:01Z",
  "updated_at": "2026-11-04T09:20:03Z"
}

Shopify로 보내기

POST/v1/products/{id}/push

연결된 Shopify 스토어에 상품을 등록해요: Shopify 상품 1개, 남긴 SKU마다 옵션 1개, 사진, 그리고 각 옵션의 재고는 Fulfilled by NinjaBuy 위치에 있어 주문이 저희에게 와요.

처음 보내면 초안으로 만들어져요. 상품명과 사진은 중국 마켓플레이스에서 온 것이니 구매자보다 먼저 읽어 본 뒤 Shopify에서 게시하세요.
다시 보내면 같은 Shopify 상품이 업데이트돼요: 가격과 재고가 다시 설정되고 뺀 옵션은 삭제돼요. 상태, 상품명, 설명, 사진은 새로 보내지 않는 한 Shopify에 둔 그대로 유지돼요.
재고는 판매자 수량이며 최대 100이에요. 저희는 주문이 들어올 때 구매하므로, Shopify가 품절로 표시하기 전까지 받을 수 있는 주문 수예요.
가격이 US$이므로 스토어가 US$로 판매해야 해요. 품절된 옵션은 건너뛰고 skipped[]에 표시돼요.

범위products:write

경로 매개변수

idstring필수: 상품 ID.

본문

shopstring: 연결된 스토어(예: acme-goods.myshopify.com). 여러 개를 연결한 경우에만 필요해요.
title, descriptionstring: 선택 사항. 보낼 때만 Shopify로 전송돼요.

오류

상태	유형	시점
409	no-linked-store	이 계정에 연결된 Shopify 스토어가 없거나, 여러 개인데 `shop`이 빠졌어요.
409	store-not-ready	스토어 접근이 만료되었거나 저희 위치가 아직 설정되지 않았어요. Shopify에서 NinjaBuy 앱을 한 번 여세요.
422	store-currency	스토어가 US$로 판매하지 않아요.
422	too-many-options	상품 옵션이 세 개를 넘어요. Shopify는 세 개까지 받아요.
422	unprocessable	모든 옵션이 품절이거나 Shopify가 필드를 거부했어요. detail에 그 내용이 전달돼요.

curl -X POST "https://www.ninjabuy.com/api/v1/products/prd_8f2k/push" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "shop": "acme-goods.myshopify.com" }'

Response 200

HTTP/2 200 OK

{
  "channel": "shopify",
  "shop": "acme-goods.myshopify.com",
  "external_id": "gid://shopify/Product/8812042",
  "status": "draft",
  "created": true,
  "variants": 5,
  "skipped": [{ "sku": "5187209555", "reason": "sold_out" }],
  "admin_url": "https://admin.shopify.com/store/acme-goods/products/8812042"
}

상품 삭제

DELETE/v1/products/{id}

동기화를 멈추고 채널 재고를 0으로 설정해요. Shopify 상품은 보관 처리할 수 있게 남아요. 이미 들어온 주문은 계속 배송돼요.

범위products:write

경로 매개변수

idstring필수: 상품 ID.

오류

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

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

Response 200

HTTP/2 200 OK

{ "id": "prd_8f2k", "deleted": true }