Retrieve a Stripe discount coupon from its code

When working with Stripe, it's common to use discount coupons to offer discounts to your customers.

Technically, Stripe identifies each promo code by a unique identifier (for example promo_1Hd0sBG03p6y1vChab7Jh6Zs).

Retrieving a coupon with its identifier

With the API, it's very simple to retrieve the information of a coupon with its unique identifier, as here using the SDK (NodeJS):

const promo = await stripe.promotionCodes.retrieve(
  'promo_1Hd0sBG03p6y1vChab7Jh6Zs'
);

But in practice, your customers don't know this technical identifier.

What they enter in your payment form is a readable promo code like BLACKFRIDAY, so how do you handle this?

Retrieving a coupon with its code

The problem is that Stripe doesn't offer a retrieve method based on the customer's code, but fortunately there's still a simple solution.

Stripe provides the List Promotion Codes API, which lets you filter directly by the code field. And since each promo code must be unique, the request will return a single item:

const promotionCodes = await stripe.promotionCodes.list({
  code: 'FIFTYOFF'
});

const promo = promotionCodes.data[0];

So you get directly the coupon corresponding to the code entered by the customer!

Be careful nonetheless to check that the promo object exists, in case of an incorrect code!

Official documentation

If you want to find these methods directly in Stripe's documentation, it's here: https://docs.stripe.com/api/promotion_codes