Sync control

With the sync:write scope, POST /products accepts three more fields that decide where a product goes: isActive, syncEnabled and destinations. They're for integrations that own that decision, for example an ERP where an "ecommerce" flag on an item means "list this product".

These switches send data to live systems, so they need their own scope on top of products:write. The Full integration preset includes both. Edit catalogue keys can't use these fields.

The three fields

All three are optional and partial. Send only the ones you want to change, per product:

The same fields appear on every product read. On a read, destinations is a list with the state of each connected app:

• enabled is whether the product is opted in.
• status is the outcome of the last push: synced, error or pending. It's null when nothing has been attempted.
• error holds the last error message, if any.
• Only apps that are installed and included in your plan are listed. With no connected apps, destinations is an empty list.

Rules

• Without sync:write, the whole request is refused. If any product in the request sends isActive, syncEnabled or destinations and the key lacks the scope, the response is 403 forbidden_scope and nothing in the request is written. This applies to dry runs too.
• Values must be real booleans. "false" as a string is an error, not off.
• Opting in to an app that isn't installed, or isn't in your plan, fails that product with a message saying so. Opting out is always allowed.
• Channel assignment isn't writable. Which BigCommerce or Shopify stores a product is listed on is set in Fulify, not through the API. Channel Sync only lets Fulify update the channels a product is already assigned to.

Linnworks

If your organization has the Linnworks app installed, Fulify creates and updates Linnworks stock items for every product that's opted in, matched on SKU. A product goes to Linnworks when all of these are true:

• isActive is on.
• The product has a SKU.
• The product is opted in with "destinations": { "linnworks": true }.

Anything the API starts follows the Linnworks opt-in and doesn't look at syncEnabled, which governs BigCommerce and Shopify. In the Fulify app, saving a product or switching on its Linnworks opt-in in the product editor pushes it to Linnworks only when Channel Sync is also on.

Opting in starts a sync

Opting a product in through the API starts a sync, just as ticking the box in the app does. The products are queued for the background Linnworks job rather than sent during your request, because Linnworks limits how many calls Fulify can make per minute. If a Linnworks job is already running, the products join it.

When a request will send products to Linnworks, the response includes a linnworks object:

• switchedOn counts only the products the job will actually send: active products that were just opted in, and opted-in products that were just switched active.
• jobId is the Linnworks job carrying them.
• Sending "linnworks": true again for products that are already opted in doesn't re-send them, so a nightly feed that repeats the opt-in doesn't re-push your whole catalog. To re-send opted-in products, use Sync all products in Settings → Apps on the Linnworks app.

Opting in an inactive product

If you opt in a product whose isActive is off, the opt-in is saved but nothing is sent. The result carries a warning:

Send "isActive": true and the product goes out.

Opting out

Opting out never deletes anything in Linnworks, because an item there may still hold stock. It only stops Fulify writing to that item.

Typical setup

For an ERP or OMS that decides what's listed:

1. Create a key with the Full integration preset.
2. For each product that should be live, send "isActive": true plus "syncEnabled": true for your sales channels and "destinations": { "linnworks": true } for Linnworks.
3. For a product that should stop syncing, send "isActive": false. It then reaches no channel and no app.
4. Run the request with ?dryRun=true first to check the scopes and values.