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 provide a link between Plain and your customer record. For example, a customer card will provide the externalId as part of its request.
• customerId: If you store the Plain customerId in your database then you will be able to exactly update a single 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
      customerGroupMemberships {
        edges {
          node {
            customerGroup {
              name
              key
            }
          }
        }
      }
    }
    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
      },
      "customerGroupIdentifiers": [
        {
          "customerGroupKey": "enterprise", 
        }
      ],
    },
    "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",
        "customerGroupMemberships": {
        "edges": [{
          "node": {
            "customerGroup": {
              "name": "Enterprise",
              "key": "enterprise"
            }
          }
        }]
      }
      },
      "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 sync jobs.

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

---

If you have any problems, please get in touch with us by email on help@plain.com, and we will be happy to help.