---
title: products
description: Manage catalog products in bulk and inspect observation evidence.
canonical_url: https://orchestor.io/docs/en/cli/product
markdown_url: https://orchestor.io/docs/en/cli/product.md
contentType: reference
---

# products

`orc products` manages a Workspace product catalog. Bulk create, update, or delete approved products, retrieve lists, details, and counts, and inspect competing offers, generated queries, attributes, and original prompts from observations. You can also investigate evidenced product candidates from JAN codes or public product URLs before registration.

Configure authentication and select the target Workspace. Use the Orchestor product ID returned by creation or listing for `get` and product-specific observation reads. An `external_id` or observed shopping result ID is not a substitute. Products from another Workspace cannot be retrieved.

## Usage

```bash title="terminal"
orc products list --workspace <workspace-id>
```

*Inspect the product catalog and product IDs.*

## Subcommands

### `list`

List active catalog products newest first. Filter with `--brand-id` and follow the next cursor with unchanged filters.

```bash title="terminal"
orc products list [options]
```

#### Unique options

##### `--brand-id`

Filter by a brand ID in the current workspace. Omit to list products across all its brands.

Type: `string`. Optional.

```bash title="terminal"
orc products list --brand-id <value>
```

### `create`

Create 1–1,000 products. Each item in `products` needs a brand in the current Workspace. Results are separated into `created` and `rejected`, allowing inspection of partial rejection. Schema validation failure rejects the whole request before processing.

```bash title="terminal"
orc products create [options]
```

#### Unique options

##### `--idempotency-key`

Retry identity for operations that support idempotency. Use a unique key for each new operation, and reuse it only when retrying the same HTTP method, path, query values and exact request body. JSON whitespace changes can count as a different body. Keys contain 1–255 characters after trimming and expire after 24 hours. A completed JSON response is replayed without repeating the operation. A different request using the same key returns 409 idempotency_error. An in-progress request returns 409 idempotency_in_progress with Retry-After: 2. Whether this header is required depends on the operation.

Type: `string`. Optional.

```bash title="terminal"
orc products create --idempotency-key <value>
```

##### `--products`

(required) Catalog products to create in request order. Each item creates a new product.; JSON array of objects (use --stdin for large resources)

Type: `string`. Optional.

```bash title="terminal"
orc products create --products <value>
```

#### Examples

Keep the same request key when retrying the same body and inspect each outcome bucket.

```bash title="terminal"
orc products create --workspace <workspace-id> --stdin --idempotency-key <request-key> --json < products.json
```

*Bulk register approved products*

### `update`

Update 1–1,000 items through a `products` array of Orchestor IDs and changed fields. Only supplied fields change. Results contain `updated`, `skipped`, and `rejected`. Unknown IDs are skipped as `not_found`; items without changes as `no_changes`.

```bash title="terminal"
orc products update [options]
```

#### Unique options

##### `--idempotency-key`

Retry identity for operations that support idempotency. Use a unique key for each new operation, and reuse it only when retrying the same HTTP method, path, query values and exact request body. JSON whitespace changes can count as a different body. Keys contain 1–255 characters after trimming and expire after 24 hours. A completed JSON response is replayed without repeating the operation. A different request using the same key returns 409 idempotency_error. An in-progress request returns 409 idempotency_in_progress with Retry-After: 2. Whether this header is required depends on the operation.

Type: `string`. Optional.

```bash title="terminal"
orc products update --idempotency-key <value>
```

##### `--products`

(required) Partial updates in request order. Each item requires an Orchestor product ID.; JSON array of objects (use --stdin for large resources)

Type: `string`. Optional.

```bash title="terminal"
orc products update --products <value>
```

#### Examples

```bash title="terminal"
orc products update --workspace <workspace-id> --stdin --idempotency-key <request-key> --json < products-update.json
```

*Update product names in bulk*

### `delete`

Soft-delete 1–1,000 products using an `ids` array or CSV `--ids`. Inspect `deleted` and `skipped`. Unknown or deleted IDs are skipped as `not_found`. Non-interactive use requires `--yes`.

```bash title="terminal"
orc products delete [options]
```

#### Unique options

##### `--idempotency-key`

Retry identity for operations that support idempotency. Use a unique key for each new operation, and reuse it only when retrying the same HTTP method, path, query values and exact request body. JSON whitespace changes can count as a different body. Keys contain 1–255 characters after trimming and expire after 24 hours. A completed JSON response is replayed without repeating the operation. A different request using the same key returns 409 idempotency_error. An in-progress request returns 409 idempotency_in_progress with Retry-After: 2. Whether this header is required depends on the operation.

Type: `string`. Optional.

```bash title="terminal"
orc products delete --idempotency-key <value>
```

##### `--ids`

(required) Orchestor product IDs to delete, processed in request order. Repeating an ID can result in a skipped entry after its first deletion.; csv

Type: `string`. Optional.

```bash title="terminal"
orc products delete --ids <value>
```

#### Examples

```bash title="terminal"
orc products delete --workspace <workspace-id> --stdin --idempotency-key <request-key> --yes --json < products-delete.json
```

*Delete reviewed products non-interactively*

### `summary get`

Retrieve counts of active products and their distinct brands. Both counts are zero for an empty catalog.

```bash title="terminal"
orc products summary get [options]
```

### `attribute-keys list`

List distinct top-level `attributes` keys used by active products. Nested keys are not expanded.

```bash title="terminal"
orc products attribute-keys list [options]
```

### `get`

Retrieve one catalog product by ID in the selected Workspace. Products in another Workspace return `not found`.

```bash title="terminal"
orc products get <id> [options]
```

### `competitors list`

Inspect competing shopping results from the same observation slices, ranked by visibility. Use `prompts list` for original questions in which the product itself appeared.

```bash title="terminal"
orc products competitors list <id> [options]
```

### `fanouts list`

Retrieve generated shopping queries associated with the product, ranked by observation count. Inspect query expansion leading to product evidence rather than the original question.

```bash title="terminal"
orc products fanouts list <id> [options]
```

### `attributes list`

Retrieve observed characteristics, offer facts, and rating evidence grouped by source and frequency. This differs from the catalog’s custom attribute-key list.

```bash title="terminal"
orc products attributes list <id> [options]
```

### `prompts list`

Retrieve prompts whose shopping observations matched the product, with appearance counts and average absolute position.

```bash title="terminal"
orc products prompts list <id> [options]
```

### `resolve-jan`

Investigate JAN/EAN product identities and URL evidence with `--jan`. Optional `--official-domain` is a caller assertion, not verified ownership. You can use `--search false` with public URL input. No catalog records are created. API keys need write scope for this POST.

```bash title="terminal"
orc products resolve-jan [options]
```

#### Unique options

##### `--jan`

(required) Body field: jan

Type: `string`. Optional.

```bash title="terminal"
orc products resolve-jan --jan <value>
```

##### `--official-domain`

Caller-supplied manufacturer domain hint. Not independently verified ownership.; max 253 chars

Type: `string`. Optional.

```bash title="terminal"
orc products resolve-jan --official-domain <value>
```

##### `--search`

Allows at most two paid organic search requests using the configured DataForSEO provider.

Type: `string`. Optional.

```bash title="terminal"
orc products resolve-jan --search <value>
```

##### `--urls`

Optional public product pages to inspect, also usable without a search provider.; csv

Type: `string`. Optional.

```bash title="terminal"
orc products resolve-jan --urls <value>
```

### `extract`

Specify 1–5 public product URLs through `--urls` or JSON to extract provenance-backed facts from Product/ProductGroup JSON-LD and supported storefront HTML. No search or catalog write occurs. API keys need write scope.

```bash title="terminal"
orc products extract [options]
```

#### Unique options

##### `--urls`

(required) Body field: urls; csv

Type: `string`. Optional.

```bash title="terminal"
orc products extract --urls <value>
```

## Examples

### Product creation input

```json title="products.json"
{
  "products": [
    {
      "external_id": "YOUR_EXTERNAL_ID",
      "brand_id": "YOUR_BRAND_ID",
      "name": "YOUR_PRODUCT_NAME",
      "attributes": {
        "category": "YOUR_CATEGORY"
      }
    }
  ]
}
```

*Product creation input*

### Product update input

```json title="products-update.json"
{
  "products": [
    {
      "id": "YOUR_PRODUCT_ID",
      "name": "YOUR_UPDATED_PRODUCT_NAME"
    }
  ]
}
```

*Product update input*

### Product deletion input

```json title="products-delete.json"
{
  "ids": [
    "YOUR_PRODUCT_ID"
  ]
}
```

*Product deletion input*

### Preview the deletion request

Display the body and target Workspace without calling the API.

```bash title="terminal"
orc products delete --workspace <workspace-id> --stdin --dry-run < products-delete.json
```

*Preview the deletion request*

## Evidence research and registration

JAN resolution is bounded to two paid DataForSEO searches and ten public pages, respecting robots and network constraints. Checksum validation is not GS1 registration verification; the GS1 registry is not connected. Exact GTIN matches are distinguished from unverified search candidates, and current sale status is not verified. URL extraction does not search, query registries, or bypass browsers.

Review and approve results before passing them to `products create`. For bulk operations, inspect each outcome bucket rather than only command-level success. Deleted products are excluded from lists, counts, and attribute-key discovery.

## Permissions

Access to the target Workspace is required. Changes require the corresponding write permissions.

## Global Options

The following [global options](https://orchestor.io/docs/cli/global-flags.md) can be used with `orc products`:

- [`--help`](https://orchestor.io/docs/cli/global-flags.md#help)
- [`--workspace`](https://orchestor.io/docs/cli/global-flags.md#workspace)
- [`--json`](https://orchestor.io/docs/cli/global-flags.md#json-output)
- [`--pretty`](https://orchestor.io/docs/cli/global-flags.md#json-output)
- [`--format`](https://orchestor.io/docs/cli/global-flags.md#output-format)
- [`--field`](https://orchestor.io/docs/cli/global-flags.md#field-selection)
- [`--fields`](https://orchestor.io/docs/cli/global-flags.md#field-selection)
- [`--raw`](https://orchestor.io/docs/cli/global-flags.md#raw-output)
- [`--output`](https://orchestor.io/docs/cli/global-flags.md#file-output)
- [`--no-pager`](https://orchestor.io/docs/cli/global-flags.md#pager)
- [`--dry-run`](https://orchestor.io/docs/cli/global-flags.md#dry-run)
- [`--yes`](https://orchestor.io/docs/cli/global-flags.md#confirmation)
- [`--limit`](https://orchestor.io/docs/cli/global-flags.md)
- [`--cursor`](https://orchestor.io/docs/cli/global-flags.md)
- [`--stdin`](https://orchestor.io/docs/cli/global-flags.md#standard-input)
- [`--from-stdin`](https://orchestor.io/docs/cli/global-flags.md#standard-input)
- [`--page-all`](https://orchestor.io/docs/cli/global-flags.md#all-pages)
- [`--timing`](https://orchestor.io/docs/cli/global-flags.md#request-timing)
- [`--readonly`](https://orchestor.io/docs/cli/global-flags.md#read-only-mode)
- [`--wrap-untrusted`](https://orchestor.io/docs/cli/global-flags.md#untrusted-content-wrapping)

For details and examples, see [global options](https://orchestor.io/docs/cli/global-flags.md).

---

[Documentation index](https://orchestor.io/docs/llms.txt)