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	Provider identity
Shopify	Products, variants, images, price, inventory, status, handles, and tags	Product and variant IDs
WooCommerce	Products, variations, images, price, stock, status, SKU, categories, and tags	Product and variation IDs
BigCommerce	Catalog products, variants, images, price, inventory, visibility, categories, and custom fields	Product and variant IDs

Product reads are live. Commerce product/tag write capabilities remain guarded platform operations; the documented merchant flow is provider-to-Upsurge pull sync.

Before you sync

1. Create the destination site in Upsurge.
2. Connect Shopify, WooCommerce, or BigCommerce in Dashboard → Integrations.
3. Select the destination site in the connection settings.
4. Verify the connection.

For Shopify OAuth, use the store's permanent *.myshopify.com domain. For WooCommerce, the store URL must use HTTPS in production.

Run a sync

1. Open Dashboard → Products.
2. Find the connected provider in the sync controls.
3. Confirm the destination site.
4. Select Sync.

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

The equivalent merchant API request is:

curl --request POST \
  'https://dashboard.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. Do not rely on a blank or missing provider field to delete unrelated Upsurge metadata.

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 button is disabled	Connect a supported commerce provider and select an Upsurge site.
Request says the connection does not support product sync	Verify that the provider is Shopify, WooCommerce, or BigCommerce and that the connection 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.
Product count changes slowly	Large catalogs are paginated and processed asynchronously. Check the job state before re-queuing.