Every GraphQL schema has a root type for both queries and mutations.

Queries vs Mutations

The difference between queries and mutations defined by GraphQL is that queries are only used to retrieve data, while mutations are used to modify data stored on the server. Therefore, the mutation type can be thought of as analogous to performing HTTP verbs such as POST, PATCH, and DELETE. Otherwise, there are significant similarities: both will require arguments that are provided in the same way and both will result in responses that only contain the requested fields.

Included here are two examples, one more basic and one more complex, to demonstrate some fundamental operations that can be done with the Printavo API. For more detailed information on individual mutations, check out their dedicated documentation, found in the sidebar.

Example Mutation: Update a Contact

mutation {
  contactUpdate(
    id: 1
    input: { email: ["john.doe@example.com", "jane.doe@example.com"] }
  ) {
    id
    email
  }
}

In the above query, the input is being passed in one field, email, which is an array of strings. The email field on the Contact type will return a single string, so the response from the server would look like this, after the update was put into effect:

{
  "data": {
    "contactUpdate": {
      "id": "1",
      "email": "john.doe@example.com, jane.doe@example.com"
    }
  }
}

Example Mutation: Update an Invoice and its Shipping Address

For a more complex example, let's look at an InvoiceUpdate to add customer notes, production notes, tags, a new date, and a new shipping address.


mutation {
  invoiceUpdate(
    id: 123
    input: {
      contact: { id: 456 }
      customerNote: "Extra charge for rush shipping"
      productionNote: "Rush job, make sure this goes out today!"
      customerDueAt: "2023-07-04"
      tags: ["#rush"]
      shippingAddress: {
        companyName: "ACME"
        customerName: "Wile E. Coyote"
        address1: "123 Main Street"
        address2: "Apt. 551"
        city: "Albuquerque"
        stateIso: "NM"
        zipCode: "87121"
      }
    }
  ) {
    id
    contact {
      id
      email
    }
    customerNote
    productionNote
    customerDueAt
    tags
    shippingAddress {
      companyName
      customerName
      address1
      address2
      city
      stateIso
      zipCode
    }
  }
}

In the above request, the user is passing multiple fields into the input, each with their own arguments. The response from the server would include all of the newly-updated fields:

{
  "data": {
    "invoiceUpdate": {
      "id": "123",
      "contact": {
        "id": "456",
        "email": "wily.e.coyote@acme.com, road.runner@acme.com"
      },
      "customerNote": "Extra charge for rush shipping",
      "productionNote": "Rush job, make sure this goes out today!",
      "customerDueAt": "2023-07-04",
      "tags": [
        "#rush"
      ],
      "shippingAddress": {
        "companyName": "ACME",
        "customerName": "Wile E. Coyote",
        "address1": "123 Main Street",
        "address2": "Apt. 551",
        "city": "Albuquerque",
        "stateIso": "NM",
        "zipCode": "87121"
      }
    }
  }
}

As a note, while it is not mandatory for a request to ask for all of the modified fields to be included in the response, it is generally good practice to do so, as it allows the user to verify that their input has been processed as expected.

Continued Reading

The above are just a few select examples to demonstrate what GraphQL mutations can do. In order to learn more, check out GraphQL's official documentation!