> ## Documentation Index > Fetch the complete documentation index at: https://docs.steppay.kr/llms.txt > Use this file to discover all available pages before exploring further. # 상품 가이드 > 스텝페이에서 상품은 판매할 아이템과 가격 플랜을 의미합니다. 상품의 주요 속성에는 상품 유형, 상품 상태, 상품 옵션이 있으며, 상품은 가격 플랜과 밀접하게 연결이 됩니다. 상품의 주요 속성에는 [상품 유형](#상품-유형), [상품 상태](#상품-상태), [상품 옵션](#상품-옵션)이 있으며, 상품은 가격 플랜과 밀접하게 연결이 됩니다. 상품은 가격 플랜과 1:N 관계이기 때문에 하나의 상품이 여러 개의 가격 플랜을 가질 수 있습니다.\ 예를들면 하나의 상품에 단건 가격 플랜, 구독 가격 플랜이 생성 될 수 있습니다. 또한 하나의 상품에 여러 구독 가격 플랜을 설정할 수 있습니다. 예를들어 주 단위 결제, 월 단위 결제, 연 단위 결제를 따로 설정할 수 있습니다.\ 상품과 가격 플랜은 API를 통해 각각 생성할 수는 있지만, 가격 플랜이 없는 상품을 주문할 수는 없습니다. **따라서 상품 생성 API를 통해 상품 생성 후 반드시 가격 플랜을 생성해야 합니다.** ## 연관 가이드 * [가격 플랜 가이드](/docs/04-0_가격플랜) ## 사전 준비 작업 * [Secret-Token 확인하기](/docs/01_인증#1-secret-token) ## 상품의 주요 속성 ### 상품 유형 스텝페이의 상품은 네 가지 유형의 상품을 지원합니다. | 타입 | 상태 | 설명 | | ---------- | ------------- | ----------------------------------------------------------------------------------------------------------- | | `BOX` | 배송 상품 | 실물로 판매되는 배송 상품입니다. 예를 들어, 책이나 가전 제품, 정기배송 상품이 이 유형에 해당합니다. | | `SOFEWARE` | 무형 상품, 서비스 포함 | SaaS 서비스나 무형의 상품입니다. 예를 들어, 온라인 콘텐츠 구독이 이 유형에 해당합니다. | | `INVOICE` | 청구서 상품 | 빠르게 발송하기 위한 인스턴트 상품으로 청구서 페이지에서 생성되는 상품 유형입니다. | | `BUNDLE` | 번들 상품 | 여러 개의 상품을 묶어서 번들로 판매할 수 있는 유형입니다.
번들 상품은 여러 개의 가격 플랜을 포함할 수 있으며, 번들에 포함된 가격 플랜이 아닌 최종 설정한 가격이 사용됩니다. | | `DRAFT` | 사전 승인 상품 | 몰인몰(앱스토어에서 몰인몰 구매 필요)에서 상위 가맹점의 승인을 대기중인 상품 유형입니다. | ### 상품 상태 스텝페이의 상품은 네 가지 유형의 상품 상태를 지원합니다. | 타입 | 상태 | 설명 | | ------------------ | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `SALE` | 판매중 | 판매중인 상품은 고객에게 노출되는 상품으로, 주문 API를 통해 주문이 가능하고 마이스토어 상품이 노출되는 상태 입니다. | | `OUT_OF_STOCK` | 품절 | 품절은 상품의 재고가 없는 상태입니다.
재고 부족 시 구독 가격플랜을 가진 상품의 정기 결제가 안될 수 있으므로, 주기적으로 재고 관리를 해야합니다.
또한, 조합형 옵션을 가진 상품에는 각각의 옵션도 재고를 관리 할 수 있습니다. | | `UNSOLD` | 미게시 | 미게시 상태의 상품은 마이스토어 상점에 노출되지 않는 상태입니다. | | `WAITING_APPROVAL` | 승인대기 | 몰인몰(앱스토어에서 몰인몰 구매 필요)에서 상위 가맹점의 승인을 대기중인 상태입니다. | ## 상품 생성 및 관리 ### 상품 옵션 스텝페이의 상품은 옵션 추가 기능을 제공합니다. 이 옵션은 사이즈, 색상, 패키지 유형 등 다양한 형태로 설정될 수 있습니다. 사용자는 상품을 생성할 때 이러한 옵션을 정의하고 추가할 수 있습니다. 옵션에는 두가지 타입이 있습니다. * `조합형 옵션` * 여러가지 옵션을 조합하여 여러 옵션을 생성할 수 있습니다. * 예를 들어, '사이즈'와 '색상'이라는 두 가지 옵션명이 있다면, 각각 '사이즈' 옵션값 (라지, 미디움)과 '색상' 옵션값 (빨강, 노랑)이 서로 조합되어 총 4가지의 제품 옵션을 생성합니다. 조합된 옵션에 대한 가격과 재고를 조합 옵션별로 관리 할 수 있습니다. * `독립형 옵션` * 개발 예정입니다. ### 무료 체험 설정 * 스텝페이의 구독 상품에는 무료 체험 여부를 적용할 수 있습니다. 무료 체험은은 일, 주, 월, 년 단위로 설정 할 수 있습니다. * V1 API를 통해 무료 체험을 적용하기 위해서는 `enabledDemo` 필드를 ‘true’로 지정 한 후 `demoPeriod`(체험 기간) `demoPeriodUnit`(체험 기간 단위)를 적절하게 입력합니다. ### 상품 재고 관리 스텝페이의 모든 상품은 재고를 설정하여 재고를 파악 할 수 있습니다. 서비스 상품의 경우에는 재고를 설정하지 않으면 자동으로 재고가 무제한으로 설정됩니다.\ 또한, 상품 옵션을 설정 한 경우에도 각각의 옵션에 대한 재고를 설정할 수 있습니다. 재고는 다음과 같이 반영됩니다. * 단건 가격 플랜에서 고객이 해당 상품을 주문 할 때 수량 만큼 차감 됩니다. * 구독 가격 플랜에서 첫 주문 시 수량 만큼 차감 후, 구독이 갱신될 때 동일 수량 만큼 자동 차감됩니다. * 구독 주기 이전에 주문 수량을 변경하면 구독이 갱신될 때 변경된 수량만큼 차감됩니다. * 상품 재고가 없을 시 상품 상태가 품절 상태로 변경됩니다. * 조합형 옵션을 설정한 경우 각각의 옵션 마다 재고를 지정 할 수 있습니다. 해당 옵션이 품절 되었을 때 해당 옵션의 상태가 품절 상태로 변하며, 다른 옵션의 재고가 있을 시 상품의 상태가 품절 상태로 변하지 않습니다. * V1 API에서 `quantity` 필드를 통해 상품의 재고를 설정할 수 있습니다. ‘null’값 입력 시 재고가 무한대로 설정됩니다. * 상품 옵션 또한 동일하게 해당 옵션의 `quantity` 필드를 통해 재고를 설정할 수 있습니다. ## 스텝페이 포탈 사용 예시 * \[포탈 → 상품관리 → 새상품 등록] 메뉴로 이동합니다. * 상품의 기본 정보를 입력하고 저장합니다. 포탈에서 상품을 생성할 때 [가격 플랜](/docs/04-0_가격플랜)과 함께 생성하지 않으면 임시저장 상태가 됩니다. > V1 API를 통해 상품을 생성하면 가격 플랜이 상품과 함께 생성되지 않기 때문에 포탈에서 오류가 발생합니다.\ > **V1 API를 통해 상품을 생성하는 경우에는 반드시 가격 플랜도 함께 생성해야 합니다.** ![create\_product.png](https://docs-image-translator-steppay.vercel.app/api/localize?dir=03_product\&name=create_product.png) ## API 사용 예시 ### 상품 생성 * Request ```bash theme={null} curl --request POST \ --url https://api.steppay.kr/api/v1/products \ --header 'Secret-Token: {Secret-Token}' \ --header 'accept: */*' \ --header 'content-type: application/json' \ --data ' { "type": "SOFTWARE", "status": "SALE", "enabledDemo": false, "demoPeriodUnit": "DAY", "useCombination": true, "name": "TEST_PRODUCT", } ' ``` * Response ```json theme={null} { "id": 6878, "code": "product_L6ySWX1F2", "type": "SOFTWARE", "status": "SALE", "name": "TEST_PRODUCT", "subTitle": null, "featuredImageUrl": "", "imageUrls": [], "description": "", "summary": null, "reasonOfReject": null, "sku": null, "quantity": null, "combinedProducts": [], "optionGroups": [], "useCombination": true, "optionCombinations": [], "prices": [], "createdAt": "2023-06-19T01:54:14.656027", "modifiedAt": "2023-06-19T01:54:14.656027", "enabledDemo": false, "demoPeriod": 7, "demoPeriodUnit": "DAY", "categories": [], "vendorUuid": "{Vendor UUID}", "productOrder": 0, "isOnetimePurchasable": false, "eventBadge": [], "notice": null, "useWidget": { "useDemo": false, "useEventBadge": false, "useOnetimePurchasable": false, "useNotice": false }, "groupId": null, "countrySetting": null } ``` ### 상품 생성 - 옵션 추가 상품의 옵션을 추가하기 위해 우선 상품 옵션을 정의해야 합니다. 각 옵션은 이름과 값으로 구성됩니다. 예를 들면, 색상 옵션을 추가하는 경우 옵션명은 "색상"이고 값은 "블랙", "화이트" 등이 될 수 있습니다. * Request ```bash theme={null} curl --request POST \ --url https://api.steppay.kr/api/v1/products \ --header 'Secret-Token: {Secret-Token}' \ --header 'accept: */*' \ --header 'content-type: application/json' \ --data ' { "type": "BOX", "status": "SALE", "enabledDemo": false, "demoPeriodUnit": "DAY", "optionGroups": [ { "type": "SELECT", "options": [ { "name": "BLACK", "quantity": 10, "addQuantity": 1000 }, { "name": "WHITE", "addQuantity": 10, "price": 2000 } ], "name": "COLOR } ], "useCombination": true, "name": "OPTION_PRODUCT", } ' ``` ### 상품 목록 조회 * Request ```bash theme={null} curl --request GET \ --url https://api.steppay.kr/api/v1/products \ --header 'Secret-Token: {Secret-Token}' \ --header 'accept: */*' ``` * Response ```json theme={null} { "content": [ { "id": 6879, "code": "product_VQyHoGO8c", "type": "SOFTWARE", "status": "SALE", "name": "[API]TEST_PRODUCT", "quantity": null, "featuredImageUrl": "", "prices": [], "createdAt": "2023-06-19T01:55:11", "modifiedAt": "2023-06-19T01:55:11", "description": "", "categories": [], "vendorUuid": "{Vendor UUID}", "enabledDemo": false, "isOnetimePurchasable": null, "productOrder": 0, "countrySetting": null } ... ] } ``` ### 상품 상세 조회 * Request ```bash theme={null} curl --request GET \ --url https://api.steppay.kr/api/v1/products/product_VQyHoGO8c \ --header 'Secret-Token: {Secret-Token}' \ --header 'accept: */*' ``` * Response ```json theme={null} { "id": 6879, "code": "product_VQyHoGO8c", "type": "SOFTWARE", "status": "SALE", "name": "[API]TEST_PRODUCT", "subTitle": null, "featuredImageUrl": "", "imageUrls": [], "description": "", "summary": null, "reasonOfReject": null, "sku": null, "quantity": null, "combinedProducts": [], "optionGroups": [], "useCombination": true, "optionCombinations": [], "prices": [], "createdAt": "2023-06-19T01:55:11", "modifiedAt": "2023-06-19T01:55:11", "enabledDemo": false, "demoPeriod": 7, "demoPeriodUnit": "DAY", "categories": [], "vendorUuid": "{Vendor UUID}", "productOrder": 0, "isOnetimePurchasable": false, "eventBadge": [], "notice": null, "useWidget": { "useDemo": false, "useEventBadge": false, "useOnetimePurchasable": false, "useNotice": false }, "groupId": null, "countrySetting": null } ```