Skip to main content

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.

Create

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 input

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.

mutation

mutation CreateCustomer($input: CreateCustomerInput!){
  createCustomer(input: $input){
    customer {
      id
      legacyId
      firstName
      lastName
      company
    }
  }
}

variables

{
  "input": {
    "customer": {
      "firstName": "Luke",
      "lastName": "Skywalker",
      "company": "Rebellion"
    }
  }
}

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 customer

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

mutation

mutation CreateCustomer($input: CreateCustomerInput!){
  createCustomer(input: $input){
    customer {
      id
      legacyId
      firstName
      lastName
      company
    }
  }
}

variables

{
  "input": {}
}

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 fields

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.

mutation

mutation CreateCustomer($input: CreateCustomerInput!){
  createCustomer(input: $input){
    customer {
      id
      legacyId
      firstName
      lastName
      company
      customFields {
        name
        value 
      }
    }
  }
}

variables

{
  "input": {
    "customer": {
      "firstName": "Luke",
      "lastName": "Skywalker",
      "company": "Rebellion",
      "customFields": {
        "name": "space_ship",
        "value": "X-wing"
      }
    }
  }
}

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"
  }
}

Update

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

mutation

mutation UpdateCustomer($input: UpdateCustomerInput!){
  updateCustomer(input: $input){
    customer {
      id
      legacyId
      firstName
      lastName
      company
    }
  }
}

variables

{
  "input": {
    "customerId": "id_of_customer",
    "customer": {
      "company": "Jedi"
    }
  }
}

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"
  }
}

Delete

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.

mutation

mutation DeleteCustomer($input: DeleteCustomerInput!){
  deleteCustomer(input: $input){
    clientMutationId
  }
}

variables

{
  "input": {
    "customerId": "id_of_customer"
  }
}

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.

mutation

query Search($input: CustomerSearchInput!){
  search{
    customers(input: $input){
      edges{
        node {
          id
          legacyId
          firstName
          lastName
          company
        }
      }
    }
  }
}

variables

{
  "input": {
    "company": {
      "is": "Rebellion"
    }
  }
}

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.

mutation

query GetCustomer{
  node(id: "id_of_customer"){
    ... on Customer {
      id
      legacyId
      firstName
      lastName
      company
    }
  }
}

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"
  }
}

Errors

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.