Skip to main content

Creating and updating a customer

info

This recipe assumes you've already familiarized yourself with the Core API getting started, Authentication, and Error Handling pages.

We’ll be using an upsertCustomer which allows to create a new customer or update them if they exist. This mutation requires the following permissions:

  • customer:create
  • customer:edit

Uniqueness will be determined by the identifier input, based either on:

  • email: The customer's email address. In Plain we only allow one customer to have an email address.
  • externalId: Your customer's ID. This will guarantee you to synchronize
  • customerId: If you store the Plain customerId in your database then you will be able to always exactly update a customer. Implicitly this also means that this will be an update and never a create.

In the following examples we'll be using email as the uniqueness constraint, but recommend providing an externalId if you have one available.

Creating a customer

Mutation

The GraphQL mutation is the following:

mutation upsertCustomer($input: UpsertCustomerInput!) {
upsertCustomer(input: $input) {
result
customer {
id
externalId
shortName
fullName
email {
email
isVerified
}
status
}
error {
message
type
code
fields {
field
message
type
}
}
}
}
note

The Customer Object has more fields you can select, but in this recipe we're only selecting a few important ones.

Variables

{
"input": {
"identifier": {
"emailAddress": "donald@example.com"
},
"onCreate": {
"fullName": "Donald Duck",
"shortName": "Donald",
"email": {
"email": "donald@example.com",
"isVerified": false
}
},
"onUpdate": {}
}
}

Response

{
"data": {
"upsertCustomer": {
"result": "CREATED",
"customer": {
"id": "c_01G8JVJ6A3CX5ZSJ4AVJYC42HW",
"externalId": null,
"shortName": "Donald",
"fullName": "Donald Duck",
"email": {
"email": "donald@example.com",
"isVerified": false
},
"status": "IDLE"
},
"error": null
}
}
}

The value of the result type will be:

  • CREATED: if a customer with the email didn't exist
  • UPDATED: if a customer with the email already existed AND the values being updated were different
  • NOOP: if a customer with the email already existed AND the values being updated were the same
tip

Your backend system can call upsertCustomer multiple times with only an onCreate safely as no duplicate customers will be created. This is useful for a sync job.

Upserting a customer

info

Upsert stands for "update or insert".

Mutation

The GraphQL mutation is the following:

mutation upsertCustomer($input: UpsertCustomerInput!) {
upsertCustomer(input: $input) {
result
customer {
id
externalId
shortName
fullName
email {
email
isVerified
}
status
}
error {
message
type
code
fields {
field
message
type
}
}
}
}
note

The Customer Object has more fields you can select, but in this recipe we're only selecting a few important ones.

Variables

For the variables you need to provide both onCreate and onUpdate as Plain may not yet have your customer already.

{
"input": {
"identifier": {
"emailAddress": "donald@example.com"
},
"onCreate": {
"fullName": "Donald Fauntleroy Duck",
"shortName": "Fauntleroy",
"email": {
"email": "donald@example.com",
"isVerified": false
}
},
"onUpdate": {
"fullName": {
"value": "Donald Fauntleroy Duck"
},
"shortName": {
"value": "Fauntleroy"
},
"email": {
"email": "donald@example.com",
"isVerified": false
}
}
}
}

Response

{
"data": {
"upsertCustomer": {
"result": "UPDATED",
"customer": {
"id": "c_01G8JNBQMCJ46JTR7FEB68HTN0",
"externalId": null,
"shortName": "Fauntleroy",
"fullName": "Donald Fauntleroy Duck",
"email": {
"email": "donald@example.com",
"isVerified": false
},
"status": "IDLE"
},
"error": null
}
}
}

The value of the result type will be:

  • CREATED: if a customer with the email didn't exist
  • UPDATED: if a customer with the email already existed AND the values being updated were different
  • NOOP: if a customer with the email already existed AND the values being updated were the same`