Product sync

Product sync imports products from a connected commerce provider into the catalog used by recommendations, search, and chatbot knowledge.

Supported sources

Provider	Imported data	How to sync
Shopify	Products, variants, images, price, inventory, status, handles, tags, metafields, and selected options	Start full sync in the Upsurge Shopify app, Sync connection in Dashboard → Integrations, or Sync from Integration in Dashboard → Products
WooCommerce	Products, variations, images, price, stock, status, SKU, categories, tags, attributes, and product meta	Sync connection in Dashboard → Integrations, or Sync from Integration in Dashboard → Products
BigCommerce	Catalog products, variants, images, price, inventory, visibility, categories, and custom fields	Sync from Integration in Dashboard → Products

Provider metafields, options, attributes, and meta become available as source fields for Product fields. Map them there to use them in search, recommendations, and storefront filters.

Before you sync

1. Create the destination site in Upsurge.
2. Connect the store:
   • Shopify: install the Upsurge Shopify app and select Link Upsurge. See Shopify setup.
   • WooCommerce or BigCommerce: connect the provider in Dashboard → Integrations and select the destination site.
3. Select Check connection for WooCommerce or BigCommerce connections.

For WooCommerce, the store URL must use HTTPS in production.

Run a sync

Shopify

Open the Upsurge Shopify app in Shopify admin and select Start full sync, select Sync connection on the Shopify connection in Dashboard → Integrations, or use Sync from Integration in Dashboard → Products. Each starts a full catalog refresh through the app. Shopify also sends product changes to Upsurge automatically after the store is linked.

From the Products page

1. Open Dashboard → Products.
2. Select Sync from Integration. When more than one store is connected, choose the connection from the menu.
3. Confirm the destination site.

Upsurge queues the request and processes provider pages in the background. You can leave the page after the job is queued.

For WooCommerce and BigCommerce, the equivalent merchant API request is:

curl --request POST \
  'https://api.upsur.ge/api/v1/integrations/connections/CONNECTION_ID/sync' \
  --header "Authorization: Bearer $FIREBASE_ID_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "sync_type": "products_pull",
    "limit": 100,
    "payload": {"website_id": "site_123"}
  }'

The endpoint returns 202 Accepted with a queued job. limit can be from 1 to 250 and controls the provider page size, not a permanent maximum catalog size.

Sync behavior

• Provider pages are pulled with a persisted cursor until the catalog page sequence completes.
• Products use deterministic external identities, so repeating a sync updates existing provider records instead of creating a new record for every run.
• Manual requests for the same connection, site, and cursor are deduplicated within a five-minute window.
• Queue jobs retry transient errors with backoff and preserve sanitized result summaries.
• Webhook-capable commerce providers can enqueue incremental changes after provider signature verification.
• Product changes request refreshed personalization embeddings when needed.

Queue states include pending, processing, retrying, rate_limited, completed, failed, and skipped. A provider rate limit reschedules work; it does not require reconnecting unless the provider also rejects the credentials.

Do not mix identifiers

A commerce product is keyed by its provider identity, while a CSV product is keyed by site and SKU. If you import the same item through both paths, Upsurge can treat them as separate records. Choose a primary source for each site.

Changes and deletions

Later pulls update fields returned by the provider. When a complete provider snapshot no longer contains a mapped source value, Upsurge removes that source value. Local overrides that you entered in the product editor are kept. See Product fields.

Provider webhooks are verified before they affect the catalog. If a webhook delivery is missed, run a manual sync to reconcile the provider catalog. Revoking a connection stops future provider access but does not automatically delete products already imported into Upsurge.

Troubleshooting

Problem	Resolution
Sync from Integration is disabled	Connect WooCommerce or BigCommerce, or link Shopify through the Upsurge Shopify app, and select an Upsurge site.
Request says the connection does not support product sync	Use Start full sync or Sync connection for Shopify. For other providers, confirm the connection is WooCommerce or BigCommerce and is connected.
Products go to the wrong site	Correct settings.website_id, then run the sync again.
Sync repeatedly needs attention	Verify credentials and provider scopes; check that the store URL/domain still matches the connected account.
A mapped metafield or attribute is missing	Run a full sync so Upsurge fetches the source field, then check the mapping in Product fields.
Product count changes slowly	Large catalogs are paginated and processed asynchronously. Check the job state before re-queuing.