Skip to content

New: AI agent integration via Model Context Protocol (MCP).Learn more

EvolveEvolvePlatform documentation

Mutations

All write operations exposed by the Evolve GraphQL gateway.

businessUnitAddressCreate

Section titled “businessUnitAddressCreate”
businessUnitAddressCreate(
  address: AddressInput!
  businessUnitId: ID!
): BusinessUnitAddressCreateResponse!

Add a new address to a business unit

Example:

mutation {
  businessUnitAddressCreate(
    businessUnitId: "bu-123"
    address: {
      firstName: "Business"
      lastName: "Contact"
      streetName: "Business Street"
      streetNumber: "100"
      city: "Amsterdam"
      postalCode: "1000AA"
      country: "NL"
    }
  ) {
    businessUnit {
      id
      addresses {
        id
        firstName
        lastName
        city
      }
    }
    errors {
      ... on ValidationError {
        message
      }
    }
  }
}

Returns: BusinessUnitAddressCreateResponse!

Arguments

businessUnitAddressDelete

Section titled “businessUnitAddressDelete”
businessUnitAddressDelete(
  addressId: ID!
  businessUnitId: ID!
): BusinessUnitAddressDeleteResponse!

Remove an address from a business unit

Example:

mutation {
  businessUnitAddressDelete(
    businessUnitId: "bu-123"
    addressId: "addr-456"
  ) {
    businessUnit {
      id
      addresses {
        id
        city
      }
    }
    errors {
      ... on ValidationError {
        message
      }
    }
  }
}

Returns: BusinessUnitAddressDeleteResponse!

Arguments

  • addressId: ID!
  • businessUnitId: ID!

businessUnitAddressUpdate

Section titled “businessUnitAddressUpdate”
businessUnitAddressUpdate(
  address: AddressInput!
  addressId: ID!
  businessUnitId: ID!
): BusinessUnitAddressUpdateResponse!

Update an existing address in a business unit

Example:

mutation {
  businessUnitAddressUpdate(
    businessUnitId: "bu-123"
    addressId: "addr-456"
    address: {
      firstName: "Updated Business"
      lastName: "Contact"
      streetName: "New Business Street"
      streetNumber: "200"
      city: "Rotterdam"
      postalCode: "2000BB"
      country: "NL"
    }
  ) {
    businessUnit {
      id
      addresses {
        id
        firstName
        lastName
        city
      }
    }
    errors {
      ... on ValidationError {
        message
      }
    }
  }
}

Returns: BusinessUnitAddressUpdateResponse!

Arguments

businessUnitAssociateInvite

Section titled “businessUnitAssociateInvite”
businessUnitAssociateInvite(
  businessUnitId: ID!
  email: String!
  roleIDs: [ID!]!
): BusinessUnitAssociateInviteResponse!

Invite a new associate to the business unit with specified roles

Example:

mutation {
  businessUnitAssociateInvite(
    businessUnitId: "bu-123"
    email: "new.associate@company.com"
    roleIDs: ["role-admin", "role-buyer"]
  ) {
    businessUnit {
      id
      associates {
        id
        email
        roles {
          id
          key
        }
      }
    }
    errors {
      ... on ValidationError {
        message
      }
    }
  }
}

Returns: BusinessUnitAssociateInviteResponse!

Arguments

  • businessUnitId: ID!
  • email: String!
  • roleIDs: [ID!]!

businessUnitAssociateRemove

Section titled “businessUnitAssociateRemove”
businessUnitAssociateRemove(
  businessUnitId: ID!
  customerId: ID!
): BusinessUnitAssociateRemoveResponse!

Remove an associate from the business unit

Example:

mutation {
  businessUnitAssociateRemove(
    businessUnitId: "bu-123"
    customerId: "customer-456"
  ) {
    businessUnit {
      id
      associates {
        id
        email
      }
    }
    errors {
      ... on ValidationError {
        message
      }
    }
  }
}

Returns: BusinessUnitAssociateRemoveResponse!

Arguments

  • businessUnitId: ID!
  • customerId: ID!

businessUnitAssociateRolesUpdate

Section titled “businessUnitAssociateRolesUpdate”
businessUnitAssociateRolesUpdate(
  businessUnitId: ID!
  customerId: ID!
  roleIDs: [ID!]!
): BusinessUnitAssociateRolesUpdateResponse!

Update associate roles for an existing associate in the business unit Note: All current roles will be replaced with the provided roles

Example:

mutation {
  businessUnitAssociateRolesUpdate(
    businessUnitId: "bu-123"
    customerId: "customer-456"
    roleIDs: ["role-buyer", "role-viewer"]
  ) {
    businessUnit {
      id
      associates {
        id
        email
        roles {
          id
          key
        }
      }
    }
    errors {
      ... on ValidationError {
        message
      }
    }
  }
}

Returns: BusinessUnitAssociateRolesUpdateResponse!

Arguments

  • businessUnitId: ID!
  • customerId: ID!
  • roleIDs: [ID!]!

createGuestSession

Section titled “createGuestSession”
createGuestSession: CreateGuestSessionResponse!

Create a guest session for anonymous users. This is useful for initializing a session before any cart or account operations. The @requiresSession(create: true) directive ensures the gateway creates a session if one doesn’t exist.

Example:

mutation {
  createGuestSession {
    success
  }
}

Returns: CreateGuestSessionResponse!

customerAddressCreate

Section titled “customerAddressCreate”
customerAddressCreate(
  address: AddressInput!
): CustomerAddressCreateResponse!

Add a new address to the customer’s address book

Example:

mutation {
  customerAddressCreate(address: {
    firstName: "John"
    lastName: "Doe"
    streetName: "Secondary Street"
    streetNumber: "456"
    city: "Rotterdam"
    postalCode: "2000BB"
    country: "NL"
  }) {
    customer {
      id
      addresses {
        id
        firstName
        lastName
        city
      }
    }
    errors {
      ... on ValidationError {
        message
      }
    }
  }
}

Returns: CustomerAddressCreateResponse!

Arguments

customerAddressDelete

Section titled “customerAddressDelete”
customerAddressDelete(
  addressId: ID!
): CustomerAddressDeleteResponse!

Remove an address from the customer’s address book

Example:

mutation {
  customerAddressDelete(addressId: "addr-123") {
    customer {
      id
      addresses {
        id
        city
      }
    }
    errors {
      ... on ValidationError {
        message
      }
    }
  }
}

Returns: CustomerAddressDeleteResponse!

Arguments

  • addressId: ID!

customerAddressUpdate

Section titled “customerAddressUpdate”
customerAddressUpdate(
  address: AddressInput!
  addressId: ID!
): CustomerAddressUpdateResponse!

Update an existing address in the customer’s address book

Example:

mutation {
  customerAddressUpdate(
    addressId: "addr-123"
    address: {
      firstName: "John"
      lastName: "Doe"
      streetName: "Updated Street"
      streetNumber: "789"
      city: "Utrecht"
      postalCode: "3000CC"
      country: "NL"
    }
  ) {
    customer {
      id
      addresses {
        id
        firstName
        lastName
        city
      }
    }
    errors {
      ... on ValidationError {
        message
      }
    }
  }
}

Returns: CustomerAddressUpdateResponse!

Arguments

customerCreate

Section titled “customerCreate”
customerCreate(
  customer: CustomerCreateInput!
): CustomerCreateResponse!

Create a new customer account with email and password

Example:

mutation {
  customerCreate(customer: {
    email: "john.doe@example.com"
    password: "securePassword123"
    givenName: "John"
    familyName: "Doe"
    salutation: MR
  }) {
    id
    email
    givenName
    familyName
  }
}

Returns: CustomerCreateResponse!

Arguments

customerDelete

Section titled “customerDelete”
customerDelete(
  password: String!
): CustomerDeleteResponse!

Delete the current customer account (requires password confirmation)

Example:

mutation {
  customerDelete(password: "currentPassword123") {
    success
    errors {
      ... on ValidationError {
        message
      }
    }
  }
}

Returns: CustomerDeleteResponse!

Arguments

  • password: String!

customerEmailUpdate

Section titled “customerEmailUpdate”
customerEmailUpdate(
  email: EmailAddress!
  password: String!
): CustomerEmailUpdateResponse!

Update customer email address (requires password for verification)

Example:

mutation {
  customerEmailUpdate(
    email: "newemail@example.com"
    password: "currentPassword123"
  ) {
    customer {
      id
      email
    }
    errors {
      ... on ValidationError {
        message
      }
    }
  }
}

Returns: CustomerEmailUpdateResponse!

Arguments

customerInformationUpdate

Section titled “customerInformationUpdate”
customerInformationUpdate(
  billingAddress: AddressInput!
): CustomerInformationUpdateResponse!

Update customer billing address information

Example:

mutation {
  customerInformationUpdate(billingAddress: {
    firstName: "John"
    lastName: "Doe"
    streetName: "Main Street"
    streetNumber: "123"
    city: "Amsterdam"
    postalCode: "1000AA"
    country: "NL"
  }) {
    customer {
      id
      billingAddress {
        firstName
        lastName
        city
      }
    }
    errors {
      ... on ValidationError {
        message
      }
    }
  }
}

Returns: CustomerInformationUpdateResponse!

Arguments

customerLogin

Section titled “customerLogin”
customerLogin(
  email: EmailAddress!
  password: String!
): CustomerLoginResponse!

Authenticate a customer with email and password

Example:

mutation {
  customerLogin(
    email: "john.doe@example.com"
    password: "securePassword123"
  ) {
    id
    email
    givenName
    familyName
  }
}

Returns: CustomerLoginResponse!

Arguments

customerLogout

Section titled “customerLogout”
customerLogout: CustomerLogoutResponse!

Log out the current customer and invalidate the session

Example:

mutation {
  customerLogout {
    success
    errors {
      ... on ValidationError {
        message
      }
    }
  }
}

Returns: CustomerLogoutResponse!

customerPasswordReset

Section titled “customerPasswordReset”
customerPasswordReset(
  password: String!
  token: String!
): CustomerPasswordResetResponse!

Reset customer password using a reset token received via email

Example:

mutation {
  customerPasswordReset(
    token: "reset-token-from-email"
    password: "newSecurePassword789"
  ) {
    customer {
      id
      email
    }
    errors {
      ... on PasswordResetError {
        code
        message
      }
      ... on ValidationError {
        message
      }
    }
  }
}

Returns: CustomerPasswordResetResponse!

Arguments

  • password: String!
  • token: String!

customerPasswordResetRequest

Section titled “customerPasswordResetRequest”
customerPasswordResetRequest(
  email: EmailAddress!
): CustomerPasswordResetRequestResponse!

Request a password reset email for the given email address

Example:

mutation {
  customerPasswordResetRequest(email: "john.doe@example.com")
}

Returns: CustomerPasswordResetRequestResponse!

Arguments

customerPasswordUpdate

Section titled “customerPasswordUpdate”
customerPasswordUpdate(
  newPassword: String!
  password: String!
): CustomerPasswordUpdateResponse!

Update customer password (requires current password for verification)

Example:

mutation {
  customerPasswordUpdate(
    password: "currentPassword123"
    newPassword: "newSecurePassword456"
  ) {
    id
    email
  }
}

Returns: CustomerPasswordUpdateResponse!

Arguments

  • newPassword: String!
  • password: String!

refreshToken

Section titled “refreshToken”
refreshToken: RefreshTokenResponse!

Refresh the authentication token for the current session

Example:

mutation {
  refreshToken {
    success
    errors {
      ... on ValidationError {
        message
      }
    }
  }
}

Returns: RefreshTokenResponse!

setActiveBusinessContext

Section titled “setActiveBusinessContext”
setActiveBusinessContext(
  businessUnitId: ID!
  storeKey: String!
): SetActiveBusinessContextResponse!

Set the active business context for B2B operations

Example:

mutation {
  setActiveBusinessContext(
    businessUnitId: "bu-123"
    storeKey: "nl-store"
  ) {
    success
    errors {
      ... on ValidationError {
        message
      }
    }
  }
}

Returns: SetActiveBusinessContextResponse!

Arguments

  • businessUnitId: ID!
  • storeKey: String!

shoppingListCreate

Section titled “shoppingListCreate”
shoppingListCreate(
  shoppingList: ShoppingListInput!
): ShoppingListCreateResponse!

Create a new shopping list for the current user

Example:

mutation {
  shoppingListCreate(shoppingList: {
    name: "Office Supplies"
    description: "Items needed for the office"
  }) {
    shoppingList {
      id
      name
      description
      lineItems {
        id
        sku
        quantity
      }
    }
  }
}

Returns: ShoppingListCreateResponse!

Arguments

shoppingListDelete

Section titled “shoppingListDelete”
shoppingListDelete(
  id: ID!
): ShoppingListDeleteResponse!

Delete a shopping list permanently

Example:

mutation {
  shoppingListDelete(id: "sl-123") {
    shoppingList {
      id
      name
    }
  }
}

Returns: ShoppingListDeleteResponse!

Arguments

  • id: ID!

shoppingListLineItemsAdd

Section titled “shoppingListLineItemsAdd”
shoppingListLineItemsAdd(
  id: ID
  items: [ShoppingListLineItemAddInput!]!
): ShoppingListLineItemAddResponse!

Add products to a shopping list Note: “id” is optional for B2C/anonymous users - if not provided, a new list is created

Example:

mutation {
  shoppingListLineItemsAdd(
    id: "sl-123"
    items: [
      {
        sku: "SKU-001"
        quantity: 2
      },
      {
        sku: "SKU-002"
        quantity: 1
      }
    ]
  ) {
    shoppingList
      id
      lineItems
        id
        sku
        quantity
  }
}

Returns: ShoppingListLineItemAddResponse!

Arguments

shoppingListLineItemsRemove

Section titled “shoppingListLineItemsRemove”
shoppingListLineItemsRemove(
  id: ID!
  itemIds: [String!]!
): ShoppingListLineItemRemoveResponse!

Remove specific items from a shopping list

Example:

mutation {
  shoppingListLineItemsRemove(
    id: "sl-123"
    itemIds: ["li-456", "li-789"]
  ) {
    shoppingList {
      id
      lineItems {
        id
        sku
      }
    }
  }
}

Returns: ShoppingListLineItemRemoveResponse!

Arguments

  • id: ID!
  • itemIds: [String!]!

shoppingListLineItemsUpdate

Section titled “shoppingListLineItemsUpdate”
shoppingListLineItemsUpdate(
  id: ID!
  items: [ShoppingListLineItemUpdateInput!]!
): ShoppingListLineItemUpdateResponse!

Update quantities or other properties of existing shopping list items

Example:

mutation {
  shoppingListLineItemsUpdate(
    id: "sl-123"
    items: [
      {
        id: "li-456"
        quantity: 5
      },
      {
        id: "li-789"
        quantity: 3
      }
    ]
  ) {
    shoppingList {
      id
      lineItems {
        id
        sku
        quantity
      }
    }

Returns: ShoppingListLineItemUpdateResponse!

Arguments

shoppingListUpdate

Section titled “shoppingListUpdate”
shoppingListUpdate(
  id: ID!
  shoppingList: ShoppingListInput!
): ShoppingListUpdateResponse!

Update an existing shopping list’s information

Example:

mutation {
  shoppingListUpdate(
    id: "sl-123"
    shoppingList: {
      name: "Updated Office Supplies"
      description: "Updated items needed for the office"
    }
  ) {
    shoppingList {
      id
      name
      description
    }
  }
}

Returns: ShoppingListUpdateResponse!

Arguments

_empty

Section titled “_empty”
_empty: String

Placeholder query to satisfy schema requirements for federation

Returns: String

cartDiscountCodeAdd

Section titled “cartDiscountCodeAdd”
cartDiscountCodeAdd(
  code: String!
  id: ID!
): CartDiscountCodeAddResponse!

Apply a discount code to the cart

Example:

mutation {
  cartDiscountCodeAdd(
    id: "cart-123",
    code: "SAVE10"
  ) {
    id
    version
    discountCodes {
      discountCode {
        id
        code
      }
      state
    }
    totalPrice {
      value
      currencyCode
    }
  }
}

Returns: CartDiscountCodeAddResponse!

Arguments

  • code: String!
  • id: ID!

cartDiscountCodeRemove

Section titled “cartDiscountCodeRemove”
cartDiscountCodeRemove(
  discountCodeId: ID!
  id: ID!
): CartDiscountCodeRemoveResponse!

Remove a discount code from the cart

Example:

mutation {
  cartDiscountCodeRemove(
    id: "cart-123",
    discountCodeId: "discount-456"
  ) {
    id
    version
    discountCodes {
      discountCode {
        id
        code
      }
    }
    totalPrice {
      value
      currencyCode
    }
  }
}

Returns: CartDiscountCodeRemoveResponse!

Arguments

  • discountCodeId: ID!
  • id: ID!

cartLineItemsAdd

Section titled “cartLineItemsAdd”
cartLineItemsAdd(
  id: ID
  lineItems: [CartLineItemCreateInput!]!
): CartLineItemsAddResponse!

Add line items to cart or create a new cart

Returns: CartLineItemsAddResponse!

Arguments

cartLineItemsRemove

Section titled “cartLineItemsRemove”
cartLineItemsRemove(
  id: ID!
  lineItemIds: [String!]!
): CartLineItemsRemoveResponse!

Remove line items from the cart

Returns: CartLineItemsRemoveResponse!

Arguments

  • id: ID!
  • lineItemIds: [String!]!

cartLineItemsUpdate

Section titled “cartLineItemsUpdate”
cartLineItemsUpdate(
  id: ID!
  lineItems: [CartLineItemUpdateInput!]!
): CartLineItemsUpdateResponse!

Update quantities of existing line items

Returns: CartLineItemsUpdateResponse!

Arguments

cartUpdate

Section titled “cartUpdate”
cartUpdate(
  actions: [CartUpdateAction!]!
  id: ID!
): CartUpdateResponse!

Update cart with various actions

Returns: CartUpdateResponse!

Arguments

checkoutComplete

Section titled “checkoutComplete”
checkoutComplete(
  id: ID!
  paymentContext: PaymentContextInput!
): CheckoutCompleteResponse!

Complete the checkout process, create an order, and initiate payment

Returns: CheckoutCompleteResponse!

Arguments

  • id: ID! — Cart ID to complete checkout for
  • paymentContext: PaymentContextInput! — Payment context for initiating payment

createPayment

Section titled “createPayment”
createPayment(
  paymentContext: PaymentContextInput!
): CreatePaymentResponse!

Create a payment for an order or cart

Example:

mutation {
  createPayment(paymentContext: {
    method: {
      internalId: "pm-123"
      provider: "stripe"
    }
    successUrl: "https://mystore.com/checkout/success"
    failureUrl: "https://mystore.com/checkout/failure"
  }) {
    payment {
      redirectURL
    }
    paymentErrors {
      ... on PaymentCreateError {
        code
        message
      }
    }
  }
}

Returns: CreatePaymentResponse!

Arguments

validateApplePayPayment

Section titled “validateApplePayPayment”
validateApplePayPayment(
  paymentContext: ApplePayPaymentContextInput!
): ValidateApplePayPaymentResponse!

Validate an Apple Pay payment method and retrieve payment data Used for Apple Pay payment processing integration

Example:

mutation {
  validateApplePayPayment(paymentContext: {
    merchantIdentifier: "merchant.com.mystore"
    domainName: "mystore.com"
    displayName: "My Store Purchase"
  }) {
    data
    applePayErrors {
      ... on ValidationError {
        message
      }
    }
  }
}

Returns: ValidateApplePayPaymentResponse!

Arguments

authoringFinalizeUploadedAsset

Section titled “authoringFinalizeUploadedAsset”
authoringFinalizeUploadedAsset(
  input: AuthoringFinalizeUploadedAssetInput!
): AuthoringFinalizeUploadedAssetResult!

Finalise a streaming asset upload. The bytes themselves are streamed from the chrome through authoring-ai directly to Contentful’s upload service — they never round-trip through this mutation as a buffered payload. This call receives the resulting uploadId plus caller-supplied metadata, creates the Asset entry, runs processForAllLocales, polls until processing completes, then publishes. Returns the public CDN URL the chrome rewrites into PageData before calling authoringPushPage.

Returns: AuthoringFinalizeUploadedAssetResult!

Arguments

authoringPreparePublishEntries

Section titled “authoringPreparePublishEntries”
authoringPreparePublishEntries(
  input: AuthoringPreparePublishEntriesInput!
): AuthoringPreparePublishEntriesResult!

Pre-publish validation + locale-backfill. Given the entry ids from a preceding authoringPushPage, fetches each entry, finds any required-localized field whose target locale is empty, and copies a value from any sibling locale that has one. Returns the list of fixes plus any deterministic-unfixable issues so the caller can halt before invoking authoringPublishEntries. No-op for entries that already validate; safe to chain on every workflow.

Returns: AuthoringPreparePublishEntriesResult!

Arguments

authoringPublishEntries

Section titled “authoringPublishEntries”
authoringPublishEntries(
  input: AuthoringPublishEntriesInput!
): AuthoringPublishEntriesResult!

Publish a set of entries via Contentful’s Bulk Action API. The bulk action handles dependency ordering automatically (children before parents), so passing the full list returned from authoringPushPage is enough — no need to topologically sort on the caller side. Blocks until the bulk action reaches a terminal status (succeeded / failed), polling Contentful every 1s with a 60s timeout. Use from a workflow step that wants to flip a push-page result to Published in one call.

Returns: AuthoringPublishEntriesResult!

Arguments

authoringPushPage

Section titled “authoringPushPage”
authoringPushPage(
  input: AuthoringPushPageInput!
): AuthoringPushResult!

Push an authored page (gateway-shape PageData) to the CMS. The editor sends the page as JSON; the subgraph flattens it into Contentful entries, diffs against existing entries (preserving ids to avoid duplicates), topologically sorts by dependency, and persists via Management API using the editor user’s OAuth token. Asset upload is not supported here — image references must already be Contentful CDN URLs (use authoringSearchAssets to pick from the library).

Returns: AuthoringPushResult!

Arguments

storeContentPreview

Section titled “storeContentPreview”
storeContentPreview(
  data: String!
  path: String!
): StoreContentPreviewResponse!

Store content preview data for a specific path to enable content previewing Used by CMS editors to preview unpublished content changes

Example:

mutation {
  storeContentPreview(
    path: "/about-us"
    data: "{"title":"About Us","content":[{"type":"text","value":"Updated content"}]}"
  ) {
    id
  }
}

Returns: StoreContentPreviewResponse!

Arguments

  • data: String!
  • path: String!

quoteRequestCreate

Section titled “quoteRequestCreate”
quoteRequestCreate(
  args: QuoteRequestCreateArgsInput!
  id: ID!
): QuoteRequestCreateResponse!

Create a quote request from a cart

Returns: QuoteRequestCreateResponse!

Arguments