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
Argument | Type | Description | Required | Validation |
---|---|---|---|---|
cartId | String! | The ID of the cart to update discount codes for | Yes | Must be a valid cart identifier (JWT token format) |
discountCodes | [String!] | A list of discount codes to apply to the cart | No | Each 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 ofUserError
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 / Field | Message | Cause | Resolution |
---|---|---|---|
cartId | "Cart ID is required." | Missing or empty cartId argument | Provide a valid, non-empty cartId |
discountCodes | "Discount code cannot be empty." | One or more discount codes are empty strings | Provide valid, non-empty discount codes |
discountCodes | "Discount code 'XYZ' is not valid." | Discount code does not exist or expired | Use 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.
Related Types
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