Data extensibility - Tutorial : Filter stock by item eligibility flag

Who is this for?

Profile	What you will do

Profile	What you will do
🔧 System Integrator (SI)	You sync item custom features from the retailer's PIM or ERP into OneStock and configure stock queries to use them in sourcing and stock exports.
⚙️ Retailer Tech Team	You own the PIM integration and want to control which items are eligible for specific fulfilment channels directly from your product catalogue.

What you will build
A custom item feature (active_sfs) that flags whether an item is eligible for Ship From Store. You will push it via the OneStock item import API, then configure an item query that filters on it — making this flag available in stock queries, orchestration rules, and stock exports.

Why this matters
Without item-level custom features, OneStock treats all items in your catalogue as equally eligible for all fulfilment channels. With a feature like active_sfs, you can restrict sourcing to items your retailer has explicitly authorised for store shipping — without touching workflow configuration.

What you need before starting

A OneStock environment with API credentials: site_id, token
At least one item already imported in your environment
The feature active_sfs indexed on your environment — if it doesn't appear in the item query backoffice dropdown, ask your OneStock contact to index it

Step 1 — Push a custom feature on your items

Item data is imported asynchronously in OneStock via a 3-step process: open an import session, push your items, then close the session.

1.1 — Open an item import session

POST /item_imports

{
  "site_id": "{{site_id}}",
  "token": "{{token}}"
}

Response:

{
  "item_import": {
    "id": "{{item_import_id}}"
  }
}

1.2 — Push items with the custom feature

Include your custom feature inside the features object, under the relevant language key. The feature name (active_sfs) must match what is indexed in your OneStock environment.

POST /item_imports/{{item_import_id}}/items

{
  "site_id": "{{site_id}}",
  "token": "{{token}}",
  "items": [
    {
      "id": "SKU-001",
      "features": {
        "en": {
          "active_sfs": "1",
          "active_ckc": "0"
        }
      }
    },
    {
      "id": "SKU-002",
      "features": {
        "en": {
          "active_sfs": "0",
          "active_ckc": "1"
        }
      }
    }
  ]
}

A few notes:

Feature values are always strings in OneStock, even for boolean-like flags. Use "1" / "0" or "true" / "false" consistently — the item query filter will match on the exact value you push.
You can push multiple features per item in a single call.
You can push up to several thousand items per batch. For large catalogues, paginate across multiple calls to the same item_import_id.

1.3 — Close the import session

PATCH /item_imports/{{item_import_id}}

{
  "site_id": "{{site_id}}",
  "token": "{{token}}",
  "item_import": {
    "status": "closed"
  }
}

OneStock processes the import asynchronously once the session is closed. Features become queryable within a few seconds on small imports.

Step 2 — Create an item query filtering on the feature

Item queries are configured in the OneStock backoffice under Configuration → Stock Queries → Items.

Click Add an item query
Name it items_sfs
Optionally inherit from your base items query if you have one
Add a Features value filter:
- Language: select your catalogue language (e.g. en)
- Feature: select active_sfs from the dropdown
- Value: select 1
Save the query

⚠️ If active_sfs does not appear in the dropdown, the feature is not yet indexed on your environment. Ask your OneStock contact to index it. Only features that have been indexed — and for which at least one item already carries a value — appear in the selector.

Step 3 — Use the item query in a stock query

The items_sfs item query can now be referenced in any stock query that should only consider SFS-eligible items.

In Configuration → Stock Queries → Stocks, edit or create a stock query and set the Items query field to items_sfs.

This stock query will now only compute stock for items where active_sfs = "1" — regardless of physical stock levels on other items.

Once saved, this stock query can be used in:

Orchestration rulesets — restrict sourcing candidates to SFS-eligible items
Delivery promise methods — only promise SFS delivery for eligible items
Stock exports — export only the SFS-eligible portion of your catalogue to your website or BI tools

Recommended item query tree

For projects with multiple fulfilment channels, build an inheritance tree rather than duplicating filters:

items                        ← base query, no feature filter (all items)
├── items_sfs                ← active_sfs = "1"
└── items_ckc                ← active_ckc = "1"

Each child query inherits the language filter from the parent and adds only its channel-specific feature filter. This keeps your stock query configuration DRY and easy to maintain as your catalogue evolves.

What's next?

Automate the feature sync — schedule a daily or real-time call to POST /item_imports/{id}/items from your PIM or ERP whenever item eligibility changes in your product catalogue.
Add more features — the same pattern applies to any item attribute: hazardous goods flags, product family tags, price brackets for range filtering. Each feature must be indexed before it can be queried.
Stock location custom data — the same async import pattern exists for stock locations. See the Trustpilot sourcing tutorial for an end-to-end example with store ratings.
Item query reference — full filter options (features value, features comparison, bundle filter) are documented in Items queries.