Phiếu giảm giá

Tạo mã giảm giá để khách hàng áp dụng khi thanh toán. Theo phần trăm hoặc số tiền cố định, giới hạn thời gian hoặc số lượt dùng, một lần hoặc định kỳ.

Phiếu giảm giá được quản lý trong Commerce panel > Products > Coupons của builder, hoặc thông qua SDK tại proyecta.commerce.coupons.

Cấu trúc của một phiếu giảm giá

Trường	Ghi chú
code	Mã khuyến mãi khách hàng nhập khi thanh toán (ví dụ: LAUNCH20)
percent_off hoặc amount_off	Chỉ dùng một trong hai. Phần trăm từ 1–100. Số tiền tính theo đơn vị tiền tệ nhỏ nhất (xu/cent).
currency	Bắt buộc với giảm giá theo amount_off (mã ISO ba chữ cái). Được chấp nhận khi tạo và chuyển tiếp đến Stripe, nhưng không được lưu trữ hoặc trả về bởi API sau đó.
duration	once (chỉ lần thanh toán đầu tiên), repeating (trong duration_in_months tháng), hoặc forever
duration_in_months	Bắt buộc khi duration là repeating
max_redemptions	Tổng số lượt sử dụng tối đa cho tất cả khách hàng
redeem_by	Ngày hết hạn, sau thời điểm này phiếu giảm giá sẽ không còn hoạt động
name	Tên hiển thị cho khách hàng
active	Bật/tắt phiếu giảm giá mà không cần xóa

Tạo phiếu giảm giá

Trong tab Coupons, nhấp Add coupon và điền các trường thông tin. Hoặc dùng 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,
});

Áp dụng phiếu giảm giá khi thanh toán

Khách hàng có thể tự nhập mã phiếu giảm giá trên trang thanh toán do Stripe host — trường mã khuyến mãi sẽ hiển thị tự động.

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

Việc truyền mã phiếu giảm giá theo dạng lập trình trong lệnh gọi checkout chưa được hỗ trợ.

Liệt kê, cập nhật, vô hiệu hóa

// 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 });

Lưu ý: coupons.list() chỉ trả về các phiếu giảm giá được tạo qua SDK. Phiếu giảm giá được tạo trong Dashboard của builder sẽ không hiển thị qua coupons.list().

Lưu ý và giới hạn

• Mã và mức giảm giá không thể thay đổi. Bạn có thể cập nhật name hiển thị và bật/tắt active, nhưng không thể thay đổi percent_off, amount_off hay chính code. Hãy tạo phiếu giảm giá mới nếu bạn cần các điều khoản khác.
• times_redeemed tự động tăng và chỉ đọc — hữu ích để theo dõi hiệu quả chiến dịch.
• Phiếu giảm giá áp dụng theo từng khách hàng, không theo từng đơn hàng — nếu phiếu giảm giá là forever và khách hàng đăng ký, mỗi lần gia hạn đều được áp dụng giảm giá.