Sitecore OrderCloud Documentation

docs

Portal Login

Working with Product Specs

Published by Andrew Sutherland on December 21, 2021

What is a Spec?

While a product may have a number of properties that provide details about the product, a spec refers to a product specification that typically allows the user to either provide some text input or choose from options, which can result in customizing the product and/or selecting a variation of the product.

For example, when selling a pen we may request a name to be engraved on the side, providing a customized product, whereas a television may offer different sizes representing variant products.

Spec Types

The configuration of a spec defines how a user will interact with a product it has been assigned to. Specs can generally be categorized under one of the following types:

Open Text Spec

The AllowOpenText property provides the user the option of inputting text associated to the product, e.g. a name to be engraved onto a pen.

POST https://sandboxapi.ordercloud.io/v1/specs HTTP/1.1
Authorization: Bearer INSERT_ACCESS_TOKEN_HERE
Content-Type: application/json; charset=UTF-8;

{
    "ID": "ENGRAVING",
    "Name": "Name Engraving",
    "AllowOpenText": true
}

Options Spec

To give the user the ability to modify a product configuration while still limiting their selection, a spec with options can be created, e.g. business cards may have a number of design templates to choose from.

POST https://sandboxapi.ordercloud.io/v1/specs HTTP/1.1
Authorization: Bearer INSERT_ACCESS_TOKEN_HERE
Content-Type: application/json; charset=UTF-8;

{
    "ID": "DESIGN_TEMPLATES",
    "Name": "Design Templates"
}

Spec Options

Spec options represent the available options that can be selected for an options spec.

POST https://sandboxapi.ordercloud.io/v1/specs/DESIGN_TEMPLATES/options HTTP/1.1
Authorization: Bearer INSERT_ACCESS_TOKEN_HERE
Content-Type: application/json; charset=UTF-8;

{
    "ID": "MODERN_TECH",
    "Name": "Blue and Black Modern Tech Specialist Landscape Double-Sided Business Card"
}

Variant Spec

A variant spec is an options spec that intends to slice a product across each spec option to create a unique variant product per option, e.g. a television with different sizes each representing a variant product.

POST https://sandboxapi.ordercloud.io/v1/specs HTTP/1.1
Authorization: Bearer INSERT_ACCESS_TOKEN_HERE
Content-Type: application/json; charset=UTF-8;

{
    "ID": "SIZE",
    "Name": "Size",
    "DefinesVariant": true,
    "Required": true
}

Generate Variants

Once variant specs have been assigned to a product, the variants can then be generated under the products resource.

POST https://sandboxapi.ordercloud.io/v1/products/{productID}/variants/generate  HTTP/1.1
Authorization: Bearer INSERT_ACCESS_TOKEN_HERE
Content-Type: application/json; charset=UTF-8;

Where multiple variant specs are assigned to a product, a matrix of variants is created. The amount of variants created can be calculated using the formula (spec A's option count) (spec B's option count) (spec C's option count) and so on. As you can see, the more variant specs assigned to a product, and the more options per spec, the greater scale of variants will be generated.

For example, let's take a product that is assigned 2 variant specs. The first spec is Color, containing options Red and Blue. The second spec is Size, which will have options of Small, Medium, and Large. This would result in the following generated variants, each with their own unique spec option combination.

  1. Red, Small

  2. Red, Medium

  3. Red, Large

  4. Blue, Small

  5. Blue, Medium

  6. Blue, Large

Variant IDs

Variants will commonly represent a unique product, which requires a unique SKU or identifier. While the variant generation also generates the variant's ID, this can be overwritten using the PUT/PATCH resource.

Disambiguating Properties

Properties at the product level may not be appropriate for the variants, so the variant model contains a subset of properties for variant-specific values; most notably Name and Description.

Inventory

For products with variants, inventory can be managed at the product level, to manage inventory across all variants, or at the variant level, to manage inventory for each product variant.

Spec Product Assignments

Specs have a one to many relationship with products, which can facilitate in avoiding duplicating spec data and overall maintenance. For example, a number of products may be available with the same design options and an option spec, e.g. DESIGN_TEMPLATES houses all available designs. With each of the products being assigned the DESIGN_TEMPLATES spec, not only will they share the available options, but any updates to the spec will also be applied to all assigned products.

POST https://sandboxapi.ordercloud.io/v1/specs/productassignments HTTP/1.1
Authorization: Bearer INSERT_ACCESS_TOKEN_HERE
Content-Type: application/json; charset=UTF-8;

{
    "SpecID": "SIZE",
    "ProductID": "MY_PRODUCT"
}

Spec Features

Required Flag

Setting the spec to be required ensures that the product cannot be added to an order unless the spec has been defined.

Default Values

Setting the DefaultValue or DefaultOptionID acts as the fallback when a spec expects either a value for open text specs or an option id for options specs.

Option Features

Open Text

Open text does not just apply to the spec level configuration. Selecting an option that has the IsOpenText set to true will allow the user to input text in the same manner, which can also leverage the other features of option specs like price markup.

Price Markup

When a user inputs a value for an open text spec or selects a value from an options spec, an additional cost may be incurred. Spec options have price markup properties to cater for these price adjustments. PriceMarkupTypes determine how the product price will be impacted, while the PriceMarkup specifies the value to be used in calculations.

The available PriceMarkupTypes are as follows:

  • NoMarkup: The default option that will not modify the product price.

  • AmountPerQuantity: Updates the product price with an amount, multiplied by the quantity of the product.

  • AmountTotal: A fixed amount to be added to the product price regardless of product quantity.

  • Percentage: Increases the product price by the defined value as a percentage.

Pricing Summary

The following table represents the line item subtotals for price markups on a product with a base price of $50 and a PriceMarkup of 10 (where the value type of the PriceMarkup is dependent on PriceMarkupType).

PriceMarkupType

PriceMarkup

Quantity 1

Quantity 10

NoMarkup

10*

$50

$500

AmountPerQuantity

($)10

$60

$600

AmountTotal

($)10

$60

$510

Percentage

10(%)

$55

$550

Conclusion

Although the flexibility in configuring product specs and options is extremely powerful in OrderCloud, the initial process can seem overwhelming and convoluted. With adequate knowledge of their workings, as described in this article, creating complex products should now be a straightforward process.


Was this page helpful? Give it a bravo!

Still have questions?
Ask in our Community Channel

Content Powered By
Sitecore Logo

© Copyright 2024, Sitecore OrderCloud®. All rights reserved.

Contact Us
Privacy Policy
Sitecore