Recipe data
Recipe storage
Recipes are stored as plain JSON objects. Downstream systems may need read recipes to receive additional details about applied customizations, such as component codes, selected images, production file links and locations, etc.
These additional details will be contained at the recipe level and can be extracted by the host site ETL process.
The recipe IDs are unique identifiers assigned to each saved design, for example 2-vBYtsQB2ndCosDcB. However, the recipe itself is a JSON object stored at the URL that can be constructed as necessary:
https://cz.drrv.co/recipe/<recipe ID>.jsonFor the recipe ID above, the corresponding URL shall be https://cz.drrv.co/recipe/2-vBYtsQB2ndCosDcB.json
Authentication
Unless configured otherwise on a per-customer basis, the recipe data required a knowledge of the exact recipe ID and does not require authentication. If authentication is required, it can be provided using Bearer authentication header or apikey query string parameter.
Recipe Components
Notable recipe components include:
id | A unique recipe ID. |
created | Timestamp when the recipe was generated. |
name | Product name. |
styleCode | Product ID. |
humanReadable | A link to the human-readable version of the recipe, if applicable. |
components | A list of placements with a reference to the selected component for each placement. |
views | Product views with rendered product image references. |
For extracting the data from recipes into ERP systems, the last two areas will be the most relevant, components and views
Components describe product options and selections
While views will contain the information about preview and production assets
Components
Components is a array that enumerates the placements within the current product configuration, and a respective component that is selected in that placement.
Each placement is identified by its code, along any number of additional parameters. The respective selected component is also identified by its placement-specific code.
Decoding Views
Recipes may contains a views array, which will contain a description of production-ready file and related proof/preview images.
Each view will have a number of attributes. Most important ones are:
code- a view unique identifierpreviewPng- a link pointing to the view image in PNG formatpreviewJpg- a link pointing to the view image in JPG formatcustom- a map of custom view attributes
Variations
In addition to the main image, a view may contain a number of variant images. These variants could be, for example, images of different sizes to match intended usage, such as cart, email, etc.
Recipe schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://example.com/schemas/recipe.yaml",
"title": "Recipe",
"type": "object",
"description": "Main recipe object.",
"required":
[
"id",
"created"
],
"properties":
{
"id":
{
"type": "string",
"description": "Unique recipe id."
},
"session":
{
"type": "string",
"format": "uuid",
"description": "Related session Id."
},
"designRequest":
{
"type": "string",
"description": "Related design request."
},
"blueprintUrl":
{
"type": "string",
"format": "uri",
"description": "Blueprint Url."
},
"created":
{
"type": "string",
"format": "date-time",
"description": "Creation timestamp in UTC."
},
"createdFrom":
{
"type": "string",
"description": "Parent recipe ID."
},
"childRecipe":
{
"type": "boolean",
"description": "Whether this is a child recipe."
},
"temporaryRecipe":
{
"type": "boolean",
"description": "Read-only flag for temporary recipes."
},
"externalInventory":
{
"type": "boolean",
"description": "Read-only flag for recipes using external inventory."
},
"custom":
{
"type": "object",
"additionalProperties":
{
"type": "string"
},
"description": "A string-to-string map of custom attributes."
},
"name":
{
"type": "string",
"description": "Product name."
},
"styleCode":
{
"type": "string",
"description": "Product style code."
},
"version":
{
"type": "string",
"description": "Product version."
},
"humanReadable":
{
"type": "string",
"format": "uri",
"description": "Link to human-readable PDF."
},
"attachments":
{
"type": "array",
"items":
{
"$ref": "#/$defs/RecipeAttachment"
},
"description": "Recipe attachments."
},
"related":
{
"type": "array",
"items":
{
"$ref": "#/$defs/RecipeProduct"
},
"description": "Related products."
},
"components":
{
"type": "array",
"items":
{
"$ref": "#/$defs/RecipePlacement"
},
"description": "Recipe placements."
},
"views":
{
"type": "array",
"items":
{
"$ref": "#/$defs/RecipeView"
},
"description": "Views mentioned in the recipe."
},
"assembly":
{
"type": "array",
"items":
{
"$ref": "#/$defs/RecipeAssembly"
},
"description": "Assemblies in the recipe."
},
"tags":
{
"type": "array",
"items":
{
"type": "string"
},
"description": "Active tags."
},
"addedTags":
{
"type": "array",
"items":
{
"type": "string"
},
"description": "Added global tags."
}
},
"$defs":
{
"RecipeAssembly":
{
"type": "object",
"description": "Describes a product component of a complex assembly.",
"required":
[
"component",
"placement"
],
"properties":
{
"component":
{
"type": "string",
"description": "Component that represents a child or connected product"
},
"placement":
{
"type": "string",
"description": "Placement where a child or connected product is attached to"
},
"socket":
{
"type": "string",
"description": "ID of a socket where a child product is attached"
},
"to":
{
"type": "string",
"description": "Child controller ID"
},
"recipe":
{
"type": "object",
"additionalProperties": true,
"description": "Child recipe payload."
}
}
},
"RecipeAttachment":
{
"type": "object",
"description": "One file or data blob attached to the recipe.",
"properties":
{
"deferred":
{
"type": "boolean",
"description": "A flag indicating that an attachment may contain temporary data that will be finalized when an order is placed"
},
"type":
{
"type": "string",
"description": "Attachment MIME type"
},
"usage":
{
"type": "string",
"description": "Free-form and customer specific identifier describing the attachment indended usage"
},
"code":
{
"type": "string",
"description": "Attachment code"
},
"name":
{
"type": "string",
"description": "Attachment friendly name"
},
"notes":
{
"type": "string",
"description": "Additional notes about the attachment"
},
"placement":
{
"type": "string",
"description": "Placement code that triggered the attachment generation"
},
"url":
{
"type": "string",
"format": "uri",
"description": "A link to the attachment file"
}
}
},
"RecipeProduct":
{
"type": "object",
"description": "A related product summary.",
"properties":
{
"name":
{
"type": "string",
"description": "Related product name"
},
"styleCode":
{
"type": "string",
"description": "Related product style code"
},
"custom":
{
"type": "object",
"additionalProperties":
{
"type": "string"
}
}
}
},
"RecipePlacement":
{
"type": "object",
"description": "Selected component information.",
"properties":
{
"name":
{
"type": "string",
"description": "User friendly placement name"
},
"code":
{
"type": "string",
"description": "Placement code"
},
"description":
{
"type": "string",
"description": "Placement description"
},
"custom":
{
"type": "object",
"additionalProperties":
{
"type": "string"
},
"description": "A string-to-string map of custom attributes"
},
"component":
{
"$ref": "#/$defs/RecipeComponent",
"description": "Selected component"
},
"addedTags":
{
"type": "array",
"items":
{
"type": "string"
},
"description": "A list of tags added to the placement to trigger custom rules functionality"
}
}
},
"RecipeComponent":
{
"type": "object",
"description": "Component selected in a placement",
"properties":
{
"placeholder":
{
"type": "boolean",
"description": "Indicates whether a component is a placeholder"
},
"code":
{
"type": "string",
"description": "Component code"
},
"trackAs":
{
"type": "string",
"description": "Alternate component code for analytics purposes, for example, when a component is known to the system under a different name"
},
"upc":
{
"type": "string",
"description": "Component UPC"
},
"sku":
{
"type": "string",
"description": "Component SKU"
},
"quantityMultiplier":
{
"type": "number",
"description": "Component quantity"
},
"description":
{
"type": "array",
"items":
{
"$ref": "#/$defs/RecipeComponentDescription"
},
"description": "A list of component options"
},
"custom":
{
"type": "object",
"additionalProperties":
{
"type": "string"
},
"description": "A string-to-string map of custom attributes"
},
"variables":
{
"type": "array",
"items":
{
"$ref": "#/$defs/RecipeVariable"
},
"description": "A list of selected variable values"
},
"addedTags":
{
"type": "array",
"items":
{
"type": "string"
},
"description": "A list of dynamically added component tags to trigger custom rules functionality"
}
}
},
"RecipeVariable":
{
"type": "object",
"properties":
{
"code":
{
"type": "string",
"description": "Variable code"
},
"value":
{
"type": "string",
"description": "Selected variable value"
}
}
},
"RecipeComponentDescription":
{
"type": "object",
"properties":
{
"code":
{
"type": "string",
"description": "Component option code"
},
"name":
{
"type": "string",
"description": "Component option name"
},
"definition":
{
"type": "string",
"description": "Component option definition code"
},
"custom":
{
"type": "object",
"additionalProperties":
{
"type": "string"
},
"description": "A string-to-string map of custom attributes"
}
}
},
"RecipeView":
{
"type": "object",
"description": "A view/render output for the recipe.",
"properties":
{
"name":
{
"type": "string",
"description": "View name"
},
"code":
{
"type": "string",
"description": "View code"
},
"previewPng":
{
"type": "string",
"format": "uri",
"description": "View preview image link in PNG format"
},
"previewJpg":
{
"type": "string",
"format": "uri",
"description": "View preview image link in JPG format"
},
"production":
{
"type": "string",
"format": "uri",
"description": "If a view represents a production file, the link to the file in configured format"
},
"productionReady":
{
"type": "boolean",
"description": "Indicates whether a view represents a production file"
},
"custom":
{
"type": "object",
"additionalProperties":
{
"type": "string"
},
"description": "A string-to-string map of custom attributes"
},
"variants":
{
"type": "array",
"items":
{
"$ref": "#/$defs/RecipeViewVariant"
},
"description": "A list of image variations, for example, saved in a different format or sizes"
}
}
},
"RecipeViewVariant":
{
"type": "object",
"properties":
{
"code":
{
"type": "string"
},
"suffix":
{
"type": "string"
},
"preview":
{
"type": "string",
"format": "uri"
}
}
}
}
}