Mutations Reference
All available GraphQL mutations for modifying data in Unified Commerce Platform.
Overview
Mutations are write operations used to create, update, or delete data. All mutations follow a consistent pattern:
mutation MutationName($input: InputType!) {
mutationName(input: $input) {
# Success case - the created/updated resource
resource {
id
field1
field2
}
# Error case - validation/business logic errors
errors {
field
message
code
}
}
}
Error Handling
All mutations return a payload with both the resource and potential errors:
type MutationPayload {
resource: Resource | null // Null if errors occurred
errors: [UserError!]! // Array of errors (empty if successful)
}
type UserError {
field: String // Which field caused the error
message: String! // Human-readable message
code: String // Machine-readable error code
}
Product Catalog
createProduct
Create a new product.
mutation CreateProduct($input: CreateProductInput!) {
createProduct(input: $input) {
product {
id
name
sku
price
currency
status
}
errors {
field
message
code
}
}
}
Input:
input CreateProductInput {
name: String!
description: String
sku: String!
price: Money!
currency: String!
compareAtPrice: Money
costPerItem: Money
categoryIds: [ID!]
tags: [String!]
images: [ProductImageInput!]
variants: [ProductVariantInput!]
status: ProductStatus
seoTitle: String
seoDescription: String
}
input ProductImageInput {
url: URL!
alt: String
order: Int
}
input ProductVariantInput {
sku: String!
price: Money
options: [VariantOptionInput!]!
}
Variables Example:
{
"input": {
"name": "Premium T-Shirt",
"description": "High-quality cotton t-shirt",
"sku": "TSHIRT-001",
"price": 2999,
"currency": "USD",
"compareAtPrice": 3999,
"categoryIds": ["cat_123"],
"tags": ["clothing", "bestseller"],
"images": [
{
"url": "https://example.com/image1.jpg",
"alt": "Front view",
"order": 1
}
],
"status": "ACTIVE"
}
}
Returns: CreateProductPayload
updateProduct
Update an existing product.
mutation UpdateProduct($id: ID!, $input: UpdateProductInput!) {
updateProduct(id: $id, input: $input) {
product {
id
name
price
updatedAt
}
errors {
field
message
code
}
}
}
Input:
input UpdateProductInput {
name: String
description: String
price: Money
compareAtPrice: Money
status: ProductStatus
tags: [String!]
# ... all fields from CreateProductInput are optional
}
Returns: UpdateProductPayload
deleteProduct
Delete a product (soft delete - sets status to ARCHIVED).
mutation DeleteProduct($id: ID!) {
deleteProduct(id: $id) {
success
deletedProductId
errors {
message
code
}
}
}
Returns: DeleteProductPayload
createCategory
Create a new category.
mutation CreateCategory($input: CreateCategoryInput!) {
createCategory(input: $input) {
category {
id
name
slug
description
}
errors {
field
message
code
}
}
}
Input:
input CreateCategoryInput {
name: String!
slug: String!
description: String
parentId: ID
image: ImageInput
seoTitle: String
seoDescription: String
}
Returns: CreateCategoryPayload
Orders
createOrder
Create a new order.
mutation CreateOrder($input: CreateOrderInput!) {
createOrder(input: $input) {
order {
id
orderNumber
total
status
customer {
name
email
}
items {
product {
name
}
quantity
price
}
}
errors {
field
message
code
}
}
}
Input:
input CreateOrderInput {
customerId: ID!
items: [OrderItemInput!]!
shippingAddress: AddressInput!
billingAddress: AddressInput
shippingMethodId: ID
couponCode: String
notes: String
}
input OrderItemInput {
productId: ID!
variantId: ID
quantity: Int!
}
input AddressInput {
line1: String!
line2: String
city: String!
state: String!
postalCode: String!
country: String!
phone: String
}
Variables Example:
{
"input": {
"customerId": "cust_123",
"items": [
{
"productId": "prod_abc",
"quantity": 2
},
{
"productId": "prod_xyz",
"variantId": "var_456",
"quantity": 1
}
],
"shippingAddress": {
"line1": "123 Main St",
"city": "San Francisco",
"state": "CA",
"postalCode": "94102",
"country": "US",
"phone": "+1-555-0100"
},
"couponCode": "WELCOME10"
}
}
Returns: CreateOrderPayload
updateOrderStatus
Update an order's status.
mutation UpdateOrderStatus($id: ID!, $status: OrderStatus!, $notes: String) {
updateOrderStatus(id: $id, status: $status, notes: $notes) {
order {
id
orderNumber
status
updatedAt
}
errors {
message
code
}
}
}
OrderStatus Enum:
enum OrderStatus {
PENDING
CONFIRMED
PROCESSING
SHIPPED
DELIVERED
CANCELLED
REFUNDED
}
Returns: UpdateOrderStatusPayload
cancelOrder
Cancel an order.
mutation CancelOrder($id: ID!, $reason: String!) {
cancelOrder(id: $id, reason: $reason) {
order {
id
status
}
refund {
id
amount
status
}
errors {
message
code
}
}
}
Returns: CancelOrderPayload
Cart
addToCart
Add an item to the cart.
mutation AddToCart($input: AddToCartInput!) {
addToCart(input: $input) {
cart {
id
items {
id
product {
name
price
}
quantity
subtotal
}
total
}
errors {
field
message
code
}
}
}
Input:
input AddToCartInput {
cartId: ID # Optional - creates new cart if not provided
productId: ID!
variantId: ID
quantity: Int!
}
Returns: AddToCartPayload
updateCartItem
Update the quantity of a cart item.
mutation UpdateCartItem($cartId: ID!, $itemId: ID!, $quantity: Int!) {
updateCartItem(cartId: $cartId, itemId: $itemId, quantity: $quantity) {
cart {
id
items {
id
quantity
subtotal
}
total
}
errors {
message
code
}
}
}
Returns: UpdateCartItemPayload
removeFromCart
Remove an item from the cart.
mutation RemoveFromCart($cartId: ID!, $itemId: ID!) {
removeFromCart(cartId: $cartId, itemId: $itemId) {
cart {
id
items {
id
}
total
}
errors {
message
code
}
}
}
Returns: RemoveFromCartPayload
applyCoupon
Apply a coupon code to the cart.
mutation ApplyCoupon($cartId: ID!, $couponCode: String!) {
applyCoupon(cartId: $cartId, couponCode: $couponCode) {
cart {
id
subtotal
discount
total
coupon {
code
discountAmount
}
}
errors {
message
code
}
}
}
Returns: ApplyCouponPayload
Customers (CRM)
createCustomer
Create a new customer.
mutation CreateCustomer($input: CreateCustomerInput!) {
createCustomer(input: $input) {
customer {
id
name
email
phone
createdAt
}
errors {
field
message
code
}
}
}
Input:
input CreateCustomerInput {
email: EmailAddress!
name: String!
phone: String
tags: [String!]
notes: String
marketingOptIn: Boolean
}
Returns: CreateCustomerPayload
updateCustomer
Update customer information.
mutation UpdateCustomer($id: ID!, $input: UpdateCustomerInput!) {
updateCustomer(id: $id, input: $input) {
customer {
id
name
email
phone
updatedAt
}
errors {
field
message
code
}
}
}
Returns: UpdateCustomerPayload
addCustomerAddress
Add a new address to a customer.
mutation AddCustomerAddress($customerId: ID!, $address: AddressInput!, $isDefault: Boolean) {
addCustomerAddress(customerId: $customerId, address: $address, isDefault: $isDefault) {
address {
id
line1
city
state
postalCode
country
isDefault
}
errors {
field
message
code
}
}
}
Returns: AddCustomerAddressPayload
Identity & Authentication
register
Register a new user account.
mutation Register($input: RegisterInput!) {
register(input: $input) {
user {
id
email
name
}
token
refreshToken
errors {
field
message
code
}
}
}
Input:
input RegisterInput {
email: EmailAddress!
password: String!
name: String!
phone: String
acceptTerms: Boolean!
}
Returns: RegisterPayload
login
Authenticate a user and receive access tokens.
mutation Login($email: EmailAddress!, $password: String!) {
login(email: $email, password: $password) {
user {
id
email
name
roles {
name
permissions
}
}
token
refreshToken
expiresAt
errors {
message
code
}
}
}
Returns: LoginPayload
refreshToken
Refresh an expired access token.
mutation RefreshToken($refreshToken: String!) {
refreshToken(refreshToken: $refreshToken) {
token
refreshToken
expiresAt
errors {
message
code
}
}
}
Returns: RefreshTokenPayload
logout
Invalidate the current session.
mutation Logout {
logout {
success
}
}
Returns: LogoutPayload
changePassword
Change the current user's password.
mutation ChangePassword($currentPassword: String!, $newPassword: String!) {
changePassword(currentPassword: $currentPassword, newPassword: $newPassword) {
success
errors {
field
message
code
}
}
}
Returns: ChangePasswordPayload
requestPasswordReset
Request a password reset email.
mutation RequestPasswordReset($email: EmailAddress!) {
requestPasswordReset(email: $email) {
success
message
}
}
Returns: RequestPasswordResetPayload
resetPassword
Reset password using a reset token.
mutation ResetPassword($token: String!, $newPassword: String!) {
resetPassword(token: $token, newPassword: $newPassword) {
success
errors {
message
code
}
}
}
Returns: ResetPasswordPayload
Payment
createPaymentIntent
Create a payment intent for processing a payment.
mutation CreatePaymentIntent($input: CreatePaymentIntentInput!) {
createPaymentIntent(input: $input) {
paymentIntent {
id
clientSecret
amount
currency
status
}
errors {
message
code
}
}
}
Input:
input CreatePaymentIntentInput {
amount: Money!
currency: String!
orderId: ID
customerId: ID
paymentMethodId: String
description: String
}
Returns: CreatePaymentIntentPayload
confirmPayment
Confirm a payment intent.
mutation ConfirmPayment($paymentIntentId: ID!, $paymentMethodId: String!) {
confirmPayment(paymentIntentId: $paymentIntentId, paymentMethodId: $paymentMethodId) {
payment {
id
status
amount
currency
}
errors {
message
code
}
}
}
Returns: ConfirmPaymentPayload
refundPayment
Issue a full or partial refund.
mutation RefundPayment($paymentId: ID!, $amount: Money, $reason: String!) {
refundPayment(paymentId: $paymentId, amount: $amount, reason: $reason) {
refund {
id
amount
reason
status
createdAt
}
errors {
message
code
}
}
}
Returns: RefundPaymentPayload
Inventory
updateInventory
Update inventory levels for a product.
mutation UpdateInventory($input: UpdateInventoryInput!) {
updateInventory(input: $input) {
inventory {
productId
available
reserved
inTransit
}
errors {
message
code
}
}
}
Input:
input UpdateInventoryInput {
productId: ID!
warehouseId: ID
available: Int
reserved: Int
inTransit: Int
lowStockThreshold: Int
}
Returns: UpdateInventoryPayload
reserveInventory
Reserve inventory for an order (prevents overselling).
mutation ReserveInventory($orderId: ID!, $items: [InventoryReservationInput!]!) {
reserveInventory(orderId: $orderId, items: $items) {
reservations {
productId
quantity
expiresAt
}
errors {
message
code
}
}
}
Input:
input InventoryReservationInput {
productId: ID!
quantity: Int!
}
Returns: ReserveInventoryPayload
Booking
createAppointment
Create a new appointment.
mutation CreateAppointment($input: CreateAppointmentInput!) {
createAppointment(input: $input) {
appointment {
id
service {
name
}
staff {
name
}
customer {
name
}
startTime
endTime
status
}
errors {
field
message
code
}
}
}
Input:
input CreateAppointmentInput {
serviceId: ID!
staffId: ID!
customerId: ID!
startTime: DateTime!
endTime: DateTime!
notes: String
}
Returns: CreateAppointmentPayload
cancelAppointment
Cancel an appointment.
mutation CancelAppointment($id: ID!, $reason: String) {
cancelAppointment(id: $id, reason: $reason) {
appointment {
id
status
}
errors {
message
code
}
}
}
Returns: CancelAppointmentPayload
Promotions
createPromotion
Create a new promotion.
mutation CreatePromotion($input: CreatePromotionInput!) {
createPromotion(input: $input) {
promotion {
id
name
code
discountType
discountValue
startDate
endDate
}
errors {
field
message
code
}
}
}
Input:
input CreatePromotionInput {
name: String!
description: String
code: String!
discountType: DiscountType!
discountValue: Int!
startDate: DateTime!
endDate: DateTime!
usageLimit: Int
conditions: PromotionConditionsInput
}
enum DiscountType {
PERCENTAGE
FIXED_AMOUNT
FREE_SHIPPING
}
input PromotionConditionsInput {
minPurchaseAmount: Money
productIds: [ID!]
categoryIds: [ID!]
customerIds: [ID!]
}
Returns: CreatePromotionPayload
generateCoupons
Generate multiple unique coupon codes for a promotion.
mutation GenerateCoupons($promotionId: ID!, $count: Int!, $prefix: String) {
generateCoupons(promotionId: $promotionId, count: $count, prefix: $prefix) {
coupons {
code
promotionId
}
count
errors {
message
code
}
}
}
Returns: GenerateCouponsPayload
sendEmail
Send a transactional email.
mutation SendEmail($input: SendEmailInput!) {
sendEmail(input: $input) {
email {
id
to
subject
status
sentAt
}
errors {
message
code
}
}
}
Input:
input SendEmailInput {
to: EmailAddress!
subject: String!
templateId: ID
templateData: JSON
html: String
text: String
}
Returns: SendEmailPayload
Merchant Account
updateMerchantSettings
Update merchant account settings.
mutation UpdateMerchantSettings($input: UpdateMerchantSettingsInput!) {
updateMerchantSettings(input: $input) {
merchantAccount {
id
settings {
currency
timezone
taxRate
}
}
errors {
field
message
code
}
}
}
Input:
input UpdateMerchantSettingsInput {
currency: String
timezone: String
taxRate: Float
shippingZones: [ShippingZoneInput!]
}
Returns: UpdateMerchantSettingsPayload
createApiKey
Create a new API key.
mutation CreateApiKey($name: String!, $permissions: [String!]!) {
createApiKey(name: $name, permissions: $permissions) {
apiKey {
id
name
key # Only shown once!
prefix
permissions
createdAt
}
errors {
message
code
}
}
}
Returns: CreateApiKeyPayload
revokeApiKey
Revoke an API key.
mutation RevokeApiKey($id: ID!) {
revokeApiKey(id: $id) {
success
errors {
message
code
}
}
}
Returns: RevokeApiKeyPayload
Common Patterns
Optimistic Updates
Update UI immediately, roll back on error:
const [updateProduct] = useMutation(UPDATE_PRODUCT, {
optimisticResponse: {
updateProduct: {
product: {
__typename: 'Product',
id: productId,
name: newName,
updatedAt: new Date().toISOString()
},
errors: []
}
}
});
Batch Mutations
Execute multiple mutations in one request:
mutation BatchUpdate {
product1: updateProduct(id: "prod_1", input: { name: "Updated 1" }) {
product { id name }
errors { message }
}
product2: updateProduct(id: "prod_2", input: { name: "Updated 2" }) {
product { id name }
errors { message }
}
}
Error Handling
Always check both resource and errors:
const { data } = await client.mutate({
mutation: CREATE_PRODUCT,
variables: { input }
});
const { product, errors } = data.createProduct;
if (errors && errors.length > 0) {
// Show validation errors
errors.forEach(error => {
console.error(`${error.field}: ${error.message}`);
});
return null;
}
// Success
return product;
Next Steps
- Queries Reference - Fetch data
- Types Reference - Type definitions
- Error Handling Guide - Handle errors properly
- Interactive Playground - Test mutations
Need help? Join our Discord community or check the FAQ!