Documentation

Create a GraphQL mutation

Elevate, May 20-22-2025, Miami Beach, Florida

Learn how to create, update, and delete Composable Commerce resources with GraphQL.

  • After completing this page, you should be able to:

    • Identify GraphQL mutations that successfully create, update, and delete resources in Composable Commerce.

    • We know that GraphQL is great for retrieving data. GraphQL can also create, update, and delete Composable Commerce resources. In GraphQL we call these actions mutations, not queries.

    With mutations in Composable Commerce, we specify an update action and the new values. The way that update actions work here is the same as how they work with the REST API.

    Use mutations to create resources

    How do you create a Customer with the API? As you learned in the Manage resources with the SDK module, you send a Draft record. In a GraphQL mutation, to create a Customer we have to specify the action customerSignUp and enter the values in a Customer draft record. You must enter all required values-for Customer, only email and password are required. To understand the address information and how to indicate the default shipping address, visit the API reference.
    As in a GraphQL query, we can ask to have values returned—in this case, we are asking for the generated id and version along with a few other fields.
    mutation createCustomer {
  customerSignUp(
    draft: {
      email: "martha.jones@example.com"
      firstName: "Martha"
      lastName: "Jones"
      password: "password"
      addresses: { country: "DE" }
      defaultShippingAddress: 0
    }
  ) {
    customer {
      id
      version
      email
      defaultShippingAddress {
        country
      }
    }
  }
}

    Our response looks like this:

    {
  "data": {
    "customerSignUp": {
      "customer": {
        "id": "57def72f-c92c-437e-a35c-f6216f780bea",
        "version": 1,
        "email": "martha.jones@example.com",
        "defaultShippingAddress": {
          "country": "DE"
        }
      }
    }
  }
}

    Does it really work like a REST request? Yes. We can also check in the Merchant Center if our request was successful:

    Example of Martha Jones having been created in the Customer List in Merchant Center.

    Use mutations to update resources

    As a developer working with Composable Commerce, you already know that to update a Composable Commerce resource you have to provide not only the id or key to specify which record you want to update but also the version number of the record handling concurrent updates. You also have to provide the actions you want to perform and any required values for that action (see our Manage resources with the SDK module section on version control).
    This is the same if you are using a GraphQL mutation to update the data. Here’s an example of updating an existing Customer record to set the firstName to a new value:
    mutation updateCustomer {
  updateCustomer(
    id: "{id}"
    version: 1
    actions: [{ setFirstName: { firstName: "Jan" } }]
  ) {
    version
    firstName
    lastName
    email
  }
}
    We’ve used the id and version to identify the record and then have one action in our array of actions to indicate we want to set the firstName field to the value Jan. It is possible to have multiple updates to one record with GraphQL, just like using the REST API and we can request which data we want to have returned.

    The above query would return:

    {
  "data": {
    "updateCustomer": {
      "version": 2,
      "firstName": "Jan",
      "lastName": "Johns",
      "email": "martha.johns@sportforall.com"
    }
  }
}

    Use mutations to delete resources

    GraphQL can be used for all actions in the resource life cycle management, including the deletion of resources. Just as with updating resources, to delete a resource we have to identify the resource and also provide the correct version number.

    Here’s an example of deleting a Customer:

    mutation deleteCustomer {
  deleteCustomer(id: "{id}", version: 2) {
    id
    version
    firstName
    lastName
    email
  }
}

    Notice that even with a delete action, we can request values to be returned from the record we are deleting.

    The above delete action would return:

    {
  "data": {
    "deleteCustomer": {
      "id": "{id}",
      "version": 2,
      "firstName": "Jan",
      "lastName": "Jones",
      "email": "martha.jones@example.com"
    }
  }
}
    For more examples on Composable Commerce GraphQL queries and mutations, check out our Get started with GraphQL guide in the docs.

    Test your knowledge