Customers

Customer is a type of object that can be used to store and organize payment methods. A single customer can have multiple payment methods. This guide will demonstrate how to create, update, delete, and search for a customer object.

CreateAnchorIcon

You can create a customer object using the createCustomer mutation. This mutation has no required inputs, so you can choose which inputs are important for your needs.

With customer inputAnchorIcon

You can provide customer input that includes fields like firstName, lastName, company and more to create a customer with the characteristics that you pass in. For a full list of customer input options, check the reference for CustomerInput.

  1. Mutation
mutation CreateCustomer($input: CreateCustomerInput!) {
  createCustomer(input: $input) {
    customer {
      id
      legacyId
      firstName
      lastName
      company
    }
  }
}
  1. Variables
{
  "input": {
    "customer": {
      "firstName": "Luke",
      "lastName": "Skywalker",
      "company": "Rebellion"
    }
  }
}
  1. Response
{
  "data": {
    "createCustomer": {
      "customer": {
        "id": "id_of_customer",
        "legacyId": "legacy_id_of_customer",
        "firstName": "Luke",
        "lastName": "Skywalker",
        "company": "Rebellion"
      }
    }
  },
  "extensions": { "requestId": "a-uuid-for-the-request" }
}

Blank customerAnchorIcon

Since the createCustomer mutation doesn't have any required inputs, you can create a blank customer and add fields to it later.

  1. Mutation
mutation CreateCustomer($input: CreateCustomerInput!) {
  createCustomer(input: $input) {
    customer {
      id
      legacyId
      firstName
      lastName
      company
    }
  }
}
  1. Variables
{ "input": {} }
  1. Response
{
  "data": {
    "createCustomer": {
      "customer": {
        "id": "id_of_customer",
        "legacyId": "legacy_id_of_customer",
        "firstName": null,
        "lastName": null,
        "company": null
      }
    }
  },
  "extensions": { "requestId": "a-uuid-for-the-request" }
}

Use custom fieldsAnchorIcon

You can use custom fields to store additional data about your customers. You'll need to configure your custom fields in the Control Panel to use them via the API.

  1. Mutation
mutation CreateCustomer($input: CreateCustomerInput!) {
  createCustomer(input: $input) {
    customer {
      id
      legacyId
      firstName
      lastName
      company
      customFields {
        name
        value
      }
    }
  }
}
  1. Variables
{
  "input": {
    "customer": {
      "firstName": "Luke",
      "lastName": "Skywalker",
      "company": "Rebellion",
      "customFields": { "name": "space_ship", "value": "X-wing" }
    }
  }
}
  1. Response
{
    "data": {
        "createCustomer": {
        "customer": {
            "id": "id_of_customer",
            "legacyId": "legacy_id_of_customer",
            "firstName": "Luke",
            "lastName": "Skywalker",
            "company": "Rebellion"
            "customFields": {
            "name": "space_ship",
            "value": "X-wing"
            }
        }
        }
    },
    "extensions": {
        "requestId": "a-uuid-for-the-request"
    }
}

UpdateAnchorIcon

You can update a customer's information using the updateCustomer mutation. This mutation requires a customerId as input.

  1. Mutation
mutation UpdateCustomer($input: UpdateCustomerInput!) {
  updateCustomer(input: $input) {
    customer {
      id
      legacyId
      firstName
      lastName
      company
    }
  }
}
  1. Variables
{
  "input": { "customerId": "id_of_customer", "customer": { "company": "Jedi" } }
}
  1. Response
{
  "data": {
    "updateCustomer": {
      "customer": {
        "id": "id_of_customer",
        "legacyId": "legacy_id_of_customer",
        "firstName": "Luke",
        "lastName": "Skywalker",
        "company": "Jedi"
      }
    }
  },
  "extensions": { "requestId": "a-uuid-for-the-request" }
}

DeleteAnchorIcon

You can delete a customer using the deleteCustomer mutation. This mutation requires a customerId as input. Deleting a customer will break the association between the customer and any of their transactions.

Important
The customer will not be deleted if the customer has existing payment methods. Before deleting a customer, delete their payment methods from your Vault.
  1. Mutation
mutation DeleteCustomer($input: DeleteCustomerInput!) {
  deleteCustomer(input: $input) {
    clientMutationId
  }
}
  1. Variables
{ "input": { "customerId": "id_of_customer" } }
  1. Response
{
  "data": { "deleteCustomer": { "clientMutationId": "id_of_client_mutation" } },
  "extensions": { "requestId": "a-uuid-for-the-request" }
}

If the customer with the inputted ID can't be found, the mutation will raise a NOT_FOUND error.

You can search for customers based on their characteristics using the search mutation. For a list of characteristics you can search on, see the reference for CustomerSearchInput.

  1. Mutation
query Search($input: CustomerSearchInput!) {
  search {
    customers(input: $input) {
      edges {
        node {
          id
          legacyId
          firstName
          lastName
          company
        }
      }
    }
  }
}
  1. Variables
{ "input": { "company": { "is": "Rebellion" } } }
  1. Response
{
  "data": {
    "search": {
      "customers": {
        "edges": [
          {
            "node": {
              "id": "id_of_customer",
              "legacyId": "legacy_id_of_customer",
              "firstName": "Han",
              "lastName": "Solo",
              "company": "Rebellion"
            }
          },
          {
            "node": {
              "id": "id_of_customer",
              "legacyId": "legacy_id_of_customer",
              "firstName": "Leia",
              "lastName": "Organa",
              "company": "Rebellion"
            }
          },
          {
            "node": {
              "id": "id_of_customer",
              "legacyId": "legacy_id_of_customer",
              "firstName": "Luke",
              "lastName": "Skywalker",
              "company": "Rebellion"
            }
          }
        ]
      }
    }
  },
  "extensions": { "requestId": "a-uuid-for-the-request" }
}

If you know the id of the customer you are searching for and want to get their characteristics, then you can use the node query.

  1. Mutation
query GetCustomer {
  node(id: "id_of_customer") {
    ... on Customer {
      id
      legacyId
      firstName
      lastName
      company
    }
  }
}
  1. Response
{
  "data": {
    "node": {
      "id": "id_of_customer",
      "legacyId": "legacy_id_of_customer",
      "firstName": "Leia",
      "lastName": "Organa",
      "company": "Rebellion"
    }
  },
  "extensions": { "requestId": "a-uuid-for-the-request" }
}

ErrorsAnchorIcon

If you run into errors while working with customer objects, check the customer error codes page to see what errors you received and why you may be receiving them.