Skip to Content
ReferenceStorefrontv0.8.0 API ReferenceMutationscartDiscountCodesUpdate

cartDiscountCodesUpdate

Updates discount codes for an existing cart.

Mutation Structure

mutation cartDiscountCodesUpdate($cartId: String!, $discountCodes: [String!]) {
  cartDiscountCodesUpdate(cartId: $cartId, discountCodes: $discountCodes) {
    cart {
      id
      discountCodes
      # Include other cart fields as needed
    }
    userErrors {
      field
      message
    }
  }
}

Input Arguments

ArgumentTypeDescriptionRequiredValidation
cartIdString!The ID of the cart to update discount codes forYesMust be a valid cart identifier (JWT token format)
discountCodes[String!]A list of discount codes to apply to the cartNoEach discount code must be a non-empty string

Return Type

Type: CartDiscountCodesUpdatePayload

Description: The payload returned by the cartDiscountCodesUpdate mutation containing the updated cart and any user errors.

Fields:

  • cart: Cart! — The updated cart object after applying discount codes.
  • userErrors: [UserError]! — A list of errors that occurred during the update operation. Each error contains:
    • field — The input field related to the error.
    • message — A descriptive error message.

Examples

Basic Mutation

mutation {
  cartDiscountCodesUpdate(
    cartId: "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0",
    discountCodes: ["SUMMER21"]
  ) {
    cart {
      id
      discountCodes
    }
    userErrors {
      field
      message
    }
  }
}

Advanced Mutation

mutation UpdateCartDiscountCodes($cartId: String!, $discountCodes: [String!]) {
  cartDiscountCodesUpdate(cartId: $cartId, discountCodes: $discountCodes) {
    cart {
      id
      discountCodes
      # Add other cart fields here as needed
    }
    userErrors {
      field
      message
    }
  }
}

Variables:

{
  "cartId": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0",
  "discountCodes": ["WELCOME10", "FREESHIP"]
}

Input Validation

mutation {
  cartDiscountCodesUpdate(
    cartId: "",
    discountCodes: [""]
  ) {
    cart {
      id
      discountCodes
    }
    userErrors {
      field
      message
    }
  }
}

cURL Example

curl -X POST https://www.mystoreurl.com/graphql/0.8.0/ \
  -H "Content-Type: application/json" \
  -d '{"query":"mutation cartDiscountCodesUpdate($cartId: String!, $discountCodes: [String!]) { cartDiscountCodesUpdate(cartId: $cartId, discountCodes: $discountCodes) { cart { id discountCodes } userErrors { field message } } }","variables":{"cartId":"eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0","discountCodes":["SUMMER21"]}}'

JavaScript Example

async function updateCartDiscountCodes(cartId, discountCodes) {
  const query = `
    mutation cartDiscountCodesUpdate($cartId: String!, $discountCodes: [String!]) {
      cartDiscountCodesUpdate(cartId: $cartId, discountCodes: $discountCodes) {
        cart {
          id
          discountCodes
        }
        userErrors {
          field
          message
        }
      }
    }
  `;
 
  const variables = { cartId, discountCodes };
 
  try {
    const response = await fetch('https://www.mystoreurl.com/graphql/0.8.0/', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ query, variables })
    });
 
    const result = await response.json();
 
    if (result.data.cartDiscountCodesUpdate.userErrors.length) {
      console.error('User errors:', result.data.cartDiscountCodesUpdate.userErrors);
      return null;
    }
 
    return result.data.cartDiscountCodesUpdate.cart;
  } catch (error) {
    console.error('Network or server error:', error);
    return null;
  }
}
 
// Usage example
updateCartDiscountCodes(
  "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0",
  ["WELCOME10", "FREESHIP"]
).then(cart => {
  if (cart) {
    console.log('Updated cart:', cart);
  }
});

Response Format

The mutation returns a CartDiscountCodesUpdatePayload object containing:

  • cart: The updated cart object with the applied discount codes.
  • userErrors: An array of UserError objects describing any issues encountered during the update.

Example successful response:

{
  "data": {
    "cartDiscountCodesUpdate": {
      "cart": {
        "id": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0",
        "discountCodes": ["SUMMER21"]
      },
      "userErrors": []
    }
  }
}

Example response with user errors:

{
  "data": {
    "cartDiscountCodesUpdate": {
      "cart": null,
      "userErrors": [
        {
          "field": ["discountCodes"],
          "message": "Discount code 'INVALIDCODE' is not valid."
        }
      ]
    }
  }
}

Error Handling

Common user errors include:

Error Code / FieldMessageCauseResolution
cartId"Cart ID is required."Missing or empty cartId argumentProvide a valid, non-empty cartId
discountCodes"Discount code cannot be empty."One or more discount codes are empty stringsProvide valid, non-empty discount codes
discountCodes"Discount code 'XYZ' is not valid."Discount code does not exist or expiredUse valid and active discount codes

Example error response for invalid discount code:

{
  "data": {
    "cartDiscountCodesUpdate": {
      "cart": null,
      "userErrors": [
        {
          "field": ["discountCodes"],
          "message": "Discount code 'EXPIRED' is not valid."
        }
      ]
    }
  }
}

Authentication

This API currently does not require authentication. However, authentication requirements may be introduced in future versions. Monitor API updates for any changes to authentication requirements.

Side Effects

  • Applying discount codes may change the cart’s total price and available promotions.
  • The mutation updates the cart in place; ensure the cartId corresponds to an active cart.
  • Invalid discount codes will not be applied, and relevant errors will be returned.
  • This mutation does not remove discount codes if the discountCodes argument is omitted; to clear discount codes, pass an empty array.

Authentication

No authentication is currently required to perform this mutation. This may change in future API versions.

  • CartDiscountCodesUpdatePayload
  • Cart
  • UserError

Notes

  • The cartId is expected to be a JWT token string representing the cart session.
  • When updating discount codes, provide the full list of discount codes to apply; partial updates are not supported.
  • Rate limiting may apply; if you encounter rate limit errors, retry after a delay.
  • Always check userErrors in the response to handle validation or business logic errors gracefully.
Last updated on
cartCreatecartLinesAdd