Customer Cards

Customer Cards

Customer Cards are a powerful feature in Plain that let you show information from your own systems when looking at a customer in Plain. This makes sure you always have important context when helping customers.

Customer Cards are:

  • Pulled from your backend so you do not have to sync your customer data to Plain.
  • Short-lived so that no data is permanently stored in Plain beyond the time frame you set.
  • Defined using a simple JSON schema, so you don't have to worry about styling them.
  • Automatically reloaded if a user is viewing a customer and the data expires.

Screenshot of the Customer Cards feature

How it works

  1. A customer is viewed in Plain.

  2. Plain fires a request to your backend with:

    • The customer's email and, if set, externalId
    • The configured Customer Card keys

  3. Your backend responds with the JSON for each card

  4. Cards are shown to the user in Plain.

Based on your Customer Card settings, Plain will send a request to your API like the below example:

{
  "cardKeys": ["plan-details"],
  "customer": {
    "email": "alex@grocery.co",
    "externalId": "your_user_id_795BFCD5-130F-4E72-BD46-14F717BE0830"
  }
}

Your API should then reply with a list of cards matching the requested keys where each card contains the components you want to display:

{
  "cards": [
    {
      "key": "plan-details",
      "timeToLiveSeconds": 86400,
      "components": [
        {
          "componentText": {
            "text": "Enterprise Tier"
          }
        }
      ]
    }
  ]
}

UI Components

You can use the Plain UI components to define how your customer data should look.

All the components are documented in the Plain UI Components section.

You can find example Customer Cards and an example API you can check out team-plain/example-customer-cards (opens in a new tab). Feel free to try these out in your workspace!

Caching of cards

Caching of Customer Cards is controlled via two properties:

  1. A time to live value (in seconds) in the Customer Card's settings. This can be changed under Settings → Customer Cards. Any changes will only apply to newly loaded Customer Cards.
  2. An explicit time to live value (in seconds) in your API response with the key timeToLiveSeconds. This overrides the value from settings and allows your API to dynamically set the TTL using custom logic.

Any card that is past its expiry time will usually be deleted within a few minutes but no later than 48 hours after expiry.

Example cards

To demonstrate what you can build with Customer Cards we've built some examples you can view and which are open source.

Customer Cards Examples → (opens in a new tab)

Playground

The Customer Cards Playground lets you build and preview the component JSON needed to create a Customer Card. Use this to prototype a Customer Card before starting to build your integration.

Customer Cards Playground → (opens in a new tab)

Customer Cards vs. Custom Timeline Entries

Customer Cards are used to add context to a customer's panel which is always visible. This is useful if the key information shown in Customer Cards is always relevant. If you want to show events that happened at a specific point in time, then using Custom Timeline Entries is more appropriate.

Upserting customersDocumentation