Redeem a coupon

​

What is a coupon?

A coupon is a code created in a specific coupon campaign that grants one or more rewards according to the campaign’s settings.

const payload = {
  customer_id: "unique-customer-id",
  code: "coupon-code",
  brand_id: "unique-brand-id", // string | null
  // Optional values
  store_id: "unique-store-id",
  channel_id: "unique-channel-id"
};

const response = await fetch(
  "https://app.masivo.ai/api/storefront/v1/coupons/redeem",
  {
    method: "POST",
    headers: { Authorization: `Bearer ${accessToken}` },
    body: JSON.stringify(payload)
  }
);

When a coupon is redeemed, depending on the amount of reward types the coupon gives, each one appear as a new item in response.data.accumulations and indicates the amount of that reward type.

The response returns wallet.totals updated after coupon redemptions. It contains the sum of the amount of the rewards just redeemed and the amount of the specific reward types the wallet already had.

​

What happens when a coupon campaign expires?

When a coupon campaign expires, all associated coupon codes become invalid and cannot be redeemed. Any attempt to redeem an expired coupon will result in an error.

It is important to highlight that a coupon campaign may still have active coupon codes, but the reward itself may expire before or after the campaign ends, depending on the configured expiration.

Additionally, the code may return an error even if it is valid, in case the coupon’s rewards are out of stock.

​

What happens when a code is invalid?

If a coupon code is invalid, the system returns an error, and no rewards are accumulated.

​

Coupons validation errors

A Coupon Campaign can be set with specific conditions. If a coupon redemption is attempted and the campaign has a condition that is not met, the response will include a requirement attribute with the default value "Condition was not met".

This requirement message will be a “custom error message” if it is set for the campaign’s condition.