How to

Activate promo code on cart

Learn how to activate promo codes on carts using Geins Merchant API

Prerequisites

  • Merchant API key
  • Existing cart id
  • Valid promo code

Goals

  • Activate a promo code on a cart
  • Complete checkout with the promo code discount applied

Architecture at a glance

  • Activate promo code on cart → Complete checkout with discount applied

APIs used

  • Merchant API: https://merchantapi.geins.io/graphql

Step-by-step

Activate promo code on cart

Using the setCartPromoCode mutation in the Merchant API, you can activate a promo code on a cart at any time before checkout. The promo code will be validated and any applicable discounts will be applied to the cart.

Try it out in the GraphQL Playground using the query, headers and variables below.

Request example

mutation setCartPromoCode(
    $id: String!
    $promoCode: String!
    $channelId: String
    $languageId: String
    $marketId: String
) {
    setCartPromoCode(
        id: $id 
        promoCode: $promoCode
        channelId: $channelId 
        languageId: $languageId
        marketId: $marketId
    ) {
        id
        promoCode
        appliedCampaigns {
            name
        }
        items {
            id
            skuId
            quantity
            campaign {
                appliedCampaigns {
                    name
                }
                prices {
                    price {
                        sellingPriceIncVat
                        isDiscounted
                    }
                }
            }
        }
    }
}
The channelId, languageId, and marketId arguments are optional and can be left out to use default values.

Response example

200 OK
response.json
{
  "data": {
    "setCartPromoCode": {
      "id": "638cf54d-74d2-4ff7-86df-45e514b19094",
      "promoCode": "VIBE_WNR",
      "appliedCampaigns": [
        {
          "name": "Cart Campaign"
        },
        {
          "name": "VIBE_WNR"
        }
      ],
      "items": [
        {
          "id": "c34a2721-dc52-415f-995a-418d76efa978",
          "skuId": 1350,
          "quantity": 1,
          "campaign": {
            "appliedCampaigns": [
              {
                "name": "Cart Campaign"
              },
              {
                "name": "VIBE_WNR"
              }
            ],
            "prices": [
              {
                "price": {
                  "sellingPriceIncVat": 2230.61,
                  "isDiscounted": true
                }
              }
            ]
          }
        },
        {
          "id": "b34a2721-dc45-415f-888a-418d76efa123",
          "skuId": 1351,
          "quantity": 1,
          "campaign": {
            "appliedCampaigns": [
              {
                "name": "Cart Campaign"
              }
            ],
            "prices": [
              {
                "price": {
                  "sellingPriceIncVat": 1234.49,
                  "isDiscounted": true
                }
              }
            ]
          }
        }
      ]
    }
  }
}

Complete the checkout

After activating the promo code, you can proceed to complete the checkout as usual. The promo code discount will be applied to the cart and included on the order.

Depending on campaign settings, the promo code discount may apply to specific items or to the entire cart. The response from the setCartPromoCode mutation includes details about which campaigns were applied to the cart as a whole and to individual items, along with the updated prices for each cart item.

Options

Channel, Language, and Market

The mutation also supports optional parameters for multi-market support:

Read more about channelId, languageId, and marketId in the "how to"-article about using multi-market support.

Authenticated access

While authentication is not required for this mutation, including a JWT bearer token in the Authorization header can provide personalized results based on the authenticated user's context, for example personalized pricing.

To include authentication, add the JWT bearer token to your request headers:

"Authorization": "Bearer {JWT_TOKEN}"
Read more about obtaining and using JWT tokens in the guide about the authentication flow.

Common pitfalls

  • Ensure the promo code is valid and active in your system.
  • Promo codes may have conditions such as minimum purchase amount or specific product categories.
  • Check for expiration dates on promo codes.
Related

Activate promo code on cartAdd custom data to cartAdd product to cartCheck out headless cartClone a cartShow shipping/payment optionsGet cartUse external payment frameUse external shipping frameUse multi-market supportSetCartPromoCode

Sitemaps

A guide to sitemaps and their usage

Add custom data to cart

Learn how to add custom data to carts using Geins Merchant API