4. Catalog feed

Moloco uses item metadata to create the campaign manager and train our machine-learning algorithms. Integration of catalog item metadata is delivered via a catalog feed. Prepare your catalog feed to synchronize seller and item information.

Update Feed

Two methods of catalog feed update exist – a Full Update Feed and an Incremental Update Feed.

  • Full Update Feed: You must prepare .csv or a compressed file (.csv.gz)with a list of all items in your marketplace and associated metadata. The compressed format is preferred.
  • Incremental Update Feed (Optional): If you would like to update ad items in your marketplace more frequently, you can use an incremental update feed in addition to your full update feed. It should include a subset of items in the full update feed. These items are either recent additions or updated or deleted items. To use the Incremental Update Feed, prepare a .csv or a compressed file (.csv.gz).

Full Update Feed (Required)

Full Update Feed is a feed file with an entire list of all items and metadata on your platform. It is typically updated at a designated time (e.g., Daily at 9 AM) daily because the feed file size is comparatively large. However, you may request more frequent daily updates (e.g., Daily every 4 hours) if the file size is less than 10 GB. You may also utilize the Incremental Update Feed for more frequent updates.

Feed URL

You must provide a dedicated catalog feed URL to which Moloco can access your catalog feed. Contact your Moloco representative to add a Moloco-trusted IP address to access the URL provided.

Feed Export Time

Specify the feed export schedule so the Moloco team schedules the import time accordingly.

  • Daily Once Example: every 4 am UTC
  • Daily Multiple Example: every 4 hours starting at 00:00 am UTC

Incremental Update Feed (Optional)

The Incremental Update Feed may contain additional class and update_time fields. See the Catalog Feed Specification guides below for more information.

Feed URL

Provide the URL for the feed. Contact your Moloco representative to add a Moloco-trusted IP address to access the feed.

Feed Export Time

Specify a time to export the feed regularly. This must be more frequent than the update interval for your Full Update Feed. For example, update every hour between 1 a.m. and 1 p.m. UTC.

📘

Note

See the sample incremental update feed file here.

Data source and how to access the data source

You can choose the data source and authentication method best suits your business needs. Contact your Moloco representative for more information.

Data sourceMedium of access
Amazon S3IP Allow List
Access Credentials
Use Federated Identity
Public Access (Not Recommended)
Google Cloud StorageIP Allow List
Access Credentials
Public Access (Not Recommend)
HTTPS URL (Self-managed remote storage)HTTP Authentication
Public Access (Not Recommend)

📘

Note

If you want to use an IP allowlist for data security purposes, contact your Moloco representative for the required IP addresses. We support HTTP Authentication and IP Allow List, but not both at the same time.

Amazon S3

If your team uses AWS, you can set up a shared S3 bucket by following this procedure. By creating a new empty S3 Bucket, in addition, you gain comprehensive control of:

  • Determining which files are intended for sharing with Moloco
  • Specifying the individuals and machines authorized to read from or write to the S3 Bucket

Step 1. Create a new Amazon S3 Bucket

If your platform is MyCommerce and you wish to share the production dataset, create an S3 Bucket named my-commerce-prod-to-moloco-shared-bucket in your preferred AWS Region.

Step 2. Configure the S3 Bucket Policy

Set up the S3 Bucket Policy to provide read access for Moloco's AWS Account to your S3 Bucket. The Bucket Policy is in JSON below. Please get in touch with us for Moloco's AWS Account ID information.

{
  "Version": "2012-10-17",
    "Statement": [
      {
        "Sid": "Read permissions for Moloco's ETL processor",
        "Effect": "Allow",
        "Principal": {
          "AWS": "arn:aws:iam::{molocos-aws-account-id}:user/RMP-Feed-Reader"
        },
        "Action": [
          "s3:List*",
          "s3:Get*"
        ],
        "Resource": [
          "arn:aws:s3:::my-commerce-prod-to-moloco-shared-bucket",
          "arn:aws:s3:::my-commerce-prod-to-moloco-shared-bucket/*"
        ]
      }
    ]
}

We recommend configuring the S3 Bucket to use server-side encryption with Amazon S3 managed keys (SSE-S3), as it's easier to configure and test. But if your organization requires the use of server-side encryption with AWS KMS keys (SSE-KMS), please give the KMS key decryption permission like the following:

{  
  "Version": "2012-10-17",  
    "Statement": [  
      {  
        "Sid": "Read permissions for Moloco's ETL processor",  
        "Effect": "Allow",  
        "Principal": {  
          "AWS": "arn:aws:iam::{molocos-aws-account-id}:user/RMP-Feed-Reader"  
        },  
        "Action": [  
          "s3:List*",  
          "s3:Get*",  
          "kms:Decrypt"
        ],  
        "Resource": [  
          "arn:aws:s3:::my-commerce-prod-to-moloco-shared-bucket",  
          "arn:aws:s3:::my-commerce-prod-to-moloco-shared-bucket/*",  
          "arn:aws:kms:us-west-2:(your-aws-account-id):key/1234abcd-12ab-34cd-56ef-1234567890ab"
        ]  
      },  
    ]  
}

Step 3. Upload catalog file to the S3

Upload the Refresh Feed or Update Feed files to S3. For example, place the full update feed in the following S3 path:

s3://my-commerce-prod-to-moloco-shared-bucket/catalog-item/full-update/latest.csv.gz

Step 4. Tell Moloco the S3 file location

After uploading the file and configuring the daily data export pipeline, please inform us of the S3 file location and the export schedule. We will then establish the daily data import pipeline on our end.

What's next

Catalog Feed Specification

The catalog feed specifications vary depending on whether SSPI (Single Seller Per Item) or MSPI (Multi Seller Per Item).

SSPI (Single Seller Per Item) refers to a 1:1 relationship between a seller and an item, where each item identifier corresponds to just one seller. MSPI (Multiple Sellers Per Item) indicates a many-to-many (n:m) relationship, where a single item ID within the platform can be associated with several seller IDs, not restricted to a single seller.

Use the below specification guides to format your catalog feeds. Submitting your item data to Moloco in the correct format is important for creating successful ads. Moloco uses this information to ensure that ad campaigns can be managed with proper catalog item information.