Skip to main content

Apply Promo Code

ApplyPromoCode Mutation

This mutation applies a promo code to an existing cart and recalculates the cart totals, including discounts. It’s designed to be used from custom landing pages or checkout flows where you control the promo input.

Use Cases​

  • Landing page promo fields: Allow customers to enter a promo code before redirecting to checkout.
  • Automatic campaign codes: Auto-apply a code based on campaign/UTM parameters.
  • Re-engagement flows: Apply discount codes to carts recovered from abandoned sessions.

Headers​

You should keep using the same sessionid header used for cart creation and updates:

{
  "sessionid": "Session_3f6a0f1d-9c4a-4f3e-8f4b-1a2b3c4d5e6f"
}

The cartId in the variables should belong to this session.

Input Parameters​

  • $storeId: ID! – The store in which the cart lives.
  • $cartId: ID! – The target cart (Cart_...).
  • $code: String! – The promo/coupon code to apply (e.g. SUMMER-2025).

Response Structure​

Returns the updated Cart with:

  • id, sessionId, status, cartStep – Cart metadata.
  • promoCode – Applied promo code details (e.g. code).
  • cartErrors – List of errors if the code is invalid or cannot be applied:
    • code – Error code from CheckoutServiceErrorCodes.
    • params.message – Human-readable error message (if provided).
  • receipt – Updated monetary breakdown:
    • subtotal – Cart subtotal before discounts.
    • discount – Total discount amount from the promo and any other discounts.
    • shipping – Shipping amount.
    • tax – Tax amount.
    • total – Final payable amount.

Example Variables​

{
  "storeId": "Store_cm84j35iy02m001i89iiu2cts",
  "cartId": "Cart_d8f8ce2f-681e-4554-93b7-230e0b34a151",
  "code": "SUMMER-2025"
}

Implementation Notes​

  • Call ApplyPromoCode after you have a valid cartId (for example after AddToCart or ReplaceCartItems + GetCart).
  • If the mutation returns cartErrors, show the message to the customer and avoid redirecting to checkout until resolved.
  • After a successful apply, you can re-call GetCart or rely on the returned Cart to display updated totals.

GraphQL Endpoint​

https://graphql.wuilt.com

Operation: ApplyPromoCode​

Try It Out​

Query​

mutation ApplyPromoCode($storeId: ID!, $cartId: ID!, $code: String!) {
customerActions(storeId: $storeId) {
  cart {
    applyPromoCode(cartId: $cartId, code: $code) {
      id
      sessionId
      status
      cartStep
      promoCode {
        code
      }
      cartErrors {
        code
        params {
          message
        }
      }
      receipt {
        subtotal {
          amount
          currencyCode
        }
        discount {
          amount
          currencyCode
        }
        shipping {
          amount
          currencyCode
        }
        tax {
          amount
          currencyCode
        }
        total {
          amount
          currencyCode
        }
      }
    }
  }
}
}

Query Variables

1
2
3
4
5

Note: Make sure to change the storeId with your store ID. For guidance on how to get your store ID, reference the Store ID guide.

Authentication​

To use this query, you will need an API key. Click the "API Key" button in the navigation bar to enter your credentials.