Managing Customer Records

Customers can be managed programmatically with the PIM API and Core API, but only the Core API has the latest functionality. Refer to our example repository for more information.

You can also manually create and maintain customer records within the Crystallize App, as described below. To perform these operations, you'll first need the requisite permissions for Customers (read, create, etc). Refer to our documentation on roles and permissions for more information.

Customers can either be defined as a simple list or can be set up as a hierarchical tree structure. The latter arrangement is especially helpful for businesses who sell to multiple businesses, markets, or subsidiaries who in turn have their own customers.

There are two customer types: Individual and Organization. There are also Groups which act as categorical folders. Individuals, Organizations, and Groups can all hold additional Customers and/or Groups of any kind, with a maximum tree depth of 5 levels. How you define your customer hierarchy (or not) is completely up to you.

To work with customers within the Crystallize App, click the Customers button on the left-hand panel. You can also bring up the command palette with [CTRL or ⌘] + K and type or select "Customers."

On the Customers screen, click the plus sign button (+) at the top left or the Individual, Organization, or Group buttons in the middle of the screen to begin defining your customer tree. 

For each Individual and Organization, you can specify the following:

• Identifier. A unique identifier that you’ll use to reference the customer programmatically. If none is specified, one will be auto-generated.
• Customer Information. First and last name are required, while the rest of the fields are optional.
• Shipping Address. Enter as much or as little information as you require.
• Billing Address. Click the Use different billing address checkbox to specify a different billing address.
• Customer Metadata and External Reference. These fields can be used to store extra information that may be needed by your company or by other service providers that you’re using. 

For each Group, you need only specify a Group Name and Identifier.

When finished, click the Create button at the top of the screen.

As you create Customers and Groups, the list/tree is represented on the left-hand side of the Customers screen. Clicking on an existing Individual or Organization displays their information. Clicking on a Group, or browsing back to the main Customers page, displays a spreadsheet view of the customers at that level of the hierarchy. Within this spreadsheet, you can:

• Drag and drop columns to reorder them.
• Find words/numbers by pressing [CTRL or ⌘] + F and entering the search input. Fields that contain the search string will be highlighted. Click the arrow buttons to navigate through the results.
• Refine the customer list to specific criteria by using the Search bar in the top left. You can filter by values in any column, or specifically by customer metadata within the Meta column. Filters are saved in the URL, so you can easily share the same view with your colleagues by sharing the link. Click the X beside any filter tag to remove it, or click the Clear Filters button to remove them all at once.

To create additional Customers and/or Groups at the base level of the tree, browse to the main Customers screen and click the plus sign button (+) in the top left.

To create additional Customers and/or Groups beneath an existing Customer/Group, follow one of these steps:

• Hover over the existing Customer/Group listed in the left-hand panel, then click the plus sign button (+) that appears to choose between Individual, Organization, or Group.
• Click on the existing Customer/Group listed in the left-hand panel, or click on a customer’s identifier within the spreadsheet view. From there, click the action button (...) on the top right and select one of the Add options (Individual, Organization, or Group).

You may build a customer hierarchy that is up to 5 levels deep. Exceeding that limit will produce an error.

To edit an existing Individual or Organization, first open it by clicking on it within the left-hand panel, or by clicking on its identifier within the spreadsheet view. From there, either click the action button (...) on the top right and select Edit customer, or click the pencil icon at the top right of the customer information panel. Once you’ve made the necessary changes, click the Save button to preserve them, or click the Cancel button to exit without saving.

To edit an existing Group, click on it within the left-hand panel. You can now modify its name at the top of the screen. Click the Update button to preserve changes.

Orders and subscription contracts involving a given customer, once created, will become visible under the Subscription Contracts and Orders headings. Click on the order number, and you’ll see its full details from the Orders screen. You can also create a new order from the Customers screen by clicking the action button (...) in the top right and choosing Add order. Refer to our documentation on creating orders for more information.

For subscription contracts, you can access a detailed breakdown of metered variables and their current usage for the ongoing period by clicking the down arrow to the left of the contract’s name. Predictive analytics provide estimates on future usage patterns and the associated total price. Leveraging data from past usage, this feature offers valuable foresight to empower informed decision-making.

You can create a new subscription contract from the Customers screen by clicking the action button (...) in the top right and choosing Add subscription contract. It’s possible to edit and cancel subscription contracts as well. Refer to our documentation on subscription contracts for more information.

You can (optionally) set up webhooks to subscribe to customer-related events. In Crystallize, events are fired whenever customers are

• Created
• Updated
• Deleted

You can set up a webhook, then come up with your own way of responding to events. For more information, read about defining webhooks here.

To delete an existing Individual or Organization, first open it by clicking on it within the left-hand panel, or by clicking on its identifier within the spreadsheet view. From there, click the action button (...) at the top of the screen and choose the Delete option. Note that orders placed by this Customer in the past will be preserved, but any subscription contracts associated with them will be deleted. Proceed carefully with deletion.

To delete an existing Group, click on it within the left-hand panel, then click the action button (...) at the top of the screen and choose the Delete option. This action will permanently delete the Group and everything within it. Proceed carefully with deletion.