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.
- 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.
Search
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.