쿠폰

고객이 결제 시 적용할 수 있는 할인 코드를 생성하세요. 퍼센트 또는 고정 금액, 기간 제한 또는 사용 횟수 제한, 일회성 또는 반복 적용이 가능합니다.

쿠폰은 builder의 Commerce panel > Products > Coupons 하위 탭에서 관리하거나, SDK의 proyecta.commerce.coupons를 통해 관리할 수 있습니다.

쿠폰 구성 요소

필드	설명
code	고객이 결제 시 입력하는 프로모션 코드 (예: LAUNCH20)
percent_off 또는 amount_off	둘 중 하나만 사용 가능합니다. 퍼센트는 1~100, 금액은 가장 작은 통화 단위(센트) 기준입니다.
currency	amount_off 할인에 필수입니다 (ISO 세 자리 코드). 생성 시 입력되어 Stripe로 전달되지만, 이후 API에서는 저장되거나 반환되지 않습니다.
duration	once (첫 번째 결제에만 적용), repeating (duration_in_months 기간 동안 적용), 또는 forever
duration_in_months	duration이 repeating일 때 필수입니다
max_redemptions	전체 고객에 걸친 총 사용 횟수 한도
redeem_by	해당 날짜 이후 쿠폰이 작동을 중지하는 만료일
name	고객에게 표시되는 이름
active	삭제하지 않고 활성화/비활성화를 전환하는 토글

쿠폰 생성

Coupons 하위 탭에서 Add coupon을 클릭하고 필드를 작성하세요. 또는 SDK를 통해 생성할 수 있습니다:

// 20% off forever
await proyecta.commerce.coupons.create({
    code: 'LAUNCH20',
    name: 'Launch discount',
    percent_off: 20,
    duration: 'forever',
});

// $10 off, single use, expires in 30 days
await proyecta.commerce.coupons.create({
    code: 'WELCOME10',
    amount_off: 1000,
    currency: 'USD',
    duration: 'once',
    max_redemptions: 1,
    redeem_by: new Date(Date.now() + 30 * 86400 * 1000).toISOString(),
});

// 50% off for the first 3 months of a subscription
await proyecta.commerce.coupons.create({
    code: 'EARLY3',
    percent_off: 50,
    duration: 'repeating',
    duration_in_months: 3,
});

결제 시 쿠폰 적용

고객은 Stripe 호스팅 결제 페이지에서 직접 쿠폰 코드를 입력할 수 있습니다 — 프로모션 코드 입력란이 자동으로 표시됩니다.

await proyecta.commerce.checkout({
    customer_id,
    line_items: [{ variant_id: 'var_pro_monthly' }],
    success_url: 'https://myapp.com/welcome',
});

결제 호출 시 쿠폰 코드를 프로그래밍 방식으로 전달하는 기능은 아직 지원되지 않습니다.

목록 조회, 업데이트, 비활성화

// Browse every coupon (only lists coupons created via the SDK)
const { data } = await proyecta.commerce.coupons.list();
for (const coupon of data.data) {
    console.log(coupon.code, coupon.times_redeemed, '/', coupon.max_redemptions);
}
// Paginate using data.has_more and the starting_after query parameter if needed.

// Disable a coupon (without deleting)
await proyecta.commerce.coupons.update({ couponId: 'coupon_123', active: false });

참고: coupons.list()는 SDK를 통해 생성된 쿠폰만 반환합니다. builder 대시보드에서 생성된 쿠폰은 coupons.list()를 통해 확인할 수 없습니다.

참고 사항 및 제한

• 코드와 할인 금액은 변경할 수 없습니다. 표시 name을 업데이트하거나 active를 토글하는 것은 가능하지만, percent_off, amount_off, 또는 code 자체는 수정할 수 없습니다. 다른 조건이 필요하다면 새 쿠폰을 생성하세요.
• times_redeemed 는 자동으로 증가하며 읽기 전용입니다 — 캠페인 성과 추적에 유용합니다.
• 쿠폰은 주문이 아닌 고객 단위로 적용됩니다 — 쿠폰이 forever이고 고객이 구독을 시작하면, 매 갱신 시마다 할인이 적용됩니다.