Orders and Fulfilment

You can perform eCommerce operations manually with the Crystallize App or programmatically with the APIs. To do so, you'll first need the requisite permissions for Orders, Pipelines, Customers, and Webhooks. Refer to our documentation on roles and permissions for more information.

Before getting into orders, you may want to set up a few things that will form the foundation of your particular eCommerce setup. We’ll look at fulfilment pipelines first, then webhooks.

Fulfilment pipelines are collections of states through which orders can be routed. They’re useful for tracking the steps different sorts of orders go through; an order for a custom bike, for instance, will require different steps than a software download. In Crystallize, you can (optionally) define as many fulfilment pipelines as you need to track the progress of your orders through these stages.

To work with fulfilment pipelines in the Crystallize App, click on the Fulfilment button on the left-hand side of the screen. You can also bring up the command palette with [CTRL or ⌘] + K and type or select "Fulfilment."

Click the plus sign button (+) at the top or the +Create fulfilment button in the center to begin creating a new pipeline. Give the pipeline a name, define as many stages as you want, and use the “New orders” flag to indicate where new orders should appear as they come in. (New orders may appear in multiple pipelines.) Then click the Create button at the top of the screen.

Once orders start coming in, you can click on them to see their full details (see the Managing Orders section for more information). From this view, you can move the order to different pipeline stages or remove the order from the pipelines it’s in, as needed.

Back in the main pipeline view, you can manually drag and drop orders between pipeline stages, or remove them entirely by dropping them into the “Drop here to remove from pipeline” area of the screen. (Again, pipeline state changes can also be done programmatically with the PIM API. Refer to our example repository for pipeline-related GraphQL samples.)

You can use the Edit button at the top of the screen to modify an existing pipeline. While editing a pipeline, you can click the action button (...) at the top of the screen and choose Delete to delete it. You can delete a pipeline even if it has orders in it; the orders themselves will not be deleted when the pipeline is removed.

You can (optionally) set up webhooks to subscribe to order-related events happening within Crystallize. For instance, you may want to automate the process of sending emails to your customers when their orders have shipped, and updating your stock values accordingly. 

In Crystallize, events are fired whenever orders are 

• Created
• Deleted
• First added to a fulfilment pipeline (pipeline state change)
• Moved from one pipeline stage to another (pipeline state change)
• Removed from a pipeline 

For more information, read about defining webhooks here.

Once you’ve added at least one customer to your tenant, you can create an order for them within the Crystallize App. Click on the Customers button on the left-hand side of the screen, then select the customer you’d like to work with, either by clicking on their name within the left-hand panel or by clicking on their identifier within the spreadsheet view. With the customer record open, click the action button (...) at the top of the screen and choose Add order. If the customer currently has no orders or subscription contracts, there will also be an Order button at the top of their record that you can click to get started.

The customer’s data will already be filled in. From here, you can specify the following:

• Price variant. Using the drop-down menu at the top right, choose one of the price variants already defined for this tenant.
• Order items. Click and drag existing products from the catalogue in the left-hand pane, then select which product variant(s) to add to the order. Or, you can define your own line item(s) by clicking the Add Custom item button. For each item in the order, specify quantity, tax, and unit price. Net and gross will be calculated automatically. Use the action button (...) beside any item to remove it, if needed.
• Additional information. Optionally specify any other order details, such as delivery instructions.
• Meta information. Optionally specify extra information that may be needed by your company or by other service providers that you’re using. You can input the data as key-value pairs.

When finished, click the Create order button. Once an order is created, it will be visible on the Orders screen for your tenant and possibly also the Fulfilment screen, if any pipelines were created for new orders. An order may appear in multiple pipelines at once, but can only occupy one stage in any given pipeline. If any webhooks were listening for order creation or pipeline state changes, they would fire at this time as well. (A new order entering a pipeline for the first time is considered a pipeline state change.)

Note that orders are created asynchronously. There is no guarantee that the order will be retrievable immediately after registering it.

In the Crystallize App, you can also create an order from a subscription contract.

Finally, orders can be created programmatically by invoking the Order API. Refer to our GraphQL sample for creating an order, which is part of our example repository. Also check out the API docs at https://api.crystallize.com/your-tenant-identifier/orders for the full list of parameters you can specify and fetch. Make sure you have access tokens set up in order to run your requests. 

You can manually view and edit orders and manage their progress through pipelines within the Crystallize App. This may be sufficient for a small shop. Order-related tasks can also be handled programmatically with either the Order API or PIM API (e.g. reducing stock), which is more realistic for businesses that may receive hundreds or thousands of orders per day.

Within the Crystallize App, click the Orders button in the left-hand panel. You can also bring up the command palette with [CTRL or ⌘] + K and type or select "Orders."

On the Orders screen, you’ll find orders listed chronologically on cards. These cards show customer name, order time, and total price in the proper currency. Click the downward-pointing arrow to expand any order card. Once expanded, you’ll see the product variants and quantities ordered, as well as a progress bar showing the name(s) of the pipeline(s) the order was routed to (if any), and the current stage(s) it’s in. Click the refresh button at top of the screen to see new orders and pipeline state changes since you last loaded the page.

You can use the Orders Filter at the top-left of the screen to display only those orders that match one or more criteria. When you click into the input box, you can select an attribute to filter against and then type in your desired value. Hit Enter, and the filter will be applied. Use the input box to add additional filter criteria as desired. Using the filters drop-down menu, you can see what filters are in place and click the X beside any one of them to remove it, or use the Clear all label to remove all filters and restore the full list of orders.

Left-clicking on an order card will open it in the main window. For each order, you can see the order ID, order reference ID (a human-readable, 8-character alphanumeric string that will never contain zeros or ones, and is unique per tenant), order date and time, customer information, items ordered (along with quantity, metadata, tax, and unit price), and total price. You can click on item thumbnails to view the associated product variants in your catalogue. You can also view the customer from the Customers screen by clicking the action button (...) at the top of the screen and choosing Go to customer.

To modify an existing order, open it in the main window, then click the action button (...) and select Edit order. You can modify the existing item names, prices, price variants, tax, and quantities; remove items; and/or add new items by using the Custom item+ or Open catalogue buttons. Click the Update order button in the top right to save changes.

You can add an order to one or more pipelines, or update its place in a pipeline, by scrolling down to the “Fulfilment pipelines” section and clicking on the progress bars displayed there. 

You can delete an order by clicking the action button (...) and choosing Delete. This action cannot be undone, so proceed carefully.