> For the complete documentation index, see [llms.txt](https://shopping-docs.toss.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://shopping-docs.toss.im/connect/fulfillment-api/sku-and.md). # 상품-SKU 연결 & 재고 동기화 ## SKU 데이터 동기화 > 풀필먼트 상품(SKU)의 변경 사항을 토스쇼핑에 증분 동기화합니다.\ > \ > \- 한 번의 요청으로 최대 200건까지 전송할 수 있습니다 ```json {"openapi":"3.0.1","info":{"title":"ShoppingFep API","version":"snapshot"},"servers":[{"url":"https://shopping-fep.toss.im"}],"security":[],"paths":{"/api/v3/shopping-fep/fulfillment/skus":{"put":{"tags":["풀필먼트 SKU 관리"],"summary":"SKU 데이터 동기화","description":"풀필먼트 상품(SKU)의 변경 사항을 토스쇼핑에 증분 동기화합니다.\n\n- 한 번의 요청으로 최대 200건까지 전송할 수 있습니다","operationId":"syncSkus","parameters":[{"name":"X-Toss-Shopping-Connect-Api-Key","in":"header","description":"토스쇼핑에서 발급한 연동 API Key","required":true,"schema":{"type":"string"}},{"name":"X-Toss-Shopping-Connect-Tx-Id","in":"header","description":"요청별 고유 거래 식별값 (ASCII, 최대 64 byte)","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"required":["skus"],"type":"object","properties":{"skus":{"maxItems":200,"minItems":0,"type":"array","description":"동기화 대상 SKU 목록 (최대 200개)","items":{"required":["createdAt","fulfillmentAccountKey","skuKey","skuName","updatedAt"],"type":"object","properties":{"skuKey":{"maxLength":64,"minLength":0,"type":"string","description":"풀필먼트 고객사 상품코드 (SKU 식별자, 최대 64자)"},"skuName":{"maxLength":300,"minLength":0,"type":"string","description":"풀필먼트 고객사 상품명 (SKU 이름, 최대 300자)"},"fulfillmentAccountKey":{"maxLength":64,"minLength":0,"type":"string","description":"풀필먼트 계정(고객사) 식별값"},"barcode":{"maxLength":100,"minLength":0,"type":"string","description":"바코드 (최대 100자)"},"widthMm":{"minimum":0,"type":"integer","description":"상품 가로 길이 (unsigned int, 단위 mm)","format":"int32"},"depthMm":{"minimum":0,"type":"integer","description":"상품 세로 길이 (unsigned int, 단위 mm)","format":"int32"},"heightMm":{"minimum":0,"type":"integer","description":"상품 높이 (unsigned int, 단위 mm)","format":"int32"},"skuTypeCode":{"type":"string","description":"상품 유형 코드","enum":["MAIN_PRODUCT","GIFT","MATERIAL"]},"isUseByDateManaged":{"type":"boolean","description":"소비기한 관리 여부"},"isLotManaged":{"type":"boolean","description":"로트번호 관리 여부"},"boxTypeCode":{"type":"string","description":"출고 박스 타입 코드","enum":["FULFILLMENT_BOX","SELLER_BOX","FULFILLMENT_POLYBAG","SELLER_POLYBAG","FULFILLMENT_STYROFOAM"]},"storageConditionCode":{"type":"string","description":"보관온도 코드","enum":["AMBIENT","CHILLED","FROZEN"]},"cushioningPackageTypeCode":{"type":"string","description":"완충재 포장 타입 코드","enum":["NONE","BASIC","EXTRA"]},"createdAt":{"type":"string","description":"풀필먼트 고객사 상품 생성 일시"},"updatedAt":{"type":"string","description":"풀필먼트 고객사 상품 수정 일시"}},"description":"동기화 대상 SKU 목록 (최대 200개)"}}}}}},"required":true},"responses":{"200":{"description":"모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)","content":{"application/json":{"schema":{"type":"object","properties":{"resultType":{"type":"string","description":"응답 결과 타입","enum":["SUCCESS","FAIL"]},"error":{"type":"object","properties":{"errorCode":{"type":"string","description":"에러 코드","enum":["INVALID_REQUEST","INVALID_IP","SERVICE_ERROR","INTERNAL_SERVER_ERROR"]},"reason":{"type":"string","description":"에러 사유"}},"description":"에러 응답, resultType FAIL 시 제공"},"success":{"required":["success"],"type":"object","properties":{"success":{"type":"boolean","description":"성공 여부"}}}}}}}}}}}}} ``` {% hint style="info" %} API 호출은 요청당 **최대 200건, 초당 최대 10건(TPS)**을 기준으로 운영하는 것을 기본으로 합니다. {% endhint %} **요청 예시** {% code title="Request" %} ```json { "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" } ] } ``` {% endcode %} **응답 예시** {% code title="Response" %} ```json { "resultType": "SUCCESS", "success": true, "error": null } ``` {% endcode %} ## SKU 재고 변경 > 풀필먼트 SKU의 최신 재고 수량을 토스쇼핑에 증분 동기화합니다.\ > \ > \- 한 번의 요청으로 최대 200건까지 전송할 수 있습니다 ```json {"openapi":"3.0.1","info":{"title":"ShoppingFep API","version":"snapshot"},"servers":[{"url":"https://shopping-fep.toss.im"}],"security":[],"paths":{"/api/v3/shopping-fep/fulfillment/skus/quantity":{"put":{"tags":["풀필먼트 SKU 관리"],"summary":"SKU 재고 변경","description":"풀필먼트 SKU의 최신 재고 수량을 토스쇼핑에 증분 동기화합니다.\n\n- 한 번의 요청으로 최대 200건까지 전송할 수 있습니다","operationId":"syncSkuQuantity","parameters":[{"name":"X-Toss-Shopping-Connect-Api-Key","in":"header","description":"토스쇼핑에서 발급한 연동 API Key","required":true,"schema":{"type":"string"}},{"name":"X-Toss-Shopping-Connect-Tx-Id","in":"header","description":"요청별 고유 거래 식별값 (ASCII, 최대 64 byte)","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"required":["skuStocks"],"type":"object","properties":{"skuStocks":{"maxItems":200,"minItems":0,"type":"array","description":"동기화 대상 SKU 재고 목록 (최대 200개)","items":{"required":["availableQuantity","fulfillmentAccountKey","fulfillmentCenterKey","fulfillmentCenterName","onHandQuantity","skuKey","updatedAt"],"type":"object","properties":{"skuKey":{"maxLength":64,"minLength":0,"type":"string","description":"풀필먼트 고객사 상품코드 (SKU 식별자)"},"fulfillmentAccountKey":{"maxLength":64,"minLength":0,"type":"string","description":"풀필먼트 계정(고객사) 식별값"},"fulfillmentCenterKey":{"maxLength":128,"minLength":0,"type":"string","description":"풀필먼트 센터 식별값"},"fulfillmentCenterName":{"maxLength":128,"minLength":0,"type":"string","description":"풀필먼트 센터 이름"},"availableQuantity":{"minimum":0,"type":"integer","description":"풀필먼트 센터 가용 재고 (현재 상태)","format":"int64"},"onHandQuantity":{"minimum":0,"type":"integer","description":"풀필먼트 센터 실 재고 (현재 상태)","format":"int64"},"updatedAt":{"type":"string","description":"변경 일시"}},"description":"동기화 대상 SKU 재고 목록 (최대 200개)"}}}}}},"required":true},"responses":{"200":{"description":"모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)","content":{"application/json":{"schema":{"type":"object","properties":{"resultType":{"type":"string","description":"응답 결과 타입","enum":["SUCCESS","FAIL"]},"error":{"type":"object","properties":{"errorCode":{"type":"string","description":"에러 코드","enum":["INVALID_REQUEST","INVALID_IP","SERVICE_ERROR","INTERNAL_SERVER_ERROR"]},"reason":{"type":"string","description":"에러 사유"}},"description":"에러 응답, resultType FAIL 시 제공"},"success":{"required":["success"],"type":"object","properties":{"success":{"type":"boolean","description":"성공 여부"}}}}}}}}}}}}} ``` {% hint style="warning" %} **delta(증분)가 아니라 절대값이에요.** `availableQuantity`·`onHandQuantity`는 증감분이 아니라 **현재 보유 재고 전체 수량**을 보내요. 예를 들어 재고 100개 중 2개가 팔렸으면 `98`을 보내요(`-2`가 아니에요). 계약 등록 초기에 보유 재고를 한 번 올린 뒤에도, 운영 중에는 항상 같은 방식(현재 절대값)으로 보내야 해요. {% endhint %} {% hint style="info" %} **SKU 미등록 상태로 재고 이벤트가 먼저 도착하는 경우(race)**: 재고 동기화 이벤트가 SKU 메타데이터 등록보다 먼저 도달하면 매핑되지 않은 재고가 될 수 있어요. 순서를 **① `PUT /skus`(SKU 먼저) → ② `PUT /skus/quantity`(재고 나중)** 로 보장해주세요. 만약 재고가 먼저 도착하는 구조가 불가피하다면, 동일 `skuKey`에 대해 SKU 등록 직후 재고를 한 번 더 보내 정합성을 맞춰주세요. 일단위 SFTP 전체 FEED가 그 다음 정합성을 보정해줘요. {% endhint %} **요청 예시** {% code title="Request" %} ```json { "stocks": [ { "skuKey": "SKU-001", "fulfillmentAccountKey": "3239", "fulfillmentCenterKey": "YI01", "fulfillmentCenterName": "용인01", "availableQuantity": 75, "onHandQuantity": 80, "updatedAt": "2026-04-01T10:00:00" } ] } ``` {% endcode %} **응답 예시** {% code title="Response" %} ```json { "resultType": "SUCCESS", "success": true, "error": null } ``` {% endcode %} ## 토스쇼핑 SKU 맵핑 정보 조회 (디버깅용) > SKU와 토스쇼핑 아이템(옵션)의 맵핑 정보를 조회합니다.\ > \ > \- 데이터를 변경하지 않는 조회(디버깅 / CS 대응) 용도입니다\ > \ > \- 한 번의 요청으로 최대 100건까지 조회할 수 있습니다 ```json {"openapi":"3.0.1","info":{"title":"ShoppingFep API","version":"snapshot"},"servers":[{"url":"https://shopping-fep.toss.im"}],"security":[],"paths":{"/api/v3/shopping-fep/fulfillment/skus/mappings":{"post":{"tags":["풀필먼트 SKU 관리"],"summary":"토스쇼핑 SKU 맵핑 정보 조회 (디버깅용)","description":"SKU와 토스쇼핑 아이템(옵션)의 맵핑 정보를 조회합니다.\n\n- 데이터를 변경하지 않는 조회(디버깅 / CS 대응) 용도입니다\n\n- 한 번의 요청으로 최대 100건까지 조회할 수 있습니다","operationId":"getSkuMappings","parameters":[{"name":"X-Toss-Shopping-Connect-Api-Key","in":"header","description":"토스쇼핑에서 발급한 연동 API Key","required":true,"schema":{"type":"string"}},{"name":"X-Toss-Shopping-Connect-Tx-Id","in":"header","description":"요청별 고유 거래 식별값 (ASCII, 최대 64 byte)","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"required":["skus"],"type":"object","properties":{"skus":{"maxItems":100,"minItems":0,"type":"array","description":"조회 대상 SKU 목록","items":{"required":["fulfillmentAccountKey","skuKey"],"type":"object","properties":{"skuKey":{"maxLength":64,"minLength":0,"type":"string","description":"풀필먼트 고객사 상품코드 (SKU 식별자)"},"fulfillmentAccountKey":{"maxLength":64,"minLength":0,"type":"string","description":"풀필먼트 계정(고객사) 식별값"}},"description":"조회 대상 SKU 목록"}}}}}},"required":true},"responses":{"200":{"description":"모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)","content":{"application/json":{"schema":{"type":"object","properties":{"resultType":{"type":"string","description":"응답 결과 타입","enum":["SUCCESS","FAIL"]},"error":{"type":"object","properties":{"errorCode":{"type":"string","description":"에러 코드","enum":["INVALID_REQUEST","INVALID_IP","SERVICE_ERROR","INTERNAL_SERVER_ERROR"]},"reason":{"type":"string","description":"에러 사유"}},"description":"에러 응답, resultType FAIL 시 제공"},"success":{"required":["mappings"],"type":"object","properties":{"mappings":{"type":"array","description":"맵핑 목록","items":{"required":["fulfillmentAccountKey","items","skuKey"],"type":"object","properties":{"skuKey":{"type":"string","description":"풀필먼트 고객사 상품코드 (SKU 식별자)"},"fulfillmentAccountKey":{"type":"string","description":"풀필먼트 계정(고객사) 식별값"},"items":{"type":"array","description":"SKU에 맵핑된 토스쇼핑 아이템(옵션) 목록","items":{"required":["id","name","productName","quantityPerItem"],"type":"object","properties":{"id":{"type":"integer","description":"토스쇼핑 아이템 ID","format":"int64"},"productName":{"type":"string","description":"토스쇼핑 상품명"},"name":{"type":"string","description":"옵션명"},"quantityPerItem":{"type":"integer","description":"재고 배수 (item 1개당 재고 차감 수량)","format":"int32"}},"description":"SKU에 맵핑된 토스쇼핑 아이템(옵션) 목록"}}},"description":"맵핑 목록"}}}}}}}}}}}}}} ``` {% hint style="info" %} SKU 동기화 직후 매핑이 바로 완료되지 않을 수 있어요. 매핑이 아직 안 된 SKU는 `isMapped=false`로 내려오고, `productItemId`가 없을 수 있어요. 주문 응답의 `item.skus`가 비어 있다면 이 API로 매핑 상태를 먼저 확인해주세요. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://shopping-docs.toss.im/connect/fulfillment-api/sku-and.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.