Plain (plain v0.2.0)

Summary

Functions

Add customers to tenants

You can add a customer to multiple tenants.

Upserting customers

Creating and updating customers is handled via a single API called upsertCustomer. You will find this name in both the API and this SDK.

Upserting tenants

When upserting a tenant you need to specify an externalId which matches the id of the tenant in your own backend.

If you already have the ID of a customer from within Plain or one of our other endpoints you can fetch more details about them using getCustomerById in the SDK.

If you know the tiers’s ID in Plain you can use this method to fetch the tier.

Remove customers from tenants

You can remove customers from multiple tenants in one API call.

Update tenant tier

If you want to explicitly set the tier for a tenant you can do so using this mutation.

Functions

Link to this function

addCustomerToTenant(customerId, tenantIds)

@spec addCustomerToTenant(String.t(), [String.t()]) :: {:ok, map()} | {:error, any()}

Add customers to tenants

You can add a customer to multiple tenants.

When selecting the customer you can chose how to identify them. This SDK uses the customer’s plain id.

For this mutation you need the following permissions:

  • customer:edit
  • customerTenantMembership:create
Link to this function

createOrUpdateCustomer(email, externalIdentifier, fullName, name)

@spec createOrUpdateCustomer(String.t(), String.t(), String.t(), String.t() | nil) ::
  {:ok, map()} | {:error, any()}

Upserting customers

Creating and updating customers is handled via a single API called upsertCustomer. You will find this name in both the API and this SDK.

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.
  1. The customer details you’d like to use if creating the customer.
  2. 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
Link to this function

createOrUpdateTenant(identifier, name)

@spec createOrUpdateTenant(String.t(), String.t()) :: {:ok, map()} | {:error, any()}
Link to this function

createOrUpdateTenant(identifier, name, url)

@spec createOrUpdateTenant(String.t(), String.t(), String.t() | nil) ::
  {:ok, map()} | {:error, any()}

Upserting tenants

When upserting a tenant you need to specify an externalId which matches the id of the tenant in your own backend.

For example if your product is structured in teams, then when creating a tenant for a team you’d use the team’s id as the externalId.

To upsert a tenant you need the following permissions:

  • tenant:read
  • tenant:create
Link to this function

createTier(name, externalId, color, defaultThreadPriority, isDefault)

@spec createTier(String.t(), String.t(), String.t(), integer(), boolean()) ::
  {:ok, map()} | {:error, any()}
Link to this function

getCustomerById(customer_id)

@spec getCustomerById(String.t()) :: {:ok, map()} | {:error, any()}

If you already have the ID of a customer from within Plain or one of our other endpoints you can fetch more details about them using getCustomerById in the SDK.

These endpoints require the following permissions:

  • customer:read
Link to this function

getTierById(tier_id)

@spec getTierById(String.t()) :: {:ok, map()} | {:error, any()}

If you know the tiers’s ID in Plain you can use this method to fetch the tier.

For this query you need the following permission:

  • tier:read
Link to this function

removeCustomerFromTenant(customerId, tenantIds)

@spec removeCustomerFromTenant(String.t(), [String.t()]) ::
  {:ok, map()} | {:error, any()}

Remove customers from tenants

You can remove customers from multiple tenants in one API call.

When selecting the customer you can chose how to identify them. This SDK uses the customer’s plain id.

For this mutation you need the following permissions:

  • customer:edit
  • customerTenantMembership:delete
Link to this function

removeTenantTier(tenantIdentifier)

@spec removeTenantTier(String.t()) :: {:ok, map()} | {:error, any()}
Link to this function

updateTenantTier(tierIdentifier, tenantIdentifier)

@spec updateTenantTier(String.t(), String.t()) :: {:ok, map()} | {:error, any()}

Update tenant tier

If you want to explicitly set the tier for a tenant you can do so using this mutation.

The tierIdentifier and tenantIdentifier refer to the IDs given by Plain.

For this mutation you need the following permissions:

  • tierMembership:read
  • tierMembership:create