Public preview

the related setting catalog ingestion Public preview

Receive and ingest business product catalogs from Stripe over the related setting.

Stripe provides business product catalogs to your SSH File Transfer Protocol (the related setting) server as daily full-catalog snapshots. Use this guide to set up your ingestion pipeline and validate incoming data.

Connectivity and directory structure

Stripe connects to your server using the following configuration:

• Protocol : the related setting (SSH File Transfer Protocol) over port 22
• Authentication : SSH key-based using Ed25519
• Password authentication : Disabled

Metadata

Each business directory contains a merchant_metadata.json file. Read this file before you ingest catalog data to verify that you’re importing data for the correct business.

{
 "stripe_profile_id": "profile_12345",
 "display_name": "Acme Widgets",
 "icon_url": "https://files.stripe.com/icon_abc123.png",
 "business_url": "https://www.acmewidgets.com",
 "return_policy": "https://www.acmewidgets.com/returns",
 "privacy_policy": "https://www.acmewidgets.com/privacy",
 "terms_of_service": "https://www.acmewidgets.com/tos",
 "last_updated": "2026-03-30T10:00:00Z"
}

Directory structure

Stripe assigns each business a unique top-level directory. Stripe organizes the the related setting root by business Stripe profile ID and separates data by feed type within each business directory.

/root
 stripe-verification.txt # Uploaded by agent during onboarding
 /[stripe_profile_id]/
 merchant_metadata.json
 /catalog/ # Full daily snapshots
 full_catalog_part_1_of_2.csv.gz
 full_catalog_part_2_of_2.csv.gz
 manifest.json
 /updates/ # High-frequency deltas (opt-in)
 delta_part_1_of_1.csv.gz
 manifest.json

Stripe automatically creates the directory ( /[stripe_profile_id]/) and its subdirectories ( /catalog/, /updates/) during the publishing process. The only file you must create manually is stripe-verification.txt in the the related setting root directory during onboarding.

the related setting server verification

During agent onboarding in the Dashboard, you provide your the related setting host details and Stripe generates a unique challenge token. You must upload this token to the root of your the related setting server in a file named stripe-verification.txt.

After Stripe receives your the related setting host details and a seller enables your agent, Stripe starts syndicating that seller’s product catalog to your the related setting host. Syndication begins only after Stripe verifies that the challenge token in stripe-verification.txt matches the token generated during onboarding. Keep this file in place—removing it can affect your ability to receive feeds.

Hybrid feed model

Stripe delivers data in two distinct streams to make efficient use of bandwidth and processing.

Sharding and manifest

For catalogs larger than 100,000 rows, Stripe might split the data into multiple shard files. Stripe uploads manifest.json last. Treat it as the signal that the batch is complete and ready to ingest. Don’t begin ingestion until manifest.json is present. If data files appear in catalog/ or updates/ but manifest.json doesn’t arrive, contact Stripe Support.

Manifest structure

The manifest includes the Stripe profile ID, batch metadata, feed type, total shard count, and the full list of shard files. Each file entry includes:

• name : The filename
• relative _ path : The path to the data file relative to the manifest’s location
• absolute _ path : The full path to the data file on the the related setting server

Note

Use relative_path or absolute_path to resolve the location of each data file. Don’t rely on name alone—it contains only the filename and doesn’t include directory context.

CSV file format

All data files use gzip compression with a .csv.gz extension. The uncompressed content is UTF-8 encoded, comma-separated, includes a header row, and follows standard CSV quoting rules for commas, quotes, and embedded line breaks.

Note

Stripe can add new columns to the product feed CSV over time as the catalog evolves. To keep your integration forward-compatible, parse the header row dynamically and ignore unknown columns.

For all fields:

• An empty value means the field is unset.
• Each row has a unique id .
• Multi-value fields such as additional _ image _ link are serialized as comma-separated URLs within a single quoted CSV field.

Product Master Feed schema

The Product Master Feed contains the full catalog snapshot for stable product metadata. Each row represents a product or variant. Required fields are always present. Recommended fields are typically present but might be absent for some products. Optional fields might or might not be populated, depending on the business’s data.

Required and recommended fields

Optional fields

Optional Delta Feed schema

Synchronization rules

The contents of the the related setting directory are the current source of truth.

How Stripe delivers data

Use the following delivery behaviors to design your ingestion process.

• Stripe overwrites the contents of catalog and updates each cycle. The the related setting directory always reflects the latest batch. Stripe doesn’t retain prior batches.
• Stripe uploads data files first and uploads manifest. json last so you don’t ingest a partial batch.

Process feeds

Use these guidelines to process each feed batch correctly.

• Use batch _ timestamp to determine whether you already processed a batch.
• Treat the latest full Product Master Feed as authoritative for the complete catalog state.

Deletion behavior

Support both explicit and implicit deletion:

• Explicit deletion : If a row in the Product Master Feed includes delete=true , remove the product or mark it inactive.
• Implicit deletion : If a product was previously known but is absent from the latest full Product Master Feed, remove the product or mark it inactive.
• Reappearance : If a previously deleted or omitted product appears again in a later full Product Master Feed, treat it as active unless delete=true is set.

Ingestion rules

Apply these rules to make your ingestion pipeline reliable and auditable:

• Timestamp validation : Only update local records if the incoming record is newer than the stored record when record-level timestamps are available.
• Idempotency : Reprocessing the same successfully processed batch must not create duplicate products or duplicate updates.
• Auditability : Retain your own record of processed batch _ timestamp values.