Skip to main content
  

Data Sources Guide

Updated

    Your integration with Athos Commerce will be driven by the product data you provide. Whether you're building your own custom feed, or are relying on one of our ecommerce connectors to generate the data, this guide provides our best practices and recommendations to ensure your product feed is optimized for success.

    Supported Feed Types

    When building your own custom product feed, Athos supports the following feed types:

    CSV Data Sample | Download sample-csv-athos.csv file

    • Columns may be delimited by a tab, comma, pipe, or semi-colon
    • Column entries are to be wrapped in double quotes to contain the data within; all double quotes within that data entry must then be escaped

    XML Data Sample | Download sample-athos.xml file

    • There must be a consistent Record Element node used throughout; for example:  <Product>
    • Each record must contain a Unique Key node that identifies that product; for example:  <Product_ID>
    • All nested nodes will be flattened, only accounting for the name of the lowest level node

    ndJSON Data Sample | Download sample-athos.json file

    • Each product object representation must exist in a new line of its own
    • Multiple levels within the product object will be flattened, only accounting for the keys at the lowest level

    Note: For a custom feed, you must provide a hosted URL to your feed file, hosted over FTP, SFTP, HTTP, or HTTPS. For HTTP/S files, you may add basic authentication to the file location. If the server where your feed file is located is IP-restricted, the Athos IP Addresses must be white-listed.

    Note: Be advised that we now pass standard variants with each child product in its own row, with an indication of the parent ID (__Parent_ID).

    Tip: Operating on one of our data-connected platforms? Skip the hassle and use our Platform Connector instead to generate your data feed.

    Base Feed Requirements

    The following data fields are required in order for us to successfully validate and index your feed:

    Unique ID

    The unique identifier for the product. This value must truly be unique for every product, and any product with a blank Unique ID will be skipped during the indexing of your data.

    SKU

    This SKU assignment will be used as part of our tracking scripts.

    Name

    This value is the product name used within your product listing item display.

    Product URL

    This value is the URL that links to your product display page.

    Price

    This value is the final selling price of the product. If the product is actively on sale, this is to be assigned the sale price, not the base price.

    Thumbnail URL

    This value is the image to be shown within your product listing item display. The dimensions of the provided thumbnail URL should match the same image dimensions used in the item display.

    Note: Your product feed must also contain a minimum of 10 products in order to index into the Athos system. 

    Variant Support

    We provide standard variant support for custom feeds. If your catalog contains variant products, there are a few fields that enable variant specific capabilities. The field reference below details the fields that are required in your feed to take full advantage of our merchandising capabilities. While most of these fields are technically optional, we recommend that customers include these so that we can provide them the best possible merchandising experience.

    Field Reference for Variant Products

    1. __parent_id = The unique identifier of the parent product to which the current variant belongs. This is used to group variants under a single product container. This value is optional If the value is not present, then we will automatically use the Unique ID selected in the Core Mappings page.

      Format: JSON

      { "type": "string" }

      Example (JSON)

      "__parent_id": "14725170364782"

     

    1. __parent_title = The general title of the parent product. This value is optional If the value is not present, then we will automatically use the Product Name selected in the Core Mappings page.

      Format: JSON

      { "type": "string" }

      Example (JSON)

      "__parent_title": "Align Crew"

     

    1. __parent_image = The URL of the primary featured image associated with the parent product. This value is optional If the value is not present, then we will automatically use the Image URL selected in the Core Mappings page.

      Format: JSON

      { "type": "string", "format": "uri"}

      Example (JSON)

      "__parent_image": "https://cdn.shopify.com/s/files/1/0916/6477/7582/files/Women_s_Apparel_Align_Crewneck_-_Olive_519ac0c5-e067-4ab7-9fe5-5421f364c52a.png?v=1747685123"

     

    1. __standard_options = A complete list of all configurable options available for the parent product (e.g., Color, Size). This object includes the position of the option and all possible values found on the parent product level. This value is optional If the value is not present, then Athos will not be able to display swatches.

      Format: JSON

      {
  "type":"object",
  "patternProperties":{
     "^[a-z_]+$":{
        "type":"object",
        "properties":{
           "position":{
              "type":"integer"
           },
           "values":{
              "type":"array",
              "items":{
                 "type":"string"
              }
           }
        }
     }
  }
}

      Example (JSON)

      "__standard_options":{
  "color":{
     "position":1,
     "values":[
        "Olive",
        "Navy",
        "Teal",
        "Crimson"
     ]
  },
  "size":{
     "position":2,
     "values":[
        "L",
        "M"
     ]
  }
}

       

    2. __variant_position = The integer index representing the order of the current variant within the list of all product variants. This value is optional This value is required in Search as a tiebreaker to determine which variant to show. If the value is not present, then all items will have a position of 0.

      Format: JSON

      { "type": "integer" }

      Example (JSON)

      "__variant_position": 1

       

    3. __in_stock = A boolean flag indicating if the specific current variant is available for purchase (inventory > 0) or allows overselling. This value is optional If the value is not present, then they would need to provide another attribute if they want to merchandise based on whether or not the product is in stock.

      Format: JSON

      { "type": "boolean" }

      Example (JSON)

      "__in_stock": true

       

    4. __in_stock_pct = The percentage of valid variants for this product that are currently in stock. This gives a high-level view of inventory health for the parent product. This value is optional If the value is not present, then this value won't be able to be used for merchandising based on the availability curve.

      Format: JSON

      { "type": "number" }

      Example (JSON)

      "__in_stock_pct": 50

       

    5. __swatch_options = A list containing details for options configured to be displayed as visual swatches. It maps the field name to its specific swatch value. Certain fields of the options will be optional and can be provided when available. This value is optional If the value is not present, then Athos will not be able to display swatches.

      Format: JSON

      {
  "type":"object",
  "patternProperties":{
     "^[a-zA-Z0-9_]+$":{
        "type":"object",
        "properties":{
           "value":{
              "type":"string"
           },
           "id":{
              "type":"string"
           },
           "colors":{
              "type":"array"
           },
           "image":{
              "type":"string"
           }
        }
     }
  }
}

      Example (JSON)

      "__swatch_options":{
  "color":{
     "value":"Olive"
  }
}

      Example with optional fields (JSON)

      "__swatch_options":{
  "color":{
     "value":"Olive",
     "id":"1234",
     "colors":[
        "F54927"
     ],
     "image":"https://cdn.shopify.com/s/files/1/0916/6477/7582/files/Women_s_Apparel_Align_Crewneck_-_Olive_519ac0c5-e067-4ab7-9fe5-5421f364c52a.png"
  }
}

       

    6. __selected_options = A list of the specific option values that define the current variant. This indicates exactly which configuration (e.g., "Olive" and "L") this variant record represents. This value is optional If the value is not present, then it reduces our ability to differentiate variants (assuming it's required).

      Format: JSON

      {
  "type":"object",
  "patternProperties":{
     "^[a-zA-Z0-9_]+$":{
        "type":"object",
        "properties":{
           "value":{
              "type":"string"
           }
        }
     }
  }
}

      Example (JSON)

      "__selected_options":{
  "size":{
     "value":"L"
  },
  "color":{
     "value":"Olive"
  }
}
    7. __group_by_swatch
      Description: A boolean flag used to identify the primary variant representative for a specific swatch attribute (e.g., color). It is set to true only the first time a unique swatch value is encountered among the variants. Subsequent variants sharing that same swatch value must be set to false. This prevents duplicate swatches from rendering in product listings while ensuring every unique visual option is represented.
      Note: This field is mandatory if product swatches are included in your storefront configuration. It should always be set to false on individual simple product records that do not contain variants.
      Format:
      {
  "type": "boolean"
}
      Example: For a variants product with variants where Color is the designated swatch option:
      Variant 1 (Rosewood) is the first time "Rosewood" appears -> true
      Variant 2 (Rosewood) "Rosewood" was already introduced in Variant 1 -> false
      Variant 3 (Thyme Green) is the first time "Thyme Green" appears -> true
      Variant 4 (Thyme Green) "Thyme Green" was already introduced in Variant 3 -> false 
      [
  {
    "Product ID": "5671290",
    "SKU": "HEH-2245-RSWD-SM",
    "Name": "Simply Sweet Tshirt",
    "__parent_id": "7615",
    "__group_by_swatch": true,
    "__selected_options": { "Color": { "value": "Rosewood" }, "Size": { "value": "Small" } }
  },
  {
    "Product ID": "678123",
    "SKU": "HEH-2245-RSWD-MD",
    "Name": "Simply Sweet Tshirt",
    "__parent_id": "7615",
    "__group_by_swatch": false, 
    "__selected_options": { "Color": { "value": "Rosewood" }, "Size": { "value": "Medium" } }
  },
  {
    "Product ID": "512345",
    "SKU": "HEH-2245-THGR-SM",
    "Name": "Simply Sweet Tshirt",
    "__parent_id": "7615",
    "__group_by_swatch": true, 
    "__selected_options": { "Color": { "value": "Thyme Green" }, "Size": { "value": "Small" } }
  },
  {
    "Product ID": "234567",
    "SKU": "HEH-2245-THGR-MD",
    "Name": "Simply Sweet Tshirt",
    "__parent_id": "7615",
    "__group_by_swatch": false,
    "__selected_options": { "Color": { "value": "Thyme Green" }, "Size": { "value": "Medium" } }
  },
  {
    "Product ID": 7463,
    "SKU": "WKS-5026",
    "Name": "Silver Lining Dress",
    "__group_by_swatch": false 
  }
]

    Data Sequencing Requirements

    To ensure accurate grouping and optimal processing efficiency, the source file must present all product variants sequentially by their Parent ID.

    Correct (Sequential): All variants for a single product are grouped together.

    Incorrect (Interleaved): Variants for a single product are split or scattered across the file.

    Example:

    Correct Sequence Incorrect Sequence

    Parent 123, Child 456

    Parent 123, Child 678

    Parent 234, Child 890

    Parent 234, Child 901

    Parent 123, Child 456

    Parent 234, Child 890

    Parent 123, Child 678 (Out of order)

    Parent 234, Child 901 (Out of order)

    Common Data Fields

    Beyond the required fields above, there are several other commonly needed data attributes you should consider including in your feed:

    Filter Attributes

    These represent any data you wish to use as a filter option within the Athos results: color, size, shape, material, occasion, brand, etc.

    Category Assignments

    Including categories in your feed is strongly recommended for both filtering and searchable data. These assignments are also required for Athos category navigation & for product recommendations. We recommend that you provide both category IDs and category names in the feed as two different fields, using a full hierarchy path for the category name assignments:

    Accessories>Jewelry>Necklaces | New Arrivals | Gifts For Her>Necklaces

    Searchable Fields

    These are any non-filtered data that you wish to be searchable within the Athos Results: search keywords, child SKUs, product descriptions.

    Price Rules

    If your product listing items ever show multiple prices as part of your item display logic, then each of those pricing data points must exist in the feed: retail price, quantity-based pricing, promotional discounts.

    Inventory Levels

    An indicator of available inventory is required in your feed to accomplish different rules on in-stock vs. out-of-stock products: de-boost out-of-stock products, show a low inventory badge, and boost high-inventory products.

    Date Created

    "Sort by newest" is a common request. To accomplish this, a creation date assignment must exist in your feed, following a "YYYY-MM-DD" format. Athos can then leverage this same assignment for a dynamic "New" badge, created within the last 30 days, for example.

    Badges

    For any badges that show in your product listing item display, those data triggers must exist in your feed: best-seller, customer favorite, and has video. Note that certain badges can be accomplished dynamically through other data assignments and do not require a separate indicator in the feed, such as "sold out" using inventory levels; "new" using date created; or "on sale" using price rules.

    Product Rating

    If you leverage product ratings in either the product listing item display, as a filter, or as a sort option, both the Rating Average and Total Count must be included in your feed. Athos does have the tools to pull in rating data from a few different third-party reviews providers. See our FAQ Section for the list of providers we currently support.

    Total Sold

    "Sort By Best-selling" is a common request. Athos has a connector with Google Analytics to pull in this sales data for you. However, if you do not use Google Analytics, or if you would rather provide your own sales rank metrics, this "Total Sold" data must exist in your feed.

    Exclude Rules

    Athos can add rules onto the index to exclude certain products from showing in your search results. Indicators must exist in your feed for any products you wish to exclude.

    Additional Thumbnails

    This includes any other thumbnail URLs that need to be used in your product listing item display, such as on-hover images or variant images.

    Variant Swatches

    If your product listing item display shows swatches below the main thumbnail, and clicking each swatch shows a different thumbnail URL, these swatches must exist in your feed. We recommend that it be included as a JSON object.

    Tip: For attribute fields with multiple assignments, any one of the following multi-value delimiters may be used: , (comma), ; (semi-colon), | (pipe), @ (at symbol), # (hash), $ (dollar sign), > (right arrow), ~ (tilde), or = (equals).

    Frequently Asked Questions

    How often will Athos update my data feed index?

    Athos will pull updates from your data feed file at daily intervals, with the scheduling set from our Data Feed Settings in the Athos Console. You may manually trigger a re-index of your product data at any time, and, if your plan level allows it, you can ask us to increase the frequency of our automated indexing. See Indexing 101 for more information.

    Can you use the attached file as my data feed?

    For initial data audits, we will offer to temporarily host your feed file on our servers. However, for your production data feed, you must host the file yourself, providing Athos with a URL of where to access the feed. When making updates to your product data, both the file name and location of your feed file must remain unchanged.

    Will Athos merge my child products together when indexing my data?

    No, Athos does not have any data-processing tools on our end to group together your child items. To support child items, you will need to list products per the instructions in the Variant Support section. Each child product should be listed in its own individual row and should reference the parent data, e.g., parent ID, etc. In addition, the examples contain information about how the child/parent relations should be listed in the feed.

    Can Athos group together, rename, and/or exclude some of my filter options?

    We will be showing your filter options the same way those data values exist in your feed. Any typos, misspellings, or mismatches in capitalization will need to be cleaned up directly in your data. For any individual Filter Options you wish to hide, those should be excluded directly from your feed.

    We pass standard variants with each child product in its own row, with an indication of the parent ID (__Parent_ID).

    Can Athos extract multiple filter fields out of a single combined "attributes" data entry?

    As long as your combined attribute field follows a consistent pattern, yes, we can expand this assignment into multiple fields for filtering. See Extract Attributes for more information.

    My store supports multiple customer groups, each with price discounts applied in the item results when logged in. How does Athos support this with only one price in the feed?

    For customer-based pricing, we often bypass any assignments from the feed by implementing a live pricing script into the load of the product listing display. See Live Pricing for more information.

    Will my Google Shopping Feed work for Athos?

    Often, Google Shopping feeds do not contain enough data to meet the requirements of your product listing display. Because Google Shopping only requires a minimal number of attributes, we often find these feeds lacking in richer data such as filter attributes, badges, category assignments, etc. Consider all of the other feed requirements listed above when determining if your Google Shopping feed is enough to meet your functionality needs.

    Can Athos pull in rating data from my third-party product reviews provider?

    To retrieve the product rating data for you, Athos currently supports the following third-party reviews providers: BazaarVoice, PowerReviews, RateVoice, Shopper Approved, Yotpo. If your provider is not in this list, and you require ratings to either be shown in the item display or enabled as a Filter or Sort option, then you will either need to provide us your ratings data directly in your product feed or consider providing a supplemental feed.

    Related Topics

    Related articles

    Comments

    0 comments

    Article is closed for comments.