Skip to main content
Using TypeScript? Check out our GraphQL SDK for a fully typed client.
Creating and updating customers is handled via a single API called upsertCustomer. When you upsert a customer, you define:
  1. The identifier: This is the field you’d like to use to select the customer and is one of
    • emailAddress: This is the customer’s email address. Within Plain email addresses are unique to customers.
    • customerId: This is Plain’s customer ID. Implicitly if you use this as an identifier you will only be updating the customer since the customer can’t have an id unless it already exists.
    • externalId: This is the customer’s id in your systems. If you previously set this it can be a powerful way of syncing customer details from your backend with Plain.
  2. The customer details you’d like to use if creating the customer.
  3. The customer details you’d like to update if the customer already exists.
When upserting a customer you will always get back a customer or an error.

​
Upserting a customer

This operation requires the following permissions:
  • customer:create
  • customer:edit
This will:
  • Find a customer with the email ‘donald@example.com’ (the identifier).
  • If a customer with that email exists will update it (see onUpdate below)
  • Otherwise, it will create the customer (see onCreate below)
The GraphQL mutation is the following:
Mutation
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
      }
    }
  }
}
Variables
{
  "input": {
    "identifier": {
      "emailAddress": "donald@example.com"
    },
    "onCreate": {
      "fullName": "Donald Duck",
      "shortName": "Donald",
      "email": {
        "email": "donald@example.com",
        "isVerified": false
      },
      "customerGroupIdentifiers": [
        {
          "customerGroupKey": "enterprise"
        }
      ]
    },
    "onUpdate": {
      "fullName": {
        "value": "Donald Duck"
      },
      "shortName": {
        "value": "Donald"
      },
      "email": {
        "email": "donald@example.com",
        "isVerified": true
      },
      "externalId": {
        "value": "c_123"
      }
    }
  }
}
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 didn’t exist and was created
  • UPDATED: if a customer already existed AND the values being updated were different.
  • NOOP: if a customer already existed AND the values being updated were the same