Tags

Browse the organization's tag vocabulary, then find the customers, suppliers, products, or product families carrying one exact tag.

Use Tags when a connected workflow starts from a shared business grouping such as preferred suppliers, strategic customers, or a product collection. Use Entity Resolution when the next step is choosing one exact record ID from business wording.

Access

Both routes require tags:read plus the acting user's current Tags access. Finding tagged records also requires current access to the requested entity type.

GET /me reports effectiveCapabilities.tags.vocabulary and the available classes in effectiveCapabilities.tags.viewableEntityTypes.

Browse the tag vocabulary

GET /tags

Optional query parameters:

Parameter	Use it for
`entityType`	Tags that apply to `customer`, `supplier`, `product`, or `product_family`.
`limit`	Rows per page from 1 to 100. The default is 25.
`cursor`	The continuation value returned by the preceding page.

curl "$SHELFCYCLE_API_BASE_URL/tags?entityType=product&limit=25" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY" \
  -H "X-ShelfCycle-Client: Product collection sync"

{
  "data": [
    {
      "id": "tag-id",
      "label": "Sustainable Solvents",
      "description": "Products in the sustainable solvents collection",
      "applicableEntityTypes": ["product", "product_family"]
    }
  ],
  "meta": {
    "capabilityKey": "list_tags",
    "capabilityVersion": "1.1.0",
    "returnedRecords": 1,
    "populationCount": 1,
    "complete": true,
    "hasMore": false,
    "nextCursor": null,
    "ordering": "label_id",
    "currentState": true,
    "snapshotIsolatedAcrossRequests": false,
    "requestId": "request-id"
  }
}

Each tag includes a stable id, its complete label, an optional description, and every supported entity type it can organize.

Find records carrying a tag

GET /tagged-records

Every request needs one entityType and exactly one case-sensitive tag selector:

tagId uses the stable ID from GET /tags.
label uses the exact tag label.

Optional nameQuery narrows the selected records by name. includeArchived=true includes archived records. limit and cursor control continuation.

curl "$SHELFCYCLE_API_BASE_URL/tagged-records?tagId=tag-id&entityType=product&nameQuery=acetone&limit=25" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY" \
  -H "X-ShelfCycle-Client: Product collection sync"

{
  "data": {
    "resolvedTag": {
      "id": "tag-id",
      "label": "Sustainable Solvents",
      "description": "Products in the sustainable solvents collection"
    },
    "records": [
      {
        "entityType": "product",
        "id": "product-id",
        "displayName": "ACETONE-PAIL",
        "externalId": "SOLVENT-1042",
        "archived": false
      }
    ]
  },
  "meta": {
    "capabilityKey": "find_tagged_records",
    "capabilityVersion": "1.1.0",
    "returnedRecords": 1,
    "populationCount": 1,
    "complete": true,
    "hasMore": false,
    "nextCursor": null,
    "ordering": "display_name_id",
    "currentState": true,
    "snapshotIsolatedAcrossRequests": false,
    "requestId": "request-id",
    "archivedExcluded": true
  }
}

resolvedTag confirms the exact grouping used. Each record provides the identity needed for a follow-up detail read, Entity Resolution comparison, report, or readiness check.

Continue larger results

When meta.hasMore is true, repeat the original filters and limit, then add meta.nextCursor:

curl "$SHELFCYCLE_API_BASE_URL/tagged-records?tagId=tag-id&entityType=product&nameQuery=acetone&limit=25&cursor=$NEXT_CURSOR" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY"

The cursor stays with the original endpoint, filters, page size, organization, and key. populationCount becomes available when the final page completes the current result set. Restart from the original filters when refreshing the directory.

Pair Tags with Entity Resolution

Tags answer which authorized records carry one exact business grouping. Entity Resolution answers which single ID best matches familiar wording.

When both search:read and tags:read are available, Entity Resolution can include relatedTags for the requested class. Each entry includes the tag label, description, and matching classes. Use that context to understand a candidate, then use GET /tagged-records when the workflow needs the complete authorized group.