Managing Customers

The Customers requests feature allows you to manage customers and requests inside of Linear.

Data Models⁠

The Customer requests relies on two objects: Customer and CustomerNeed.

Customer⁠

The Customer object represents an external company.

Fields⁠

CustomerNeed⁠

The CustomerNeed object represents a customer request. It is attached to an Issue and optionally, to a specific Customer.

Fields⁠

Create a Customer⁠

The customerCreate mutation allows to create a customer through the API:

mutation CustomerCreate($input: CustomerCreateInput!) {
  customerCreate(input: $input) {
    success
    customer {
      id
    }
  }
}
 
{
  "input": {
    "name": "ACME"
  }
}

{
  "data": {
    "customerCreate": {
      "success": true,
      "customer": {
        "id": "bc993fb1-bf7e-48ab-aff9-2d014cfc5842"
      }
    }
  }
}

Customer with metadata⁠

The following request creates a customer with additional metadata:

• tierId is the id of Linear tier this customer is associated with. Tiers must be created with mutation customerTierCreate before they can be used with a Customer
• externalIds contains a list of all unique external identifiers for this Customer. It can be the uuid of the Customer in your own database or any other external system you are getting customer information from. Setting this value allows to refer to this customer by this specific external id when creating customer requests rather than the Linear defined Customer id.
• domains must contain unique values and cannot contain any public email provider.

mutation CustomerCreate($input: CustomerCreateInput!) {
  customerCreate(input: $input) {
    success
    customer {
      id
    }
  }
}
 
{
  "input": {
    "name": "ACME",
    "domains": ["acme.com"],
    "externalIds": ["cus-acme-12345"]
    "tierId": "e7cfd601-5582-41aa-8f52-77685191e221",
    "revenue": 1250,
    "size": 12,
  }
}

Create a Customer Request⁠

Once a Customer has been created, it is possible to use it to create a Customer Request on a specific issue.

mutation CustomerNeedCreate($customerNeedCreateInput: CustomerNeedCreateInput!) {
  customerNeedCreate(input: $customerNeedCreateInput) {
    success
  }
}
 
{
 "input": {
   "issueId": "be65eaec-314c-412c-baf8-4787f2b85bdd",
   "body": "Content of the request",
   "customerId": "021d4b25-b0a9-4f02-85ad-bd840ac9c3ee" 
 }
}

Alternatively, it is possible to use one of the external id of the Customer to attach the request to the Customer:

mutation CustomerNeedCreate($customerNeedCreateInput: CustomerNeedCreateInput!) {
  customerNeedCreate(input: $customerNeedCreateInput) {
    success
  }
}
 
{
 "input": {
   "issueId": "be65eaec-314c-412c-baf8-4787f2b85bdd",
   "body": "Content of the request",
   "customerExternalId": "cus-acme-12345"
 }
}

When passing an url to the input, an Attachment will be created and attached to the request:

mutation CustomerNeedCreate($customerNeedCreateInput: CustomerNeedCreateInput!) {
  customerNeedCreate(input: $customerNeedCreateInput) {
    success
  }
}
 
{
 "input": {
   "issueId": "be65eaec-314c-412c-baf8-4787f2b85bdd",
   "body": "Content of the request",
   "customerExternalId": "cus-acme-12345",
   "attachmentUrl": "https://conversations.support.com/conversations/12345"
 }
}

{
  "data": {
    "customerNeedCreate": {
      "success": true,
      "need": {
        "id": "26c9dbf5-44b5-4e00-9978-c779467d87f0",
        "body": "Content of the request",
        "attachment": {
          "url": "https://conversations.support.com/conversations/12345"
        }
      }
    }
  }
}

Update a Customer⁠

The customerUpdate mutation allows to update a Customer. Linear will automatically attempt to match created Customers against customers in your integrations (Intercom, Zendesk or Front). When a match happens, the Customer object in Linear becomes managed by the integration and only certain fields can be updated.

Customers managed by Intercom:

"ownerId" | "statusId" | "logoUrl"

Customers managed by Zendesk or Front:

"ownerId" | "statusId" | "logoUrl" | "revenue" | "size" | "tierId"

If you are building an integration with Linear and need to manage or operate with Customers that could have been created by other integrations, please refer to the Upsert Customers section

Upsert Customers⁠

Customers are created automatically when an issue is created from one of the supported sources: Intercom, Zendesk, Front, Email intake or Slack. If you are building an integration that will create Customer Requests and associate them with Customers, it is likely that you will encounter the case where the request should be attached to a Customer that's been already created by another integration. As there is a uniqueness constraint on domains, you cannot create a duplicate Customer in Linear. Instead, you must re-use this existing Customer. The customerUpsert mutation allows you to append domains and external identifiers to an existing Customer and contribute to its definition.

Starting with the following Customer, assuming it has been created by the Intercom integration:

{
    "name": "ACME",
    "domains": ["acme.com"],
    "externalIds": ["intercom-654536452625"]
    "revenue": 1250,
    "size": 12,
}

It is possible to upsert this existing Customer with your integration's own definition:

mutation CustomerUpsert($customerUpsertInput: CustomerUpsertInput!) {
  customerUpsert(input: $customerUpsertInput) {
    success
    customer {
      domains
      name
      externalIds
    }
  }
}
 
{
  "customerUpsertInput": {
    "domains": ["acme.com", "acme.dev"],
    "externalId": "own-customer-id",
  }
}

{
  "data": {
    "customerUpsert": {
      "success": true,
      "customer": {
        "domains": [
          "acme.com",
          "acme.dev"
        ],
        "name": "ACME",
        "externalIds": [
          "cus-acme-12345",
          "own-customer-id"
        ]
      }
    }
  }
}

Your integration's Customer id has been appended to the list of externalIds of the Customer, after it matched by domain. If there had been no match, a new Customer would have been created.

This allows your integration to push Customers into Linear without having to check ahead of time if there is already an existing Customer for the same domains. Either the Customer does not exist and will be created, either it exists already and will be reused. The domains and externalIds will be merged.

Your integration can then attach Customer Requests using your integration's customer id:

mutation CustomerNeedCreate($customerNeedCreateInput: CustomerNeedCreateInput!) {
  customerNeedCreate(input: $customerNeedCreateInput) {
    success
  }
}
 
{
 "input": {
   "issueId": "be65eaec-314c-412c-baf8-4787f2b85bdd",
   "body": "Content of the request",
   "customerExternalId": "own-customer-id",
   "attachmentUrl": "https://conversations.support.com/conversations/12345"
 }
}