General concepts

Building blocks#

When building a storefront using the DTC API, it's essential to understand the interaction between specific DTC API and general Centra concepts.

First, you need to know some Centra basics before you start, such as the concepts of Pricelists, Languages and Markets.

An important part for deciding upon how you will use the DTC API is to understand how the combination of Market, Pricelist and Language decides what products that will be visible, what price/currency they will use and what language the description fields will contain.

Session#

The session is only available if you use a token with the Session scope.

A session is tied to one shopper, containing information regarding their market, pricelist, selected language, ship-to-country and whether they are logged in. The session token also has connections to the active selection.

One session can span several orders and selections during its lifetime.

Customer#

Either a logged in shopper or a shopper that has started the payment process.

Selection#

Selection is the “shopping cart” / “basket”, which is tied to the shopper’s session and only accessible if you are using a session token.

It’s to the selection you add items, get access to the Checkout properties such as PaymentMethods, ShippingMethods, AddressFields, tax summary, address data etc.

The DTC API will always return the latest version of the selection even if an error happens during a mutation. A selection will only be created once there’s some data set on it (addItem, update address fields etc). Empty selections are queryable, but will return an “empty selection” response. For the “empty selection” response the selection.id: String property will be null.

Affiliate#

If you enter the site using the URI of an affiliate, the affiliate will be connected to the selection, allowing you to keep track of orders placed coming from this affiliate. This is useful if you are, for example, running partnerships with influencers.

Order#

Once a customer has gone through the payment process the selection will be converted into an order. For registered customers you can see your historical orders if you are logged in.

Product#

A Product is stored in a hierarchical structure, in which the Product is broken down into Variants and Sizes. The Product represents a certain design. Variants are different versions of the same product, typically different colors. Sizes are the different sizes you can buy the style in. This product structure enables very efficient product information management. More information about products can be found Here

Bundles#

A bundle is built up of several sections of displayItems. It is exposed as a displayItem with a non-null bundle property.

Bundles can be configured in several ways.

Fixed

Used if you have a fixed set of items that should be part of the bundle. For example, a 3-pack three coloured boxers that are also sold individually.

Flexible

Allows the shopper to select each displayItem per section. For example, a top and bottom part of a bikini.

Bundles can also be either statically or dynamically priced. Statically priced bundles will have the same price by market and pricelist regardless of the items in the sections or choices for flexible bundles. While a dynamically price bundle depends on the displayItems in the bundle, giving it a min and max price if it’s flexible. Dynamically priced fixed bundles will still only have a single price.

canonicalCategory#

The canonical category of the displayItem.

canonicalUri#

The canonical URI of the displayItem, uses the canonicalCategory and the uri properties together.

category#

If you supply category information via a single filterValue or if the DisplayItem / DisplayItemList is part of a lookupUri response where we have category information, this will be set to the matching category. Defaults to the canonical category.

URI#

The URI of the displayItem - if category is deduced by the lookupUri mutation the URI will reflect the category.uri in it.

categories#

Which categories the displayItem is available in. Only available for non session scope tokens.

Custom attributes#

You can enrich Centra’s default data with custom attributes several entities;

product, productVariant, display attributes are exposed on the displayItem

Displays and Items#

A DisplayItem is the entity which primarily ties display and variant together creating something you can browse and buy.

The visibility of a DisplayItem is determined by its markets.

The price of the DisplayItem is determined by its price lists

The price can also be affected by market and price lists specific campaigns, giving it a discount.

The stock of the DisplayItem is determined by its allocation rules which determine which warehouses it can be allocated from based on market and ship-to country.

There are a few fields on the displayItem that are of extra importance.

Items#

A list of activated sizes for this displayItem, this is what you add to your selection.

price lists#

The price lists in which the displayItem has a price. Only available for non session scope tokens.

Pricelist#

In Session mode the market is determined by the shopper’s Ship-to country, via the price lists geolocation.

price#

The price for the current market and price list, either deduced by the session or if you filter explicitly on one market and one price list. Null if multiple markets or price lists are used in then query.

priceByPricelist#

priceByPricelist returns a list of price information for the selected price lists and markets (priceByMarket subfield). Only available for non session scope tokens.

Campaigns#

A campaign can alter the price of a variant or simply mark it as "new" for the selected markets and price lists. Each variant in the campaign has a date range of when it’s active.

If the news checkbox is ticked for the variant it will show as showAsNew: true on the displayItem.

If the sale checkbox is ticked for the variant the originalPrice of the displayItem won’t be affected, meaning originalPrice will show the price list price.

If the sale checkbox it's not ticked the originalPrice of the displayItem will be the same as price set by the campaign.

showAsSale: true/false on the displayItem reflects the state of the checkbox in the API.

Campaign site#

A campaign site connects a specific route to a market, allowing you to change the market of the shopper, i.e. if you are running a secret sale you can send out an email to your VIP customers with this link and through the new market they will get discounts from the VIP campaign.

Lines#

Once an item is added to the selection it will become a line with its own UUID. It’s worth noting that the same item can become multiple lines, depending on several factors such as the price it receives when added, the subscription plan you’d like for it or custom line level comment(s). You can access the underlying displayItem and item from the line, and also see which promotions (vouchers or campaigns) were applied on it.

Checkout#

The Checkout field on the Selection exposes the additional fields you would typically need on the checkout page but not in the mini-cart.

addressFields#

List of available address fields used to build an address form on the checkout page, includes information whether the fields are required, should be visible and possible choices for them.

shippingAddress#

The current shipping address of the shopper, the DTC API always require some data for the shipping address to be present before proceeding to payment.

hasSeparateBillingAddress

Whether the shopper has entered any separate billing address.

If false when proceeding to payment, the shippingAddress will be used as the separate billing address.

separateBillingAddress#

The current billing address of the shopper.

If empty when proceeding to the payment, the shippingAddress will be used as the separate billing address on the order.

paymentMethod#

The current paymentMethod of the selection. Contains both simple data like name and id, but also exposes additional information such as if it supports recurring payments or paymentInitiateOnly which might affect your checkout logic.

The selected paymentMethod can affect the addressFields, since some paymentMethods collect and provide the address to Centra.

paymentMethods#

The list of currently available paymentMethods. The availability of a paymentMethod can depend on your shipTo country, market, pricelist and language on the selection. However, there are also other parameters that influence the availability such as the grandTotal of the selection and whether they support recurring payments. If a line has a subscriptionPlan attached to it, paymentMethods which don’t support recurring payments will be filtered out. These are also optional settings that Centra admin can configure depending on their needs.

shippingMethod#

The current shippingMethod of the selection. The shippingMethod is tied to both the price list, market and shipTo country of the selection.

NOTE: shippingMethod does not reflect the selected “shipping method” in any external shipping widget.

shippingMethods#

Available shippingMethods for this selection. The available shippingMethods is tied to both the price list, market and shipTo country of the selection.

NOTE: shippingMethods does not reflect the available shippingMethods in any external shipping widget.

widgets#

A list of inline widgets available for the selection, or meta data for certain paymentMethods.

totals#

A list of totals for the selection, includes the subtotal, shipping cost, total discount, deducted credit, grand total and taxes for the selection.

Language#

Language information as configured in Centra. The primary identifier for the language is the code property.

markets#

The markets in which the displayItem is available. Only available for non session scope tokens.

In Session mode the market is determined by the shopper’s Ship-to country, via the market’s geolocation, or by an applied campaign site.

Allocation rules#

Allocation rules are setup by the Centra admin to control from which warehouse(s) orders will be allocated for a certain store, market and country combination. Allocation rules affect the stock levels you see in the API. You can configure the API to choose which allocation rule should be used for the allocation of your order but it’s preferable to abstract it via the Brick and mortar concept, since it’s usually Buy online, pick up in store (BOPIS) or Buy online, ship from store (BOSFS) flows which require such a choice.

Brick and mortars#

List of physical stores where the products are being sold. Can be used to build your store locator.

If tied to either an allocationRule or warehouse you can use Brick and Mortars to influence how the order will be allocated.