Create or update customer

Note: You can download a postman example of the below queries in this article's attachments.

Unicity Check

When creating or updating customers, the Customer Code is usually used as the unique identifier. Because of this, it is good practice to check for existence before creating a new customer.

To do so, you can run the following query :

{
  customers(last: 10, filter: {code: "enter customer code here"}) {
    edges {
      node {
        code
        description
        dbId
        companyDbId
      }
    }
  }
}

If the answer is as follows, it means the customer doesn't exist and you can proceed to create it :

{
  "data": {
    "customers": {
       "edges": null
    }
  }
}

If the answer is as follows, it means the customer exists and you can proceed to update it :

{
  "data": {
    "customers": {
      "edges": [
        {
          "node": {
            "code": "code",
            "dbId": 12345678,
            "description": "description",
            "companyDbId": 22345678
          }
        }
      ]
    }
  }
}

Note: If the existence query returns more than one result, it means multiple entries of the queried resource share the same code. This might cause issues when unicity is needed in mutations, for example when creating an invoice against a customer. It would be a good idea to sanitize the data should that happen.

Customer creation

Customers in Xledger are linked to companies, therefore a company needs to be created first as follows :

mutation{
  addCompanies(inputs: [{node: {
    code: "123412341234"
    description: "test"
  }}]) {
    edges {
      node {
        dbId
      }
    }
  }
}

Note: Typically in the UK we have a 1:1 relationship between customer and company. If your use case is different you might need to also check for company existence as well as customer existence before creating a new company for each customer.

Here is an example of customer creation, mandatory fields are company dbId (from the mutation above), code and description only, use the rest according to your needs.

mutation{
  addCustomers(inputs: [{node: {
    company: {dbId: 27809941}
    code: "123412341234"
    description: "test"
    email: ""
    bankAccount: ""
    country: {code: "GB"}
    streetAddress: ""
    zipCode: ""
    place: ""
    streetAddress2: ""
    zipCode2: ""
    place2: ""
    country2: {code: "GB"}
  }}]) {
    edges {
      node {
        dbId
      }
    }
  }
}

Note: If countries are passed, ISO Alpha-2 country codes need to be used.

Customer update

If updating the customer code and description, it is advised to also update the company to reflect this. Here is an example of the company update mutation :

mutation{
  updateCompanies(inputs: [{node: {
    dbId: 28618955
    code: "123412341234"
    description: "test"
  }}]) {
    edges {
      node {
        dbId
      }
    }
  }
}

Here is an example of a customer update, dbId and Company dbId are returned by the existence check, use this to specify which customer to update.

mutation{
  updateCustomers(inputs: [{node: {
    dbId: 28618888
    code: "123412341234"
    description: "test"
    email: ""
    bankAccount: ""
    country: {code: "GB"}
    streetAddress: ""
    zipCode: ""
    place: ""
    streetAddress2: ""
    zipCode2: ""
    place2: ""
    country2: {code: "GB"}
  }}]) {
    edges {
      node {
        dbId
      }
    }
  }
}