Managing Customers Programmatically
Managing Customers Through the API
Let's start by managing customers programmatically. If you'd like to see examples of these queries and mutations in code, check out this python script that wraps many of the customer-related queries and mutations.
Querying Customers Through the API
If you know the ID of the customer you would like to query, use the customer query.
The myCustomerId (you can call it anything) query variable that you pass into the query is substituted in for customer(id), and a customer with the given ID is returned:
query ($myCustomerId: ID!) {
customer(id: $myCustomerId) {
id
name
externalId
}
}
{
"myCustomerId": "Q3VzdG9tZXI6ZDM0NTZjZWItNTNlOS00YmI5LWFhODItN2QyZDQ3YjZkMTA4"
}
While you can do some string concatenation or hard-code customer IDs, instance variable values, etc., to create a query, we recommend that you instead leverage GraphQL query variables. The examples below use query variables.
If you would like information about several customers, use the customers query instead:
query exampleGetCustomers {
customers(isSystem: false) {
nodes {
id
name
externalId
}
}
}
The isSystem: false property above removes system-generated customers that are used when testing integrations in the integration designer.
Adding a New Customer Through the API
To add a new customer to your account, use the createCustomer mutation. (It's called a mutation and not a query because you are mutating data, not just accessing it). We'll make heave use of query variables for this mutation:
mutation ($customerName: String!, $customerDescription: String, $customerExternalId: String) {
createCustomer(
input: {name: $customerName, description: $customerDescription, externalId: $customerExternalId}
) {
customer {
id
}
errors {
field
messages
}
}
}
{
"customerName": "FTL Rockets",
"customerDescription": "Faster-than-light Rocket Company, LLC",
"customerExternalId": "abc-123"
}
In the createCustomer example above, we capture the id of the customer that is created, as well as errors (if any) that are thrown.
The API might throw an error if a customer with the same name or external ID already exists.
Updating a Customer Through the API
You can update a customer using the updateCustomer mutation. You must know the ID of the customer you want to update. In this example, the ID of the customer and the new information that we want to change are passed in as query variables:
mutation ($customerId: ID!, $newDescription: String) {
updateCustomer(input: {id: $customerId, description: $newDescription}) {
errors {
field
messages
}
}
}
{
"customerId": "Q3VzdG9tZXI6ZDM0NTZjZWItNTNlOS00YmI5LWFhODItN2QyZDQ3YjZkMTA4",
"newDescription": "My Updated Description"
}
Deleting a Customer Through the API
The deleteCustomer mutation takes a customer ID, and returns the customer (if it has been deleted), or an error if the customer can't be found.
mutation ($customerId: ID!) {
deleteCustomer(input: {id: $customerId}) {
customer {
name
}
errors {
field
messages
}
}
}
{
"customerId": "Q3VzdG9tZXI6ZDM0NTZjZWItNTNlOS00YmI5LWFhODItN2QyZDQ3YjZkMTA4"
}
Managing Users Through the API
There are two types of users: your customer's users and your organization's team members. If you're using the embedded marketplace and signed JWTs to seamlessly authenticate customer users, you probably won't need to manage your customer users programmatically. It's more likely that you'll manage organization users, but we'll look at how to manage both.
Creating a User Through the API
In order to create a new user, you will need to know the user's email address, and role. You can optionally include the user's name and phone number.
First, look up the roles you can assign a user using either the customerRoles or organizationRoles query:
query {
organizationRoles {
id
name
permissions {
nodes {
name
description
}
}
}
}
This will give you a series of roles along with their IDs and the permissions that are associated with them. Find an appropriate role for the user you want to add, and note its ID. Next, run the either the createCustomerUser or createOrganizationUser mutation to create the user:
mutation ($email: String!, $name: String, $externalId: String, $role: ID!) {
createOrganizationUser(
input: {email: $email, name: $name, externalId: $externalId, role: $role}
) {
user {
id
name
email
externalId
}
errors {
field
messages
}
}
}
{
"email": "lisa.nguyen@smith-rockets.co",
"name": "Lisa Nguyen",
"externalId": "ABCCBC0B-98D0-453B-A795-0B430EFBF020",
"role": "Um9sZTo0NzdmNGRlYi03NzRlLTQ0M2UtOWY0MS01OGRmOWNhZjllNmM="
}
Users who are created in this way are immediately sent an email asking them to set a password for Prismatic.
Listing Users by Customer Through the API
One big advantage of GraphQL is that you can query resources for related data. Once again we'll use the customers query to list each customer's ID and name, but in addition we'll list the users attached to the customer. Specifically, we'll list each customer user's ID, email address, name, and external ID:
query {
customers(isSystem: false) {
nodes {
id
name
users {
nodes {
id
email
name
externalId
}
}
}
}
}
Updating and Deleting Users Through the API
You can accomplish the other CRUD operations (update and delete) using the updateUser and deleteUser mutations, similar to how you update or delete customers