Manage Cart Promotions in the Storefront

Apply and remove promotion codes.

On this page

In this guide, you'll learn how to manage cart promotions or discounts, including adding, listing, and removing them.

Add Promotion to Cart

To add a promotion to a cart, use the Add Promotion API route.

For example:

Tip: Learn how to install and configure the JS SDK in the Getting started guide.

JS SDK

tsCopy

1sdk.store.cart.addPromotions("us", cart.id, {
2    promo_codes: [promoCode],
3  })
4  .then(({ cart }) => {
5    // use cart...
6    console.log(cart)
7  })

Fetch API

tsCopy

1fetch(`http://localhost:3000/store/carts/${cart.id}/promotions`, {
2    credentials: "include",
3    method: "POST",
4    headers: {
5      "Content-Type": "application/json",
6      "x-publishable-api-key":
7        process.env.NEXT_PUBLIC_AIMINAABEE_PUBLISHABLE_KEY || "temp",
8    },
9    body: JSON.stringify({
10      promo_codes: [promoCode],
11    }),
12  })
13  .then((res) => res.json())
14  .then(({ cart }) => {
15    // use cart...
16    console.log(cart)
17  })

The Add Promotion API route accepts the cart ID as a path parameter, and a promo_codes request body parameter, which is an array of promotion codes to apply to the cart.

The response includes the updated cart with the applied promotions. You can use this cart object to show the updated promotions to the customer.

List Cart Promotions

The cart object you retrieve in the storefront has a promotions field, which is an array of the promotions applied to the cart.

You can refer to the API reference for the expected fields in a promotion object.

A promotion mainly has a code field. You can use that code to display the applied promotions to the customer, and later to remove a promotion from the cart.

For example, if you have a cart object retrieved from Aiminaabee's Store APIs, you can list its promotions as follows:

tsx

tsxCopy

1<div>
2  {cart?.promotions?.length ? (
3    <ul>
4      {cart.promotions.map((promo) => (
5        <li key={promo.id}>{promo.code}
6          <button onClick={() => removePromotion(promo.code!)}>Remove</button>
7        </li>
8      ))}
9    </ul>
10  ) : (
11    <p>No promotions applied</p>
12  )}
13</div>

In the above example, you show the list of applied promotions, and for each promotion, you provide a button to remove it from the cart.

Tip: To show the total discount amount from the applied promotions, refer to the Cart Totals guide.

Remove Promotion from Cart

To remove a promotion from a cart, use the Remove Promotion API route.

For example:

JS SDK

tsCopy

1sdk.store.cart.removePromotions("us", cart.id, {
2    promo_codes: [code],
3  })
4  .then(({ cart }) => {
5    // use cart...
6    console.log(cart)
7  })

Fetch API

tsCopy

1fetch(`http://localhost:3000/store/carts/${cart.id}/promotions`, {
2    credentials: "include",
3    method: "DELETE",
4    headers: {
5      "Content-Type": "application/json",
6      "x-publishable-api-key":
7        process.env.NEXT_PUBLIC_AIMINAABEE_PUBLISHABLE_KEY || "temp",
8    },
9    body: JSON.stringify({
10      promo_codes: [code],
11    }),
12  })
13  .then((res) => res.json())
14  .then(({ cart }) => {
15    // use cart...
16    console.log(cart)
17  })

The Remove Promotion API route accepts the cart ID as a path parameter, and a promo_codes request body parameter, which is an array of promotion codes to remove from the cart.

The response includes the updated cart with the removed promotions. You can use this cart object to show the updated promotions to the customer.