Skip to main content
This guide describes the requirements and supported methods for integrating commerce platforms that host multiple merchants or storefronts into the catalog for the store sync feature of PayPal’s agentic commerce services, which includes product feed integration.
Important: To access and use store sync, including the product feed integration, merchants must complete this form to contact the AI team at PayPal and request access.

​
Required data components

To participate in PayPal’s agentic commerce ecosystem, your platform needs to provide 2 essential data components that enable product discovery and merchant management. These components work together to ensure that AI agents can accurately search your inventory, understand merchant capabilities, and facilitate seamless transactions across your entire merchant network.

​
1. Merchant product feed

Each merchant must provide a product feed in Google Shopping CSV format. This file should include all relevant product attributes, such as:
  • id - This should refer to the variantID on your platform.
  • item_group_id - This should refer to the parentID on your platform. If this does not exist in the feed file, he merchant’s products are ingested as single-variant-products.
  • title
  • description
  • link
  • image_link
  • price
  • availability
  • brand
Note: Each merchant must have an individual feed file.

​
2. Merchant onboarding requirements

When a merchant is onboarded into the commerce AI system, we need some way to know that this merchant exists on your platform, how we should download their data, etc. We can receive this notification in a few ways, such as:

​
Option A. Merchant manifest file

Each platform provides 1 merchant manifest file for the platform. This manifest should contain metadata for all participating merchants on your platform. The file must be structured as a CSV or JSON and include one row (or object) per merchant. Required fields
FieldDescriptionExampleRequired
storeNameStore nameBlueberry BoutiqueYes
storeUrlStore URLhttps://blueberry-boutique.comYes
currencyDefault currency codeUSDYes
countryStore country codeUSYes
favIconURL to store faviconhttps://blueberry-boutique.com/favicon.icoYes
Recommended additional fields
  • Supported shipping regions
  • Store category or vertical (such as apparel or electronics)
  • Internal merchant ID (if applicable)
Note:️ Keep the manifest current with the latest list of merchants who opt in and their metadata.

​
Option B. Merchant sends us a webhook to onboard

Make 1 POST for each merchant. The webhook should be a POST that contains merchant information in a JWT encoded blob; content-type=plain/text. When decoded, the JWT looks like the following example. 
{
  "storeName": "acme store",
  "storeUrl": "acmestore.com"
  "currency": "USD",
  "country": "US",
  "favIcon": "favIcon.jpg",
  "platformMerchantId": "your-platforms-merchant-identifier",
  // Optional fields:
  "paypalId": "SAMPLEPYPLID5", # 13-character PayPal merchant id
  "shippingRegions": ["US","CA","MX"...],
  ...
  Any additional merchant-specific information you may deem relevant
}

​
2. Supported feed ingestion methods

We support several ingestion methods for fetching your merchant feeds and manifest files, allowing you to choose the approach that best aligns with your existing infrastructure and security requirements. Whether you prefer hosting files on your own servers, leveraging cloud storage, or providing API access, our system can accommodate your preferred delivery method. Select the option below that works best for your platform’s architecture and operational needs.

​
Option 1: SFTP/FTP server

  • Host the files on your SFTP/FTP server.
  • Share your access credentials and path details with your PayPal account representative or designated point of contact.
  • Files must be updated on a predictable schedule.

​
Option 2: Cloud storage (your bucket)

  • Supported services: Google Cloud Storage (GCS) or Amazon S3.
  • Grant our service account read access to the specific bucket or path.
  • Ensure that file names and structure remain consistent over time.

​
Option 3: Cloud storage (our Google Cloud Storage bucket)

  • We provision a path within our Google Cloud Storage (GCS) bucket for your platform.
  • You will be granted write access for your service account.
  • Upload merchant feeds and manifest files to this path.

​
Option 4: API access

  • You expose an API that can export a merchant’s catalog through a paginated endpoint.
  • You can give our backend services access to this API and describe the preferred workflow for authentication.
  • We download each merchant’s catalog daily.
  • Ensure that your systems supports this rate of API requests without encountering rate limits.

​
Option 5: Direct URL

  • Host feed files directly on a publicly accessible or allowlisted URL.
  • File URLs must follow a consistent naming scheme, such as https://merchantsite.com/product_feed.csv.
  • Ensure that files are accessible using HTTPS.

​
Next steps

  1. Choose and confirm the ingestion method that you will use.
  2. Share access details (credentials, service account IDs, URLs, and so on) with our onboarding team.
  3. Provide a sample merchant feed file and manifest for validation.
  4. Coordinate a test ingestion run with PayPal’s engineering team.