Shopify Integration Data Model - CreatorCommerce.dev

CreatorCommerce syncs creator data to Shopify through metaobjects, collections, and customer accounts. This document explains the integration points and data flow.

Metaobject Integration

No Configuration Required: CreatorCommerce automatically creates and configures the creator metaobject type in your Shopify store. The metaobject is pre-configured to create new pages on entries by default, so you can start building landing page templates immediately without any metaobject setup.

Creator Metaobject

CreatorCommerce automatically creates a Shopify metaobject of type creator that mirrors creator data for Liquid template access. You don’t need to create or configure this metaobject — CC handles all setup, including:

Metaobject type creation
Field definitions and types
Page creation enabled by default (new pages are automatically created for each creator entry)
Data synchronization from CreatorCommerce to Shopify

The metaobject is ready to use as soon as CreatorCommerce is installed and your first creator is added.

Metaobject Structure

Metaobject Type: creator

Base Fields (Out-of-the-Box, No Custom Fields Required)

These fields are part of the default CreatorCommerce creator payload and are available without creating additional custom fields.

Group	Base Fields
Creator identity	`cc-creator-id`, `cc-creator-first-name`, `cc-creator-last-name`, `cc-creator-email`, `cc-creator-handle`, `cc-creator-is-onboarded`, `cc-creator-profile-picture`
Creator shop	`cc-creator-shop-id`, `cc-creator-shop-handle`, `cc-creator-shop-title`, `cc-creator-shop-url`, `cc-creator-shop-description`, `cc-creator-shop-theme-primary-color`
Collaboration	`cc-collab-id`, `cc-collab-relationship-manager`, `cc-collab-tier`, `cc-collab-tier-key`, `cc-collab-discount-amount`, `cc-collab-discount-type`, `cc-collab-tier-discount-amount`, `cc-collab-tier-discount-type`, `cc-collab-affiliate-code`, `cc-collab-discount-code`, `cc-collab-affiliate-link`
Shopify object refs	`cc-creator-collection`, `cc-creator-metaobject`, `cc-collab-metaobject`, `cc-creator-customer`
Channel / brand kit	`cc-channel-handle`, `cc-channel-myshopify-domain`, `cc-channel-brandkit-primary-color`, `cc-channel-brandkit-title`, `cc-channel-brandkit-primary-logo`, `cc-channel-integrations-klaviyo-enabled`, `cc-channel-default-messaging-enabled`
Campaign	`cc-campaign-id`, `cc-campaign-title`
Drops JSON	`cc-creator-drops` and nested fields like `cc-creator-drop-id`, `cc-creator-drop-collection-id`, `cc-creator-drop-product-shopify-id`, `cc-creator-drop-product-enhancement-note`, `cc-creator-drop-product-enhancement-media`, `cc-creator-drop-product-enhancement-variant`

Drop/Product Nested Base Keys

Inside each cc-creator-drops[] object, default keys include:

Drop-level: cc-creator-drop-id, cc-creator-drop-handle, cc-creator-drop-title, cc-creator-drop-description, cc-creator-drop-collection-id
Product-level: cc-creator-drop-product-id, cc-creator-drop-product-title, cc-creator-drop-product-shopify-id, cc-creator-drop-product-shopify-handle, cc-creator-drop-product-enhancement-id, cc-creator-drop-product-enhancement-note, cc-creator-drop-product-enhancement-media, cc-creator-drop-product-enhancement-variant
Enhancement object mirrors: enhancement.cc-creator-drop-product-enhancement-id, enhancement.cc-creator-drop-product-enhancement-note, enhancement.cc-creator-drop-product-enhancement-media, enhancement.cc-creator-drop-product-enhancement-variant, plus compatibility mirrors enhancement.note, enhancement.media, enhancement.cc-creator-drop-product-shopify-id
Shopify product mirrors for rendering convenience: id, title, vendor, handle, images[], variants[]

Some payloads include both cc-channel-myshopify-domain (correct spelling) and cc-channel-myshopify-domian (legacy typo variant). Prefer cc-channel-myshopify-domain when present, but handle both defensively.

Top-Level Fields:

{{ metaobject.cc-creator-first-name }}
{{ metaobject.cc-creator-last-name }}
{{ metaobject.cc-creator-profile-picture }}
{{ metaobject.cc-creator-shop-handle }}
{{ metaobject.cc-creator-shop-theme-primary-color }}
{{ metaobject.cc-creator-shop-description }}
{{ metaobject.cc-creator-drops }}  {# Collection list reference #}

JSON Data Field:

{{ metaobject.data.value.cc-creator-first-name }}
{{ metaobject.data.value['cc-creator-drops'] }}  {# JSON array #}
{{ metaobject.data.value['cc-public'] }}
{{ metaobject.data.value['cc-collab-discount-code'] }}

Metaobject Field Mapping

CreatorCommerce Field	Metaobject Field	Type
`firstName`	`cc-creator-first-name`	Single line text
`lastName`	`cc-creator-last-name`	Single line text
`profilePicture.url`	`cc-creator-profile-picture`	File reference / URL
`shop.handle`	`cc-creator-shop-handle`	Single line text
`shop.theme.primaryColor`	`cc-creator-shop-theme-primary-color`	Color
`shop.description`	`cc-creator-shop-description`	Multi-line text
`drops[]`	`cc-creator-drops`	Collection list
Drops JSON	`data.value['cc-creator-drops']`	JSON

Use this field mapping table for concepts and storage shape, and use Base Fields (Out-of-the-Box) above as the canonical runtime key list.

Metaobject Access Patterns

On Metaobject Page Templates:

{# Direct access to metaobject #}
{{ metaobject.cc-creator-first-name }}
{% assign cc_creator = metaobject %}

On Other Pages/Sections:

{% liquid
  if metaobject
    assign cc_creator = metaobject
  else
    assign cc_handle = cart.attributes['cc-creator-handle']
    assign cc_creator = metaobjects.creator[cc_handle]
  endif
  
  assign has_creator = cc_creator != blank
%}

In Snippets:

{% liquid
  if metaobject
    assign cc_creator = metaobject
  else
    assign cc_handle = cart.attributes['cc-creator-handle']
    assign cc_creator = metaobjects.creator[cc_handle]
  endif
  
  assign has_creator = cc_creator != blank
%}

Collection Integration

Drop → Collection Mapping

Each drop maps to one Shopify collection: Relationship:

Drop ID → Collection ID (stored in shopifyCreatorCollectionId)
Collection contains all products from the drop
Products sync automatically when drop is updated

Collection Access

Via Creator Metaobject:

{# Collection list field #}
{% assign drops_collections = cc_creator['cc-creator-drops'].value %}

{# JSON drop data with collection IDs #}
{% assign drops_json = cc_creator.data.value['cc-creator-drops'] %}

Matching JSON Drops to Collections:

{% for json_drop in drops_json %}
  {% assign collection_id = json_drop['cc-creator-drop-collection-id'] %}
  
  {% for collection_drop in drops_collections %}
    {% if collection_drop.id | append: '' == collection_id %}
      {# Match found - collection_drop is the Shopify collection #}
      {% for product in collection_drop.products %}
        {# Display product #}
      {% endfor %}
      {% break %}
    {% endif %}
  {% endfor %}
{% endfor %}

Collection Metadata

Collections created by CreatorCommerce include metadata:

Title: Drop title
Description: Drop description
Products: Synced from drop product list
Handle: Auto-generated or custom

Customer Account Integration

Creator Customer Account

Optional Shopify customer account for creators, used for:

Discount code association
Customer portal access
Order attribution

Customer Account Fields

Metadata Stored:

shopifyCustomerId - Customer GID
shopifyCustomerAccountActivationUrl - Activation link (if needed)
Linked to collab via metadata.shopifyCustomerId

Customer Account Access

For Discount Codes: Discount codes can be associated with creator customer accounts for automatic application. Activation Flow:

Customer account created
Activation URL generated
Creator receives invitation
Account activated

ID Formats

Shopify GID (Global ID) Format

Shopify uses GIDs (Global Identifiers) in this format:

gid://shopify/{Type}/{NumericId}

Examples:

gid://shopify/Metaobject/77942685991
gid://shopify/Collection/488980119847
gid://shopify/Customer/8587704402215
gid://shopify/Product/8491113971999
gid://shopify/ProductVariant/46033520296223

ID Storage in CreatorCommerce

Metaobject IDs:

{
  "metadata": {
    "shopifyCreatorMetaobjectId": "gid://shopify/Metaobject/77942685991"
  }
}

Collection IDs:

{
  "metadata": {
    "shopifyCreatorCollectionId": "gid://shopify/Collection/488980119847"
  }
}

In Metaobject JSON:

{
  "cc-creator-drop-collection-id": "488980119847"  {# Numeric ID only #}
}

ID Conversion for Comparison

Critical: Shopify object IDs (integers) must be converted to strings when comparing with JSON-stored IDs:

{# ❌ Wrong - type mismatch #}
{% if collection_drop.id == json_drop['cc-creator-drop-collection-id'] %}

{# ✅ Correct - convert to string #}
{% if collection_drop.id | append: '' == json_drop['cc-creator-drop-collection-id'] %}

Data Synchronization

Sync Triggers

Real-time Sync:

Drop creation/update
Product additions/removals
Creator profile updates
Custom field changes

Scheduled Sync:

Metaobject enrichment workflows
Collection product updates
Analytics aggregation
Data consistency checks

Sync Flow

CreatorCommerce Backend
  ↓ (API call / webhook)
Shopify Admin API
  ↓
Metaobject Update
  ↓
Collection Update (if drop changed)
  ↓
Shop Liquid templates can access updated data

Bidirectional Sync

CreatorCommerce → Shopify:

Creator data updates
Drop changes
Product lists
Custom fields

Shopify → CreatorCommerce:

Collection changes (rare)
Product availability updates
Metadata enrichment

Metaobject Data Field

JSON Structure

The data field in metaobjects stores a JSON representation:

{
  "cc-creator-id": "6997d1305fe142fd13cff4b6",
  "cc-creator-first-name": "Jill",
  "cc-creator-last-name": "Doe",
  "cc-creator-is-onboarded": false,
  "cc-creator-profile-picture": "https://assets.drops.shop/-6997d1305fe142fd13cff4b6/6997ddb0f02b371d3a82df4a.png",
  "cc-creator-handle": "jill-650",
  "cc-creator-email": "jill+nuudstest123@creatorcommerce.shop",
  "cc-creator-shop-id": "6997d1b29655870ce8359c45",
  "cc-creator-shop-handle": "jill-650",
  "cc-creator-shop-title": "Jill's Shop",
  "cc-creator-shop-url": "https://drops.shop/jill-650/nuuds",
  "cc-creator-shop-description": "Explore my handpicked products from my favorite brands. Everything here is personally tested and approved by me, and your purchase helps support what I do. Plus, you’ll score an exclusive discount!",
  "cc-creator-shop-theme-primary-color": "#270803",
  "cc-collab-id": "6997d1305fe142fd13cff4d7",
  "cc-collab-relationship-manager": "social-snowball",
  "cc-collab-tier": "CC // Test Pages",
  "cc-collab-tier-key": "28002",
  "cc-collab-discount-amount": "20",
  "cc-collab-discount-type": "Percentage",
  "cc-collab-tier-discount-amount": "20",
  "cc-collab-tier-discount-type": "Percentage",
  "cc-collab-affiliate-code": "JILL23878",
  "cc-collab-discount-code": "JILL23878",
  "cc-collab-affiliate-link": "https://www.nuuds.com/JILL23878",
  "cc-creator-collection": "gid://shopify/Collection/451608281339",
  "cc-creator-metaobject": "gid://shopify/Metaobject/156200567035",
  "cc-collab-metaobject": "gid://shopify/Metaobject/156200567035",
  "cc-creator-customer": "gid://shopify/Customer/9161177006331",
  "cc-channel-handle": "nuuds",
  "cc-channel-myshopify-domian": "nuuds-com.myshopify.com",
  "cc-channel-myshopify-domain": "nuuds-com.myshopify.com",
  "cc-channel-brandkit-primary-color": "#270803",
  "cc-channel-brandkit-title": "nuuds",
  "cc-channel-brandkit-primary-logo": "https://assets.drops.shop/699752d1f02b371d3a82cb67/6997d7b976e884895ba4a29d.png",
  "cc-channel-integrations-klaviyo-enabled": true,
  "cc-channel-default-messaging-enabled": "false",
  "cc-campaign-id": "699752d110aaf04ada0eb4ef",
  "cc-campaign-title": "Default Campaign",
  "cc-creator-drops": [
    {
      "cc-creator-drop-id": "6997dd60c65868de8b5a1aaf",
      "cc-creator-drop-handle": "without-these-id-just-go-nude",
      "cc-creator-drop-title": "Without these, I'd just go nude",
      "cc-creator-drop-description": "nuuds is serious a game changer and I have to admit I literally took like all my other active wear and such to the donation bin. I'm just going nuud now....",
      "cc-creator-drop-collection-id": "451608248571",
      "cc-creator-drop-products": [
        {
          "cc-creator-drop-product-id": "6997dd615fe142fd13d8b43e",
          "cc-creator-drop-product-title": "Slinky Rib Lounge Pant | Navy",
          "cc-creator-drop-product-enhancement-id": "6997dd61c65868de8b5a1ac4",
          "cc-creator-drop-product-enhancement-note": "Love these so much !",
          "cc-creator-drop-product-enhancement-variant": "47773464363259",
          "cc-creator-drop-product-enhancement-media": [
            {
              "mediaContentType": "IMAGE",
              "mimeType": "image/webp",
              "url": "https://assets.drops.shop/all/6997dbf076e884895ba4a345.webp",
              "originalFilename": "62_W-276-DNAV_On-Model_Full-Front_S_72cedbdd-30be-4499-9402-992f1e7e3b26.webp",
              "filename": "6997dbf076e884895ba4a345",
              "extension": "webp",
              "owner": "all",
              "tags": [],
              "_id": "6997dbf076e884895ba4a345",
              "__v": 0
            },
            {
              "mediaContentType": "IMAGE",
              "mimeType": "image/webp",
              "url": "https://assets.drops.shop/all/6997dbeb0c4242d6139e3237.webp",
              "originalFilename": "63_W-276-DNAV_On-Model_Front-Crop_S_5a9e05e9-1e4f-4cfb-b997-47b51ea933b3.webp",
              "filename": "6997dbeb0c4242d6139e3237",
              "extension": "webp",
              "owner": "all",
              "tags": [],
              "_id": "6997dbeb0c4242d6139e3237",
              "__v": 0
            }
          ],
          "cc-creator-drop-product-shopify-id": "9192128643323",
          "cc-creator-drop-product-shopify-handle": "slinky-rib-lounge-pant-navy",
          "enhancement": {
            "cc-creator-drop-product-enhancement-id": "6997dd61c65868de8b5a1ac4",
            "cc-creator-drop-product-enhancement-note": "Love these so much !",
            "cc-creator-drop-product-enhancement-media": [
              {
                "mediaContentType": "IMAGE",
                "mimeType": "image/webp",
                "url": "https://assets.drops.shop/all/6997dbf076e884895ba4a345.webp",
                "originalFilename": "62_W-276-DNAV_On-Model_Full-Front_S_72cedbdd-30be-4499-9402-992f1e7e3b26.webp",
                "filename": "6997dbf076e884895ba4a345",
                "extension": "webp",
                "owner": "all",
                "tags": [],
                "_id": "6997dbf076e884895ba4a345",
                "__v": 0
              },
              {
                "mediaContentType": "IMAGE",
                "mimeType": "image/webp",
                "url": "https://assets.drops.shop/all/6997dbeb0c4242d6139e3237.webp",
                "originalFilename": "63_W-276-DNAV_On-Model_Front-Crop_S_5a9e05e9-1e4f-4cfb-b997-47b51ea933b3.webp",
                "filename": "6997dbeb0c4242d6139e3237",
                "extension": "webp",
                "owner": "all",
                "tags": [],
                "_id": "6997dbeb0c4242d6139e3237",
                "__v": 0
              }
            ],
            "cc-creator-drop-product-enhancement-variant": "47773464363259",
            "note": "Love these so much !",
            "media": [
              {
                "mimeType": "image/webp",
                "url": "https://assets.drops.shop/all/6997dbf076e884895ba4a345.webp"
              },
              {
                "mimeType": "image/webp",
                "url": "https://assets.drops.shop/all/6997dbeb0c4242d6139e3237.webp"
              }
            ],
            "cc-creator-drop-product-shopify-id": "9192128643323"
          },
          "id": "9192128643323",
          "title": "Slinky Rib Lounge Pant | Navy",
          "vendor": "nuuds",
          "handle": "slinky-rib-lounge-pant-navy",
          "images": [
            {
              "src": "https://cdn.shopify.com/s/files/1/0654/5565/3115/files/62_W-276-DNAV_On-Model_Full-Front_S_72cedbdd-30be-4499-9402-992f1e7e3b26.jpg?v=1771019513"
            },
          ],
          "variants": [
            {
              "id": "47773464494331",
              "title": "XXXL",
              "price": "88.0",
              "selectedOptions": [
                {
                  "name": "Color",
                  "value": "Navy"
                },
                {
                  "name": "Size",
                  "value": "XXXL"
                }
              ]
            }
          ]
        },
        {
          "cc-creator-drop-product-id": "6997dd615fe142fd13d8b43f",
          "cc-creator-drop-product-title": "Slinky Rib Lounge Pant | Darkest Olive",
          "cc-creator-drop-product-enhancement-id": "6997dd61c65868de8b5a1ac7",
          "cc-creator-drop-product-enhancement-note": "These are great!",
          "cc-creator-drop-product-enhancement-media": [],
          "cc-creator-drop-product-shopify-id": "9177537970427",
          "cc-creator-drop-product-shopify-handle": "slinky-rib-lounge-pant-darkest-olive",
          "enhancement": {
            "cc-creator-drop-product-enhancement-id": "6997dd61c65868de8b5a1ac7",
            "cc-creator-drop-product-enhancement-note": "These are great!",
            "cc-creator-drop-product-enhancement-media": [],
            "note": "These are great!",
            "media": [],
            "cc-creator-drop-product-shopify-id": "9177537970427"
          },
          "id": "9177537970427",
          "title": "Slinky Rib Lounge Pant | Darkest Olive",
          "vendor": "nuuds",
          "handle": "slinky-rib-lounge-pant-darkest-olive",
          "images": [
            {
              "src": "https://cdn.shopify.com/s/files/1/0654/5565/3115/files/69_W-276-DKOL_On-Model_Full-Front_S.jpg?v=1767886874"
            },
            {
              "src": "https://cdn.shopify.com/s/files/1/0654/5565/3115/files/74_W-276-DKOL_Detail_2_S.jpg?v=1767886061"
            }
          ],
          "variants": [
            {
              "id": "47717321965819",
              "title": "XXXL",
              "price": "88.0",
              "selectedOptions": [
                {
                  "name": "Color",
                  "value": "Darkest Olive"
                },
                {
                  "name": "Size",
                  "value": "XXXL"
                }
              ]
            }
          ]
        },
        {
          "cc-creator-drop-product-id": "6997dd615fe142fd13d8b451",
          "cc-creator-drop-product-title": "Contrast Panel Refine Short | Black/White",
          "cc-creator-drop-product-enhancement-id": "6997dd61c65868de8b5a1ac8",
          "cc-creator-drop-product-enhancement-note": "",
          "cc-creator-drop-product-enhancement-media": [
            {
              "mediaContentType": "VIDEO",
              "mimeType": "video/mp4",
              "url": "https://assets.drops.shop/all/699a15751ec44fac06fa5441.mp4",
              "originalFilename": "DTS_CHILL_DUDES_Joey_Bania_Clips_ID701 (1).mp4",
              "filename": "699a15751ec44fac06fa5441",
              "extension": "mp4",
              "owner": "all",
              "tags": [],
              "_id": "699a15751ec44fac06fa5441",
              "__v": 0
            }
          ],
          "cc-creator-drop-product-shopify-id": "9145700090107",
          "cc-creator-drop-product-shopify-handle": "contrast-panel-refine-short-black-white",
          "enhancement": {
            "cc-creator-drop-product-enhancement-id": "6997dd61c65868de8b5a1ac8",
            "cc-creator-drop-product-enhancement-note": "",
            "cc-creator-drop-product-enhancement-media": [
              {
                "mediaContentType": "VIDEO",
                "mimeType": "video/mp4",
                "url": "https://assets.drops.shop/all/699a15751ec44fac06fa5441.mp4",
                "originalFilename": "DTS_CHILL_DUDES_Joey_Bania_Clips_ID701 (1).mp4",
                "filename": "699a15751ec44fac06fa5441",
                "extension": "mp4",
                "owner": "all",
                "tags": [],
                "_id": "699a15751ec44fac06fa5441",
                "__v": 0
              }
            ],
            "note": "",
            "media": [
              {
                "mimeType": "video/mp4",
                "url": "https://assets.drops.shop/all/699a15751ec44fac06fa5441.mp4"
              }
            ],
            "cc-creator-drop-product-shopify-id": "9145700090107"
          },
          "id": "9145700090107",
          "title": "Contrast Panel Refine Short | Black/White",
          "vendor": "nuuds",
          "handle": "contrast-panel-refine-short-black-white",
          "images": [
            {
              "src": "https://cdn.shopify.com/s/files/1/0654/5565/3115/files/302_M-1053-BKWH_On-Model_Full-Front_M.jpg?v=1768318272"
            },
          ],
          "variants": [
            {
              "id": "47627884790011",
              "title": "XL",
              "price": "72.0",
              "selectedOptions": [
                {
                  "name": "Color",
                  "value": "White"
                },
                {
                  "name": "Size",
                  "value": "XL"
                }
              ]
            },
            {
              "id": "47627884822779",
              "title": "XXL",
              "price": "72.0",
              "selectedOptions": [
                {
                  "name": "Color",
                  "value": "White"
                },
                {
                  "name": "Size",
                  "value": "XXL"
                }
              ]
            },
            {
              "id": "47627884855547",
              "title": "XXXL",
              "price": "72.0",
              "selectedOptions": [
                {
                  "name": "Color",
                  "value": "White"
                },
                {
                  "name": "Size",
                  "value": "XXXL"
                }
              ]
            }
          ]
        },
        {
          "cc-creator-drop-product-id": "6997dd615fe142fd13d8b445",
          "cc-creator-drop-product-title": "Contrast Panel Refine Short | Black/Espresso",
          "cc-creator-drop-product-enhancement-id": "6997dd61c65868de8b5a1ac9",
          "cc-creator-drop-product-enhancement-note": "",
          "cc-creator-drop-product-enhancement-media": [],
          "cc-creator-drop-product-shopify-id": "9145700057339",
          "cc-creator-drop-product-shopify-handle": "contrast-panel-refine-short-black-espresso",
          "enhancement": {
            "cc-creator-drop-product-enhancement-id": "6997dd61c65868de8b5a1ac9",
            "cc-creator-drop-product-enhancement-note": "",
            "cc-creator-drop-product-enhancement-media": [],
            "note": "",
            "media": [],
            "cc-creator-drop-product-shopify-id": "9145700057339"
          },
          "id": "9145700057339",
          "title": "Contrast Panel Refine Short | Black/Espresso",
          "vendor": "nuuds",
          "handle": "contrast-panel-refine-short-black-espresso",
          "images": [
            {
              "src": "https://cdn.shopify.com/s/files/1/0654/5565/3115/files/300_M-1053-BESP_Detail_2_M.jpg?v=1768318125"
            }
          ],
          "variants": [
            {
              "id": "47627884593403",
              "title": "XL",
              "price": "72.0",
              "selectedOptions": [
                {
                  "name": "Color",
                  "value": "Espresso"
                },
                {
                  "name": "Size",
                  "value": "XL"
                }
              ]
            },
            {
              "id": "47627884626171",
              "title": "XXL",
              "price": "72.0",
              "selectedOptions": [
                {
                  "name": "Color",
                  "value": "Espresso"
                },
                {
                  "name": "Size",
                  "value": "XXL"
                }
              ]
            },
            {
              "id": "47627884658939",
              "title": "XXXL",
              "price": "72.0",
              "selectedOptions": [
                {
                  "name": "Color",
                  "value": "Espresso"
                },
                {
                  "name": "Size",
                  "value": "XXXL"
                }
              ]
            }
          ]
        },
        {
          "cc-creator-drop-product-id": "6997dd615fe142fd13d8b458",
          "cc-creator-drop-product-title": "Men's Refine Jogger | Blackpine",
          "cc-creator-drop-product-enhancement-id": "6997dd61c65868de8b5a1aca",
          "cc-creator-drop-product-enhancement-note": "",
          "cc-creator-drop-product-enhancement-media": [],
          "cc-creator-drop-product-shopify-id": "9145699860731",
          "cc-creator-drop-product-shopify-handle": "mens-refine-jogger-blackpine",
          "enhancement": {
            "cc-creator-drop-product-enhancement-id": "6997dd61c65868de8b5a1aca",
            "cc-creator-drop-product-enhancement-note": "",
            "cc-creator-drop-product-enhancement-media": [],
            "note": "",
            "media": [],
            "cc-creator-drop-product-shopify-id": "9145699860731"
          },
          "id": "9145699860731",
          "title": "Men's Refine Jogger | Blackpine",
          "vendor": "nuuds",
          "handle": "mens-refine-jogger-blackpine",
          "images": [
            {
              "src": "https://cdn.shopify.com/s/files/1/0654/5565/3115/files/283_M-1028-BKPN_Detail_2_L.jpg?v=1768317671"
            }
          ],
          "variants": [
            {
              "id": "47627883315451",
              "title": "L",
              "price": "98.0",
              "selectedOptions": [
                {
                  "name": "Color",
                  "value": "Blackpine"
                },
                {
                  "name": "Size",
                  "value": "L"
                }
              ]
            },
            {
              "id": "47627883413755",
              "title": "XXXL",
              "price": "98.0",
              "selectedOptions": [
                {
                  "name": "Color",
                  "value": "Blackpine"
                },
                {
                  "name": "Size",
                  "value": "XXXL"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Why Two Access Patterns?

Top-Level Fields:

Direct Shopify field access
Simple, fast queries
Standard Liquid patterns

JSON Data Field:

Complete data structure
Preserves order (for drops)
Custom fields
Nested structures

Best Practice: Use data.value for complex structures (drops, custom fields), top-level for simple fields.

Collection Product Sync

Automatic Product Updates

When a drop is updated:

Drop products changed → Collection products updated
Product removed from drop → Removed from collection
Product added to drop → Added to collection
Drop deleted → Collection remains (archived)

Product Ordering

In Collections:

Products ordered by drop product list
Order preserved from drop definition

In JSON:

Order preserved in cc-creator-drop-products array
Always iterate JSON first to maintain order

Cart Attributes Integration

Cart Attribute Flow

Creator Link Clicked
  ↓
Cart Attributes Set:
  - cc-creator-id
  - cc-creator-handle
  - cc-campaign-id
  ↓
Metaobject Lookup via Handle
  ↓
Creator Data Available in Liquid

Reference in Liquid:

{% liquid
  if metaobject
    assign cc_creator = metaobject
  else
    assign cc_handle = cart.attributes['cc-creator-handle']
    assign cc_creator = metaobjects.creator[cc_handle]
  endif
  
  assign has_creator = cc_creator != blank
%}

Cart Attribute Persistence

Cart attributes persist:

Through checkout process
In order metadata
For attribution tracking

Best Practices

1. Always Use Handle for Lookups

Handles are more reliable than IDs for metaobject access:

{# ✅ Correct #}
{% liquid
  if metaobject
    assign cc_creator = metaobject
  else
    assign cc_handle = cart.attributes['cc-creator-handle']
    assign cc_creator = metaobjects.creator[cc_handle]
  endif
%}

{# ❌ Wrong #}
{% assign cc_creator = metaobjects.creator[creator_id] %}

2. Type-Safe ID Comparison

Always convert Shopify IDs to strings:

{% assign collection_id = collection.id | append: '' %}
{% if collection_id == json_drop['cc-creator-drop-collection-id'] %}

3. Handle Missing Metaobjects

Check for metaobject existence:

{% if cc_creator and cc_creator.data and cc_creator.data.value %}
  {# Safe to access #}
{% endif %}

4. Prefer Data.Value for Complex Structures

Use JSON for drops, nested data, custom fields:

{# ✅ For drops order #}
{% for drop in cc_creator.data.value['cc-creator-drops'] %}

{# ✅ For custom fields #}
{{ cc_creator.data.value['cc-public'] }}

Data Model Overview - High-level architecture
Creator & Collab Data Model - Creator structures
Drops & Products Data Model - Drop structures
Custom Fields Reference - Field patterns

DATA MODEL

SHOPIFY

SDKS

TRACKING & ATTRIBUTION

UNIFIED API

WEBHOOKS

KLAVIYO

​Metaobject Integration

​Creator Metaobject

​Metaobject Structure

​Base Fields (Out-of-the-Box, No Custom Fields Required)

​Drop/Product Nested Base Keys

​Metaobject Field Mapping

​Metaobject Access Patterns

​Collection Integration

​Drop → Collection Mapping

​Collection Access

​Collection Metadata

​Customer Account Integration

​Creator Customer Account

​Customer Account Fields

​Customer Account Access

​ID Formats

​Shopify GID (Global ID) Format

​ID Storage in CreatorCommerce

​ID Conversion for Comparison

​Data Synchronization

​Sync Triggers

​Sync Flow

​Bidirectional Sync

​Metaobject Data Field

​JSON Structure

​Why Two Access Patterns?

​Collection Product Sync

​Automatic Product Updates

​Product Ordering

​Cart Attributes Integration

​Cart Attribute Flow

​Cart Attribute Persistence

​Best Practices

​1. Always Use Handle for Lookups

​2. Type-Safe ID Comparison

​3. Handle Missing Metaobjects

​4. Prefer Data.Value for Complex Structures

​Related Documentation

Metaobject Integration

Creator Metaobject

Metaobject Structure

Base Fields (Out-of-the-Box, No Custom Fields Required)

Drop/Product Nested Base Keys

Metaobject Field Mapping

Metaobject Access Patterns

Collection Integration

Drop → Collection Mapping

Collection Access

Collection Metadata

Customer Account Integration

Creator Customer Account

Customer Account Fields

Customer Account Access

ID Formats

Shopify GID (Global ID) Format

ID Storage in CreatorCommerce

ID Conversion for Comparison

Data Synchronization

Sync Triggers

Sync Flow

Bidirectional Sync

Metaobject Data Field

JSON Structure

Why Two Access Patterns?

Collection Product Sync

Automatic Product Updates

Product Ordering

Cart Attributes Integration

Cart Attribute Flow

Cart Attribute Persistence

Best Practices

1. Always Use Handle for Lookups

2. Type-Safe ID Comparison

3. Handle Missing Metaobjects

4. Prefer Data.Value for Complex Structures

Related Documentation