1. Configuration

Working with product specs

What is a spec?

A product spec is a specification that allows users to provide text input or select options to customize a product or choose variations. For example:

  • Text input: Adding an engraved name to a pen
  • Options selection: Choosing a television size from available variants

Spec types

Specs define how users interact with products. The main types are:

Open text spec

The AllowOpenText property enables user text input for product customization:

http
POST sandboxapi.ordercloud.io/v1/specs HTTP/1.1
Authorization: Bearer INSERT_ACCESS_TOKEN_HERE
Content-Type: application/json; charset=UTF-8
json
{
  "ID": "ENGRAVING",
  "Name": "Name Engraving",
  "AllowOpenText": true
}

Options spec

Options specs provide controlled product configuration choices, such as business card design templates:

http
POST https://sandboxapi.ordercloud.io/v1/specs HTTP/1.1
Authorization: Bearer INSERT_ACCESS_TOKEN_HERE
Content-Type: application/json; charset=UTF-8
json
{
  "ID": "DESIGN_TEMPLATES",
  "Name": "Design Templates"
}

Spec options

Options represent available choices for an options spec:

http
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
json
{
  "ID": "MODERN_TECH",
  "Name": "Blue and Black Modern Tech Specialist Landscape Double-Sided Business Card"
}

Variant spec

A variant spec creates unique product variants for each option, such as different television sizes:

http
POST https://sandboxapi.ordercloud.io/v1/specs HTTP/1.1
Authorization: Bearer INSERT_ACCESS_TOKEN_HERE
Content-Type: application/json; charset=UTF-8
json
{
  "ID": "SIZE",
  "Name": "Size",
  "DefinesVariant": true,
  "Required": true
}

Variant specs must be Required as the base product represents a collection of variants.

Generate variants

Create variants after assigning variant specs to a product:

http
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

Multiple variant specs create a matrix of combinations. Example with Color (Red, Blue) and Size (Small, Medium, Large):

  1. Red, Small
  2. Red, Medium
  3. Red, Large
  4. Blue, Small
  5. Blue, Medium
  6. Blue, Large

Use overwriteExisting=true to regenerate variants. Deactivate unwanted variants by setting Active to false.

Variant IDs

Variants need unique identifiers. Override generated IDs using PUT/PATCH endpoints.

Disambiguating properties

Variants can have specific values for properties like Name and Description, separate from the base product.

Inventory

Manage inventory at:

  • Product level: All variants share inventory
  • Variant level: Each variant has separate inventory

Enable variant-level tracking with Inventory.VariantLevelTracking set to true.

Spec product assignments

Assign specs to multiple products to share configurations:

http
POST https://sandboxapi.ordercloud.io/v1/specs/productassignments HTTP/1.1
Authorization: Bearer INSERT_ACCESS_TOKEN_HERE
Content-Type: application/json; charset=UTF-8
json
{
  "SpecID": "SIZE",
  "ProductID": "MY_PRODUCT"
}

Create unique specs for products needing different option subsets.

Spec features

Required flag

Required specs must be defined when adding products to orders.

Default values

  • DefaultValue: Default text for open text specs
  • DefaultOptionID: Default selection for options specs
  • Set DefaultOptionID after creating spec and options
  • Override defaults in spec product assignments

Option features

Open text

Options can allow text input with IsOpenText property.

Price markup

Adjust prices based on selections using:

  • PriceMarkupType:
    • NoMarkup: No price change
    • AmountPerQuantity: Price per unit
    • AmountTotal: Fixed amount
    • Percentage: Percentage increase
  • PriceMarkup: Value for calculation

Pricing summary

Example: Base price $50, PriceMarkup 10

PriceMarkupTypePriceMarkupQuantity 1Quantity 10
NoMarkup10*$50$500
AmountPerQuantity($)10$60$600
AmountTotal($)10$60$510
Percentage10(%)$55$550

*NoMarkup values are ignored in calculations

If you have suggestions for improving this article, let us know!