Skip to main content

Managing Customers Programmatically

Managing customers through the API​

You can manage customers programmatically. If you would 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:

Fetch a Specific Customer
query ($myCustomerId: ID!) {
  customer(id: $myCustomerId) {
    id
    name
    externalId
  }
}
Query Variables
{
  "myCustomerId": "Q3VzdG9tZXI6ZDM0NTZjZWItNTNlOS00YmI5LWFhODItN2QyZDQ3YjZkMTA4"
}
Try It Out ❯
Use Query Variables

While you can do some string concatenation or hard-code customer IDs, instance variable values, etc., to create a query, use GraphQL query variables instead. The examples below use query variables.

If you would like information about several customers, use the customers query instead:

Fetch All Customers
query exampleGetCustomers {
  customers {
    nodes {
      id
      name
      externalId
    }
  }
}
Try It Out ❯

Adding a new customer through the API​

To add a new customer to your account, use the createCustomer mutation. (It's called a mutation rather than a query because you're changing data, not just retrieving it). You'll use query variables in this mutation:

Create a New Customer
mutation ($customerName: String!, $customerDescription: String, $customerExternalId: String) {
  createCustomer(
    input: {name: $customerName, description: $customerDescription, externalId: $customerExternalId}
  ) {
    customer {
      id
    }
    errors {
      field
      messages
    }
  }
}
Query Variables
{
  "customerName": "FTL Rockets",
  "customerDescription": "Faster-than-light Rocket Company, LLC",
  "customerExternalId": "abc-123"
}
Try It Out ❯

In the createCustomer example above, you 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, you pass the customer ID and new information as query variables:

Update a Customer
mutation ($customerId: ID!, $newDescription: String) {
  updateCustomer(input: {id: $customerId, description: $newDescription}) {
    errors {
      field
      messages
    }
  }
}
Query Variables
{
  "customerId": "Q3VzdG9tZXI6ZDM0NTZjZWItNTNlOS00YmI5LWFhODItN2QyZDQ3YjZkMTA4",
  "newDescription": "My Updated Description"
}
Try It Out ❯

Deleting a customer through the API​

Use the deleteCustomer mutation to delete a customer by ID. The mutation returns the deleted customer or an error if the customer cannot be found.

Delete a Customer
mutation ($customerId: ID!) {
  deleteCustomer(input: {id: $customerId}) {
    customer {
      name
    }
    errors {
      field
      messages
    }
  }
}
Query Variables
{
  "customerId": "Q3VzdG9tZXI6ZDM0NTZjZWItNTNlOS00YmI5LWFhODItN2QyZDQ3YjZkMTA4"
}
Try It Out ❯

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. You'll more likely manage team members, but you can manage both types.

Creating a user through the API​

To create a new user, you 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 for Organization Roles
query {
  organizationRoles {
    id
    name
    permissions {
      nodes {
        name
        description
      }
    }
  }
}
Try It Out ❯

This returns a series of roles with their IDs and associated permissions. Find an appropriate role for the user you want to add, and note its ID. Next, run either the createCustomerUser or createOrganizationUser mutation to create the user:

Create an Organization Team Member
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
    }
  }
}
Query Variables
{
  "email": "lisa.nguyen@smith-rockets.co",
  "name": "Lisa Nguyen",
  "externalId": "ABCCBC0B-98D0-453B-A795-0B430EFBF020",
  "role": "Um9sZTo0NzdmNGRlYi03NzRlLTQ0M2UtOWY0MS01OGRmOWNhZjllNmM="
}
Try It Out ❯

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​

GraphQL lets you query related data across resources. 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:

List All Customer Users by Customer
query {
  customers {
    nodes {
      id
      name
      users {
        nodes {
          id
          email
          name
          externalId
        }
      }
    }
  }
}
Try It Out ❯

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.