상품

판매 상품, 상품별 판매 실적, 재고를 조회합니다.

재고 조회

GET

https://api.superplace.so

/retail/v1/inventory

OAuth 2.0

상품별 재고 수량을 돌려줍니다. 재고를 관리하는 상품(tracked가 true)만 quantity가 담깁니다. 판매 중 여부(active)와 품절 여부(soldOut)도 함께 확인할 수 있습니다.

필요 권한: 상품·재고·할인 등 판매 설정 관리(retail:catalog:write)

MCP 도구: retail_get_inventory

재고 조회 › query Parameters

start

integer · min: 0

범위 조회의 시작 위치입니다. end와 함께 보내며, page·perPage를 함께 보내면 무시됩니다.

end

integer · min: 0

범위 조회의 끝 위치입니다. 이 값은 포함되지 않습니다. 한 번에 200건까지 조회할 수 있습니다.

filter

string

조직 계정으로 연결한 경우 매장 하나를 고르는 JSON입니다. 예: {"placeId":"01932b1e-4c3a-7f10-9a2b-5d6e7f800010"}. 매장 계정에서는 생략합니다.

재고 조회 › Responses

요청이 처리됐습니다. 결과는 data에 담겨 옵니다.

success

boolean

data

total

integer

상품 목록 조회

GET

https://api.superplace.so

/retail/v1/products

OAuth 2.0

매장이 판매하는 상품을 가격, 분류, 판매 가능 여부와 함께 돌려줍니다. 상품마다 가격(price), 정가(regularPrice, 할인 중일 때만), 판매 중 여부(active), 품절 여부(soldOut), 손님에게 보이는 여부(customerVisible)가 있습니다.

MCP 도구: retail_get_products

상품 목록 조회 › query Parameters

filter

string

조직 계정으로 연결한 경우 매장 하나를 고르는 JSON입니다. 예: {"placeId":"01932b1e-4c3a-7f10-9a2b-5d6e7f800010"}. 매장 계정에서는 생략합니다.

상품 목록 조회 › Responses

요청이 처리됐습니다. 결과는 data에 담겨 옵니다.

success

boolean

data

total

integer

상품별 판매 조회

GET

https://api.superplace.so

/retail/v1/reports/product-sales

OAuth 2.0

기간의 상품을 판매 수량과 금액 순으로 돌려줍니다. 결제가 완료된 주문만 집계됩니다. 금액은 환불 전 판매액이고, 부분 환불은 상품별로 나누어 반영되지 않습니다.

필요 권한: 매출 합계 보기(pay:sales:read)

MCP 도구: retail_get_reports_product_sales

상품별 판매 조회 › query Parameters

from

string · date

시작 날짜입니다. YYYY-MM-DD 형식입니다.

to

string · date

끝 날짜입니다. YYYY-MM-DD 형식입니다.

tz

string

날짜를 나누는 시간대입니다. 예: Asia/Seoul

filter

string

조직 계정으로 연결한 경우 매장 하나를 고르는 JSON입니다. 예: {"placeId":"01932b1e-4c3a-7f10-9a2b-5d6e7f800010"}. 매장 계정에서는 생략합니다.

상품별 판매 조회 › Responses

요청이 처리됐습니다. 결과는 data에 담겨 옵니다.

success

boolean · enum · required

Enum values:

object[] · required

total

integer · required

매출 프로모션