job_id — follow with dtc_job_wait. Scopes are
enforced per call; a key missing one gets 403 FORBIDDEN_SCOPE. Full input schemas are
always available live via dtc_capabilities.
A tool ships with the release that introduces it, so the server you are calling may advertise
fewer tools than are listed here. Treat
tools/list (or dtc_capabilities) against your
environment as the authoritative set — this page describes the build, not any one deployment.
See Endpoint Status for what production currently serves.Identity & jobs
| Tool | Scope | Async | What |
|---|---|---|---|
dtc_cancel_job | – | – | Request best-effort cancellation of a still-running GATEWAY job (a job_id from an async tool) |
dtc_capabilities | – | – | Return the machine-readable catalog of all dtc_* tools with their JSON schemas and scopes |
dtc_get_job | – | – | Get the status/result of an async gateway job by job_id (returned by async tools) |
dtc_job_wait | – | – | Poll a job until terminal (succeeded/failed/cancelled) or timeout |
dtc_list_gateway_jobs | – | – | List this merchant’s GATEWAY async jobs newest first — the values returned by async tools (dtc_create_store, dtc_publish_project, dtc_send_campaign,… |
dtc_whoami | – | – | Return the current agent principal: kind (api_key/user_jwt), merchant_id, store_id, granted scopes, and remaining rate budget |
Store building
| Tool | Scope | Async | What |
|---|---|---|---|
dtc_add_custom_domain | store:publish | ✓ | Attach a custom domain to a published store (provisions SSL + CloudFront routing) |
dtc_build_landing_page | store:write | ✓ | Create a single marketing landing page from a brief (template_kind=landing_page) |
dtc_create_project | store:write | ✓ | Lower-level project creation (same engine as dtc_create_store) when you need explicit control over template_kind |
dtc_create_store | store:write | ✓ | Create a new storefront from a natural-language brief |
dtc_delete_metaobject | store:write | – | Delete a metaobject by id |
dtc_get_brand_system | store:read | – | Get the store’s Brand Design System (BDS): identity (brand_name, tagline, voice, tone, dos/donts, target_audience, imagery_style, product_kb_summary), design (preset,… |
dtc_get_metaobject | store:read | – | Get one metaobject (custom-data record) by id |
dtc_get_project_status | store:read | – | Get a project’s lifecycle status (initializing/active/failed) plus preview URL and metadata |
dtc_get_publish_status | store:read | – | Get the deployment status of a project (pending/building/uploading/deploying/ready/failed) and the live URL when ready |
dtc_list_metaobjects | store:read | – | List custom-data metaobjects (arbitrary typed records agents can persist on the store — e.g. campaign plans, brand notes, experiment configs) |
dtc_list_pages | store:read | – | List the store’s landing pages |
dtc_publish_project | store:publish | ✓ | Publish a project/store to its live URL (build → upload to S3 → CloudFront) |
dtc_upsert_metaobject | store:write | – | Create or update a metaobject (custom data) |
dtc_validate_against_brand | store:read | – | Validate generated output (HTML and/or explicit color/font lists) against the store’s resolved Brand Design System (BDS) and report DRIFT so the generation can… |
Products
| Tool | Scope | Async | What |
|---|---|---|---|
dtc_bulk_import_products | catalog:write | ✓ | Import many products at once. Async; returns job_id |
dtc_delete_product | catalog:write | – | Delete a product (soft delete — recoverable) |
dtc_get_product | catalog:read | – | Get one product with full detail — variants, media, pricing, status |
dtc_import_shopify_product | catalog:write | – | Import products into the store from their public Shopify product URLs — title, sanitized description, images (re-hosted on our CDN), options, and every variant with its… |
dtc_list_products | catalog:read | – | List the products in THIS store’s own catalog — what the storefront actually sells |
dtc_preview_shopify_product | catalog:write | – | Read a public Shopify product URL and return what would be imported — title, vendor, options, every variant with price/compare-at/SKU, and images — without writing… |
dtc_update_product | catalog:write | – | Update an existing product’s fields (title, price in dollars, status DRAFT/ACTIVE/ARCHIVED, tags, vendor, type, description) |
dtc_upsert_product | catalog:write | – | Create or update a product (title, price, images, variants, description) |
Catalog
| Tool | Scope | Async | What |
|---|---|---|---|
dtc_create_collection | catalog:write | – | Create a product collection (category) and optionally assign products |
dtc_delete_collection | catalog:write | – | Delete a collection (soft delete — recoverable) |
dtc_list_collections | catalog:read | – | List the store’s product collections (categories) |
dtc_search_catalog | catalog:read | – | Search the public sourcing catalog for products to add to a store (by keyword, category, price) |
dtc_set_collection_products | catalog:write | – | Replace the full ordered set of products in a collection |
dtc_update_collection | catalog:write | – | Update a collection’s title, description, or published state |
Orders
| Tool | Scope | Async | What |
|---|---|---|---|
dtc_fulfill_order | orders:write | – | Mark an order fulfilled with tracking info |
dtc_get_order | orders:read | – | Get one order with full detail — line items, totals, customer, shipping, fulfillment & payment status |
dtc_list_orders | orders:read | – | List store orders with filters (status, keyword, date range) |
dtc_list_subscriptions | orders:read | – | List the store’s customer (recurring) subscriptions |
Checkout recovery
| Tool | Scope | Async | What |
|---|---|---|---|
dtc_list_abandoned_checkouts | checkout:read | – | List abandoned checkouts (carts that didn’t convert) with customer, product and value |
dtc_recovery_cart_conversion | checkout:read | – | Check whether a specific abandoned cart has since converted into an order |
dtc_recovery_due_carts | checkout:read | – | List abandoned carts DUE for a recovery touch this tick, pre-tagged by the Gateway (eligibility, touch stage, segment, consent, holdout, dedup, routing already applied —… |
dtc_recovery_exceptions | checkout:read | – | List recovery carts routed for agent reasoning or human approval (the exceptions the automatic pipeline did not auto-handle) |
dtc_recovery_log_touch | checkout:recover | – | Log a DELIVERED recovery touch so the next tick advances the cart’s touch stage |
dtc_recovery_mint_discount | checkout:recover | – | Mint a single-use recovery discount with margin guardrails |
dtc_recovery_report | checkout:read | – | Recovery outcome report for this store: touched / recovered / revenue and true lift vs the holdout |
dtc_recovery_send_email | checkout:recover | – | Send ONE recovery email via the store’s branded template + SMTP |
dtc_recovery_suggest_products | checkout:read | – | Fetch up to 3 REAL store products to cross-sell in a recovery email (‘You might also like’) |
Customers
| Tool | Scope | Async | What |
|---|---|---|---|
dtc_create_segment | customers:write | – | Create a customer segment from filter rules (country, purchase count, events, etc.) |
dtc_delete_customer | customers:write | – | Delete a customer (soft delete — recoverable) |
dtc_get_customer | customers:read | – | Get one customer by id — profile, contact, subscription/marketing status and lifetime stats |
dtc_list_customers | customers:read | – | List the store’s customers with aggregate stats (total, email/SMS subscribers) |
dtc_list_segments | customers:read | – | List customer segments (saved audiences) |
dtc_upsert_customer | customers:write | – | Create a customer, or update one if customer_id is given |
Marketing
| Tool | Scope | Async | What |
|---|---|---|---|
dtc_create_campaign | marketing:write | – | Create (draft) a marketing campaign — EMAIL, SMS, or PUSH_NOTIFICATION — targeting a segment or audience filter |
dtc_get_campaign | marketing:read | – | Get one marketing campaign by id (content, audience, status, metrics) |
dtc_list_campaigns | marketing:read | – | List marketing campaigns (EMAIL/SMS/PUSH) |
dtc_send_campaign | marketing:send | ✓ | Send or schedule an existing campaign to its audience |
Ads
| Tool | Scope | Async | What |
|---|---|---|---|
dtc_connect_ad_platform | ads:write | – | Begin connecting a Meta/Google/TikTok ad account via OAuth |
dtc_sync_ad_platform | ads:write | ✓ | Refresh the data for connected ad accounts on one platform — re-imports the latest spend/performance from Meta/Google/TikTok |
Analytics
| Tool | Scope | Async | What |
|---|---|---|---|
dtc_get_ad_insights | analytics:read | – | Get ad performance (spend, impressions, clicks, conversions, ROAS) for connected accounts over a date range |
dtc_get_dashboard_analytics | analytics:read | – | Get the complete store dashboard for a range: revenue, orders, ad spend, ROAS, profit breakdown, top products, top countries, daily timeseries |
dtc_get_goal | analytics:read | – | Return the brand’s active goal: objective, target_metrics (target_roas/cac/revenue/ltv, daily_spend_cap, horizon_days), guardrails (max_daily_spend,… |
dtc_goal_dashboard | analytics:read | – | Combined orchestrator dashboard: active goal + target-vs-actual progress + action log + Self-Driving Score over a window |
dtc_record_progress | analytics:read | – | Record one orchestrator tick against the active goal: a batch of per-metric observations (metric=roas|cac|revenue|ltv|spend, with… |
Offer optimization
| Tool | Scope | Async | What |
|---|---|---|---|
dtc_apply_winner | offers:approve | – | Apply the merchant-confirmed winning offer and start rollout monitoring |
dtc_check_margin | offers:read | – | Server-side margin/COGS check for a product at a proposed discount — answers ‘is this offer still profitable, and is it too deep?’ BEFORE you commit |
dtc_claim_job | offers:write | – | Claim a pending offer job before working on it |
dtc_create_session | offers:write | – | Create an offer optimization session for one product and enqueue its create_offers job |
dtc_fail_job | offers:write | – | Close a claimed offer job that cannot be completed |
dtc_get_abtest_results | offers:read | – | Raw A/B metrics per variant: views, buys, conversionRate |
dtc_get_evaluation_status | offers:read | – | Read the stored evaluation recommendation and winner-application state for a session index |
dtc_get_market_benchmarks | offers:read | – | Market intelligence for product research from the platform’s own data (GLOBAL, not merchant-scoped): top brands in a category ranked by promo activity (active… |
dtc_get_monitor_data | offers:read | – | Live rollout metrics for the applied winner: views, buys, conversionRate within the monitor window |
dtc_get_offer_job | offers:read | – | Read one OFFER-queue job by id, including completed and failed ones — dtc_list_jobs only shows pending work |
dtc_get_session_context | offers:read | – | Internal source of truth for offer drafting: session state + constraints (cost, max_discount_percent, requirePositiveMargin), product + variants with prices, 3-month… |
dtc_list_jobs | offers:read | – | List pending OFFER OPTIMIZE jobs (create_offers | evaluate_abtest | monitor_decision) whose availability time has passed |
dtc_start_selected_abtest | offers:approve | – | Start the A/B test for the merchant-selected variants (at least two) |
dtc_submit_evaluation | offers:write | – | Store the A/B evaluation recommendation |
dtc_submit_monitor_decision | offers:write | – | Submit exactly one monitor decision: keep (insufficient data or acceptable performance), update (viable but change copy/value/conditions via ‘updated’), replace… |
dtc_submit_offer_drafts | offers:write | – | Store the validated draft offer variants for a session index |
Finance
| Tool | Scope | Async | What |
|---|---|---|---|
dtc_get_balance | finance:read | – | Get the merchant’s account balance (available / pending funds) |
dtc_get_transactions | finance:read | – | List the merchant’s financial transactions (trading statement); filter by search/status, paginate, sort |
Administration
| Tool | Scope | Async | What |
|---|---|---|---|
dtc_create_webhook | agent:admin | – | Subscribe to outbound store events — the platform POSTs (HMAC-signed) to your URL when an event fires |
dtc_delete_webhook | agent:admin | – | Delete an outbound webhook subscription by id |
dtc_list_audit_log | agent:admin | – | List this merchant’s Agent Gateway audit log newest first — every call made with their sq_agt_* keys, with path and status code |
dtc_list_webhooks | agent:admin | – | List the store’s outbound webhook subscriptions (no secrets) |
dtc_set_goal | agent:admin | – | Set or replace the brand’s active goal (objective + target_metrics + guardrails + autonomy_level) |