In GraphQL, API requests that are intended to change the data in the API (e.g. adding a new order to the system) are called Mutations. Unlike queries, which only read data, mutations can be used to write, update or delete data.

The syntax of a mutation query in the Aptus OMS API look like the following:

mutation{
  updateOrderStatus(id: "ckip2fskk11681zqp8u4tcdmy", status: COMPLETE){
    id
    number
    status
    urgency
    totalPrice
    totalTax
    totalSize
  }
}

Mutations start with the mutation keyword, and any variables can be defined from there. All mutations accept parameters. In this case, we’re updating the status field of an order given it’s id, as well as returning the id, number, status, urgency, totalPrice, totalTax and totalSize fields.

The mutation will return the defined data if it’s successful. If it fails - for example when the user is trying to update the status of an order that doesn’t exists or when the user doesn’t have sufficient permissions to perform the action being attempted - it will instead return an empty data object and an errors object.

Each type of mutation has different parameters. The specific parameters are documented in the GraphQL schema, wich you can always find in detail here.

createOrder

The createOrder mutation query creates a new order with the following fields: number and input, in this last one you must specify the other subfields and it’s corresponding values, like in the query below.

mutation{
  createOrder(
    number: 4,
    input: {
      totalPrice: 40.5
      totalTax: 25.5
      note: "Order example"
      externalNotes1: "No external note 1"
      externalNotes2: "No external note 2"
      dueDate: "2020-12-10T02:31:30.900Z"
      customerId: "ckidq5eg80028b0dyudw99rfi"
      items: {
        name: "Order"
        totalPrice: 30.5
        totalTax: 20
        width: 3.5
        height: 4.5
        pieces: 3
        materialId: "ckio06lkp03691zqpc96f37lh"
        filePath: "https://devorders.priusintelli.com/static/media/noimage.png"
      }
      status: ACCEPTED
      urgency: 2
    }
    ){
    id
    number
    status
    urgency
    totalPrice
    dueDate
    createdAt
    updatedAt
  }
}

Response: a new order added to the system with it’s corresponding values.

{
  "data": {
    "createOrder": {
      "id": "ckip2fskk11681zqp8u4tcdmy",
      "number": 4,
      "status": "ACCEPTED",
      "urgency": 2,
      "totalPrice": 40.5,
      "dueDate": "2020-12-10T02:31:30.900Z",
      "createdAt": "2020-12-14T21:25:14.468Z",
      "updatedAt": "2020-12-14T21:25:14.469Z"
    }

changePassword

The changePassword mutation query changes the user password just by providing the old password, the API will find for the user and then update the user’s password with the new one provided in the mutation query arguments.

mutation($old: String!, $new: String!){
  changePassword(oldPassword: $old, newPassword: $new){
    id
    name
    email
    role
  }
}

Response: the user’s information updated with the new pasword.

{
  "data": {
    "changePassword": {
      "id": "ckidq5cnd0000b0dywp3xevzb",
      "name": "Admin",
      "email": "admin",
      "role": "EXECUTIVE"
    }
  }
}

updateOrder

The updateOrder query updates the order data by providing the id of the order as well as the input field in which the new data to be updated is included, input receives the following subfields.

mutation{
  updateOrder(
    id: "ckip2fskk11681zqp8u4tcdmy",
    input: {
      totalPrice: 40.5
      totalTax: 25.5
      note: "Order example"
      externalNotes1: "No external note 1"
      externalNotes2: "No external note 2"
      dueDate: "2020-12-10T02:31:30.900Z"
      customerId: "ckidq5eg80028b0dyudw99rfi"
      items: {
        name: "Order"
        totalPrice: 30.5
        totalTax: 20
        width: 3.5
        height: 4.5
        pieces: 3
        materialId: "ckio06lkp03691zqpc96f37lh"
        filePath: "https://devorders.priusintelli.com/static/media/noimage.png"
      }
      status: ACCEPTED
      urgency: 2
    }
    ){
    id
    number
    status
    urgency
    totalPrice
  }
}

Response: returns the updated order with the new data.

{
  "data": {
    "updateOrder": {
      "id": "ckip2fskk11681zqp8u4tcdmy",
      "number": 4,
      "status": "ACCEPTED",
      "urgency": 2,
      "totalPrice": 40.5
    }
  }
}

updateOrderNote

The updateOrderNote mutation query updates the note attached to the order, it receives as an argument the id of the order and the note you want to attach to the order.

mutation{
  updateOrderNote(id: "ckip2fskk11681zqp8u4tcdmy", note: "Note example"){
    id
    number
    status
    urgency
    totalPrice
    note
  }
}

Response: returns the updated note attached to the order, as well as the order fields you specified previously.

{
  "data": {
    "updateOrderNote": {
      "id": "ckip2fskk11681zqp8u4tcdmy",
      "number": 4,
      "status": "ACCEPTED",
      "urgency": 2,
      "totalPrice": 40.5,
      "note": "Note example"
    }
  }
}

createCustomer

The createCustomer mutation query creates a new customer with the provided data, this query only takes an input argument where different fields and subfields are derived that must be required in order to create a new customer.

mutation{
  createCustomer(input: {
  name: "ABC company" 
  personName: "Jhon Doe"
  phone: "84435326"
  email: "jhondoe@email.com"
  identificationNumber: "110723532"
  taxIdentificationNumber: "2233093"
  note: "Example"
  addresses: {
    street: "Av 3"
    number: "1921373"
    city: "San Jose"
    postNumber: "1092334"
    isPrimary: true
    } 
  }){
    id
    name
    email
    phone
    identificationNumber
    taxIdentificationNumber
    personName
    note
  }
}

Response: returns a new customer with the specified data.

{
  "data": {
    "createCustomer": {
      "id": "ckisofbiq00571zl8kh58tyvm",
      "name": "ABC company",
      "email": "jhondoe@email.com",
      "phone": "84435326",
      "identificationNumber": "110723532",
      "taxIdentificationNumber": "2233093",
      "personName": "Jhon Doe",
      "note": "Example"
    }
  }
}