Getting started

​
Set up shopping prompts from products and personas

Build product-linked prompts from categories, comparisons, personas, and consideration stage.

​
When to use this workflow

“Track comparison and recommendation questions for our key products by customer segment.”

​
Before fetching

Confirm products, specifications, competitors, personas, region, and platforms. Observed products are not a complete merchant catalog; use an approved catalog for missing products.

Complete the CLI quickstart and confirm the workspace with orc workspace current --json. Replace example IDs, URLs, dates, and settings. Apply only approved mutations.

​
1. Check the measurement channel

Fetch the stable channels available to this workspace. Use the returned channel id as YOUR_CHANNEL_ID throughout prompt creation, execution, and answer retrieval.

orc channels list --json

Run the measurement flow in this order: channels list → prompts create --platforms <channel> → runs create --model-channel-id <channel> --wait → answers list.

​
2. Synchronize the approved product catalog

Review custom attribute keys and register missing products in bulk. Inspect created and rejected separately so rejected items are not reported as successful.

orc products attribute-keys list --workspace YOUR_WORKSPACE_ID --json
printf '%s' '{"products":[{"external_id":"YOUR_EXTERNAL_ID","brand_id":"YOUR_BRAND_ID","name":"YOUR_PRODUCT_NAME","attributes":{"category":"YOUR_CATEGORY"}}]}' \
  | orc products create --workspace YOUR_WORKSPACE_ID --stdin --idempotency-key YOUR_CREATE_REQUEST_KEY --json
orc products list --brand-id YOUR_BRAND_ID --workspace YOUR_WORKSPACE_ID --json
orc products get YOUR_PRODUCT_ID --workspace YOUR_WORKSPACE_ID --json

When a product changes, inspect every item in updated, skipped, and rejected.

printf '%s' '{"products":[{"id":"YOUR_PRODUCT_ID","name":"YOUR_UPDATED_PRODUCT_NAME"}]}' \
  | orc products update --workspace YOUR_WORKSPACE_ID --stdin --idempotency-key YOUR_UPDATE_REQUEST_KEY --json

​
3. Read products and existing prompts

Read product IDs, observed competitors and prompts, and personas. Do not invent unobserved product attributes.

orc products list --brand-id YOUR_BRAND_ID --json
orc products competitors list YOUR_PRODUCT_ID --json
orc products prompts list YOUR_PRODUCT_ID --json
orc personas list --json

​
4. Build a persona-by-stage matrix

Have the agent propose category, comparison, and use-case recommendation questions. Reuse existing prompts and preview approved candidates for priority products first.

orc prompts create --topic-id YOUR_TOPIC_ID --text 'YOUR_APPROVED_SHOPPING_QUESTION' --persona-ids YOUR_PERSONA_ID --platforms YOUR_CHANNEL_ID --country-code JP --preview true --idempotency-key YOUR_REQUEST_KEY --json

​
5. Verify saved prompts and product mapping

Save approved prompts with new request keys and read back the returned IDs. Prompt creation does not establish successful shopping-surface observation. Retain the product-to-prompt mapping in the deliverable. Run the saved prompt on the channel, then read answers back with the same channel filter.

orc prompts create --topic-id YOUR_TOPIC_ID --text 'YOUR_APPROVED_SHOPPING_QUESTION' --persona-ids YOUR_PERSONA_ID --platforms YOUR_CHANNEL_ID --country-code JP --idempotency-key YOUR_CREATE_REQUEST_KEY --json
orc prompts get YOUR_CREATED_PROMPT_ID --json
orc runs create --prompt-id YOUR_CREATED_PROMPT_ID --model-channel-id YOUR_CHANNEL_ID --idempotency-key YOUR_RUN_REQUEST_KEY --wait --json
orc answers list --prompt-id YOUR_CREATED_PROMPT_ID --platform YOUR_CHANNEL_ID --json

​
6. Remove retired products from the catalog

Soft-delete only products confirmed as retired in the approved catalog. First use --dry-run to inspect the body and workspace; noninteractive execution requires --yes. Inspect deleted and skipped separately.

printf '%s' '{"ids":["YOUR_RETIRED_PRODUCT_ID"]}' \
  | orc products delete --workspace YOUR_WORKSPACE_ID --stdin --dry-run --json
printf '%s' '{"ids":["YOUR_RETIRED_PRODUCT_ID"]}' \
  | orc products delete --workspace YOUR_WORKSPACE_ID --stdin --idempotency-key YOUR_DELETE_REQUEST_KEY --yes --json

​
Deliverable

Deliver the product-by-persona-by-stage matrix, prompt IDs, priorities, and unsupported products or collection conditions.

On fetch failure, retain the error and request scope. Do not count empty data, incomplete pagination, or missing permissions as a completed investigation.

​
Next steps

products reference · Workflow index · Set up prompts across the buyer journey

If a failure remains, report it and verify the fix, including this workflow and the failed step.