How To: Use Stripe Coupons and Promo Codes

Stripe offers two ways to provide discounts to your customers: Coupons and Promo Codes. While they’re related, they serve different purposes and are implemented differently.

​

Understanding Coupons vs Promo Codes

​

Coupons

• Coupons are the underlying discount rules you create in Stripe.
• They define the actual discount (e.g., 20% off, $10 off, etc).
• They are not customer-facing and are identified by IDs in Stripe, that can either look like A1b2C3d4 or an ID chosen by you.
• You can create coupons in your Stripe Dashboard.

​

Promo Codes

• Promo codes are customer-facing codes that are linked to coupons.
• They are what customers actually enter to get a discount.
• They have a customer-friendly format (e.g., “BLACKFRIDAY50”), and they also have a unique ID generated by Stripe that looks like promo_1A2B3C4D5E6F7G8H9I0J.
• You can create promo codes in your Stripe Dashboard from within a Coupon.

​

Implementing Promo Codes in Your Embeddable

There are two ways to implement promo codes in your Embeddable:

​

1. Manual Entry by Customer

To let customers enter their own promo codes:

function output(userData, { setUserData }) {
  // Get the promo code from the input, using its key
  const promoCode = userData.new_promo_code;
  
  // Apply the promo code using the Stripe Checkout function
  window.StripeCheckout.applyPromotionCode(promoCode)
    .then((result) => {
      if (result.type === 'success') {
        // On success:
        // - Update the success message to show the applied discount
        // - Clear any error message
        // - Reset the input box to empty
        setUserData({
          promo_code_success_message: `Promo code "${promoCode}" applied successfully!`,
          promo_code_error_message: "",
          new_promo_code: "",
        });
      } else {
        // Handle error case
        setUserData({
          promo_code_success_message: "",
          promo_code_error_message: result.error.message || "Invalid promo code",
        });
      }
    })
    .catch((error) => {
      // Handle any unexpected errors
      setUserData({
        promo_code_success_message: "",
        promo_code_error_message: "An unexpected error occurred",
      });
    });
}

function output(userData, { setUserData }) {
  setUserData({
    promo_code_success_message: "",
    promo_code_error_message: "",
  });
}

​

2. Automatic Application

Use this method to automatically apply a promo code for all customers.

In your Stripe component Options, open the JSON editor and add the following to the checkout session configuration:

{
  "checkout_session": {
    // ... other checkout session configuration ...
    "discounts": [  // Stripe currently only supports one object in the array
      {
        "promotion_code": "YOUR_PROMO_CODE_ID", // EITHER THIS
        "coupon": "YOUR_COUPON_ID"              // OR THIS
      }
    ]
  }
}

Tips:

• Replace YOUR_PROMO_CODE_ID or YOUR_COUPON_ID with your actual promo code ID from Stripe.
• Or, if you prefer, replace them with {{promo_code_id}} or {{coupon_id}} to use an ID calculated from a Computed Field or Action.
• Make sure to remove either the promotion_code or coupon key, not both.
• Make sure to remove all the comments (// ...) since JSON doesn’t support comments.
• Make sure to remove the // ... other checkout session configuration ... line, since you’re only adding the discounts section.

​

Troubleshooting

​

Best Practices

1. Test Both Modes: Always test your promo codes in both test and live modes to ensure they work as expected.

2. Clear Messaging: Make sure your UI clearly communicates:

   • Where to enter the promo code.
   • When a code has been successfully applied.
   • When a code is invalid and why.
   • That only one promo code can be applied at a time.

3. Error Handling: Implement proper error handling in your Action to provide a good user experience when:

   • The code is invalid.
   • The code has expired.
   • The code doesn’t apply to the current products.
   • The code has already been applied.

4. Security: Remember that promo codes are public-facing. Don’t include sensitive information in them, and consider implementing rate limiting if you’re concerned about brute force attempts.

5. Data Management:

   • Register all user data keys in your Embeddable settings to ensure proper tracking and management.
   • Reset success/error messages on page load to handle Stripe checkout session refreshes.
   • Keep your user data structure clean by clearing input fields after successful code application.