프로모션

쿠폰과 캠페인, 캠페인 성과를 조회합니다.

캠페인 목록 조회

GET

https://api.superplace.so

/promo/v1/campaigns

OAuth 2.0

마케팅 캠페인을 상태와 함께 돌려줍니다. 캠페인마다 방식(mode: 일회성 one_off, 자동 automatic), 동작(action: coupon, message, both), 대상 인원, 성공·실패 건수가 있습니다.

MCP 도구: promo_get_campaigns

캠페인 목록 조회 › query Parameters

page

integer · min: 1

페이지 번호입니다. 1부터 시작합니다.

perPage

integer · min: 1 · max: 200

한 페이지에 담을 건수입니다. 생략하면 서버 기본값이 적용됩니다.

filter

string

조건 JSON입니다. status, mode(one_off 또는 automatic), phone(수신자 전화번호), placeId를 쓸 수 있습니다.

start

integer · min: 0

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

end

integer · min: 0

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

캠페인 목록 조회 › Responses

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

success

boolean · enum

Enum values:

object[]

total

integer · int64

GET/promo/v1/campaigns

curl https://api.superplace.so/promo/v1/campaigns \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "success": true,
  "data": [
    {
      "id": "01932b1e-4c3a-7f10-9a2b-5d6e7f800161",
      "placeId": "01932b1e-4c3a-7f10-9a2b-5d6e7f800010",
      "name": "휴면 손님 재방문 쿠폰",
      "mode": "one_off",
      "action": "both",
      "couponDefId": "01932b1e-4c3a-7f10-9a2b-5d6e7f800151",
      "messageBody": "오랜만이에요. 쿠폰을 보내드립니다.",
      "targetView": "dormant",
      "targetLabel": "휴면 손님",
      "status": "completed",
      "targetCount": 40,
      "excludedCount": 2,
      "successCount": 38,
      "failureCount": 0,
      "createdBy": "01932b1e-4c3a-7f10-9a2b-5d6e7f800001",
      "createdAt": "2026-10-25T00:00:00Z",
      "updatedAt": "2026-10-25T01:00:00Z"
    }
  ],
  "total": 1
}

json

application/json

캠페인 성과 조회

GET

https://api.superplace.so

/promo/v1/campaigns/{id}/performance

OAuth 2.0

캠페인의 결과를 돌려줍니다. funnel에는 대상 인원부터 쿠폰 발급, 메시지 발송·도착, 쿠폰 사용까지 단계별 건수가, revenue에는 캠페인 쿠폰이 적용된 주문의 합계가 담깁니다.

MCP 도구: promo_get_campaigns_id_performance

캠페인 성과 조회 › path Parameters

id

string · uuid · required

캠페인 ID입니다. 캠페인 목록의 id입니다.

캠페인 성과 조회 › Responses

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

success

boolean · enum · required

Enum values:

object · required

GET/promo/v1/campaigns/{id}/performance

curl https://api.superplace.so/promo/v1/campaigns/:id/performance \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "success": true,
  "data": {
    "generatedAt": "2026-11-03T00:00:00Z",
    "couponApplicable": true,
    "messageApplicable": true,
    "funnel": {
      "candidates": 42,
      "eligible": 40,
      "excluded": 2,
      "succeeded": 38,
      "failed": 0,
      "couponIssued": 38,
      "messageAccepted": 38,
      "messageSent": 38,
      "messageDelivered": 37,
      "messageFailed": 1,
      "couponRedeemed": 9
    },
    "revenue": {
      "attributedOrders": 9,
      "orderTotal": 180000,
      "discount": 27000,
      "afterDiscount": 153000
    }
  }
}

json

application/json

쿠폰 목록 조회

GET

https://api.superplace.so

/promo/v1/coupon-defs

OAuth 2.0

매장이 제공하는 쿠폰과 사용 가능 여부를 돌려줍니다. 쿠폰마다 혜택(benefit: amount는 금액 할인, percent는 비율 할인, item은 증정), 최소 주문 금액, 유효 기간, 인당 발급 한도, 지금까지 발급한 수(issued)가 있습니다.

MCP 도구: promo_get_coupon_defs

쿠폰 목록 조회 › query Parameters

filter

string

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

start

integer · min: 0

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

end

integer · min: 0

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

쿠폰 목록 조회 › Responses

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

success

boolean

data

total

integer

상품 직원