Choose between file feeds and the Merchant API

You can upload product data to Merchant Center using file-based feeds, the Merchant API, or a combination of both:

• File-based product feeds: Upload CSV, TSV, or XML files using SFTP, Google Cloud Storage, Google Sheets, or scheduled fetches.
• Merchant API: Send programmatic requests directly from your backend for incremental updates as product data changes, alongside periodic full catalog syncs.

This guide compares both approaches, explains when to use one over the other (or both together), and provides a step-by-step migration playbook if you decide to move some or all of your products from file feeds to the API.

Choose your data source approach

Evaluate your catalog volatility, backend architecture, and operational workflows to decide whether to use the Merchant API, file feeds, or a hybrid setup.

When to use the Merchant API

Use an API primary data source if:

• Direct programmatic integration: You prefer calling an API directly from your backend instead of generating files and managing file transfer pipelines (such as SFTP or Google Cloud Storage).
• High price and inventory volatility: Your product prices or stock levels change frequently throughout the day.
• Immediate updates when data changes: You want to send product changes to Google as soon as they happen in your backend, rather than waiting for the next scheduled file generation and upload.
• Incremental catalog updates: You want to insert, update, or delete individual products as they change, without re-uploading your entire catalog every time.
• Partial attribute updates: You want to update specific fields of a product (such as price or availability using productInputs.patch) without resending the complete product payload.

When to use file feeds

Use a file-based primary data source if:

• Static catalog: Your product data changes infrequently (for example, once a day or less).
• Snapshot-only backend without delta tracking: Your backend only exports full catalog snapshots and cannot track item-level changes or explicit product deletions.
• Spreadsheet-based workflows: Non-engineering teams curate or override product data directly in Google Sheets or CSV files.
• Low-maintenance operations: You prefer a scheduled file export where Merchant Center handles fetching and snapshot processing, rather than operating an API integration with request pacing, retry handling, and periodic full-catalog syncs.

When to use both

You can combine file feeds and the Merchant API in the same Merchant Center account in the following scenarios:

• Partitioned product catalogs: You use the Merchant API for fast-changing products (such as flash sales or high-turnover inventory) and file feeds for static catalog segments or separate product lines. Ensure each product is only uploaded by one primary data source (see Parallel use and primary data source ownership).
• API primary data with file-based supplemental feeds: You manage core product data through an API primary data source while non-engineering teams or third-party partners supply additional attributes through file-based supplemental feeds (such as Google Sheets or CSV files) joined with attribute rules, or the reverse.
• Partial or phased migration: You transition specific markets, categories, or sub-accounts to the API while keeping the rest of your catalog on file feeds.

If you decide to move some or all of your products from file feeds to the Merchant API, follow the Step-by-step migration playbook.

Key architectural differences

File feeds and the push-based Merchant API differ in how Google processes and manages product data:

Concept	File Feeds	Merchant API
Integration Model	Offline file dump: You export your catalog to a file and transfer it using SFTP, Google Cloud Storage, Google Sheets, or scheduled fetches.	Direct programmatic integration: Your backend sends requests directly to the API endpoint.
Mutation Granularity	Bulk processing: Modifying one item typically requires re-processing the entire file.	Granular transactions: You can insert, patch, or delete only the products that changed.
Synchronization Timing	Batch synchronization: Changes wait in your backend until the next scheduled file export and transfer cycle.	Immediate or scheduled calls: You can send incremental changes immediately as they occur, alongside periodic full syncs.
Deletion Behavior	Implicit (Snapshot): Each file is a complete snapshot; removing a row from your primary file deletes the product.	Explicit: There is no snapshot concept; call productInputs.delete to remove a discontinued product.
Resource Representation	Single State: Your file's rows represent the raw input.	Separate raw and processed: The API splits data into ProductInput (your raw input) and Product (the final processed state).
Attribute (Feed) Rules	Applied to raw file columns in the Merchant Center UI.	Supported in the Merchant Center UI. Required when merging API data with 3P supplemental files; optional for single-source transformations if handled in your backend.

Parallel use and primary data source ownership ("last update wins")

While you can use both file feeds and the API in the same Merchant Center account, we strongly recommend using only one method to insert any given product.

Merchant Center operates on a "last update wins" model. The primary data source (API or file feed) that pushed the most recent product insert gains primary ownership of that product's data:

• When the file data source owns the product: Omitting the product from a subsequent file upload triggers implicit deletion, removing the product from Merchant Center.
• When the API data source owns the product: Omitting the product from a file upload has no effect because the file feed no longer owns the product. You must call accounts.productInputs.delete to remove it.
• Risk of accidental re-ownership: If an updated file feed runs after an API push and contains the product, the file data source regains ownership. Subsequent omissions from the file will then unexpectedly delete the product.

To avoid unexpected deletions or loss of API updates, do not perform concurrent updates on the same products using both API and file primary data sources.

Key API considerations

Understand these critical Merchant API behaviors before starting your implementation:

Flexible data sources (without language or label)

Unlike file feeds that require you to define a specific target feed label and language upfront, the Merchant API lets you create primary data sources without specifying a feedLabel or contentLanguage.

• Flexible uploads: This lets you upload products with any language or feed label combination to a single data source.
• Simplified management: You do not need to create and manage separate data sources for every target market. Note: For more details on choosing a data source strategy, see Choose a data source strategy.

Synchronization strategy and quotas

Unlike a file feed where you upload your entire catalog in a single batch, design your Merchant API integration around both incremental updates and paced full syncs:

• Combine incremental updates with periodic full syncs: Send productInputs.insert or productInputs.patch requests as product attributes change in your backend. Because relying solely on incremental updates can cause your data to drift out of sync over time, also run periodic full syncs to reconcile your catalog with your source of truth (which also refreshes the 30-day product expiration). How frequently you run a full sync depends on your catalog size and available API quota.
• Pace requests to respect API quotas: Do not call the API for all of your products at once. While incremental changes can be sent as they occur, spread full sync requests evenly across the day to stay within your per-minute and daily method call quotas. For details, see Quotas and limits and Make frequent updates to your products.

Testing your integration

Validate your integration logic in a safe environment before moving to production.

Use test accounts

Before making changes in production, we recommend executing the initial steps of the migration in a sandboxed test account:

1. Create a test account: Set up an isolated test account to experiment safely without impacting live ads or free listings.
2. Create an API data source: Practice creating your API primary data source.
3. Test attribute rules: Verify data transformations and supplemental feed joins.
4. Validate payloads and product keys: Push sample products to verify SKU casing, encoding, and error handling.

For details, see Step 1: Create test accounts and the Test Accounts guide.

Validate product key alignment

Ensure your programmatic payload product key matches your file feed SKUs exactly. Google identifies products by combining:

• offerId (called id in file feeds, case-sensitive)
• contentLanguage (for example en)
• feedLabel (for example US)

Caution: If your file feed uses lowercase SKUs (for example sku-123) and your API integration sends uppercase (for example SKU-123), Google treats them as different products. This results in duplicate items and a loss of serving history.

Special characters and encoding

If your product identifiers contain characters such as /, %, or ~, use the Encoded Format (unpadded base64url encoding) in your API calls. For more information, see ProductInput.name

Concurrency control

In a real-time integration, updates can arrive out of order due to network latency. To prevent older updates from overwriting newer data, use the versionNumber field in the ProductInput resource.

Step-by-step migration playbook

If you decide to move some or all of your products from file feeds to the Merchant API, follow this playbook to transition your products without losing impressions or serving history.

1. Rehearse the migration in a test account

Before making changes in production, create a sandboxed test account using the accounts.createTestAccount method (see the Test Accounts guide). Test accounts provide an isolated environment where offers are approved by default, domain verification is not required, and data is never served publicly.

Use your test account to mirror your production setup and rehearse the migration end-to-end:

1. Mirror your file feed setup: Create a file primary data source (and any supplemental data sources) in the test account and upload a sample of your production feed file.
2. Create a test API data source and rules: Create an API primary data source and configure any required attribute rules or supplemental feed joins.
3. Test ownership takeover and key alignment: Send productInputs.insert requests for the sample products and verify that the API data source takes ownership of the existing items without creating duplicate products.
4. Verify updates and deletions: Test partial updates with productInputs.patch and removals with productInputs.delete, and inspect the resulting resources with products.get.

2. Create production API data sources

Before pushing data, create a primary data source of type API in your account.

Create your API primary data source

To create a data source that accepts API pushes, send a POST request to the dataSources endpoint. For more details, see Create a primary products data source.

3. Transition custom attribute rules

Custom attribute rules bind to specific data sources and don't automatically transfer from your file data source to your new API data source.

How you transition your attribute rules depends on their purpose:

• Cross-source merging and third-party supplemental feeds: If you combine primary API data with external supplemental data sources (such as third-party supplier files, inventory spreadsheets, or promotional feeds), you must recreate the attribute rules in the Merchant Center UI and attach them to the new API data source. Client-side pre-processing cannot replace rules that join data across multiple independent sources.
• Single-source data transformations: For single-source cleanup, default values, or string formatting on your primary catalog data, choose between:
  • Backend transformations (Recommended): Apply transformations in your own system before calling the API. This gives you greater programmatic control, easier testing, and simplified debugging.
  • Merchant Center attribute rules: Recreate the transformation rules for your new API data source in the Merchant Center UI if you want Merchant Center to continue managing them automatically.

4. Enable the API integration

Turn on your production API integration to start inserting, updating, and deleting products in your new API primary data source:

• Insert and update products (ownership takeover): Send productInputs.insert and productInputs.patch requests from your integration. When you insert a product using the API with the same key (offerId, contentLanguage, feedLabel) as an existing file-feed product, the API data source takes ownership of that product and preserves its serving history. For more guidance, see Insert a product and Add and manage products.

  Important: You can only use productInputs.patch to update a product that already was inserted in your API primary data source. Before performing any updates on products, make sure they are inserted in your API primary data source first (and therefore owned by the API primary data source).

• Delete discontinued products: Configure your integration to explicitly call productInputs.delete whenever a product is removed from your catalog.

• Deploy gradually: For large catalogs, enable your integration one Merchant Center sub-account or one data source at a time.

• Configure concurrency: If sending many requests, configure your client to handle concurrent requests and manage multiple connections. See the Refactor code for concurrent requests guide.

5. Pause file data source updates

Once your API integration is active, stop file updates before the next scheduled file run so the file data source does not overwrite your API updates:

1. Stop uploading new files to your SFTP/FTP location, Google Cloud Storage, or Google Sheets.
2. In the Merchant Center UI, navigate to your file data source and pause its scheduled fetch.
3. Existing products owned by the file data source remain live for up to 30 days until your API integration inserts them.

6. Wait for the migration to complete and verify

Wait until all active products migrate from the file data source to the API data source. While incremental updates migrate products as they change, running a paced full catalog sync through your regular integration speeds up migrating your entire catalog (see Synchronization strategy and quotas).

During this phase:

1. In the Merchant Center UI, monitor the item counts. Wait until the file data source count decreases to 0 and the API data source count matches your active catalog.
2. Use products.get to verify that attributes and custom attribute rules merge as expected.
3. Monitor the API diagnostics tool in the Merchant Center UI to track error rates and API performance.

7. Decommission the file data source

After the transition is complete and the file feed item count is 0:

1. Confirm that updates are reflecting in real-time.
2. Delete the legacy file data source in the Merchant Center UI to prevent accidental file-based updates from overwriting your API data.