​

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.

Inspect the product catalog and product IDs.

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

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

Type: string. Optional.

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.

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.

(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.

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

Bulk register approved products

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.

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.

(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.

Update product names in bulk

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.

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.

(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.

Delete reviewed products non-interactively

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

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

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

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

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

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

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

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.

(required) Body field: jan

Type: string. Optional.

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

Type: string. Optional.

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

Type: string. Optional.

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

Type: string. Optional.

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.

(required) Body field: urls; csv

Type: string. Optional.

Product creation input

Product update input

Product deletion input

Display the body and target Workspace without calling the API.

Preview the deletion request

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.

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

The following global options can be used with orc products:

For details and examples, see global options.