토스쇼핑 API 개발/연동에 대한 질문이 있다면 남겨주세요. 토스쇼핑 담당자와 질의응답할 수 있어요.
토스쇼핑 개발자센터
Ctrlk
API 개발/연동 문의하기
For the complete documentation index, see llms.txt. This page is also available as Markdown.

상품-SKU 연결 & 재고 동기화

SKU 데이터 동기화

put

풀필먼트 상품(SKU)의 변경 사항을 토스쇼핑에 증분 동기화합니다.

  • 한 번의 요청으로 최대 200건까지 전송할 수 있습니다

Header parameters
X-Toss-Shopping-Connect-Api-KeystringRequired

토스쇼핑에서 발급한 연동 API Key

X-Toss-Shopping-Connect-Tx-IdstringRequired

요청별 고유 거래 식별값 (ASCII, 최대 64 byte)

Body
Responses
200

모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)

application/json
resultTypestring · enumOptional

응답 결과 타입

Possible values:
put/api/v3/shopping-fep/fulfillment/skus
PUT /api/v3/shopping-fep/fulfillment/skus HTTP/1.1
Host: shopping-fep.toss.im
X-Toss-Shopping-Connect-Api-Key: text
X-Toss-Shopping-Connect-Tx-Id: text
Content-Type: application/json
Accept: */*
Content-Length: 373

{
  "skus": [
    {
      "skuKey": "text",
      "skuName": "text",
      "fulfillmentAccountKey": "text",
      "barcode": "text",
      "widthMm": 1,
      "depthMm": 1,
      "heightMm": 1,
      "skuTypeCode": "MAIN_PRODUCT",
      "isUseByDateManaged": true,
      "isLotManaged": true,
      "boxTypeCode": "FULFILLMENT_BOX",
      "storageConditionCode": "AMBIENT",
      "cushioningPackageTypeCode": "NONE",
      "createdAt": "2026-04-01T10:00:00",
      "updatedAt": "2026-04-02T15:30:00"
    }
  ]
}
200

모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)

{
  "resultType": "SUCCESS",
  "error": {
    "errorCode": "INVALID_REQUEST",
    "reason": "text"
  },
  "success": {
    "success": true
  }
}

API 호출은 요청당 최대 200건, 초당 최대 10건(TPS)을 기준으로 운영하는 것을 기본으로 합니다.

요청 예시

Request
{
  "skus": [
    {
      "skuKey": "SKU-001",
      "skuName": "블랙 / L",
      "fulfillmentAccountKey": "3239",
      "barcode": "8801234567890",
      "widthMm": 120,
      "depthMm": 280,
      "heightMm": 40,
      "skuTypeCode": "MAIN_PRODUCT",
      "isUseByDateManaged": false,
      "isLotManaged": false,
      "isActive": true,
      "boxTypeCode": "FULFILLMENT_BOX",
      "cushioningPackageTypeCode": "BASIC",
      "storageConditionCode": "AMBIENT",
      "createdAt": "2026-04-01T10:00:00",
      "updatedAt": "2026-04-01T10:00:00"
    }
  ]
}

응답 예시

SKU 재고 변경

put

풀필먼트 SKU의 최신 재고 수량을 토스쇼핑에 증분 동기화합니다.

  • 한 번의 요청으로 최대 200건까지 전송할 수 있습니다

Header parameters
X-Toss-Shopping-Connect-Api-KeystringRequired

토스쇼핑에서 발급한 연동 API Key

X-Toss-Shopping-Connect-Tx-IdstringRequired

요청별 고유 거래 식별값 (ASCII, 최대 64 byte)

Body
Responses
200

모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)

application/json
resultTypestring · enumOptional

응답 결과 타입

Possible values:
put/api/v3/shopping-fep/fulfillment/skus/quantity
PUT /api/v3/shopping-fep/fulfillment/skus/quantity HTTP/1.1
Host: shopping-fep.toss.im
X-Toss-Shopping-Connect-Api-Key: text
X-Toss-Shopping-Connect-Tx-Id: text
Content-Type: application/json
Accept: */*
Content-Length: 200

{
  "skuStocks": [
    {
      "skuKey": "text",
      "fulfillmentAccountKey": "text",
      "fulfillmentCenterKey": "text",
      "fulfillmentCenterName": "text",
      "availableQuantity": 1,
      "onHandQuantity": 1,
      "updatedAt": "2026-04-02T15:30:00"
    }
  ]
}
200

모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)

{
  "resultType": "SUCCESS",
  "error": {
    "errorCode": "INVALID_REQUEST",
    "reason": "text"
  },
  "success": {
    "success": true
  }
}

delta(증분)가 아니라 절대값이에요. availableQuantity·onHandQuantity는 증감분이 아니라 현재 보유 재고 전체 수량을 보내요. 예를 들어 재고 100개 중 2개가 팔렸으면 98을 보내요(-2가 아니에요). 계약 등록 초기에 보유 재고를 한 번 올린 뒤에도, 운영 중에는 항상 같은 방식(현재 절대값)으로 보내야 해요.

SKU 미등록 상태로 재고 이벤트가 먼저 도착하는 경우(race): 재고 동기화 이벤트가 SKU 메타데이터 등록보다 먼저 도달하면 매핑되지 않은 재고가 될 수 있어요. 순서를 ① PUT /skus(SKU 먼저) → ② PUT /skus/quantity(재고 나중) 로 보장해주세요. 만약 재고가 먼저 도착하는 구조가 불가피하다면, 동일 skuKey에 대해 SKU 등록 직후 재고를 한 번 더 보내 정합성을 맞춰주세요. 일단위 SFTP 전체 FEED가 그 다음 정합성을 보정해줘요.

요청 예시

응답 예시

토스쇼핑 SKU 맵핑 정보 조회 (디버깅용)

post

SKU와 토스쇼핑 아이템(옵션)의 맵핑 정보를 조회합니다.

  • 데이터를 변경하지 않는 조회(디버깅 / CS 대응) 용도입니다

  • 한 번의 요청으로 최대 100건까지 조회할 수 있습니다

Header parameters
X-Toss-Shopping-Connect-Api-KeystringRequired

토스쇼핑에서 발급한 연동 API Key

X-Toss-Shopping-Connect-Tx-IdstringRequired

요청별 고유 거래 식별값 (ASCII, 최대 64 byte)

Body
Responses
200

모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)

application/json
resultTypestring · enumOptional

응답 결과 타입

Possible values:
post/api/v3/shopping-fep/fulfillment/skus/mappings
POST /api/v3/shopping-fep/fulfillment/skus/mappings HTTP/1.1
Host: shopping-fep.toss.im
X-Toss-Shopping-Connect-Api-Key: text
X-Toss-Shopping-Connect-Tx-Id: text
Content-Type: application/json
Accept: */*
Content-Length: 59

{
  "skus": [
    {
      "skuKey": "text",
      "fulfillmentAccountKey": "text"
    }
  ]
}
200

모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)

{
  "resultType": "SUCCESS",
  "error": {
    "errorCode": "INVALID_REQUEST",
    "reason": "text"
  },
  "success": {
    "mappings": [
      {
        "skuKey": "text",
        "fulfillmentAccountKey": "text",
        "items": [
          {
            "id": 1,
            "productName": "text",
            "name": "text",
            "quantityPerItem": 1
          }
        ]
      }
    ]
  }
}

SKU 동기화 직후 매핑이 바로 완료되지 않을 수 있어요. 매핑이 아직 안 된 SKU는 isMapped=false로 내려오고, productItemId가 없을 수 있어요. 주문 응답의 item.skus가 비어 있다면 이 API로 매핑 상태를 먼저 확인해주세요.

Previous계정·물류센터 등록
NextSKU, 재고, 셀러 동기화(SFTP)

Last updated

Was this helpful?