product_id, and Depict computes it from your product data. If a card went out without it, your storefront couldn’t add the product to the cart. Merchant attributes make such fields part of your store’s contract.
The card carries two kinds of attribute. Declared attributes are computed when Depict imports your product data, and come on every card. Display attributes are the fields your display settings list, and come only when you ask with include=attributes.
Declared attributes
Depict computes each declared attribute when it imports your product data, and stores the result. The API reads the stored value. It returns declared attributes onbrowse, products and recommendations, with or without include.
On the card, an attribute appears under its key, on each variant:
key, as in filter_by=add_to_cart_id:=1001-M-SE. See Fields you can filter on.
Each attribute has a type:
- A key is lowercase snake case, matching
^[a-z][a-z0-9_]*$. - A variant without a value for an attribute doesn’t carry it, unless the attribute is required.
- Changing an attribute’s type is a breaking change for your store’s card. To change what an attribute means with the same type, say from color names to hex codes, use a new key.
- If one key ends up stored with two types, neither is served. Use a new key instead.
- An empty string counts as no value.
Required attributes
Depict can mark an attribute as required for your store, with an optional pattern its values must match, such as your cart’s id format. One attribute can be marked as the add-to-cart id. The add-to-cart id is always required.- Every variant on a card carries a valid value for each required attribute.
- A variant without a valid value is left out of the card. A card with no variants left is left out of the page. The rest of the page is still served.
- On
products, the id of a card left out this way is inmissing.
Display attributes
Sendinclude=attributes on browse, products or recommendations to get the fields your store’s display settings list, named by their id in those settings:
variants[i].attributes.<id>is that variant’s value.attributes.<id>on the card is the value when every variant agrees. Otherwise it is a list of the distinct values, with numbers and booleans as strings. On a style card, a value that differs between colorways is on each variant, not on the card.- A value with translations comes in the request’s language.
- A display attribute that lives on your price list, such as a
show_as_saleflag, takes its value from the request’s market. - Ids that are already card fields, such as the title, SKU, prices and images, are not repeated.
- On a variant, a declared attribute wins over a display attribute with the same name.
- The ids your store groups cards by, such as
item_group_id, are display attributes too, even when your display settings don’t list them. - Color comes without
include. The color namecolor_nameand the hex codecolor_hexorcolor_hex_codeare served as the card’scolorand each colorway’s, not inattributes. Withinclude=attributesthey are inattributestoo. A color attribute you declare is always inattributes. - Image details such as alt text are not part of the card.
If your store has its own attribute with one of these ids, you get your value instead. On Shopify stores you always get the built-in, and
tags, barcode, pim_variant_index, product_type, published_at and variant_title come from Shopify’s product fields.
