Data extensibility - Tutorial : Orchestrate orders to top rated stores from Trustpilot

Who is this for?

Profile	What you will do

Profile	What you will do
🔧 System Integrator (SI)	You configure custom data on stock locations and orders, then wire up an orchestration rule that uses both to route top-tier customer orders to top-rated stores.
⚙️ Retailer Business Admin	You configure the manual tags on stock locations in the backoffice and set up the orchestration filter rule.

What you will build
A Trustpilot-based store rating tag on your stock locations, and a matching candidate_tags field on orders. Combined with an orchestration filter, this routes orders from your top-tier customers exclusively to your highest-rated stores — without any workflow code changes.

Why this matters
OneStock's sourcing engine selects stores based on stock availability and orchestration rules. By adding a custom tag on locations and a matching field on orders, you can express business preferences — "this customer deserves a 5-star store" — directly in the data layer, keeping your workflow configuration clean and reusable.

What you need before starting

A OneStock environment with API credentials: site_id, token
Admin access to the backoffice (Configuration Manager role or above)
Stock locations already imported in your environment
A Trustpilot rating source for your stores (manual or automated via your own pipeline)

Step 1 — Add a Trustpilot manual tag to your stock locations

1.1 — Configure the manual tag in the backoffice

Go to Configuration → Stock locations → Manual tags and create a new tag with the following settings:

Name: Trustpilot
Id: trustpilot
Mandatory for all stock locations: yes
Single value only: yes
Options:
- Id: 2 — Rated under 3
- Id: 3 — Rated between 3 and 4
- Id: 4 — Rated between 4 and 5
- Id: 5 — 5 stars

See the Stock location documentation for full details on manual tags configuration.

Once the tag is created, you can set the value manually per store from the stock location detail page in the backoffice, or automate it via API (Step 1.2).

1.2 — Automate store ratings via the stock location import API

For production use, maintain Trustpilot ratings programmatically using the asynchronous stock location import. This is the same 3-step pattern as any stock location data update.

Open an import session:

POST /endpoint_imports

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

Response:

{
  "endpoint_import": {
    "id": "{{endpoint_import_id}}"
  }
}

Push your stock locations with their Trustpilot rating:

POST /endpoint_imports/{{endpoint_import_id}}/endpoints

{
  "site_id": "{{site_id}}",
  "token": "{{token}}",
  "endpoints": [
    {
      "id": "store_paris_01",
      "classification": {
        "trustpilot": ["5"]
      }
    },
    {
      "id": "store_lyon_02",
      "classification": {
        "trustpilot": ["3"]
      }
    }
  ]
}

A few notes:

The classification key must match the tag id you defined in the backoffice (trustpilot).
The value must be an array with a single string matching one of the option ids you configured ("2", "3", "4", or "5").
You only need to include the fields you want to update — other stock location data is left unchanged.

Close the import session:

PATCH /endpoint_imports/{{endpoint_import_id}}

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

OneStock processes the import asynchronously once the session is closed. Tags become available in orchestration within a few seconds on small imports.

Step 2 — Configure the orchestration filter rule

In your backoffice Orchestration menu, open the ruleset where you filter sourcing candidates and add a new filter:

Filter Source: Stock locations → All
Stock locations: Tags → Select stock locations with specific tag values
Tag selection: trustpilot
Condition: Order field

This tells OneStock: "only consider stores whose Trustpilot tag matches the value carried on the incoming order." The matching happens dynamically at sourcing time — no rule update needed when ratings change, only the data changes.

Step 3 — Create an order with the matching candidate tag

When creating an order for a top-tier customer, include the candidate_tags field with the Trustpilot rating you want to enforce. OneStock will only source this order from stores whose tag matches.

POST /orders

{
  "site_id": "{{site_id}}",
  "token": "{{token}}",
  "order": {
    "candidate_tags": {
      "trustpilot": "5"
    }
  }
}

A few notes:

candidate_tags is a key-value map where the key matches the tag id (trustpilot) and the value matches one of the configured options ("5" for 5-star stores).
Orders without a candidate_tags.trustpilot field are not constrained by this filter and can be sourced from any store.
Your commerce platform or order creation service is responsible for setting the correct tag value based on customer tier — OneStock does not infer it.

What's next?

Automate the rating sync — schedule a nightly or real-time call to POST /endpoint_imports/{id}/endpoints from your Trustpilot integration or store data pipeline whenever ratings change.
Extend to other store attributes — the same pattern works for any stock location attribute: fulfilment capacity tiers, certified store labels, SLA tiers. Each new manual tag creates a new filterable dimension in orchestration.
Combine with item eligibility flags — stack this filter with an item-level filter (e.g. active_sfs = "1") to create multi-dimensional sourcing rules. See the Filter stock by item eligibility flag tutorial.
Stock location custom data reference — full import API documentation is available at POST /endpoint_imports/{id}/endpoints.