ApplyCouponToCartMutation

Description

Applies a coupon code to the cart. This mutation allows you to add a discount coupon to a cart, which may reduce the total price based on the coupon's rules.

Endpoint

mutation applyCouponToCart($cartId: String!, $couponCode: String!) {
  applyCouponToCart(cartId: $cartId, couponCode: $couponCode) {
    # Return fields
  }
}

Arguments

Argument	Type	Required	Description
cartId	String	Yes	The unique identifier of the cart to which the coupon will be applied. This ID is obtained from createGuestCart or createCustomerCart mutations.
couponCode	String	Yes	The coupon code to apply to the cart.

Return Values

The mutation returns a CartType object with the following structure:

Field	Type	Description
billing_address	Object	The billing address associated with the cart.
shipping_address	Object	The shipping address associated with the cart.
items	[CartItem]	Array of items in the cart.
selected_shipping_method	Object	The selected shipping method for the cart.
selected_payment_method	Object	The selected payment method for the cart.
totals	Object	Cart totals information, including any discounts applied by the coupon.

For detailed information about the structure of these fields, refer to the CartQuery documentation.

Usage Example

mutation {
  applyCouponToCart(
    cartId: "abc123",
    couponCode: "DISCOUNT10"
  ) {
    items {
      id
      quantity
      name
      row_total {
        value
        currency
      }
    }
    totals {
      grand_total {
        value
        currency
      }
      discount_amount {
        value
        currency
      }
    }
  }
}

Example Response

{
  "data": {
    "applyCouponToCart": {
      "items": [
        {
          "id": "123",
          "quantity": 2,
          "name": "Sample Product",
          "row_total": {
            "value": 39.98,
            "currency": "USD"
          }
        }
      ],
      "totals": {
        "grand_total": {
          "value": 35.98,
          "currency": "USD"
        },
        "discount_amount": {
          "value": 4.00,
          "currency": "USD"
        }
      }
    }
  }
}

Notes

• If the coupon code is invalid or cannot be applied to the cart, an error will be thrown with a descriptive message.
• Only one coupon can be applied to a cart at a time. If you apply a new coupon, it will replace any existing coupon.
• The discount amount and rules depend on the coupon configuration in the store's backend.
• To remove a coupon from the cart, use the removeCouponFromCart mutation.