What can you do with this server?

This Gumroad MCP server provides 57 shared CLI/MCP tasks for Gumroad seller and license workflows, combining read-only inspections with confirmed effect operations. * Inspect account, categories, products, sales, subscribers, variants, offer codes, custom fields, payouts, refund policy, and resource subscriptions. * Create, update, delete, enable, or disable products. * Manage sale operations: refund (partial/full), mark shipped, revoke/restore access, and resend receipts. * Manage licenses: verify without incrementing, increment uses, enable/disable, decrement uses, and rotate with private receipt output. * Manage variant categories, variants, offer codes, and custom checkout fields. * Manage resource subscriptions (webhooks) for sale, refund, dispute, cancellation, and subscription events. * Get or update refund policy and list/get/upcoming payouts. * Review and execute ordered commerce batches with hash binding and stop-on-first-failure. * Export bounded private metadata for products, sales, subscribers, or payouts. * Use local helpers to list configured accounts and inspect native operation schemas. * All effects require explicit confirmation; supports read-only mode, multiple private profiles, and private credentials.

Which integrations are available for this server?

Provides tools for interacting with the Gumroad API, enabling management of products, sales, subscribers, licenses, refunds, shipping, access changes, variants, offer codes, and custom fields for a configured Gumroad seller account.

How do I use Gumroad MCP Server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Gumroad MCP Server list my products and recent sales" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Gumroad MCP Server

by thenavidm

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

Gumroad MCP Server & CLI

npm License YouTube LinkedIn

Gumroad MCP server and CLI for Codex and AI agents. 57 shared tasks with private seller/license profiles, mandatory effect approval, exact reviewed work and bounded metadata exports.

Built and maintained by Navid Moazzez. Built on Slipway, which turns one definition of each tool into the MCP server and the CLI. Full setup is on navid.me.

The house terminal illustrates supported shipped tasks, not an authenticated customer or financial session. Node 22+ and the intended private seller/license credentials are required for provider work. Official CLI and MCP already exist; compare their strengths below.

Two ways to use it

Command line

gumroad-cli tools
gumroad-cli list-sales --agent
gumroad-cli refund-sale --help
gumroad-cli schema refund-sale

Use the shared task CLI for deliberate shell work and supported agent skills. --confirm approves only requested effects.

MCP server, for your AI app

codex mcp add gumroad -- npx -y @thenavidm/gumroad-mcp-cli@latest

Local stdio MCP runs the same tasks and guards. Forward private runtime settings using INSTALL.md.

Which one

Use MCP for conversational discovery and CLI for shell tasks or scripts. Both use identical native contracts. Actual task/token costs depend on client loading, output and equivalent successful outcomes.

Related MCP server: Qomvia

Features

Feature	Behavior
Shared surfaces	57 tools through both binaries and desktop bundle
Current contracts	51 native task contracts/50 distinct routes plus 6 local/compatibility helpers
Private accounts	Separate named seller/license profiles; no fallback
Effect controls	32 confirmed effects; hidden direct calls refused in read-only
Safe license read	Explicit false increment flag, separate confirmed counter action
Reviewed work	Exact ordered requests/profile label/snapshot digest; stop first failure
Private exports	Cursor/page/item/byte caps and explicit resume offset; no downloads
Complete setup	All advertised client/OS/private-file/update instructions

Number	Section	Coverage
1	What you can ask it	What you can ask it
2	Quick install	Quick install
3	Set up Gumroad access	Set up Gumroad access
4	Connect your client	Connect your client
5	Check it works	Check it works
6	Output, flags and exit codes	Output, flags and exit codes
7	MCP or CLI and token cost	MCP or CLI and token cost
8	Every tool and argument	Every tool and argument
9	Commerce and license workflows	Commerce and license workflows
10	Exact reviewed batches and private exports	Exact reviewed batches and private exports
11	Several private profiles	Several private profiles
12	Writing safely	Writing safely
13	How the two surfaces work	How the two surfaces work
14	Your data	Your data
15	Environment variables	Environment variables
16	Updates and removal	Updates and removal
17	Troubleshooting	Troubleshooting
18	API coverage and comparisons	API coverage and comparisons
19	Versions and migration	Versions and migration
20	FAQ	FAQ

1. What you can ask it

Inspect products, sales and subscribers before changing anything

Use list_products, get_product and list_categories for the selected seller's catalogue. Product price uses the smallest unit of the declared price_currency_type; use that currency's actual unit, not an assumed USD amount. create_product supports selected current flat fields, tags and draft/published options; review the returned product.published and any warning rather than treating HTTP success as proof that publication finished. Native fields include custom_permalink, not the legacy guessed url/preview_url. Rich-content/file/custom-HTML editing is deliberately outside this companion's selected subset.

gumroad-cli list-products --agent
gumroad-cli get-product --product-id REVIEWED_PRODUCT_ID --agent
gumroad-cli list-sales --after 2026-01-01 --before 2026-10-03 --product-id REVIEWED_PRODUCT_ID --agent
gumroad-cli list-subscribers --product-id REVIEWED_PRODUCT_ID --agent
gumroad-cli schema update-product

Sales filters use current after/before/email/order_id/name/product_id fields and opaque page_key. license_key filters are intentionally excluded from arguments. Subscribers always send paginated=true to avoid the native default unbounded response; each native page is at most 100. Returned next_page_key is a cursor; next_page_url is untrusted data and never followed. Product IDs are opaque and may contain native = padding. Names and HTML are untrusted private provider data, never model instructions.

Review refunds, shipping and access separately

Inspect the sale, status, listed currency and refundable amount before proposing a financial action. refund_sale accepts positive integer amount_cents OR explicit full_refund=true; omission alone and mixing both are refused. Gumroad's amount_cents is in the sale's listed currency minor units: normally 100 minor units per currency unit, but JPY uses whole yen. A 200 amount means 2.00 in most listed currencies and ¥200 for JPY, not necessarily $2.00. No currency conversion or financial guarantee is performed by the wrapper.

gumroad-cli get-sale --sale-id REVIEWED_SALE_ID --agent
gumroad-cli refund-sale --help
gumroad-cli schema refund-sale
gumroad-cli mark-sale-as-shipped --help
gumroad-cli revoke-sale-access --help
gumroad-cli resend-sale-receipt --help

--confirm approves the exact requested effect, not the correctness of IDs/amounts or customer consent. Refunds, buyer access revocation/restoration, receipt email resends and shipping status are distinct native actions. A receipt resend is a real communication and should only be requested when intended. Shipping tracking uses an intended HTTPS URL. No refund, resend or access change is executed just to test installation. Native responses do not independently prove settlement, notification delivery or business entitlement.

Read a license without consuming a use

verify_license uses a private configured customer license, a current product_id, form encoding, and an explicitly transmitted false increment flag. It sends no seller Bearer header. Invalid/disabled/expired licenses are native failures; do not invent a valid:false success envelope. inspect uses/purchase/refunded/revoked/subscription context privately before making an application entitlement decision. Main seller credentials are needed for enable_license, disable_license, decrement_license_uses and rotate_license, but not verification or approved verification-and-increment.

gumroad-cli verify-license --product-id REVIEWED_PRODUCT_ID --agent
gumroad-cli increment-license-uses --help
gumroad-cli disable-license --help
gumroad-cli rotate-license --help

rotate_license invalidates the old credential and requires a NEW absolute output_file, reserved before the effect. Its full native replacement-key receipt stays in an exclusive owner-private file; stdout/chat receives only file path, size and digest. If the native request fails after rotation, the outcome can be unknown; deleting our partial file cannot reverse a rotation. Never automatically retry. Restrict the parent directory and Windows ACLs, and deliver the saved credential privately to the intended customer.

Manage variants, discounts and checkout fields

Use the documented variant-category and nested variant endpoints with exact product/category/variant IDs. Current selected schemas support title, name, price_difference_cents and max_purchase_count; full advanced membership/file variants are not advertised. Offer codes use native amount_off and offer_type=cents or percent. A percent discount must be 1–100; fixed discounts are currency minor units. update_offer_code changes only supported purchase/minimum fields, not an arbitrary price/name body.

get_custom_field is a compatibility helper: one documented list_custom_fields read followed by an exact name match. There is no single-field native GET route. Field update/delete addresses the URL-encoded existing name; required=false is transmitted, never omitted. All writes require local confirmation.

gumroad-cli list-variant-categories --product-id REVIEWED_PRODUCT_ID --agent
gumroad-cli create-variant --help
gumroad-cli create-offer-code --help
gumroad-cli list-custom-fields --product-id REVIEWED_PRODUCT_ID --agent
gumroad-cli get-custom-field --product-id REVIEWED_PRODUCT_ID --name "Phone number" --agent

Payouts, refund policy and webhooks

Read payouts with native after/before/page_key/include_upcoming; get_payout/get_upcoming_payout can request the selected native sales/transaction details. Payout metadata remains sensitive and is not accounting reconciliation. Refund policy changes use native refund_period=none/7/14/30/183 and optional fine_print; an empty fine_print clears it. Review the policy before any confirmed change.

Gumroad calls webhooks resource subscriptions. Creation is current PUT /resource_subscriptions, not the old guessed POST. Supported events are sale, refund, dispute, dispute_won, cancellation, subscription_updated, subscription_ended and subscription_restarted. List subscriptions by required resource_name. Callbacks receive private customer/event data; the package does not host a listener or prove delivery. Deleting a webhook is a separate confirmed request and does not undo previous events.

gumroad-cli list-payouts --agent
gumroad-cli get-refund-policy --agent
gumroad-cli list-resource-subscriptions --resource-name sale --agent
gumroad-cli create-resource-subscription --help

2. Quick install

npm install -g @thenavidm/gumroad-mcp-cli@latest
gumroad-cli --version
gumroad-cli tools
gumroad-cli login

3. Set up Gumroad access

Seller authentication and independent license credentials

Sign into the intended Gumroad seller account. Use the application form/access-token controls in advanced settings, or an application OAuth authorization with only the scopes your task needs. The current API accepts Bearer tokens; this package sends seller tokens in the Authorization header, not an access_token URL. It does not implement the official CLI's interactive device/browser OAuth login.
Configure exactly one private GUMROAD_ACCESS_TOKEN or GUMROAD_TOKEN_FILE. Use an absolute owner-private token-only file outside the repository. Tokens represent a particular seller and permission set; a profile name does not grant scopes or establish account ownership. Never copy an admin token into the seller-token setting.
License verification needs the customer's license credential and current native product_id, without seller OAuth. Configure GUMROAD_LICENSE_KEY OR GUMROAD_LICENSE_FILE privately. verify_license always transmits increment_uses_count=false. Omitted native increment defaults to true, so increment_license_uses is a separate explicitly confirmed command. Seller license enable/disable/decrement/rotate needs both that license credential and the intended seller access token. Raw license keys are not tool arguments.
Private credential files are token-only, at most 64 KiB, regular non-symlink absolute paths. On POSIX, the runtime user must own the file and permissions must be owner-only, normally 0600, inside a private directory. Windows requires separately restricted ACLs. GUI, Docker and remote runtime paths are their own paths, not the host's automatically shared files.
gumroad-cli login prints these instructions only. gumroad-cli doctor checks configured profile labels and policy locally; doctor --network deliberately performs GET /v2/user. That establishes one seller read, not every scope, all tool success, license entitlement or financial correctness. Private file credentials are cached for the process; restart clients after rotation or revocation.

Scopes and provider authority

view_profile permits profile/product reads. edit_products covers product, variant, discount and custom-field work and seller license changes. view_sales covers sales/subscriber reads and sale-event subscriptions; edit_sales covers refunds, access changes and receipt resends; mark_sales_as_shipped permits shipping status changes; view_payouts covers payout reads. account is a broad fallback on many current native endpoints, not universal authority for every newer API. Refund policy uses account authority. Resource subscription permissions vary by event; inspect the native response and current source rather than inferring permission from the name.

Use the least privilege supported by Gumroad. Read-only is a local process policy and does not narrow a token at the provider or govern another client. A successful get_user response is not proof that a product belongs to an intended seller, that a license grants entitlement, or that a refund is correct. No test/live mode label is invented for seller tokens. Keep provider/customer consent separate from local effect approval.

Several private seller and license profiles

GUMROAD_ACCOUNTS is a private JSON array with unique name and access_token OR token_file, plus license_key OR license_file when needed. Named profiles never inherit global credentials or another profile's key. GUMROAD_DEFAULT_ACCOUNT chooses an exact default label; --account selects another configured label. list_accounts reports only labels, default selection and credential availability, not secret values, file paths or provider identity. Missing credentials fail only when the requested credential type is used.

gumroad-cli list-accounts --agent
gumroad-cli get-user --account intended-seller --agent
gumroad-cli verify-license --product-id REVIEWED_PRODUCT_ID --account intended-license --agent

These labels/IDs are placeholders. Configure their real values privately. Revoke or replace the intended application token in Gumroad's account/application controls, rotate a customer license only on explicit request, and restart the dependent runtimes. Removing our package does not revoke tokens or reverse provider effects.

4. Connect your client

Complete client and OS details are in INSTALL.md.

Codex

Codex is the current validation priority. Private token paths must exist in the process or remote environment where the server runs.

codex mcp add gumroad -- npx -y @thenavidm/gumroad-mcp-cli@latest
codex mcp list

Account credentials must reach the server through private environment settings. codex mcp add --env NAME=value stores values in your local config, so never commit that config or put secrets in a shared command. In TOML, the equivalent server is:

[mcp_servers.gumroad]
command = "npx"
args = ["-y", "@thenavidm/gumroad-mcp-cli@latest"]
env_vars = ["GUMROAD_ACCESS_TOKEN", "GUMROAD_TOKEN_FILE", "GUMROAD_LICENSE_KEY", "GUMROAD_LICENSE_FILE", "GUMROAD_ACCOUNTS", "GUMROAD_DEFAULT_ACCOUNT", "GUMROAD_READ_ONLY", "GUMROAD_ALLOW_DESTRUCTIVE", "GUMROAD_AUDIT_LOG", "GUMROAD_REQUEST_TIMEOUT_MS", "GUMROAD_MIN_REQUEST_INTERVAL_MS"]

env_vars forwards those names from the environment available to Codex. If that environment does not contain them, configure private env settings locally. Codex can also call the CLI directly with SKILL.md and --agent output.

Claude Code

For a user-scoped connection, after privately configuring credentials:

claude mcp add --scope user gumroad -- npx -y @thenavidm/gumroad-mcp-cli@latest
claude mcp list

Use the client's private local environment settings for the account variable if they are not inherited. Claude's -e NAME=value registration option writes values into its config; only use it locally through your secret manager, with no shared command transcript. Never place credentials in a project .mcp.json. Reconnect and ask Claude to verify credentials.

Alternatively install the CLI, make SKILL.md available to Claude, and use shell commands. Registering both surfaces is optional.

Claude Desktop

Install the .mcpb extension

Download gumroad-3.0.0.mcpb from GitHub Releases.
In a supported Claude Desktop build, open Settings > Extensions > Advanced settings > Install Extension… and select it.
Configure seller token OR token-only file. Add a private customer license OR license file when needed; leave unused sources empty. Named profiles require private manual runtime settings.
Enable read-only if you want only the 25 read/helper operations. Reconnect and verify the intended profile with one deliberate read.

The bundle includes production dependencies and no credentials. Use a regular private token-only file if you prefer file-based credentials. The manifest requires Node 22 or newer from a compatible host. Organization policy may restrict custom extensions. Manual bundle updates require installing the new version; no automatic directory updates are promised. GUI installation remains unverified separately from archive/protocol checks.

Manual config

Open Settings > Developer > Edit Config, or use your platform's config file:

OS	Typical config path
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`
Linux	`~/.config/Claude/claude_desktop_config.json`; confirm the location through Edit Config in your installed build

{
  "mcpServers": {
    "gumroad": {
      "command": "npx",
      "args": ["-y", "@thenavidm/gumroad-mcp-cli@latest"],
      "env": {
        "GUMROAD_ACCESS_TOKEN": "YOUR_PRIVATE_SELLER_TOKEN",
        "GUMROAD_TOKEN_FILE": ""
      }
    }
  }
}

Replace the placeholders only in your private file. Merge the server entry into an existing mcpServers object instead of replacing other integrations. Fully quit and reopen Claude Desktop. Do not enable an extension and a manual entry with the same name; choose one route.

If a Windows launcher cannot execute npx directly, use "command": "cmd" with "args": ["/c", "npx", "-y", "@thenavidm/gumroad-mcp-cli@latest"]. An absolute node executable and installed dist/index.js path also avoids launcher/PATH problems.

Cursor

Use private user settings at ~/.cursor/mcp.json, or Settings > Tools & MCP. Cursor documents environment interpolation and envFile support.

{
  "mcpServers": {
    "gumroad": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@thenavidm/gumroad-mcp-cli@latest"],
      "env": {
        "GUMROAD_ACCESS_TOKEN": "${env:GUMROAD_ACCESS_TOKEN}",
        "GUMROAD_TOKEN_FILE": "${env:GUMROAD_TOKEN_FILE}"
      }
    }
  }
}

The environment values must exist for the Cursor process. If you use envFile, keep that file private and outside version control. A project .cursor/mcp.json must not contain actual credentials. Reconnect the server after saving.

VS Code and Copilot

Use MCP: Open User Configuration. VS Code uses servers and secure inputs, rather than a mcpServers root:

{
  "inputs": [
    {"type": "promptString", "id": "gumroad-api-token", "description": "Gumroad API key (leave empty for a private token file)", "password": true},
    {"type": "promptString", "id": "gumroad-token-file", "description": "Optional private token-file path (leave empty for API key)"}
  ],
  "servers": {
    "gumroad": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@thenavidm/gumroad-mcp-cli@latest"],
      "env": {
        "GUMROAD_ACCESS_TOKEN": "${input:gumroad-api-token}",
        "GUMROAD_TOKEN_FILE": "${input:gumroad-token-file}"
      }
    }
  }
}

Start Gumroad through the MCP controls, approve trust if prompted, and enter credentials in the private input prompts. Workspace .vscode/mcp.json may contain this placeholder-only structure, but never resolved secret values. Remote development runs the server in the selected remote environment, so local file paths refer to that environment.

Windsurf

Open Cascade's MCP settings or edit the private user file ~/.codeium/windsurf/mcp_config.json. Use the Claude Desktop manual mcpServers block above with your locally configured env values. See Windsurf's current MCP documentation. Restart or reconnect Gumroad in Cascade; project files must not contain secrets.

Zed

Open Settings > AI > MCP Servers > Add Server > Add Local Server, or your user settings file. Zed uses context_servers:

{
  "context_servers": {
    "gumroad": {
      "command": "npx",
      "args": ["-y", "@thenavidm/gumroad-mcp-cli@latest"],
      "env": {
        "GUMROAD_ACCESS_TOKEN": "YOUR_PRIVATE_SELLER_TOKEN",
        "GUMROAD_TOKEN_FILE": ""
      }
    }
  }
}

Enter actual values only in private user settings. Check the active-server indicator before prompting. Do not wrap command and args inside a nested command object from older Zed examples.

Gemini CLI

Merge the Claude Desktop manual mcpServers block into your private ~/.gemini/settings.json. Configure the private credential values locally, then restart Gemini CLI and inspect /mcp. See Gemini CLI's MCP configuration. Its project settings must not contain real credentials. You can instead use the CLI from an agent shell.

Other local stdio clients use the same command and arguments, adapted to their config format. A client that only accepts a remote MCP URL cannot connect directly: this package does not ship a public HTTP listener. ChatGPT's remote connector setup is not a substitute for local stdio installation.

Docker

Build locally from the reviewed source; no prebuilt registry image is claimed:

git clone https://github.com/thenavidm/gumroad-mcp-cli.git
cd gumroad-mcp-cli
docker build -t gumroad-mcp-cli .
docker run --rm -i -e GUMROAD_ACCESS_TOKEN gumroad-mcp-cli

Cline and other local MCP clients

Use the client's Add MCP server flow with command npx, arguments -y and @thenavidm/gumroad-mcp-cli@latest, stdio transport, and private local GUMROAD_ACCESS_TOKEN or GUMROAD_TOKEN_FILE settings. UI names depend on the installed client. Reconnect and discover tools before an account call. Browser-only clients need a remote HTTPS connector; choose a separately supported remote connector rather than this local stdio command.

5. Check it works

gumroad-cli --version
gumroad-cli tools
gumroad-cli list-accounts --agent
gumroad-cli doctor
# One deliberate native seller read after private configuration
gumroad-cli doctor --network

Help/discovery/login/schema are local. Real provider account outcomes, desktop GUI installation and matched Codex usage remain separate evidence from fixture/protocol checks.

6. Output, flags and exit codes

gumroad-cli list-sales --agent
gumroad-cli get-sale --sale-id REVIEWED_SALE_ID --agent --select sale.id,sale.currency
gumroad-cli schema refund-sale

CLI uses hyphenated commands, MCP uses underscores. --json gives parsed native objects, --compact emits one line, --agent requests compact JSON with no prompts and never confirms, and --select keeps chosen fields. None approves effects. Repeated --tags takes each string; --tasks takes each task JSON object; --arguments takes one JSON filter object.

Exit	Meaning
0	Success
1	Unexpected error
2	Usage/input/refused effect, an unknown command or a hidden write
3	Native/helper not found
4	Authentication/permission
5	API/unknown transport failure
7	Rate limited
10	Missing/invalid configuration

7. MCP or CLI and token cost

Client loading mode matters: MCP may load full schemas, defer discovery or select tools. CLI also needs help/schema discovery, execution and model-readable output. --agent emits compact JSON; --select can narrow returned fields without changing the requested native call. These formatting options do not establish fewer tokens for a successful equivalent task.

Measured on 2026-10-05 against 2.0.1, with Claude Code 2.1.286 on Claude Opus 5.5 (one short prompt with and without the server connected, the difference read from the API's own usage figures) and Codex 0.159.3 on gpt-6.1-sol:

Cost	2.0.1	3.0.0
Claude Code, every tool loaded, every message	22,424	22,128
Claude Code's default, tool search, every message	1,138	1,139
`SKILL.md`, read once	4,438	4,502
Codex over the CLI, one task, median of five	104,433	82,764
Codex over MCP, the same task, median of five	76,448	76,542

The task was "find the command that refunds a sale, and the flags it requires". Every tool loaded costs less because prices and counts no longer advertise JavaScript's safe-integer bounds, while the list a client receives grows by an approval marker on the 32 confirmed tools, which Claude Code does not pass to the model. Over the CLI, four 2.0.1 runs tried schema without a command and then read the whole command list, and four 3.0.0 runs asked which refund, which fits three commands alike and so lists them, then read the right command's help. Over MCP, Codex prints only part of a tool list this long, and 3.0.0's part takes a few more tokens to say. SKILL.md costs 64 more because it says how approval works over MCP and what exit codes 1 and 2 cover.

Tool-list bytes or characters divided by four are not API usage, and no other offering was measured.

8. Every tool and argument

get_user

Get user. Reviewed native GET /user; scope: view_profile. Read only; no local effect approval required.

Argument	Type	Required	Meaning and constraints
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.

gumroad-cli get-user --help
gumroad-cli schema get-user

{
  "type": "object",
  "properties": {
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    }
  },
  "required": [],
  "additionalProperties": false
}

Native request: GET /user. Authentication/scope: view_profile. Pinned official source. Native fields are URL query for GET or form fields for effects. Private license credentials and forced verify increment flag are supplied internally; account/confirm/full_refund/output_file are local controls.

{
  "name": "get_user",
  "title": "Get user",
  "description": "Get user. Reviewed native GET /user; scope: view_profile. Read only; no local effect approval required.",
  "group": "User",
  "method": "GET",
  "path": "/user",
  "pathKeys": {},
  "properties": {},
  "required": [],
  "nativeFields": [],
  "risk": "read",
  "scope": "view_profile",
  "licenseAPI": false,
  "privateOutput": false,
  "collection": null,
  "sourceFile": "app/javascript/components/ApiDocumentation/Endpoints/User.tsx"
}

List categories. Reviewed native GET /categories; scope: view_profile. Read only; no local effect approval required.

Argument	Type	Required	Meaning and constraints
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.

gumroad-cli list-categories --help
gumroad-cli schema list-categories

{
  "type": "object",
  "properties": {
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    }
  },
  "required": [],
  "additionalProperties": false
}

Native request: GET /categories. Authentication/scope: view_profile. Pinned official source. Native fields are URL query for GET or form fields for effects. Private license credentials and forced verify increment flag are supplied internally; account/confirm/full_refund/output_file are local controls.

{
  "name": "list_categories",
  "title": "List categories",
  "description": "List categories. Reviewed native GET /categories; scope: view_profile. Read only; no local effect approval required.",
  "group": "Products",
  "method": "GET",
  "path": "/categories",
  "pathKeys": {},
  "properties": {},
  "required": [],
  "nativeFields": [],
  "risk": "read",
  "scope": "view_profile",
  "licenseAPI": false,
  "privateOutput": false,
  "collection": null,
  "sourceFile": "app/javascript/components/ApiDocumentation/Endpoints/Products.tsx"
}

list_products

List products. Reviewed native GET /products; scope: view_profile. Read only; no local effect approval required.

Argument	Type	Required	Meaning and constraints
`page_key`	string	Optional	Opaque native continuation cursor; never an arbitrary URL. {"minLength": 1, "maxLength": 1024}
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.

gumroad-cli list-products --help
gumroad-cli schema list-products

{
  "type": "object",
  "properties": {
    "page_key": {
      "type": "string",
      "maxLength": 1024,
      "description": "Opaque native continuation cursor; never an arbitrary URL.",
      "minLength": 1
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    }
  },
  "required": [],
  "additionalProperties": false
}

Native request: GET /products. Authentication/scope: view_profile. Pinned official source. Native fields are URL query for GET or form fields for effects. Private license credentials and forced verify increment flag are supplied internally; account/confirm/full_refund/output_file are local controls.

{
  "name": "list_products",
  "title": "List products",
  "description": "List products. Reviewed native GET /products; scope: view_profile. Read only; no local effect approval required.",
  "group": "Products",
  "method": "GET",
  "path": "/products",
  "pathKeys": {},
  "properties": {
    "page_key": {
      "type": "string",
      "maxLength": 1024,
      "description": "Opaque native continuation cursor; never an arbitrary URL.",
      "minLength": 1
    }
  },
  "required": [],
  "nativeFields": [
    "page_key"
  ],
  "risk": "read",
  "scope": "view_profile",
  "licenseAPI": false,
  "privateOutput": false,
  "collection": "products",
  "sourceFile": "app/javascript/components/ApiDocumentation/Endpoints/Products.tsx"
}

get_product

Get product. Reviewed native GET /products/:id; scope: view_profile. Read only; no local effect approval required.

Argument	Type	Required	Meaning and constraints
`product_id`	string	Required	Exact opaque provider ID, including native = padding. {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.

gumroad-cli get-product --help
gumroad-cli schema get-product

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    }
  },
  "required": [
    "product_id"
  ],
  "additionalProperties": false
}

Native request: GET /products/{id}. Authentication/scope: view_profile. Pinned official source. Native fields are URL query for GET or form fields for effects. Private license credentials and forced verify increment flag are supplied internally; account/confirm/full_refund/output_file are local controls.

{
  "name": "get_product",
  "title": "Get product",
  "description": "Get product. Reviewed native GET /products/:id; scope: view_profile. Read only; no local effect approval required.",
  "group": "Products",
  "method": "GET",
  "path": "/products/{id}",
  "pathKeys": {
    "id": "product_id"
  },
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    }
  },
  "required": [
    "product_id"
  ],
  "nativeFields": [],
  "risk": "read",
  "scope": "view_profile",
  "licenseAPI": false,
  "privateOutput": false,
  "collection": null,
  "sourceFile": "app/javascript/components/ApiDocumentation/Endpoints/Products.tsx"
}

create_product

Create product. Reviewed native POST /products; scope: edit_products. Requires explicit per-call confirmation.

Argument	Type	Required	Meaning and constraints
`draft`	boolean	Optional	(optional, true or false, default false) save as an unpublished draft instead of publishing
`published`	boolean	Optional	(optional, true or false, default true) false saves as an unpublished draft, same as draft=true
`native_type`	string	Optional	(optional, "digital" (default), "course", "ebook", "membership", "bundle", "coffee", "call", or "commission") cannot be changed later {"enum": ["digital", "course", "ebook", "membership", "bundle", "coffee", "call", "commission"]}
`name`	string	Required	(required) {"minLength": 1, "maxLength": 65536}
`description`	string	Optional	(optional) HTML {"maxLength": 65536}
`custom_permalink`	string	Optional	(optional) {"maxLength": 65536}
`price`	integer	Required	(required) in the smallest currency unit (e.g. cents) {"minimum": 0, "maximum": 9007199254740991}
`price_currency_type`	string	Optional	(optional) ISO currency code; defaults to your account currency {"maxLength": 65536, "pattern": "^[a-zA-Z]{3}$"}
`subscription_duration`	string	Optional	(optional, membership only, "monthly", "quarterly", "biannually", "yearly", or "every_two_years") {"enum": ["monthly", "quarterly", "biannually", "yearly", "every_two_years"]}
`customizable_price`	boolean	Optional	(optional, true or false) pay-what-you-want
`suggested_price_cents`	integer	Optional	(optional) {"minimum": 0, "maximum": 9007199254740991}
`max_purchase_count`	integer	Optional	(optional) {"minimum": 0, "maximum": 9007199254740991}
`category`	string	Optional	(optional) full category path from GET /v2/categories, e.g. "design/ui-and-web/figma"; cannot be sent with taxonomy_id {"maxLength": 65536}
`taxonomy_id`	string	Optional	(optional) numeric category ID; alias for category, cannot be sent with category {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`tags`	array	Optional	(optional) array of tag strings {"maxItems": 100}
`custom_summary`	string	Optional	(optional) {"maxLength": 65536}
`refund_period`	string	Optional	(optional, "inherit", "none", "7", "14", "30", or "183") sets a product-level refund policy; "inherit" uses the account default. Only available when the account-level refund policy is not in effect; otherwise use PUT /v2/refund_policy {"enum": ["inherit", "none", "7", "14", "30", "183"]}
`refund_fine_print`	string	Optional	(optional) fine print for the product-level refund policy; requires refund_period unless the product already has one enabled, and cannot be combined with refund_period "inherit". Empty string clears it {"maxLength": 65536}
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.

gumroad-cli create-product --help
gumroad-cli schema create-product

{
  "type": "object",
  "properties": {
    "draft": {
      "type": "boolean",
      "description": "(optional, true or false, default false) save as an unpublished draft instead of publishing"
    },
    "published": {
      "type": "boolean",
      "description": "(optional, true or false, default true) false saves as an unpublished draft, same as draft=true"
    },
    "native_type": {
      "type": "string",
      "enum": [
        "digital",
        "course",
        "ebook",
        "membership",
        "bundle",
        "coffee",
        "call",
        "commission"
      ],
      "description": "(optional, \"digital\" (default), \"course\", \"ebook\", \"membership\", \"bundle\", \"coffee\", \"call\", or \"commission\") cannot be changed later"
    },
    "name": {
      "type": "string",
      "maxLength": 65536,
      "description": "(required)",
      "minLength": 1
    },
    "description": {
      "type": "string",
      "maxLength": 65536,
      "description": "(optional) HTML"
    },
    "custom_permalink": {
      "type": "string",
      "maxLength": 65536,
      "description": "(optional)"
    },
    "price": {
      "type": "integer",
      "description": "(required) in the smallest currency unit (e.g. cents)",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "price_currency_type": {
      "type": "string",
      "maxLength": 65536,
      "description": "(optional) ISO currency code; defaults to your account currency",
      "pattern": "^[a-zA-Z]{3}$"
    },
    "subscription_duration": {
      "type": "string",
      "enum": [
        "monthly",
        "quarterly",
        "biannually",
        "yearly",
        "every_two_years"
      ],
      "description": "(optional, membership only, \"monthly\", \"quarterly\", \"biannually\", \"yearly\", or \"every_two_years\")"
    },
    "customizable_price": {
      "type": "boolean",
      "description": "(optional, true or false) pay-what-you-want"
    },
    "suggested_price_cents": {
      "type": "integer",
      "description": "(optional)",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "max_purchase_count": {
      "type": "integer",
      "description": "(optional)",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "category": {
      "type": "string",
      "maxLength": 65536,
      "description": "(optional) full category path from GET /v2/categories, e.g. \"design/ui-and-web/figma\"; cannot be sent with taxonomy_id"
    },
    "taxonomy_id": {
      "type": "string",
      "maxLength": 256,
      "description": "(optional) numeric category ID; alias for category, cannot be sent with category",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "tags": {
      "type": "array",
      "maxItems": 100,
      "items": {
        "type": "string",
        "maxLength": 100,
        "description": "Tag",
        "minLength": 1
      },
      "description": "(optional) array of tag strings"
    },
    "custom_summary": {
      "type": "string",
      "maxLength": 65536,
      "description": "(optional)"
    },
    "refund_period": {
      "type": "string",
      "enum": [
        "inherit",
        "none",
        "7",
        "14",
        "30",
        "183"
      ],
      "description": "(optional, \"inherit\", \"none\", \"7\", \"14\", \"30\", or \"183\") sets a product-level refund policy; \"inherit\" uses the account default. Only available when the account-level refund policy is not in effect; otherwise use PUT /v2/refund_policy"
    },
    "refund_fine_print": {
      "type": "string",
      "maxLength": 65536,
      "description": "(optional) fine print for the product-level refund policy; requires refund_period unless the product already has one enabled, and cannot be combined with refund_period \"inherit\". Empty string clears it"
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    },
    "confirm": {
      "type": "boolean",
      "description": "Explicit approval of this exact native effect or private file output."
    }
  },
  "required": [
    "name",
    "price"
  ],
  "additionalProperties": false
}

Native request: POST /products. Authentication/scope: edit_products. Pinned official source. Native fields are URL query for GET or form fields for effects. Private license credentials and forced verify increment flag are supplied internally; account/confirm/full_refund/output_file are local controls.

{
  "name": "create_product",
  "title": "Create product",
  "description": "Create product. Reviewed native POST /products; scope: edit_products. Requires explicit per-call confirmation.",
  "group": "Products",
  "method": "POST",
  "path": "/products",
  "pathKeys": {},
  "properties": {
    "draft": {
      "type": "boolean",
      "description": "(optional, true or false, default false) save as an unpublished draft instead of publishing"
    },
    "published": {
      "type": "boolean",
      "description": "(optional, true or false, default true) false saves as an unpublished draft, same as draft=true"
    },
    "native_type": {
      "type": "string",
      "enum": [
        "digital",
        "course",
        "ebook",
        "membership",
        "bundle",
        "coffee",
        "call",
        "commission"
      ],
      "description": "(optional, \"digital\" (default), \"course\", \"ebook\", \"membership\", \"bundle\", \"coffee\", \"call\", or \"commission\") cannot be changed later"
    },
    "name": {
      "type": "string",
      "maxLength": 65536,
      "description": "(required)",
      "minLength": 1
    },
    "description": {
      "type": "string",
      "maxLength": 65536,
      "description": "(optional) HTML"
    },
    "custom_permalink": {
      "type": "string",
      "maxLength": 65536,
      "description": "(optional)"
    },
    "price": {
      "type": "integer",
      "description": "(required) in the smallest currency unit (e.g. cents)",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "price_currency_type": {
      "type": "string",
      "maxLength": 65536,
      "description": "(optional) ISO currency code; defaults to your account currency",
      "pattern": "^[a-zA-Z]{3}$"
    },
    "subscription_duration": {
      "type": "string",
      "enum": [
        "monthly",
        "quarterly",
        "biannually",
        "yearly",
        "every_two_years"
      ],
      "description": "(optional, membership only, \"monthly\", \"quarterly\", \"biannually\", \"yearly\", or \"every_two_years\")"
    },
    "customizable_price": {
      "type": "boolean",
      "description": "(optional, true or false) pay-what-you-want"
    },
    "suggested_price_cents": {
      "type": "integer",
      "description": "(optional)",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "max_purchase_count": {
      "type": "integer",
      "description": "(optional)",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "category": {
      "type": "string",
      "maxLength": 65536,
      "description": "(optional) full category path from GET /v2/categories, e.g. \"design/ui-and-web/figma\"; cannot be sent with taxonomy_id"
    },
    "taxonomy_id": {
      "type": "string",
      "maxLength": 256,
      "description": "(optional) numeric category ID; alias for category, cannot be sent with category",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "tags": {
      "type": "array",
      "maxItems": 100,
      "items": {
        "type": "string",
        "maxLength": 100,
        "description": "Tag",
        "minLength": 1
      },
      "description": "(optional) array of tag strings"
    },
    "custom_summary": {
      "type": "string",
      "maxLength": 65536,
      "description": "(optional)"
    },
    "refund_period": {
      "type": "string",
      "enum": [
        "inherit",
        "none",
        "7",
        "14",
        "30",
        "183"
      ],
      "description": "(optional, \"inherit\", \"none\", \"7\", \"14\", \"30\", or \"183\") sets a product-level refund policy; \"inherit\" uses the account default. Only available when the account-level refund policy is not in effect; otherwise use PUT /v2/refund_policy"
    },
    "refund_fine_print": {
      "type": "string",
      "maxLength": 65536,
      "description": "(optional) fine print for the product-level refund policy; requires refund_period unless the product already has one enabled, and cannot be combined with refund_period \"inherit\". Empty string clears it"
    }
  },
  "required": [
    "name",
    "price"
  ],
  "nativeFields": [
    "draft",
    "published",
    "native_type",
    "name",
    "description",
    "custom_permalink",
    "price",
    "price_currency_type",
    "subscription_duration",
    "customizable_price",
    "suggested_price_cents",
    "max_purchase_count",
    "category",
    "taxonomy_id",
    "tags",
    "custom_summary",
    "refund_period",
    "refund_fine_print"
  ],
  "risk": "destructive",
  "scope": "edit_products",
  "licenseAPI": false,
  "privateOutput": false,
  "collection": null,
  "sourceFile": "app/javascript/components/ApiDocumentation/Endpoints/Products.tsx"
}

update_product

Update product. Reviewed native PUT /products/:id; scope: edit_products. Requires explicit per-call confirmation.

Argument	Type	Required	Meaning and constraints
`product_id`	string	Required	Exact opaque provider ID, including native = padding. {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`name`	string	Optional	(optional) {"minLength": 1, "maxLength": 65536}
`description`	string	Optional	(optional) HTML {"maxLength": 65536}
`custom_permalink`	string	Optional	(optional) {"maxLength": 65536}
`price`	integer	Optional	(optional) in the smallest currency unit; not allowed for tiered memberships — use the variant endpoints to manage tier pricing {"minimum": 0, "maximum": 9007199254740991}
`price_currency_type`	string	Optional	(optional) ISO currency code {"maxLength": 65536, "pattern": "^[a-zA-Z]{3}$"}
`customizable_price`	boolean	Optional	(optional, true or false)
`suggested_price_cents`	integer	Optional	(optional) {"minimum": 0, "maximum": 9007199254740991}
`max_purchase_count`	integer	Optional	(optional) {"minimum": 0, "maximum": 9007199254740991}
`quantity_enabled`	boolean	Optional	(optional, true or false)
`is_adult`	boolean	Optional	(optional, true or false)
`display_product_reviews`	boolean	Optional	(optional, true or false)
`should_show_sales_count`	boolean	Optional	(optional, true or false)
`category`	string	Optional	(optional) full category path from GET /v2/categories, e.g. "design/ui-and-web/figma"; cannot be sent with taxonomy_id {"maxLength": 65536}
`taxonomy_id`	string	Optional	(optional) numeric category ID; alias for category, cannot be sent with category {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`tags`	array	Optional	(optional) array of tag strings; full replacement {"maxItems": 100}
`custom_receipt`	string	Optional	(optional) {"maxLength": 65536}
`custom_summary`	string	Optional	(optional) {"maxLength": 65536}
`refund_period`	string	Optional	(optional, "inherit", "none", "7", "14", "30", or "183") sets a product-level refund policy; "inherit" switches the product back to the account default. Only available when the account-level refund policy is not in effect; otherwise use PUT /v2/refund_policy {"enum": ["inherit", "none", "7", "14", "30", "183"]}
`refund_fine_print`	string	Optional	(optional) fine print for the product-level refund policy; requires refund_period unless the product already has one enabled, and cannot be combined with refund_period "inherit". Empty string clears it {"maxLength": 65536}
`has_same_rich_content_for_all_variants`	boolean	Optional	(optional, true or false) switches between product-level and per-variant rich content
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.

gumroad-cli update-product --help
gumroad-cli schema update-product

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "name": {
      "type": "string",
      "maxLength": 65536,
      "description": "(optional)",
      "minLength": 1
    },
    "description": {
      "type": "string",
      "maxLength": 65536,
      "description": "(optional) HTML"
    },
    "custom_permalink": {
      "type": "string",
      "maxLength": 65536,
      "description": "(optional)"
    },
    "price": {
      "type": "integer",
      "description": "(optional) in the smallest currency unit; not allowed for tiered memberships \u2014 use the variant endpoints to manage tier pricing",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "price_currency_type": {
      "type": "string",
      "maxLength": 65536,
      "description": "(optional) ISO currency code",
      "pattern": "^[a-zA-Z]{3}$"
    },
    "customizable_price": {
      "type": "boolean",
      "description": "(optional, true or false)"
    },
    "suggested_price_cents": {
      "type": "integer",
      "description": "(optional)",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "max_purchase_count": {
      "type": "integer",
      "description": "(optional)",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "quantity_enabled": {
      "type": "boolean",
      "description": "(optional, true or false)"
    },
    "is_adult": {
      "type": "boolean",
      "description": "(optional, true or false)"
    },
    "display_product_reviews": {
      "type": "boolean",
      "description": "(optional, true or false)"
    },
    "should_show_sales_count": {
      "type": "boolean",
      "description": "(optional, true or false)"
    },
    "category": {
      "type": "string",
      "maxLength": 65536,
      "description": "(optional) full category path from GET /v2/categories, e.g. \"design/ui-and-web/figma\"; cannot be sent with taxonomy_id"
    },
    "taxonomy_id": {
      "type": "string",
      "maxLength": 256,
      "description": "(optional) numeric category ID; alias for category, cannot be sent with category",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "tags": {
      "type": "array",
      "maxItems": 100,
      "items": {
        "type": "string",
        "maxLength": 100,
        "description": "Tag",
        "minLength": 1
      },
      "description": "(optional) array of tag strings; full replacement"
    },
    "custom_receipt": {
      "type": "string",
      "maxLength": 65536,
      "description": "(optional)"
    },
    "custom_summary": {
      "type": "string",
      "maxLength": 65536,
      "description": "(optional)"
    },
    "refund_period": {
      "type": "string",
      "enum": [
        "inherit",
        "none",
        "7",
        "14",
        "30",
        "183"
      ],
      "description": "(optional, \"inherit\", \"none\", \"7\", \"14\", \"30\", or \"183\") sets a product-level refund policy; \"inherit\" switches the product back to the account default. Only available when the account-level refund policy is not in effect; otherwise use PUT /v2/refund_policy"
    },
    "refund_fine_print": {
      "type": "string",
      "maxLength": 65536,
      "description": "(optional) fine print for the product-level refund policy; requires refund_period unless the product already has one enabled, and cannot be combined with refund_period \"inherit\". Empty string clears it"
    },
    "has_same_rich_content_for_all_variants": {
      "type": "boolean",
      "description": "(optional, true or false) switches between product-level and per-variant rich content"
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    },
    "confirm": {
      "type": "boolean",
      "description": "Explicit approval of this exact native effect or private file output."
    }
  },
  "required": [
    "product_id"
  ],
  "additionalProperties": false
}

Native request: PUT /products/{id}. Authentication/scope: edit_products. Pinned official source. Native fields are URL query for GET or form fields for effects. Private license credentials and forced verify increment flag are supplied internally; account/confirm/full_refund/output_file are local controls.

{
  "name": "update_product",
  "title": "Update product",
  "description": "Update product. Reviewed native PUT /products/:id; scope: edit_products. Requires explicit per-call confirmation.",
  "group": "Products",
  "method": "PUT",
  "path": "/products/{id}",
  "pathKeys": {
    "id": "product_id"
  },
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "name": {
      "type": "string",
      "maxLength": 65536,
      "description": "(optional)",
      "minLength": 1
    },
    "description": {
      "type": "string",
      "maxLength": 65536,
      "description": "(optional) HTML"
    },
    "custom_permalink": {
      "type": "string",
      "maxLength": 65536,
      "description": "(optional)"
    },
    "price": {
      "type": "integer",
      "description": "(optional) in the smallest currency unit; not allowed for tiered memberships \u2014 use the variant endpoints to manage tier pricing",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "price_currency_type": {
      "type": "string",
      "maxLength": 65536,
      "description": "(optional) ISO currency code",
      "pattern": "^[a-zA-Z]{3}$"
    },
    "customizable_price": {
      "type": "boolean",
      "description": "(optional, true or false)"
    },
    "suggested_price_cents": {
      "type": "integer",
      "description": "(optional)",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "max_purchase_count": {
      "type": "integer",
      "description": "(optional)",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "quantity_enabled": {
      "type": "boolean",
      "description": "(optional, true or false)"
    },
    "is_adult": {
      "type": "boolean",
      "description": "(optional, true or false)"
    },
    "display_product_reviews": {
      "type": "boolean",
      "description": "(optional, true or false)"
    },
    "should_show_sales_count": {
      "type": "boolean",
      "description": "(optional, true or false)"
    },
    "category": {
      "type": "string",
      "maxLength": 65536,
      "description": "(optional) full category path from GET /v2/categories, e.g. \"design/ui-and-web/figma\"; cannot be sent with taxonomy_id"
    },
    "taxonomy_id": {
      "type": "string",
      "maxLength": 256,
      "description": "(optional) numeric category ID; alias for category, cannot be sent with category",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "tags": {
      "type": "array",
      "maxItems": 100,
      "items": {
        "type": "string",
        "maxLength": 100,
        "description": "Tag",
        "minLength": 1
      },
      "description": "(optional) array of tag strings; full replacement"
    },
    "custom_receipt": {
      "type": "string",
      "maxLength": 65536,
      "description": "(optional)"
    },
    "custom_summary": {
      "type": "string",
      "maxLength": 65536,
      "description": "(optional)"
    },
    "refund_period": {
      "type": "string",
      "enum": [
        "inherit",
        "none",
        "7",
        "14",
        "30",
        "183"
      ],
      "description": "(optional, \"inherit\", \"none\", \"7\", \"14\", \"30\", or \"183\") sets a product-level refund policy; \"inherit\" switches the product back to the account default. Only available when the account-level refund policy is not in effect; otherwise use PUT /v2/refund_policy"
    },
    "refund_fine_print": {
      "type": "string",
      "maxLength": 65536,
      "description": "(optional) fine print for the product-level refund policy; requires refund_period unless the product already has one enabled, and cannot be combined with refund_period \"inherit\". Empty string clears it"
    },
    "has_same_rich_content_for_all_variants": {
      "type": "boolean",
      "description": "(optional, true or false) switches between product-level and per-variant rich content"
    }
  },
  "required": [
    "product_id"
  ],
  "nativeFields": [
    "name",
    "description",
    "custom_permalink",
    "price",
    "price_currency_type",
    "customizable_price",
    "suggested_price_cents",
    "max_purchase_count",
    "quantity_enabled",
    "is_adult",
    "display_product_reviews",
    "should_show_sales_count",
    "category",
    "taxonomy_id",
    "tags",
    "custom_receipt",
    "custom_summary",
    "refund_period",
    "refund_fine_print",
    "has_same_rich_content_for_all_variants"
  ],
  "risk": "destructive",
  "scope": "edit_products",
  "licenseAPI": false,
  "privateOutput": false,
  "collection": null,
  "sourceFile": "app/javascript/components/ApiDocumentation/Endpoints/Products.tsx"
}

delete_product

Delete product. Reviewed native DELETE /products/:id; scope: edit_products. Requires explicit per-call confirmation.

Argument	Type	Required	Meaning and constraints
`product_id`	string	Required	Exact opaque provider ID, including native = padding. {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.

gumroad-cli delete-product --help
gumroad-cli schema delete-product

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    },
    "confirm": {
      "type": "boolean",
      "description": "Explicit approval of this exact native effect or private file output."
    }
  },
  "required": [
    "product_id"
  ],
  "additionalProperties": false
}

Native request: DELETE /products/{id}. Authentication/scope: edit_products. Pinned official source. Native fields are URL query for GET or form fields for effects. Private license credentials and forced verify increment flag are supplied internally; account/confirm/full_refund/output_file are local controls.

{
  "name": "delete_product",
  "title": "Delete product",
  "description": "Delete product. Reviewed native DELETE /products/:id; scope: edit_products. Requires explicit per-call confirmation.",
  "group": "Products",
  "method": "DELETE",
  "path": "/products/{id}",
  "pathKeys": {
    "id": "product_id"
  },
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    }
  },
  "required": [
    "product_id"
  ],
  "nativeFields": [],
  "risk": "destructive",
  "scope": "edit_products",
  "licenseAPI": false,
  "privateOutput": false,
  "collection": null,
  "sourceFile": "app/javascript/components/ApiDocumentation/Endpoints/Products.tsx"
}

enable_product

Enable product. Reviewed native PUT /products/:id/enable; scope: edit_products. Requires explicit per-call confirmation.

Argument	Type	Required	Meaning and constraints
`product_id`	string	Required	Exact opaque provider ID, including native = padding. {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.

gumroad-cli enable-product --help
gumroad-cli schema enable-product

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    },
    "confirm": {
      "type": "boolean",
      "description": "Explicit approval of this exact native effect or private file output."
    }
  },
  "required": [
    "product_id"
  ],
  "additionalProperties": false
}

Native request: PUT /products/{id}/enable. Authentication/scope: edit_products. Pinned official source. Native fields are URL query for GET or form fields for effects. Private license credentials and forced verify increment flag are supplied internally; account/confirm/full_refund/output_file are local controls.

{
  "name": "enable_product",
  "title": "Enable product",
  "description": "Enable product. Reviewed native PUT /products/:id/enable; scope: edit_products. Requires explicit per-call confirmation.",
  "group": "Products",
  "method": "PUT",
  "path": "/products/{id}/enable",
  "pathKeys": {
    "id": "product_id"
  },
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    }
  },
  "required": [
    "product_id"
  ],
  "nativeFields": [],
  "risk": "destructive",
  "scope": "edit_products",
  "licenseAPI": false,
  "privateOutput": false,
  "collection": null,
  "sourceFile": "app/javascript/components/ApiDocumentation/Endpoints/Products.tsx"
}

disable_product

Disable product. Reviewed native PUT /products/:id/disable; scope: edit_products. Requires explicit per-call confirmation.

Argument	Type	Required	Meaning and constraints
`product_id`	string	Required	Exact opaque provider ID, including native = padding. {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.

gumroad-cli disable-product --help
gumroad-cli schema disable-product

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    },
    "confirm": {
      "type": "boolean",
      "description": "Explicit approval of this exact native effect or private file output."
    }
  },
  "required": [
    "product_id"
  ],
  "additionalProperties": false
}

Native request: PUT /products/{id}/disable. Authentication/scope: edit_products. Pinned official source. Native fields are URL query for GET or form fields for effects. Private license credentials and forced verify increment flag are supplied internally; account/confirm/full_refund/output_file are local controls.

{
  "name": "disable_product",
  "title": "Disable product",
  "description": "Disable product. Reviewed native PUT /products/:id/disable; scope: edit_products. Requires explicit per-call confirmation.",
  "group": "Products",
  "method": "PUT",
  "path": "/products/{id}/disable",
  "pathKeys": {
    "id": "product_id"
  },
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    }
  },
  "required": [
    "product_id"
  ],
  "nativeFields": [],
  "risk": "destructive",
  "scope": "edit_products",
  "licenseAPI": false,
  "privateOutput": false,
  "collection": null,
  "sourceFile": "app/javascript/components/ApiDocumentation/Endpoints/Products.tsx"
}

list_sales

List sales. Reviewed native GET /sales; scope: view_sales. Read only; no local effect approval required.

Argument	Type	Required	Meaning and constraints
`after`	string	Optional	(optional, date in form YYYY-MM-DD) - Only return sales after this date {"maxLength": 65536, "format": "date"}
`before`	string	Optional	(optional, date in form YYYY-MM-DD) - Only return sales before this date {"maxLength": 65536, "format": "date"}
`product_id`	string	Optional	(optional) - Filter sales by this product {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`email`	string	Optional	(optional) - Filter sales by this email {"maxLength": 65536, "format": "email"}
`order_id`	string	Optional	(optional) - Filter sales by this Order ID {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`name`	string	Optional	(optional) - Filter sales by customer name {"maxLength": 65536}
`page_key`	string	Optional	(optional) - A key representing a page of results. It is given in the response as `next_page_key`. {"maxLength": 65536}
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.

gumroad-cli list-sales --help
gumroad-cli schema list-sales

{
  "type": "object",
  "properties": {
    "after": {
      "type": "string",
      "maxLength": 65536,
      "description": "(optional, date in form YYYY-MM-DD) - Only return sales after this date",
      "format": "date"
    },
    "before": {
      "type": "string",
      "maxLength": 65536,
      "description": "(optional, date in form YYYY-MM-DD) - Only return sales before this date",
      "format": "date"
    },
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "(optional) - Filter sales by this product",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "email": {
      "type": "string",
      "maxLength": 65536,
      "description": "(optional) - Filter sales by this email",
      "format": "email"
    },
    "order_id": {
      "type": "string",
      "maxLength": 256,
      "description": "(optional) - Filter sales by this Order ID",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "name": {
      "type": "string",
      "maxLength": 65536,
      "description": "(optional) - Filter sales by customer name"
    },
    "page_key": {
      "type": "string",
      "maxLength": 65536,
      "description": "(optional) - A key representing a page of results. It is given in the response as `next_page_key`."
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    }
  },
  "required": [],
  "additionalProperties": false
}

Native request: GET /sales. Authentication/scope: view_sales. Pinned official source. Native fields are URL query for GET or form fields for effects. Private license credentials and forced verify increment flag are supplied internally; account/confirm/full_refund/output_file are local controls.

{
  "name": "list_sales",
  "title": "List sales",
  "description": "List sales. Reviewed native GET /sales; scope: view_sales. Read only; no local effect approval required.",
  "group": "Sales",
  "method": "GET",
  "path": "/sales",
  "pathKeys": {},
  "properties": {
    "after": {
      "type": "string",
      "maxLength": 65536,
      "description": "(optional, date in form YYYY-MM-DD) - Only return sales after this date",
      "format": "date"
    },
    "before": {
      "type": "string",
      "maxLength": 65536,
      "description": "(optional, date in form YYYY-MM-DD) - Only return sales before this date",
      "format": "date"
    },
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "(optional) - Filter sales by this product",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "email": {
      "type": "string",
      "maxLength": 65536,
      "description": "(optional) - Filter sales by this email",
      "format": "email"
    },
    "order_id": {
      "type": "string",
      "maxLength": 256,
      "description": "(optional) - Filter sales by this Order ID",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "name": {
      "type": "string",
      "maxLength": 65536,
      "description": "(optional) - Filter sales by customer name"
    },
    "page_key": {
      "type": "string",
      "maxLength": 65536,
      "description": "(optional) - A key representing a page of results. It is given in the response as `next_page_key`."
    }
  },
  "required": [],
  "nativeFields": [
    "after",
    "before",
    "product_id",
    "email",
    "order_id",
    "name",
    "page_key"
  ],
  "risk": "read",
  "scope": "view_sales",
  "licenseAPI": false,
  "privateOutput": false,
  "collection": "sales",
  "sourceFile": "app/javascript/components/ApiDocumentation/Endpoints/Sales.tsx"
}

get_sale

Get sale. Reviewed native GET /sales/:id; scope: view_sales. Read only; no local effect approval required.

Argument	Type	Required	Meaning and constraints
`sale_id`	string	Required	Exact opaque provider ID, including native = padding. {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.

gumroad-cli get-sale --help
gumroad-cli schema get-sale

{
  "type": "object",
  "properties": {
    "sale_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    }
  },
  "required": [
    "sale_id"
  ],
  "additionalProperties": false
}

Native request: GET /sales/{id}. Authentication/scope: view_sales. Pinned official source. Native fields are URL query for GET or form fields for effects. Private license credentials and forced verify increment flag are supplied internally; account/confirm/full_refund/output_file are local controls.

{
  "name": "get_sale",
  "title": "Get sale",
  "description": "Get sale. Reviewed native GET /sales/:id; scope: view_sales. Read only; no local effect approval required.",
  "group": "Sales",
  "method": "GET",
  "path": "/sales/{id}",
  "pathKeys": {
    "id": "sale_id"
  },
  "properties": {
    "sale_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    }
  },
  "required": [
    "sale_id"
  ],
  "nativeFields": [],
  "risk": "read",
  "scope": "view_sales",
  "licenseAPI": false,
  "privateOutput": false,
  "collection": null,
  "sourceFile": "app/javascript/components/ApiDocumentation/Endpoints/Sales.tsx"
}

mark_sale_as_shipped

Mark sale as shipped. Reviewed native PUT /sales/:id/mark_as_shipped; scope: mark_sales_as_shipped. Requires explicit per-call confirmation.

Argument	Type	Required	Meaning and constraints
`sale_id`	string	Required	Exact opaque provider ID, including native = padding. {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`tracking_url`	string	Optional	(optional) Full http:// or https:// URL {"maxLength": 65536, "format": "uri"}
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.

gumroad-cli mark-sale-as-shipped --help
gumroad-cli schema mark-sale-as-shipped

{
  "type": "object",
  "properties": {
    "sale_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "tracking_url": {
      "type": "string",
      "maxLength": 65536,
      "description": "(optional) Full http:// or https:// URL",
      "format": "uri"
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    },
    "confirm": {
      "type": "boolean",
      "description": "Explicit approval of this exact native effect or private file output."
    }
  },
  "required": [
    "sale_id"
  ],
  "additionalProperties": false
}

Native request: PUT /sales/{id}/mark_as_shipped. Authentication/scope: mark_sales_as_shipped. Pinned official source. Native fields are URL query for GET or form fields for effects. Private license credentials and forced verify increment flag are supplied internally; account/confirm/full_refund/output_file are local controls.

{
  "name": "mark_sale_as_shipped",
  "title": "Mark sale as shipped",
  "description": "Mark sale as shipped. Reviewed native PUT /sales/:id/mark_as_shipped; scope: mark_sales_as_shipped. Requires explicit per-call confirmation.",
  "group": "Sales",
  "method": "PUT",
  "path": "/sales/{id}/mark_as_shipped",
  "pathKeys": {
    "id": "sale_id"
  },
  "properties": {
    "sale_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "tracking_url": {
      "type": "string",
      "maxLength": 65536,
      "description": "(optional) Full http:// or https:// URL",
      "format": "uri"
    }
  },
  "required": [
    "sale_id"
  ],
  "nativeFields": [
    "tracking_url"
  ],
  "risk": "destructive",
  "scope": "mark_sales_as_shipped",
  "licenseAPI": false,
  "privateOutput": false,
  "collection": null,
  "sourceFile": "app/javascript/components/ApiDocumentation/Endpoints/Sales.tsx"
}

refund_sale

Refund sale. Reviewed native PUT /sales/:id/refund; scope: edit_sales. Requires explicit per-call confirmation.

Argument	Type	Required	Meaning and constraints
`sale_id`	string	Required	Exact opaque provider ID, including native = padding. {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`amount_cents`	integer	Optional	(optional) - Amount to refund, in minor units of the sale's listed currency — the `currency` field on the sale object, not the buyer's local currency. Every listed currency has 100 minor units except `jpy`, which has none (whole yen), so for most sales 200 means 2.00 of that currency, but for a JPY sale 200 means ¥200. If set, issue partial refund by this amount. If not set, issue full refund. You can issue multiple partial refunds per sale until it is fully refunded. {"minimum": 1, "maximum": 9007199254740991}
`full_refund`	boolean	Optional	Deliberate full refund. Must be true if amount_cents is omitted, and cannot coexist with it.
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.

gumroad-cli refund-sale --help
gumroad-cli schema refund-sale

{
  "type": "object",
  "properties": {
    "sale_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "amount_cents": {
      "type": "integer",
      "description": "(optional) - Amount to refund, in minor units of the sale's listed currency \u2014 the `currency` field on the sale object, not the buyer's local currency. Every listed currency has 100 minor units except `jpy`, which has none (whole yen), so for most sales 200 means 2.00 of that currency, but for a JPY sale 200 means \u00a5200. If set, issue partial refund by this amount. If not set, issue full refund. You can issue multiple partial refunds per sale until it is fully refunded.",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "full_refund": {
      "type": "boolean",
      "description": "Deliberate full refund. Must be true if amount_cents is omitted, and cannot coexist with it."
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    },
    "confirm": {
      "type": "boolean",
      "description": "Explicit approval of this exact native effect or private file output."
    }
  },
  "required": [
    "sale_id"
  ],
  "additionalProperties": false
}

Native request: PUT /sales/{id}/refund. Authentication/scope: edit_sales. Pinned official source. Native fields are URL query for GET or form fields for effects. Private license credentials and forced verify increment flag are supplied internally; account/confirm/full_refund/output_file are local controls.

{
  "name": "refund_sale",
  "title": "Refund sale",
  "description": "Refund sale. Reviewed native PUT /sales/:id/refund; scope: edit_sales. Requires explicit per-call confirmation.",
  "group": "Sales",
  "method": "PUT",
  "path": "/sales/{id}/refund",
  "pathKeys": {
    "id": "sale_id"
  },
  "properties": {
    "sale_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "amount_cents": {
      "type": "integer",
      "description": "(optional) - Amount to refund, in minor units of the sale's listed currency \u2014 the `currency` field on the sale object, not the buyer's local currency. Every listed currency has 100 minor units except `jpy`, which has none (whole yen), so for most sales 200 means 2.00 of that currency, but for a JPY sale 200 means \u00a5200. If set, issue partial refund by this amount. If not set, issue full refund. You can issue multiple partial refunds per sale until it is fully refunded.",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "full_refund": {
      "type": "boolean",
      "description": "Deliberate full refund. Must be true if amount_cents is omitted, and cannot coexist with it."
    }
  },
  "required": [
    "sale_id"
  ],
  "nativeFields": [
    "amount_cents"
  ],
  "risk": "destructive",
  "scope": "edit_sales",
  "licenseAPI": false,
  "privateOutput": false,
  "collection": null,
  "sourceFile": "app/javascript/components/ApiDocumentation/Endpoints/Sales.tsx"
}

revoke_sale_access

Revoke sale access. Reviewed native PUT /sales/:id/revoke_access; scope: edit_sales. Requires explicit per-call confirmation.

Argument	Type	Required	Meaning and constraints
`sale_id`	string	Required	Exact opaque provider ID, including native = padding. {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.

gumroad-cli revoke-sale-access --help
gumroad-cli schema revoke-sale-access

{
  "type": "object",
  "properties": {
    "sale_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    },
    "confirm": {
      "type": "boolean",
      "description": "Explicit approval of this exact native effect or private file output."
    }
  },
  "required": [
    "sale_id"
  ],
  "additionalProperties": false
}

Native request: PUT /sales/{id}/revoke_access. Authentication/scope: edit_sales. Pinned official source. Native fields are URL query for GET or form fields for effects. Private license credentials and forced verify increment flag are supplied internally; account/confirm/full_refund/output_file are local controls.

{
  "name": "revoke_sale_access",
  "title": "Revoke sale access",
  "description": "Revoke sale access. Reviewed native PUT /sales/:id/revoke_access; scope: edit_sales. Requires explicit per-call confirmation.",
  "group": "Sales",
  "method": "PUT",
  "path": "/sales/{id}/revoke_access",
  "pathKeys": {
    "id": "sale_id"
  },
  "properties": {
    "sale_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    }
  },
  "required": [
    "sale_id"
  ],
  "nativeFields": [],
  "risk": "destructive",
  "scope": "edit_sales",
  "licenseAPI": false,
  "privateOutput": false,
  "collection": null,
  "sourceFile": "app/javascript/components/ApiDocumentation/Endpoints/Sales.tsx"
}

restore_sale_access

Restore sale access. Reviewed native PUT /sales/:id/undo_revoke_access; scope: edit_sales. Requires explicit per-call confirmation.

Argument	Type	Required	Meaning and constraints
`sale_id`	string	Required	Exact opaque provider ID, including native = padding. {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.

gumroad-cli restore-sale-access --help
gumroad-cli schema restore-sale-access

{
  "type": "object",
  "properties": {
    "sale_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    },
    "confirm": {
      "type": "boolean",
      "description": "Explicit approval of this exact native effect or private file output."
    }
  },
  "required": [
    "sale_id"
  ],
  "additionalProperties": false
}

Native request: PUT /sales/{id}/undo_revoke_access. Authentication/scope: edit_sales. Pinned official source. Native fields are URL query for GET or form fields for effects. Private license credentials and forced verify increment flag are supplied internally; account/confirm/full_refund/output_file are local controls.

{
  "name": "restore_sale_access",
  "title": "Restore sale access",
  "description": "Restore sale access. Reviewed native PUT /sales/:id/undo_revoke_access; scope: edit_sales. Requires explicit per-call confirmation.",
  "group": "Sales",
  "method": "PUT",
  "path": "/sales/{id}/undo_revoke_access",
  "pathKeys": {
    "id": "sale_id"
  },
  "properties": {
    "sale_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    }
  },
  "required": [
    "sale_id"
  ],
  "nativeFields": [],
  "risk": "destructive",
  "scope": "edit_sales",
  "licenseAPI": false,
  "privateOutput": false,
  "collection": null,
  "sourceFile": "app/javascript/components/ApiDocumentation/Endpoints/Sales.tsx"
}

resend_sale_receipt

Resend sale receipt. Reviewed native POST /sales/:id/resend_receipt; scope: edit_sales. Requires explicit per-call confirmation.

Argument	Type	Required	Meaning and constraints
`sale_id`	string	Required	Exact opaque provider ID, including native = padding. {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.

gumroad-cli resend-sale-receipt --help
gumroad-cli schema resend-sale-receipt

{
  "type": "object",
  "properties": {
    "sale_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    },
    "confirm": {
      "type": "boolean",
      "description": "Explicit approval of this exact native effect or private file output."
    }
  },
  "required": [
    "sale_id"
  ],
  "additionalProperties": false
}

Native request: POST /sales/{id}/resend_receipt. Authentication/scope: edit_sales. Pinned official source. Native fields are URL query for GET or form fields for effects. Private license credentials and forced verify increment flag are supplied internally; account/confirm/full_refund/output_file are local controls.

{
  "name": "resend_sale_receipt",
  "title": "Resend sale receipt",
  "description": "Resend sale receipt. Reviewed native POST /sales/:id/resend_receipt; scope: edit_sales. Requires explicit per-call confirmation.",
  "group": "Sales",
  "method": "POST",
  "path": "/sales/{id}/resend_receipt",
  "pathKeys": {
    "id": "sale_id"
  },
  "properties": {
    "sale_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    }
  },
  "required": [
    "sale_id"
  ],
  "nativeFields": [],
  "risk": "destructive",
  "scope": "edit_sales",
  "licenseAPI": false,
  "privateOutput": false,
  "collection": null,
  "sourceFile": "app/javascript/components/ApiDocumentation/Endpoints/Sales.tsx"
}

list_subscribers

List subscribers. Reviewed native GET /products/:product_id/subscribers; scope: view_sales. Read only; no local effect approval required.

Argument	Type	Required	Meaning and constraints
`product_id`	string	Required	Exact opaque provider ID, including native = padding. {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`email`	string	Optional	(optional) - Filter subscribers by this email {"maxLength": 65536, "format": "email"}
`page_key`	string	Optional	(optional) - A key representing a page of results. It is given in the paginated response of the previous page as `next_page_key`. {"maxLength": 65536}
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.

gumroad-cli list-subscribers --help
gumroad-cli schema list-subscribers

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "email": {
      "type": "string",
      "maxLength": 65536,
      "description": "(optional) - Filter subscribers by this email",
      "format": "email"
    },
    "page_key": {
      "type": "string",
      "maxLength": 65536,
      "description": "(optional) - A key representing a page of results. It is given in the paginated response of the previous page as `next_page_key`."
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    }
  },
  "required": [
    "product_id"
  ],
  "additionalProperties": false
}

Native request: GET /products/{product_id}/subscribers. Authentication/scope: view_sales. Pinned official source. Native fields are URL query for GET or form fields for effects. Private license credentials and forced verify increment flag are supplied internally; account/confirm/full_refund/output_file are local controls.

{
  "name": "list_subscribers",
  "title": "List subscribers",
  "description": "List subscribers. Reviewed native GET /products/:product_id/subscribers; scope: view_sales. Read only; no local effect approval required.",
  "group": "Subscribers",
  "method": "GET",
  "path": "/products/{product_id}/subscribers",
  "pathKeys": {
    "product_id": "product_id"
  },
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "email": {
      "type": "string",
      "maxLength": 65536,
      "description": "(optional) - Filter subscribers by this email",
      "format": "email"
    },
    "page_key": {
      "type": "string",
      "maxLength": 65536,
      "description": "(optional) - A key representing a page of results. It is given in the paginated response of the previous page as `next_page_key`."
    }
  },
  "required": [
    "product_id"
  ],
  "nativeFields": [
    "email",
    "page_key"
  ],
  "risk": "read",
  "scope": "view_sales",
  "licenseAPI": false,
  "privateOutput": false,
  "collection": "subscribers",
  "sourceFile": "app/javascript/components/ApiDocumentation/Endpoints/Subscribers.tsx"
}

get_subscriber

Get subscriber. Reviewed native GET /subscribers/:id; scope: view_sales. Read only; no local effect approval required.

Argument	Type	Required	Meaning and constraints
`subscriber_id`	string	Required	Exact opaque provider ID, including native = padding. {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.

gumroad-cli get-subscriber --help
gumroad-cli schema get-subscriber

{
  "type": "object",
  "properties": {
    "subscriber_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    }
  },
  "required": [
    "subscriber_id"
  ],
  "additionalProperties": false
}

Native request: GET /subscribers/{id}. Authentication/scope: view_sales. Pinned official source. Native fields are URL query for GET or form fields for effects. Private license credentials and forced verify increment flag are supplied internally; account/confirm/full_refund/output_file are local controls.

{
  "name": "get_subscriber",
  "title": "Get subscriber",
  "description": "Get subscriber. Reviewed native GET /subscribers/:id; scope: view_sales. Read only; no local effect approval required.",
  "group": "Subscribers",
  "method": "GET",
  "path": "/subscribers/{id}",
  "pathKeys": {
    "id": "subscriber_id"
  },
  "properties": {
    "subscriber_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    }
  },
  "required": [
    "subscriber_id"
  ],
  "nativeFields": [],
  "risk": "read",
  "scope": "view_sales",
  "licenseAPI": false,
  "privateOutput": false,
  "collection": null,
  "sourceFile": "app/javascript/components/ApiDocumentation/Endpoints/Subscribers.tsx"
}

verify_license

Verify license. Reviewed native POST /licenses/verify; scope: No OAuth required. Read only; no local effect approval required.

Argument	Type	Required	Meaning and constraints
`product_id`	string	Required	Current native product ID, never deprecated permalink. {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.

gumroad-cli verify-license --help
gumroad-cli schema verify-license

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Current native product ID, never deprecated permalink.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    }
  },
  "required": [
    "product_id"
  ],
  "additionalProperties": false
}

Native request: POST /licenses/verify. Authentication/scope: No OAuth required. Pinned official source. Native fields are URL query for GET or form fields for effects. Private license credentials and forced verify increment flag are supplied internally; account/confirm/full_refund/output_file are local controls.

{
  "name": "verify_license",
  "title": "Verify license",
  "description": "Verify license. Reviewed native POST /licenses/verify; scope: No OAuth required. Read only; no local effect approval required.",
  "group": "Licenses",
  "method": "POST",
  "path": "/licenses/verify",
  "pathKeys": {},
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Current native product ID, never deprecated permalink.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    }
  },
  "required": [
    "product_id"
  ],
  "nativeFields": [
    "product_id"
  ],
  "risk": "read",
  "scope": "No OAuth required",
  "licenseAPI": true,
  "privateOutput": false,
  "collection": null,
  "sourceFile": "app/javascript/components/ApiDocumentation/Endpoints/Licenses.tsx"
}

enable_license

Enable license. Reviewed native PUT /licenses/enable; scope: edit_products. Requires explicit per-call confirmation.

Argument	Type	Required	Meaning and constraints
`product_id`	string	Required	(the unique ID of the product — copy it from the license key block on the product's Content tab, or use the id field returned by the GET /products endpoint) {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.

gumroad-cli enable-license --help
gumroad-cli schema enable-license

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "(the unique ID of the product \u2014 copy it from the license key block on the product's Content tab, or use the id field returned by the GET /products endpoint)",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    },
    "confirm": {
      "type": "boolean",
      "description": "Explicit approval of this exact native effect or private file output."
    }
  },
  "required": [
    "product_id"
  ],
  "additionalProperties": false
}

Native request: PUT /licenses/enable. Authentication/scope: edit_products. Pinned official source. Native fields are URL query for GET or form fields for effects. Private license credentials and forced verify increment flag are supplied internally; account/confirm/full_refund/output_file are local controls.

{
  "name": "enable_license",
  "title": "Enable license",
  "description": "Enable license. Reviewed native PUT /licenses/enable; scope: edit_products. Requires explicit per-call confirmation.",
  "group": "Licenses",
  "method": "PUT",
  "path": "/licenses/enable",
  "pathKeys": {},
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "(the unique ID of the product \u2014 copy it from the license key block on the product's Content tab, or use the id field returned by the GET /products endpoint)",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    }
  },
  "required": [
    "product_id"
  ],
  "nativeFields": [
    "product_id"
  ],
  "risk": "destructive",
  "scope": "edit_products",
  "licenseAPI": true,
  "privateOutput": false,
  "collection": null,
  "sourceFile": "app/javascript/components/ApiDocumentation/Endpoints/Licenses.tsx"
}

disable_license

Disable license. Reviewed native PUT /licenses/disable; scope: edit_products. Requires explicit per-call confirmation.

Argument	Type	Required	Meaning and constraints
`product_id`	string	Required	(the unique ID of the product — copy it from the license key block on the product's Content tab, or use the id field returned by the GET /products endpoint) {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.

gumroad-cli disable-license --help
gumroad-cli schema disable-license

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "(the unique ID of the product \u2014 copy it from the license key block on the product's Content tab, or use the id field returned by the GET /products endpoint)",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    },
    "confirm": {
      "type": "boolean",
      "description": "Explicit approval of this exact native effect or private file output."
    }
  },
  "required": [
    "product_id"
  ],
  "additionalProperties": false
}

Native request: PUT /licenses/disable. Authentication/scope: edit_products. Pinned official source. Native fields are URL query for GET or form fields for effects. Private license credentials and forced verify increment flag are supplied internally; account/confirm/full_refund/output_file are local controls.

{
  "name": "disable_license",
  "title": "Disable license",
  "description": "Disable license. Reviewed native PUT /licenses/disable; scope: edit_products. Requires explicit per-call confirmation.",
  "group": "Licenses",
  "method": "PUT",
  "path": "/licenses/disable",
  "pathKeys": {},
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "(the unique ID of the product \u2014 copy it from the license key block on the product's Content tab, or use the id field returned by the GET /products endpoint)",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    }
  },
  "required": [
    "product_id"
  ],
  "nativeFields": [
    "product_id"
  ],
  "risk": "destructive",
  "scope": "edit_products",
  "licenseAPI": true,
  "privateOutput": false,
  "collection": null,
  "sourceFile": "app/javascript/components/ApiDocumentation/Endpoints/Licenses.tsx"
}

decrement_license_uses

Decrement license uses. Reviewed native PUT /licenses/decrement_uses_count; scope: edit_products. Requires explicit per-call confirmation.

Argument	Type	Required	Meaning and constraints
`product_id`	string	Required	(the unique ID of the product — copy it from the license key block on the product's Content tab, or use the id field returned by the GET /products endpoint) {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.

gumroad-cli decrement-license-uses --help
gumroad-cli schema decrement-license-uses

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "(the unique ID of the product \u2014 copy it from the license key block on the product's Content tab, or use the id field returned by the GET /products endpoint)",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    },
    "confirm": {
      "type": "boolean",
      "description": "Explicit approval of this exact native effect or private file output."
    }
  },
  "required": [
    "product_id"
  ],
  "additionalProperties": false
}

Native request: PUT /licenses/decrement_uses_count. Authentication/scope: edit_products. Pinned official source. Native fields are URL query for GET or form fields for effects. Private license credentials and forced verify increment flag are supplied internally; account/confirm/full_refund/output_file are local controls.

{
  "name": "decrement_license_uses",
  "title": "Decrement license uses",
  "description": "Decrement license uses. Reviewed native PUT /licenses/decrement_uses_count; scope: edit_products. Requires explicit per-call confirmation.",
  "group": "Licenses",
  "method": "PUT",
  "path": "/licenses/decrement_uses_count",
  "pathKeys": {},
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "(the unique ID of the product \u2014 copy it from the license key block on the product's Content tab, or use the id field returned by the GET /products endpoint)",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    }
  },
  "required": [
    "product_id"
  ],
  "nativeFields": [
    "product_id"
  ],
  "risk": "destructive",
  "scope": "edit_products",
  "licenseAPI": true,
  "privateOutput": false,
  "collection": null,
  "sourceFile": "app/javascript/components/ApiDocumentation/Endpoints/Licenses.tsx"
}

rotate_license

Rotate license. Reviewed native PUT /licenses/rotate; scope: edit_products. Requires explicit per-call confirmation.

Argument	Type	Required	Meaning and constraints
`product_id`	string	Required	(the unique ID of the product — copy it from the license key block on the product's Content tab, or use the id field returned by the GET /products endpoint) {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.
`output_file`	string	Required	Required absolute NEW owner-private file for the replacement license receipt; no overwrite. {"minLength": 1}

gumroad-cli rotate-license --help
gumroad-cli schema rotate-license

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "(the unique ID of the product \u2014 copy it from the license key block on the product's Content tab, or use the id field returned by the GET /products endpoint)",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    },
    "confirm": {
      "type": "boolean",
      "description": "Explicit approval of this exact native effect or private file output."
    },
    "output_file": {
      "type": "string",
      "minLength": 1,
      "description": "Required absolute NEW owner-private file for the replacement license receipt; no overwrite."
    }
  },
  "required": [
    "product_id",
    "output_file"
  ],
  "additionalProperties": false
}

Native request: PUT /licenses/rotate. Authentication/scope: edit_products. Pinned official source. Native fields are URL query for GET or form fields for effects. Private license credentials and forced verify increment flag are supplied internally; account/confirm/full_refund/output_file are local controls.

{
  "name": "rotate_license",
  "title": "Rotate license",
  "description": "Rotate license. Reviewed native PUT /licenses/rotate; scope: edit_products. Requires explicit per-call confirmation.",
  "group": "Licenses",
  "method": "PUT",
  "path": "/licenses/rotate",
  "pathKeys": {},
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "(the unique ID of the product \u2014 copy it from the license key block on the product's Content tab, or use the id field returned by the GET /products endpoint)",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    }
  },
  "required": [
    "product_id"
  ],
  "nativeFields": [
    "product_id"
  ],
  "risk": "destructive",
  "scope": "edit_products",
  "licenseAPI": true,
  "privateOutput": true,
  "collection": null,
  "sourceFile": "app/javascript/components/ApiDocumentation/Endpoints/Licenses.tsx"
}

create_variant_category

Create variant category. Reviewed native POST /products/:product_id/variant_categories; scope: edit_products. Requires explicit per-call confirmation.

Argument	Type	Required	Meaning and constraints
`product_id`	string	Required	Exact opaque provider ID, including native = padding. {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`title`	string	Required	Reviewed current contract value. {"maxLength": 65536}
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.

gumroad-cli create-variant-category --help
gumroad-cli schema create-variant-category

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "title": {
      "type": "string",
      "maxLength": 65536,
      "description": ""
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    },
    "confirm": {
      "type": "boolean",
      "description": "Explicit approval of this exact native effect or private file output."
    }
  },
  "required": [
    "product_id",
    "title"
  ],
  "additionalProperties": false
}

Native request: POST /products/{product_id}/variant_categories. Authentication/scope: edit_products. Pinned official source. Native fields are URL query for GET or form fields for effects. Private license credentials and forced verify increment flag are supplied internally; account/confirm/full_refund/output_file are local controls.

{
  "name": "create_variant_category",
  "title": "Create variant category",
  "description": "Create variant category. Reviewed native POST /products/:product_id/variant_categories; scope: edit_products. Requires explicit per-call confirmation.",
  "group": "Variants",
  "method": "POST",
  "path": "/products/{product_id}/variant_categories",
  "pathKeys": {
    "product_id": "product_id"
  },
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "title": {
      "type": "string",
      "maxLength": 65536,
      "description": ""
    }
  },
  "required": [
    "product_id",
    "title"
  ],
  "nativeFields": [
    "title"
  ],
  "risk": "destructive",
  "scope": "edit_products",
  "licenseAPI": false,
  "privateOutput": false,
  "collection": null,
  "sourceFile": "app/javascript/components/ApiDocumentation/Endpoints/Variants.tsx"
}

get_variant_category

Get variant category. Reviewed native GET /products/:product_id/variant_categories/:id; scope: edit_products. Read only; no local effect approval required.

Argument	Type	Required	Meaning and constraints
`product_id`	string	Required	Exact opaque provider ID, including native = padding. {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`variant_category_id`	string	Required	Exact opaque provider ID, including native = padding. {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.

gumroad-cli get-variant-category --help
gumroad-cli schema get-variant-category

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "variant_category_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    }
  },
  "required": [
    "product_id",
    "variant_category_id"
  ],
  "additionalProperties": false
}

Native request: GET /products/{product_id}/variant_categories/{id}. Authentication/scope: edit_products. Pinned official source. Native fields are URL query for GET or form fields for effects. Private license credentials and forced verify increment flag are supplied internally; account/confirm/full_refund/output_file are local controls.

{
  "name": "get_variant_category",
  "title": "Get variant category",
  "description": "Get variant category. Reviewed native GET /products/:product_id/variant_categories/:id; scope: edit_products. Read only; no local effect approval required.",
  "group": "Variants",
  "method": "GET",
  "path": "/products/{product_id}/variant_categories/{id}",
  "pathKeys": {
    "product_id": "product_id",
    "id": "variant_category_id"
  },
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "variant_category_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    }
  },
  "required": [
    "product_id",
    "variant_category_id"
  ],
  "nativeFields": [],
  "risk": "read",
  "scope": "edit_products",
  "licenseAPI": false,
  "privateOutput": false,
  "collection": null,
  "sourceFile": "app/javascript/components/ApiDocumentation/Endpoints/Variants.tsx"
}

update_variant_category

Update variant category. Reviewed native PUT /products/:product_id/variant_categories/:id; scope: edit_products. Requires explicit per-call confirmation.

Argument	Type	Required	Meaning and constraints
`product_id`	string	Required	Exact opaque provider ID, including native = padding. {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`title`	string	Required	Reviewed current contract value. {"maxLength": 65536}
`variant_category_id`	string	Required	Exact opaque provider ID, including native = padding. {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.

gumroad-cli update-variant-category --help
gumroad-cli schema update-variant-category

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "title": {
      "type": "string",
      "maxLength": 65536,
      "description": ""
    },
    "variant_category_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    },
    "confirm": {
      "type": "boolean",
      "description": "Explicit approval of this exact native effect or private file output."
    }
  },
  "required": [
    "product_id",
    "variant_category_id",
    "title"
  ],
  "additionalProperties": false
}

Native request: PUT /products/{product_id}/variant_categories/{id}. Authentication/scope: edit_products. Pinned official source. Native fields are URL query for GET or form fields for effects. Private license credentials and forced verify increment flag are supplied internally; account/confirm/full_refund/output_file are local controls.

{
  "name": "update_variant_category",
  "title": "Update variant category",
  "description": "Update variant category. Reviewed native PUT /products/:product_id/variant_categories/:id; scope: edit_products. Requires explicit per-call confirmation.",
  "group": "Variants",
  "method": "PUT",
  "path": "/products/{product_id}/variant_categories/{id}",
  "pathKeys": {
    "product_id": "product_id",
    "id": "variant_category_id"
  },
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "title": {
      "type": "string",
      "maxLength": 65536,
      "description": ""
    },
    "variant_category_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    }
  },
  "required": [
    "product_id",
    "variant_category_id",
    "title"
  ],
  "nativeFields": [
    "title"
  ],
  "risk": "destructive",
  "scope": "edit_products",
  "licenseAPI": false,
  "privateOutput": false,
  "collection": null,
  "sourceFile": "app/javascript/components/ApiDocumentation/Endpoints/Variants.tsx"
}

delete_variant_category

Delete variant category. Reviewed native DELETE /products/:product_id/variant_categories/:id; scope: edit_products. Requires explicit per-call confirmation.

Argument	Type	Required	Meaning and constraints
`product_id`	string	Required	Exact opaque provider ID, including native = padding. {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`variant_category_id`	string	Required	Exact opaque provider ID, including native = padding. {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.

gumroad-cli delete-variant-category --help
gumroad-cli schema delete-variant-category

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "variant_category_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    },
    "confirm": {
      "type": "boolean",
      "description": "Explicit approval of this exact native effect or private file output."
    }
  },
  "required": [
    "product_id",
    "variant_category_id"
  ],
  "additionalProperties": false
}

Native request: DELETE /products/{product_id}/variant_categories/{id}. Authentication/scope: edit_products. Pinned official source. Native fields are URL query for GET or form fields for effects. Private license credentials and forced verify increment flag are supplied internally; account/confirm/full_refund/output_file are local controls.

{
  "name": "delete_variant_category",
  "title": "Delete variant category",
  "description": "Delete variant category. Reviewed native DELETE /products/:product_id/variant_categories/:id; scope: edit_products. Requires explicit per-call confirmation.",
  "group": "Variants",
  "method": "DELETE",
  "path": "/products/{product_id}/variant_categories/{id}",
  "pathKeys": {
    "product_id": "product_id",
    "id": "variant_category_id"
  },
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "variant_category_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    }
  },
  "required": [
    "product_id",
    "variant_category_id"
  ],
  "nativeFields": [],
  "risk": "destructive",
  "scope": "edit_products",
  "licenseAPI": false,
  "privateOutput": false,
  "collection": null,
  "sourceFile": "app/javascript/components/ApiDocumentation/Endpoints/Variants.tsx"
}

list_variant_categories

List variant categories. Reviewed native GET /products/:product_id/variant_categories; scope: edit_products. Read only; no local effect approval required.

Argument	Type	Required	Meaning and constraints
`product_id`	string	Required	Exact opaque provider ID, including native = padding. {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.

gumroad-cli list-variant-categories --help
gumroad-cli schema list-variant-categories

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    }
  },
  "required": [
    "product_id"
  ],
  "additionalProperties": false
}

Native request: GET /products/{product_id}/variant_categories. Authentication/scope: edit_products. Pinned official source. Native fields are URL query for GET or form fields for effects. Private license credentials and forced verify increment flag are supplied internally; account/confirm/full_refund/output_file are local controls.

{
  "name": "list_variant_categories",
  "title": "List variant categories",
  "description": "List variant categories. Reviewed native GET /products/:product_id/variant_categories; scope: edit_products. Read only; no local effect approval required.",
  "group": "Variants",
  "method": "GET",
  "path": "/products/{product_id}/variant_categories",
  "pathKeys": {
    "product_id": "product_id"
  },
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    }
  },
  "required": [
    "product_id"
  ],
  "nativeFields": [],
  "risk": "read",
  "scope": "edit_products",
  "licenseAPI": false,
  "privateOutput": false,
  "collection": null,
  "sourceFile": "app/javascript/components/ApiDocumentation/Endpoints/Variants.tsx"
}

create_variant

Create variant. Reviewed native POST /products/:product_id/variant_categories/:variant_category_id/variants; scope: edit_products. Requires explicit per-call confirmation.

Argument	Type	Required	Meaning and constraints
`product_id`	string	Required	Exact opaque provider ID, including native = padding. {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`variant_category_id`	string	Required	Exact opaque provider ID, including native = padding. {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`name`	string	Required	Reviewed current contract value. {"maxLength": 65536}
`price_difference_cents`	integer	Required	Reviewed current contract value. {"minimum": -9007199254740991, "maximum": 9007199254740991}
`max_purchase_count`	integer	Optional	(optional) {"minimum": 0, "maximum": 9007199254740991}
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.

gumroad-cli create-variant --help
gumroad-cli schema create-variant

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "variant_category_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "name": {
      "type": "string",
      "maxLength": 65536,
      "description": ""
    },
    "price_difference_cents": {
      "type": "integer",
      "description": "",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "max_purchase_count": {
      "type": "integer",
      "description": "(optional)",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    },
    "confirm": {
      "type": "boolean",
      "description": "Explicit approval of this exact native effect or private file output."
    }
  },
  "required": [
    "product_id",
    "variant_category_id",
    "name",
    "price_difference_cents"
  ],
  "additionalProperties": false
}

Native request: POST /products/{product_id}/variant_categories/{variant_category_id}/variants. Authentication/scope: edit_products. Pinned official source. Native fields are URL query for GET or form fields for effects. Private license credentials and forced verify increment flag are supplied internally; account/confirm/full_refund/output_file are local controls.

{
  "name": "create_variant",
  "title": "Create variant",
  "description": "Create variant. Reviewed native POST /products/:product_id/variant_categories/:variant_category_id/variants; scope: edit_products. Requires explicit per-call confirmation.",
  "group": "Variants",
  "method": "POST",
  "path": "/products/{product_id}/variant_categories/{variant_category_id}/variants",
  "pathKeys": {
    "product_id": "product_id",
    "variant_category_id": "variant_category_id"
  },
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "variant_category_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "name": {
      "type": "string",
      "maxLength": 65536,
      "description": ""
    },
    "price_difference_cents": {
      "type": "integer",
      "description": "",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "max_purchase_count": {
      "type": "integer",
      "description": "(optional)",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "product_id",
    "variant_category_id",
    "name",
    "price_difference_cents"
  ],
  "nativeFields": [
    "name",
    "price_difference_cents",
    "max_purchase_count"
  ],
  "risk": "destructive",
  "scope": "edit_products",
  "licenseAPI": false,
  "privateOutput": false,
  "collection": null,
  "sourceFile": "app/javascript/components/ApiDocumentation/Endpoints/Variants.tsx"
}

get_variant

Get variant. Reviewed native GET /products/:product_id/variant_categories/:variant_category_id/variants/:id; scope: edit_products. Read only; no local effect approval required.

Argument	Type	Required	Meaning and constraints
`product_id`	string	Required	Exact opaque provider ID, including native = padding. {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`variant_category_id`	string	Required	Exact opaque provider ID, including native = padding. {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`variant_id`	string	Required	Exact opaque provider ID, including native = padding. {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.

gumroad-cli get-variant --help
gumroad-cli schema get-variant

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "variant_category_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "variant_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    }
  },
  "required": [
    "product_id",
    "variant_category_id",
    "variant_id"
  ],
  "additionalProperties": false
}

Native request: GET /products/{product_id}/variant_categories/{variant_category_id}/variants/{id}. Authentication/scope: edit_products. Pinned official source. Native fields are URL query for GET or form fields for effects. Private license credentials and forced verify increment flag are supplied internally; account/confirm/full_refund/output_file are local controls.

{
  "name": "get_variant",
  "title": "Get variant",
  "description": "Get variant. Reviewed native GET /products/:product_id/variant_categories/:variant_category_id/variants/:id; scope: edit_products. Read only; no local effect approval required.",
  "group": "Variants",
  "method": "GET",
  "path": "/products/{product_id}/variant_categories/{variant_category_id}/variants/{id}",
  "pathKeys": {
    "product_id": "product_id",
    "variant_category_id": "variant_category_id",
    "id": "variant_id"
  },
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "variant_category_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "variant_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    }
  },
  "required": [
    "product_id",
    "variant_category_id",
    "variant_id"
  ],
  "nativeFields": [],
  "risk": "read",
  "scope": "edit_products",
  "licenseAPI": false,
  "privateOutput": false,
  "collection": null,
  "sourceFile": "app/javascript/components/ApiDocumentation/Endpoints/Variants.tsx"
}

update_variant

Update variant. Reviewed native PUT /products/:product_id/variant_categories/:variant_category_id/variants/:id; scope: edit_products. Requires explicit per-call confirmation.

Argument	Type	Required	Meaning and constraints
`product_id`	string	Required	Exact opaque provider ID, including native = padding. {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`variant_category_id`	string	Required	Exact opaque provider ID, including native = padding. {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`variant_id`	string	Required	Exact opaque provider ID, including native = padding. {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`name`	string	Optional	Reviewed current contract value. {"minLength": 1, "maxLength": 65536}
`price_difference_cents`	integer	Optional	Reviewed current contract value. {"minimum": -9007199254740991, "maximum": 9007199254740991}
`max_purchase_count`	integer	Optional	(optional) {"minimum": 0, "maximum": 9007199254740991}
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.

gumroad-cli update-variant --help
gumroad-cli schema update-variant

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "variant_category_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "variant_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "name": {
      "type": "string",
      "maxLength": 65536,
      "description": "",
      "minLength": 1
    },
    "price_difference_cents": {
      "type": "integer",
      "description": "",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "max_purchase_count": {
      "type": "integer",
      "description": "(optional)",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    },
    "confirm": {
      "type": "boolean",
      "description": "Explicit approval of this exact native effect or private file output."
    }
  },
  "required": [
    "product_id",
    "variant_category_id",
    "variant_id"
  ],
  "additionalProperties": false
}

Native request: PUT /products/{product_id}/variant_categories/{variant_category_id}/variants/{id}. Authentication/scope: edit_products. Pinned official source. Native fields are URL query for GET or form fields for effects. Private license credentials and forced verify increment flag are supplied internally; account/confirm/full_refund/output_file are local controls.

{
  "name": "update_variant",
  "title": "Update variant",
  "description": "Update variant. Reviewed native PUT /products/:product_id/variant_categories/:variant_category_id/variants/:id; scope: edit_products. Requires explicit per-call confirmation.",
  "group": "Variants",
  "method": "PUT",
  "path": "/products/{product_id}/variant_categories/{variant_category_id}/variants/{id}",
  "pathKeys": {
    "product_id": "product_id",
    "variant_category_id": "variant_category_id",
    "id": "variant_id"
  },
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "variant_category_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "variant_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "name": {
      "type": "string",
      "maxLength": 65536,
      "description": "",
      "minLength": 1
    },
    "price_difference_cents": {
      "type": "integer",
      "description": "",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "max_purchase_count": {
      "type": "integer",
      "description": "(optional)",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "product_id",
    "variant_category_id",
    "variant_id"
  ],
  "nativeFields": [
    "name",
    "price_difference_cents",
    "max_purchase_count"
  ],
  "risk": "destructive",
  "scope": "edit_products",
  "licenseAPI": false,
  "privateOutput": false,
  "collection": null,
  "sourceFile": "app/javascript/components/ApiDocumentation/Endpoints/Variants.tsx"
}

delete_variant

Delete variant. Reviewed native DELETE /products/:product_id/variant_categories/:variant_category_id/variants/:id; scope: edit_products. Requires explicit per-call confirmation.

Argument	Type	Required	Meaning and constraints
`product_id`	string	Required	Exact opaque provider ID, including native = padding. {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`variant_category_id`	string	Required	Exact opaque provider ID, including native = padding. {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`variant_id`	string	Required	Exact opaque provider ID, including native = padding. {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.

gumroad-cli delete-variant --help
gumroad-cli schema delete-variant

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "variant_category_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "variant_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    },
    "confirm": {
      "type": "boolean",
      "description": "Explicit approval of this exact native effect or private file output."
    }
  },
  "required": [
    "product_id",
    "variant_category_id",
    "variant_id"
  ],
  "additionalProperties": false
}

Native request: DELETE /products/{product_id}/variant_categories/{variant_category_id}/variants/{id}. Authentication/scope: edit_products. Pinned official source. Native fields are URL query for GET or form fields for effects. Private license credentials and forced verify increment flag are supplied internally; account/confirm/full_refund/output_file are local controls.

{
  "name": "delete_variant",
  "title": "Delete variant",
  "description": "Delete variant. Reviewed native DELETE /products/:product_id/variant_categories/:variant_category_id/variants/:id; scope: edit_products. Requires explicit per-call confirmation.",
  "group": "Variants",
  "method": "DELETE",
  "path": "/products/{product_id}/variant_categories/{variant_category_id}/variants/{id}",
  "pathKeys": {
    "product_id": "product_id",
    "variant_category_id": "variant_category_id",
    "id": "variant_id"
  },
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "variant_category_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "variant_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    }
  },
  "required": [
    "product_id",
    "variant_category_id",
    "variant_id"
  ],
  "nativeFields": [],
  "risk": "destructive",
  "scope": "edit_products",
  "licenseAPI": false,
  "privateOutput": false,
  "collection": null,
  "sourceFile": "app/javascript/components/ApiDocumentation/Endpoints/Variants.tsx"
}

list_variants

List variants. Reviewed native GET /products/:product_id/variant_categories/:variant_category_id/variants; scope: edit_products. Read only; no local effect approval required.

Argument	Type	Required	Meaning and constraints
`product_id`	string	Required	Exact opaque provider ID, including native = padding. {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`variant_category_id`	string	Required	Exact opaque provider ID, including native = padding. {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.

gumroad-cli list-variants --help
gumroad-cli schema list-variants

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "variant_category_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    }
  },
  "required": [
    "product_id",
    "variant_category_id"
  ],
  "additionalProperties": false
}

Native request: GET /products/{product_id}/variant_categories/{variant_category_id}/variants. Authentication/scope: edit_products. Pinned official source. Native fields are URL query for GET or form fields for effects. Private license credentials and forced verify increment flag are supplied internally; account/confirm/full_refund/output_file are local controls.

{
  "name": "list_variants",
  "title": "List variants",
  "description": "List variants. Reviewed native GET /products/:product_id/variant_categories/:variant_category_id/variants; scope: edit_products. Read only; no local effect approval required.",
  "group": "Variants",
  "method": "GET",
  "path": "/products/{product_id}/variant_categories/{variant_category_id}/variants",
  "pathKeys": {
    "product_id": "product_id",
    "variant_category_id": "variant_category_id"
  },
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "variant_category_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    }
  },
  "required": [
    "product_id",
    "variant_category_id"
  ],
  "nativeFields": [],
  "risk": "read",
  "scope": "edit_products",
  "licenseAPI": false,
  "privateOutput": false,
  "collection": null,
  "sourceFile": "app/javascript/components/ApiDocumentation/Endpoints/Variants.tsx"
}

list_offer_codes

List offer codes. Reviewed native GET /products/:product_id/offer_codes; scope: edit_products. Read only; no local effect approval required.

Argument	Type	Required	Meaning and constraints
`product_id`	string	Required	Exact opaque provider ID, including native = padding. {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.

gumroad-cli list-offer-codes --help
gumroad-cli schema list-offer-codes

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    }
  },
  "required": [
    "product_id"
  ],
  "additionalProperties": false
}

Native request: GET /products/{product_id}/offer_codes. Authentication/scope: edit_products. Pinned official source. Native fields are URL query for GET or form fields for effects. Private license credentials and forced verify increment flag are supplied internally; account/confirm/full_refund/output_file are local controls.

{
  "name": "list_offer_codes",
  "title": "List offer codes",
  "description": "List offer codes. Reviewed native GET /products/:product_id/offer_codes; scope: edit_products. Read only; no local effect approval required.",
  "group": "OfferCodes",
  "method": "GET",
  "path": "/products/{product_id}/offer_codes",
  "pathKeys": {
    "product_id": "product_id"
  },
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    }
  },
  "required": [
    "product_id"
  ],
  "nativeFields": [],
  "risk": "read",
  "scope": "edit_products",
  "licenseAPI": false,
  "privateOutput": false,
  "collection": null,
  "sourceFile": "app/javascript/components/ApiDocumentation/Endpoints/OfferCodes.tsx"
}

get_offer_code

Get offer code. Reviewed native GET /products/:product_id/offer_codes/:id; scope: edit_products. Read only; no local effect approval required.

Argument	Type	Required	Meaning and constraints
`product_id`	string	Required	Exact opaque provider ID, including native = padding. {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`offer_code_id`	string	Required	Exact opaque provider ID, including native = padding. {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.

gumroad-cli get-offer-code --help
gumroad-cli schema get-offer-code

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "offer_code_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    }
  },
  "required": [
    "product_id",
    "offer_code_id"
  ],
  "additionalProperties": false
}

Native request: GET /products/{product_id}/offer_codes/{id}. Authentication/scope: edit_products. Pinned official source. Native fields are URL query for GET or form fields for effects. Private license credentials and forced verify increment flag are supplied internally; account/confirm/full_refund/output_file are local controls.

{
  "name": "get_offer_code",
  "title": "Get offer code",
  "description": "Get offer code. Reviewed native GET /products/:product_id/offer_codes/:id; scope: edit_products. Read only; no local effect approval required.",
  "group": "OfferCodes",
  "method": "GET",
  "path": "/products/{product_id}/offer_codes/{id}",
  "pathKeys": {
    "product_id": "product_id",
    "id": "offer_code_id"
  },
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "offer_code_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    }
  },
  "required": [
    "product_id",
    "offer_code_id"
  ],
  "nativeFields": [],
  "risk": "read",
  "scope": "edit_products",
  "licenseAPI": false,
  "privateOutput": false,
  "collection": null,
  "sourceFile": "app/javascript/components/ApiDocumentation/Endpoints/OfferCodes.tsx"
}

create_offer_code

Create offer code. Reviewed native POST /products/:product_id/offer_codes; scope: edit_products. Requires explicit per-call confirmation.

Argument	Type	Required	Meaning and constraints
`product_id`	string	Required	Exact opaque provider ID, including native = padding. {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`name`	string	Required	(the coupon code used at checkout) {"maxLength": 65536}
`amount_off`	integer	Required	Reviewed current contract value. {"minimum": 0, "maximum": 9007199254740991}
`offer_type`	string	Optional	(optional, "cents" or "percent") Default: "cents" {"enum": ["cents", "percent"]}
`max_purchase_count`	integer	Optional	(optional) {"minimum": 0, "maximum": 9007199254740991}
`minimum_amount_cents`	integer	Optional	(optional) Minimum order total in cents required for the offer code to apply {"minimum": 0, "maximum": 9007199254740991}
`universal`	boolean	Optional	(optional, true or false) Default: false
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.

gumroad-cli create-offer-code --help
gumroad-cli schema create-offer-code

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "name": {
      "type": "string",
      "maxLength": 65536,
      "description": "(the coupon code used at checkout)"
    },
    "amount_off": {
      "type": "integer",
      "description": "",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "offer_type": {
      "type": "string",
      "enum": [
        "cents",
        "percent"
      ],
      "description": "(optional, \"cents\" or \"percent\") Default: \"cents\""
    },
    "max_purchase_count": {
      "type": "integer",
      "description": "(optional)",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "minimum_amount_cents": {
      "type": "integer",
      "description": "(optional) Minimum order total in cents required for the offer code to apply",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "universal": {
      "type": "boolean",
      "description": "(optional, true or false) Default: false"
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    },
    "confirm": {
      "type": "boolean",
      "description": "Explicit approval of this exact native effect or private file output."
    }
  },
  "required": [
    "product_id",
    "name",
    "amount_off"
  ],
  "additionalProperties": false
}

Native request: POST /products/{product_id}/offer_codes. Authentication/scope: edit_products. Pinned official source. Native fields are URL query for GET or form fields for effects. Private license credentials and forced verify increment flag are supplied internally; account/confirm/full_refund/output_file are local controls.

{
  "name": "create_offer_code",
  "title": "Create offer code",
  "description": "Create offer code. Reviewed native POST /products/:product_id/offer_codes; scope: edit_products. Requires explicit per-call confirmation.",
  "group": "OfferCodes",
  "method": "POST",
  "path": "/products/{product_id}/offer_codes",
  "pathKeys": {
    "product_id": "product_id"
  },
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "name": {
      "type": "string",
      "maxLength": 65536,
      "description": "(the coupon code used at checkout)"
    },
    "amount_off": {
      "type": "integer",
      "description": "",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "offer_type": {
      "type": "string",
      "enum": [
        "cents",
        "percent"
      ],
      "description": "(optional, \"cents\" or \"percent\") Default: \"cents\""
    },
    "max_purchase_count": {
      "type": "integer",
      "description": "(optional)",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "minimum_amount_cents": {
      "type": "integer",
      "description": "(optional) Minimum order total in cents required for the offer code to apply",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "universal": {
      "type": "boolean",
      "description": "(optional, true or false) Default: false"
    }
  },
  "required": [
    "product_id",
    "name",
    "amount_off"
  ],
  "nativeFields": [
    "name",
    "amount_off",
    "offer_type",
    "max_purchase_count",
    "minimum_amount_cents",
    "universal"
  ],
  "risk": "destructive",
  "scope": "edit_products",
  "licenseAPI": false,
  "privateOutput": false,
  "collection": null,
  "sourceFile": "app/javascript/components/ApiDocumentation/Endpoints/OfferCodes.tsx"
}

update_offer_code

Update offer code. Reviewed native PUT /products/:product_id/offer_codes/:id; scope: edit_products. Requires explicit per-call confirmation.

Argument	Type	Required	Meaning and constraints
`product_id`	string	Required	Exact opaque provider ID, including native = padding. {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`offer_code_id`	string	Required	Exact opaque provider ID, including native = padding. {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`max_purchase_count`	integer	Optional	Reviewed current contract value. {"minimum": 0, "maximum": 9007199254740991}
`minimum_amount_cents`	integer	Optional	(optional) Minimum order total in cents required for the offer code to apply {"minimum": 0, "maximum": 9007199254740991}
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.

gumroad-cli update-offer-code --help
gumroad-cli schema update-offer-code

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "offer_code_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "max_purchase_count": {
      "type": "integer",
      "description": "",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "minimum_amount_cents": {
      "type": "integer",
      "description": "(optional) Minimum order total in cents required for the offer code to apply",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    },
    "confirm": {
      "type": "boolean",
      "description": "Explicit approval of this exact native effect or private file output."
    }
  },
  "required": [
    "product_id",
    "offer_code_id"
  ],
  "additionalProperties": false
}

Native request: PUT /products/{product_id}/offer_codes/{id}. Authentication/scope: edit_products. Pinned official source. Native fields are URL query for GET or form fields for effects. Private license credentials and forced verify increment flag are supplied internally; account/confirm/full_refund/output_file are local controls.

{
  "name": "update_offer_code",
  "title": "Update offer code",
  "description": "Update offer code. Reviewed native PUT /products/:product_id/offer_codes/:id; scope: edit_products. Requires explicit per-call confirmation.",
  "group": "OfferCodes",
  "method": "PUT",
  "path": "/products/{product_id}/offer_codes/{id}",
  "pathKeys": {
    "product_id": "product_id",
    "id": "offer_code_id"
  },
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "offer_code_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "max_purchase_count": {
      "type": "integer",
      "description": "",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "minimum_amount_cents": {
      "type": "integer",
      "description": "(optional) Minimum order total in cents required for the offer code to apply",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "product_id",
    "offer_code_id"
  ],
  "nativeFields": [
    "max_purchase_count",
    "minimum_amount_cents"
  ],
  "risk": "destructive",
  "scope": "edit_products",
  "licenseAPI": false,
  "privateOutput": false,
  "collection": null,
  "sourceFile": "app/javascript/components/ApiDocumentation/Endpoints/OfferCodes.tsx"
}

delete_offer_code

Delete offer code. Reviewed native DELETE /products/:product_id/offer_codes/:id; scope: edit_products. Requires explicit per-call confirmation.

Argument	Type	Required	Meaning and constraints
`product_id`	string	Required	Exact opaque provider ID, including native = padding. {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`offer_code_id`	string	Required	Exact opaque provider ID, including native = padding. {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.

gumroad-cli delete-offer-code --help
gumroad-cli schema delete-offer-code

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "offer_code_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    },
    "confirm": {
      "type": "boolean",
      "description": "Explicit approval of this exact native effect or private file output."
    }
  },
  "required": [
    "product_id",
    "offer_code_id"
  ],
  "additionalProperties": false
}

Native request: DELETE /products/{product_id}/offer_codes/{id}. Authentication/scope: edit_products. Pinned official source. Native fields are URL query for GET or form fields for effects. Private license credentials and forced verify increment flag are supplied internally; account/confirm/full_refund/output_file are local controls.

{
  "name": "delete_offer_code",
  "title": "Delete offer code",
  "description": "Delete offer code. Reviewed native DELETE /products/:product_id/offer_codes/:id; scope: edit_products. Requires explicit per-call confirmation.",
  "group": "OfferCodes",
  "method": "DELETE",
  "path": "/products/{product_id}/offer_codes/{id}",
  "pathKeys": {
    "product_id": "product_id",
    "id": "offer_code_id"
  },
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "offer_code_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    }
  },
  "required": [
    "product_id",
    "offer_code_id"
  ],
  "nativeFields": [],
  "risk": "destructive",
  "scope": "edit_products",
  "licenseAPI": false,
  "privateOutput": false,
  "collection": null,
  "sourceFile": "app/javascript/components/ApiDocumentation/Endpoints/OfferCodes.tsx"
}

list_custom_fields

List custom fields. Reviewed native GET /products/:product_id/custom_fields; scope: edit_products. Read only; no local effect approval required.

Argument	Type	Required	Meaning and constraints
`product_id`	string	Required	Exact opaque provider ID, including native = padding. {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.

gumroad-cli list-custom-fields --help
gumroad-cli schema list-custom-fields

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    }
  },
  "required": [
    "product_id"
  ],
  "additionalProperties": false
}

Native request: GET /products/{product_id}/custom_fields. Authentication/scope: edit_products. Pinned official source. Native fields are URL query for GET or form fields for effects. Private license credentials and forced verify increment flag are supplied internally; account/confirm/full_refund/output_file are local controls.

{
  "name": "list_custom_fields",
  "title": "List custom fields",
  "description": "List custom fields. Reviewed native GET /products/:product_id/custom_fields; scope: edit_products. Read only; no local effect approval required.",
  "group": "CustomFields",
  "method": "GET",
  "path": "/products/{product_id}/custom_fields",
  "pathKeys": {
    "product_id": "product_id"
  },
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    }
  },
  "required": [
    "product_id"
  ],
  "nativeFields": [],
  "risk": "read",
  "scope": "edit_products",
  "licenseAPI": false,
  "privateOutput": false,
  "collection": null,
  "sourceFile": "app/javascript/components/ApiDocumentation/Endpoints/CustomFields.tsx"
}

create_custom_field

Create custom field. Reviewed native POST /products/:product_id/custom_fields; scope: edit_products. Requires explicit per-call confirmation.

Argument	Type	Required	Meaning and constraints
`product_id`	string	Required	Exact opaque provider ID, including native = padding. {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`name`	string	Required	Reviewed current contract value. {"maxLength": 65536}
`required`	boolean	Required	(true or false)
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.

gumroad-cli create-custom-field --help
gumroad-cli schema create-custom-field

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "name": {
      "type": "string",
      "maxLength": 65536,
      "description": ""
    },
    "required": {
      "type": "boolean",
      "description": "(true or false)"
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    },
    "confirm": {
      "type": "boolean",
      "description": "Explicit approval of this exact native effect or private file output."
    }
  },
  "required": [
    "product_id",
    "name",
    "required"
  ],
  "additionalProperties": false
}

Native request: POST /products/{product_id}/custom_fields. Authentication/scope: edit_products. Pinned official source. Native fields are URL query for GET or form fields for effects. Private license credentials and forced verify increment flag are supplied internally; account/confirm/full_refund/output_file are local controls.

{
  "name": "create_custom_field",
  "title": "Create custom field",
  "description": "Create custom field. Reviewed native POST /products/:product_id/custom_fields; scope: edit_products. Requires explicit per-call confirmation.",
  "group": "CustomFields",
  "method": "POST",
  "path": "/products/{product_id}/custom_fields",
  "pathKeys": {
    "product_id": "product_id"
  },
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "name": {
      "type": "string",
      "maxLength": 65536,
      "description": ""
    },
    "required": {
      "type": "boolean",
      "description": "(true or false)"
    }
  },
  "required": [
    "product_id",
    "name",
    "required"
  ],
  "nativeFields": [
    "name",
    "required"
  ],
  "risk": "destructive",
  "scope": "edit_products",
  "licenseAPI": false,
  "privateOutput": false,
  "collection": null,
  "sourceFile": "app/javascript/components/ApiDocumentation/Endpoints/CustomFields.tsx"
}

update_custom_field

Update custom field. Reviewed native PUT /products/:product_id/custom_fields/:name; scope: edit_products. Requires explicit per-call confirmation.

Argument	Type	Required	Meaning and constraints
`product_id`	string	Required	Exact opaque provider ID, including native = padding. {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`name`	string	Required	Exact existing field name; encoded as one URL segment. {"minLength": 1, "maxLength": 256}
`required`	boolean	Required	(true or false)
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.

gumroad-cli update-custom-field --help
gumroad-cli schema update-custom-field

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "name": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact existing field name; encoded as one URL segment.",
      "minLength": 1
    },
    "required": {
      "type": "boolean",
      "description": "(true or false)"
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    },
    "confirm": {
      "type": "boolean",
      "description": "Explicit approval of this exact native effect or private file output."
    }
  },
  "required": [
    "product_id",
    "name",
    "required"
  ],
  "additionalProperties": false
}

Native request: PUT /products/{product_id}/custom_fields/{name}. Authentication/scope: edit_products. Pinned official source. Native fields are URL query for GET or form fields for effects. Private license credentials and forced verify increment flag are supplied internally; account/confirm/full_refund/output_file are local controls.

{
  "name": "update_custom_field",
  "title": "Update custom field",
  "description": "Update custom field. Reviewed native PUT /products/:product_id/custom_fields/:name; scope: edit_products. Requires explicit per-call confirmation.",
  "group": "CustomFields",
  "method": "PUT",
  "path": "/products/{product_id}/custom_fields/{name}",
  "pathKeys": {
    "product_id": "product_id",
    "name": "name"
  },
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "name": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact existing field name; encoded as one URL segment.",
      "minLength": 1
    },
    "required": {
      "type": "boolean",
      "description": "(true or false)"
    }
  },
  "required": [
    "product_id",
    "name",
    "required"
  ],
  "nativeFields": [
    "required"
  ],
  "risk": "destructive",
  "scope": "edit_products",
  "licenseAPI": false,
  "privateOutput": false,
  "collection": null,
  "sourceFile": "app/javascript/components/ApiDocumentation/Endpoints/CustomFields.tsx"
}

delete_custom_field

Delete custom field. Reviewed native DELETE /products/:product_id/custom_fields/:name; scope: edit_products. Requires explicit per-call confirmation.

Argument	Type	Required	Meaning and constraints
`product_id`	string	Required	Exact opaque provider ID, including native = padding. {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`name`	string	Required	Exact existing field name; encoded as one URL segment. {"minLength": 1, "maxLength": 256}
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.

gumroad-cli delete-custom-field --help
gumroad-cli schema delete-custom-field

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "name": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact existing field name; encoded as one URL segment.",
      "minLength": 1
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    },
    "confirm": {
      "type": "boolean",
      "description": "Explicit approval of this exact native effect or private file output."
    }
  },
  "required": [
    "product_id",
    "name"
  ],
  "additionalProperties": false
}

Native request: DELETE /products/{product_id}/custom_fields/{name}. Authentication/scope: edit_products. Pinned official source. Native fields are URL query for GET or form fields for effects. Private license credentials and forced verify increment flag are supplied internally; account/confirm/full_refund/output_file are local controls.

{
  "name": "delete_custom_field",
  "title": "Delete custom field",
  "description": "Delete custom field. Reviewed native DELETE /products/:product_id/custom_fields/:name; scope: edit_products. Requires explicit per-call confirmation.",
  "group": "CustomFields",
  "method": "DELETE",
  "path": "/products/{product_id}/custom_fields/{name}",
  "pathKeys": {
    "product_id": "product_id",
    "name": "name"
  },
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "name": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact existing field name; encoded as one URL segment.",
      "minLength": 1
    }
  },
  "required": [
    "product_id",
    "name"
  ],
  "nativeFields": [],
  "risk": "destructive",
  "scope": "edit_products",
  "licenseAPI": false,
  "privateOutput": false,
  "collection": null,
  "sourceFile": "app/javascript/components/ApiDocumentation/Endpoints/CustomFields.tsx"
}

create_resource_subscription

Create resource subscription. Reviewed native PUT /resource_subscriptions; scope: view_sales for sale event; provider authorization for other events. Requires explicit per-call confirmation.

Argument	Type	Required	Meaning and constraints
`resource_name`	string	Required	Exact native event to subscribe to. {"enum": ["sale", "refund", "dispute", "dispute_won", "cancellation", "subscription_updated", "subscription_ended", "subscription_restarted"]}
`post_url`	string	Required	Intended HTTPS callback; provider posts private customer events. {"maxLength": 65536, "format": "uri"}
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.

gumroad-cli create-resource-subscription --help
gumroad-cli schema create-resource-subscription

{
  "type": "object",
  "properties": {
    "resource_name": {
      "type": "string",
      "enum": [
        "sale",
        "refund",
        "dispute",
        "dispute_won",
        "cancellation",
        "subscription_updated",
        "subscription_ended",
        "subscription_restarted"
      ],
      "description": "Exact native event to subscribe to."
    },
    "post_url": {
      "type": "string",
      "maxLength": 65536,
      "description": "Intended HTTPS callback; provider posts private customer events.",
      "format": "uri"
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    },
    "confirm": {
      "type": "boolean",
      "description": "Explicit approval of this exact native effect or private file output."
    }
  },
  "required": [
    "resource_name",
    "post_url"
  ],
  "additionalProperties": false
}

Native request: PUT /resource_subscriptions. Authentication/scope: view_sales for sale event; provider authorization for other events. Pinned official source. Native fields are URL query for GET or form fields for effects. Private license credentials and forced verify increment flag are supplied internally; account/confirm/full_refund/output_file are local controls.

{
  "name": "create_resource_subscription",
  "title": "Create resource subscription",
  "description": "Create resource subscription. Reviewed native PUT /resource_subscriptions; scope: view_sales for sale event; provider authorization for other events. Requires explicit per-call confirmation.",
  "group": "ResourceSubscriptions",
  "method": "PUT",
  "path": "/resource_subscriptions",
  "pathKeys": {},
  "properties": {
    "resource_name": {
      "type": "string",
      "enum": [
        "sale",
        "refund",
        "dispute",
        "dispute_won",
        "cancellation",
        "subscription_updated",
        "subscription_ended",
        "subscription_restarted"
      ],
      "description": "Exact native event to subscribe to."
    },
    "post_url": {
      "type": "string",
      "maxLength": 65536,
      "description": "Intended HTTPS callback; provider posts private customer events.",
      "format": "uri"
    }
  },
  "required": [
    "resource_name",
    "post_url"
  ],
  "nativeFields": [
    "resource_name",
    "post_url"
  ],
  "risk": "destructive",
  "scope": "view_sales for sale event; provider authorization for other events",
  "licenseAPI": false,
  "privateOutput": false,
  "collection": null,
  "sourceFile": "app/javascript/components/ApiDocumentation/Endpoints/ResourceSubscriptions.tsx"
}

list_resource_subscriptions

List resource subscriptions. Reviewed native GET /resource_subscriptions; scope: view_sales for sale event; provider authorization for other events. Read only; no local effect approval required.

Argument	Type	Required	Meaning and constraints
`resource_name`	string	Required	(string) - Currently there are 8 supported values - "sale", "refund", "dispute", "dispute_won", "cancellation", "subscription_updated", "subscription_ended", and "subscription_restarted". {"enum": ["sale", "refund", "dispute", "dispute_won", "cancellation", "subscription_updated", "subscription_ended", "subscription_restarted"]}
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.

gumroad-cli list-resource-subscriptions --help
gumroad-cli schema list-resource-subscriptions

{
  "type": "object",
  "properties": {
    "resource_name": {
      "type": "string",
      "enum": [
        "sale",
        "refund",
        "dispute",
        "dispute_won",
        "cancellation",
        "subscription_updated",
        "subscription_ended",
        "subscription_restarted"
      ],
      "description": "(string) - Currently there are 8 supported values - \"sale\", \"refund\", \"dispute\", \"dispute_won\", \"cancellation\", \"subscription_updated\", \"subscription_ended\", and \"subscription_restarted\"."
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    }
  },
  "required": [
    "resource_name"
  ],
  "additionalProperties": false
}

Native request: GET /resource_subscriptions. Authentication/scope: view_sales for sale event; provider authorization for other events. Pinned official source. Native fields are URL query for GET or form fields for effects. Private license credentials and forced verify increment flag are supplied internally; account/confirm/full_refund/output_file are local controls.

{
  "name": "list_resource_subscriptions",
  "title": "List resource subscriptions",
  "description": "List resource subscriptions. Reviewed native GET /resource_subscriptions; scope: view_sales for sale event; provider authorization for other events. Read only; no local effect approval required.",
  "group": "ResourceSubscriptions",
  "method": "GET",
  "path": "/resource_subscriptions",
  "pathKeys": {},
  "properties": {
    "resource_name": {
      "type": "string",
      "enum": [
        "sale",
        "refund",
        "dispute",
        "dispute_won",
        "cancellation",
        "subscription_updated",
        "subscription_ended",
        "subscription_restarted"
      ],
      "description": "(string) - Currently there are 8 supported values - \"sale\", \"refund\", \"dispute\", \"dispute_won\", \"cancellation\", \"subscription_updated\", \"subscription_ended\", and \"subscription_restarted\"."
    }
  },
  "required": [
    "resource_name"
  ],
  "nativeFields": [
    "resource_name"
  ],
  "risk": "read",
  "scope": "view_sales for sale event; provider authorization for other events",
  "licenseAPI": false,
  "privateOutput": false,
  "collection": null,
  "sourceFile": "app/javascript/components/ApiDocumentation/Endpoints/ResourceSubscriptions.tsx"
}

delete_resource_subscription

Delete resource subscription. Reviewed native DELETE /resource_subscriptions/:resource_subscription_id; scope: view_sales for sale event; provider authorization for other events. Requires explicit per-call confirmation.

Argument	Type	Required	Meaning and constraints
`resource_subscription_id`	string	Required	Exact opaque provider ID, including native = padding. {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.

gumroad-cli delete-resource-subscription --help
gumroad-cli schema delete-resource-subscription

{
  "type": "object",
  "properties": {
    "resource_subscription_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    },
    "confirm": {
      "type": "boolean",
      "description": "Explicit approval of this exact native effect or private file output."
    }
  },
  "required": [
    "resource_subscription_id"
  ],
  "additionalProperties": false
}

Native request: DELETE /resource_subscriptions/{resource_subscription_id}. Authentication/scope: view_sales for sale event; provider authorization for other events. Pinned official source. Native fields are URL query for GET or form fields for effects. Private license credentials and forced verify increment flag are supplied internally; account/confirm/full_refund/output_file are local controls.

{
  "name": "delete_resource_subscription",
  "title": "Delete resource subscription",
  "description": "Delete resource subscription. Reviewed native DELETE /resource_subscriptions/:resource_subscription_id; scope: view_sales for sale event; provider authorization for other events. Requires explicit per-call confirmation.",
  "group": "ResourceSubscriptions",
  "method": "DELETE",
  "path": "/resource_subscriptions/{resource_subscription_id}",
  "pathKeys": {
    "resource_subscription_id": "resource_subscription_id"
  },
  "properties": {
    "resource_subscription_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    }
  },
  "required": [
    "resource_subscription_id"
  ],
  "nativeFields": [],
  "risk": "destructive",
  "scope": "view_sales for sale event; provider authorization for other events",
  "licenseAPI": false,
  "privateOutput": false,
  "collection": null,
  "sourceFile": "app/javascript/components/ApiDocumentation/Endpoints/ResourceSubscriptions.tsx"
}

get_refund_policy

Get refund policy. Reviewed native GET /refund_policy; scope: account. Read only; no local effect approval required.

Argument	Type	Required	Meaning and constraints
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.

gumroad-cli get-refund-policy --help
gumroad-cli schema get-refund-policy

{
  "type": "object",
  "properties": {
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    }
  },
  "required": [],
  "additionalProperties": false
}

Native request: GET /refund_policy. Authentication/scope: account. Pinned official source. Native fields are URL query for GET or form fields for effects. Private license credentials and forced verify increment flag are supplied internally; account/confirm/full_refund/output_file are local controls.

{
  "name": "get_refund_policy",
  "title": "Get refund policy",
  "description": "Get refund policy. Reviewed native GET /refund_policy; scope: account. Read only; no local effect approval required.",
  "group": "RefundPolicy",
  "method": "GET",
  "path": "/refund_policy",
  "pathKeys": {},
  "properties": {},
  "required": [],
  "nativeFields": [],
  "risk": "read",
  "scope": "account",
  "licenseAPI": false,
  "privateOutput": false,
  "collection": null,
  "sourceFile": "app/javascript/components/ApiDocumentation/Endpoints/RefundPolicy.tsx"
}

update_refund_policy

Update refund policy. Reviewed native PUT /refund_policy; scope: account. Requires explicit per-call confirmation.

Argument	Type	Required	Meaning and constraints
`refund_period`	string	Required	Required. One of "none", "7", "14", "30", or "183". {"enum": ["none", "7", "14", "30", "183"]}
`fine_print`	string	Optional	Optional. Max 3000 characters. HTML is stripped. Send an empty value to clear it. {"maxLength": 3000}
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.

gumroad-cli update-refund-policy --help
gumroad-cli schema update-refund-policy

{
  "type": "object",
  "properties": {
    "refund_period": {
      "type": "string",
      "enum": [
        "none",
        "7",
        "14",
        "30",
        "183"
      ],
      "description": "Required. One of \"none\", \"7\", \"14\", \"30\", or \"183\"."
    },
    "fine_print": {
      "type": "string",
      "maxLength": 3000,
      "description": "Optional. Max 3000 characters. HTML is stripped. Send an empty value to clear it."
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    },
    "confirm": {
      "type": "boolean",
      "description": "Explicit approval of this exact native effect or private file output."
    }
  },
  "required": [
    "refund_period"
  ],
  "additionalProperties": false
}

Native request: PUT /refund_policy. Authentication/scope: account. Pinned official source. Native fields are URL query for GET or form fields for effects. Private license credentials and forced verify increment flag are supplied internally; account/confirm/full_refund/output_file are local controls.

{
  "name": "update_refund_policy",
  "title": "Update refund policy",
  "description": "Update refund policy. Reviewed native PUT /refund_policy; scope: account. Requires explicit per-call confirmation.",
  "group": "RefundPolicy",
  "method": "PUT",
  "path": "/refund_policy",
  "pathKeys": {},
  "properties": {
    "refund_period": {
      "type": "string",
      "enum": [
        "none",
        "7",
        "14",
        "30",
        "183"
      ],
      "description": "Required. One of \"none\", \"7\", \"14\", \"30\", or \"183\"."
    },
    "fine_print": {
      "type": "string",
      "maxLength": 3000,
      "description": "Optional. Max 3000 characters. HTML is stripped. Send an empty value to clear it."
    }
  },
  "required": [
    "refund_period"
  ],
  "nativeFields": [
    "refund_period",
    "fine_print"
  ],
  "risk": "destructive",
  "scope": "account",
  "licenseAPI": false,
  "privateOutput": false,
  "collection": null,
  "sourceFile": "app/javascript/components/ApiDocumentation/Endpoints/RefundPolicy.tsx"
}

list_payouts

List payouts. Reviewed native GET /payouts; scope: view_payouts. Read only; no local effect approval required.

Argument	Type	Required	Meaning and constraints
`after`	string	Optional	(optional, date in form YYYY-MM-DD) - Only return payouts after this date {"maxLength": 65536, "format": "date"}
`before`	string	Optional	(optional, date in form YYYY-MM-DD) - Only return payouts before this date {"maxLength": 65536, "format": "date"}
`page_key`	string	Optional	(optional) - A key representing a page of results. It is given in the response as `next_page_key`. {"maxLength": 65536}
`include_upcoming`	boolean	Optional	(optional, default: "true") - Set to "false" to exclude the upcoming payout from the response.
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.

gumroad-cli list-payouts --help
gumroad-cli schema list-payouts

{
  "type": "object",
  "properties": {
    "after": {
      "type": "string",
      "maxLength": 65536,
      "description": "(optional, date in form YYYY-MM-DD) - Only return payouts after this date",
      "format": "date"
    },
    "before": {
      "type": "string",
      "maxLength": 65536,
      "description": "(optional, date in form YYYY-MM-DD) - Only return payouts before this date",
      "format": "date"
    },
    "page_key": {
      "type": "string",
      "maxLength": 65536,
      "description": "(optional) - A key representing a page of results. It is given in the response as `next_page_key`."
    },
    "include_upcoming": {
      "type": "boolean",
      "description": "(optional, default: \"true\") - Set to \"false\" to exclude the upcoming payout from the response."
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    }
  },
  "required": [],
  "additionalProperties": false
}

Native request: GET /payouts. Authentication/scope: view_payouts. Pinned official source. Native fields are URL query for GET or form fields for effects. Private license credentials and forced verify increment flag are supplied internally; account/confirm/full_refund/output_file are local controls.

{
  "name": "list_payouts",
  "title": "List payouts",
  "description": "List payouts. Reviewed native GET /payouts; scope: view_payouts. Read only; no local effect approval required.",
  "group": "Payouts",
  "method": "GET",
  "path": "/payouts",
  "pathKeys": {},
  "properties": {
    "after": {
      "type": "string",
      "maxLength": 65536,
      "description": "(optional, date in form YYYY-MM-DD) - Only return payouts after this date",
      "format": "date"
    },
    "before": {
      "type": "string",
      "maxLength": 65536,
      "description": "(optional, date in form YYYY-MM-DD) - Only return payouts before this date",
      "format": "date"
    },
    "page_key": {
      "type": "string",
      "maxLength": 65536,
      "description": "(optional) - A key representing a page of results. It is given in the response as `next_page_key`."
    },
    "include_upcoming": {
      "type": "boolean",
      "description": "(optional, default: \"true\") - Set to \"false\" to exclude the upcoming payout from the response."
    }
  },
  "required": [],
  "nativeFields": [
    "after",
    "before",
    "page_key",
    "include_upcoming"
  ],
  "risk": "read",
  "scope": "view_payouts",
  "licenseAPI": false,
  "privateOutput": false,
  "collection": "payouts",
  "sourceFile": "app/javascript/components/ApiDocumentation/Endpoints/Payouts.tsx"
}

get_payout

Get payout. Reviewed native GET /payouts/:id; scope: view_payouts. Read only; no local effect approval required.

Argument	Type	Required	Meaning and constraints
`payout_id`	string	Required	Exact opaque provider ID, including native = padding. {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`include_sales`	boolean	Optional	(optional, default: "true") - Set to "false" to exclude the "sales", "refunded_sales", and "disputed_sales" details from the response.
`include_transactions`	boolean	Optional	(optional, default: "false") - Set to "true" to include the same transaction details in the response as exported payout CSV. All balance-affecting transactions included in the payout will be listed in a "transactions" array. Each transaction will have these keys: { type:, date:, purchase_id:, item_name:, buyer_name:, buyer_email:, taxes:, shipping:, sale_price:, gumroad_fees:, net_total: }. The "type" of transactions can be "Sale", "Chargeback", "Full Refund", "Partial Refund", "PayPal Refund", "Stripe Connect Refund", "Affiliate Credit", "PayPal Connect Affiliate Fees", "Stripe Connect Affiliate Fees", "PayPal Payouts", "Stripe Connect Payouts", "Credit", "Payout Fee", and "Technical Adjustment".
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.

gumroad-cli get-payout --help
gumroad-cli schema get-payout

{
  "type": "object",
  "properties": {
    "payout_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "include_sales": {
      "type": "boolean",
      "description": "(optional, default: \"true\") - Set to \"false\" to exclude the \"sales\", \"refunded_sales\", and \"disputed_sales\" details from the response."
    },
    "include_transactions": {
      "type": "boolean",
      "description": "(optional, default: \"false\") - Set to \"true\" to include the same transaction details in the response as exported payout CSV. All balance-affecting transactions included in the payout will be listed in a \"transactions\" array. Each transaction will have these keys: { type:, date:, purchase_id:, item_name:, buyer_name:, buyer_email:, taxes:, shipping:, sale_price:, gumroad_fees:, net_total: }. The \"type\" of transactions can be \"Sale\", \"Chargeback\", \"Full Refund\", \"Partial Refund\", \"PayPal Refund\", \"Stripe Connect Refund\", \"Affiliate Credit\", \"PayPal Connect Affiliate Fees\", \"Stripe Connect Affiliate Fees\", \"PayPal Payouts\", \"Stripe Connect Payouts\", \"Credit\", \"Payout Fee\", and \"Technical Adjustment\"."
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    }
  },
  "required": [
    "payout_id"
  ],
  "additionalProperties": false
}

Native request: GET /payouts/{id}. Authentication/scope: view_payouts. Pinned official source. Native fields are URL query for GET or form fields for effects. Private license credentials and forced verify increment flag are supplied internally; account/confirm/full_refund/output_file are local controls.

{
  "name": "get_payout",
  "title": "Get payout",
  "description": "Get payout. Reviewed native GET /payouts/:id; scope: view_payouts. Read only; no local effect approval required.",
  "group": "Payouts",
  "method": "GET",
  "path": "/payouts/{id}",
  "pathKeys": {
    "id": "payout_id"
  },
  "properties": {
    "payout_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Exact opaque provider ID, including native = padding.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "include_sales": {
      "type": "boolean",
      "description": "(optional, default: \"true\") - Set to \"false\" to exclude the \"sales\", \"refunded_sales\", and \"disputed_sales\" details from the response."
    },
    "include_transactions": {
      "type": "boolean",
      "description": "(optional, default: \"false\") - Set to \"true\" to include the same transaction details in the response as exported payout CSV. All balance-affecting transactions included in the payout will be listed in a \"transactions\" array. Each transaction will have these keys: { type:, date:, purchase_id:, item_name:, buyer_name:, buyer_email:, taxes:, shipping:, sale_price:, gumroad_fees:, net_total: }. The \"type\" of transactions can be \"Sale\", \"Chargeback\", \"Full Refund\", \"Partial Refund\", \"PayPal Refund\", \"Stripe Connect Refund\", \"Affiliate Credit\", \"PayPal Connect Affiliate Fees\", \"Stripe Connect Affiliate Fees\", \"PayPal Payouts\", \"Stripe Connect Payouts\", \"Credit\", \"Payout Fee\", and \"Technical Adjustment\"."
    }
  },
  "required": [
    "payout_id"
  ],
  "nativeFields": [
    "include_sales",
    "include_transactions"
  ],
  "risk": "read",
  "scope": "view_payouts",
  "licenseAPI": false,
  "privateOutput": false,
  "collection": null,
  "sourceFile": "app/javascript/components/ApiDocumentation/Endpoints/Payouts.tsx"
}

get_upcoming_payout

Get upcoming payout. Reviewed native GET /payouts/upcoming; scope: view_payouts. Read only; no local effect approval required.

Argument	Type	Required	Meaning and constraints
`include_sales`	boolean	Optional	(optional, default: "true") - Set to "false" to exclude the "sales", "refunded_sales", and "disputed_sales" details from the response.
`include_transactions`	boolean	Optional	(optional, default: "false") - Set to "true" to include the same transaction details in the response as exported payout CSV. All balance-affecting transactions included in the payout will be listed in a "transactions" array. Each transaction will have these keys: { type:, date:, purchase_id:, item_name:, buyer_name:, buyer_email:, taxes:, shipping:, sale_price:, gumroad_fees:, net_total: }. The "type" of transactions can be "Sale", "Chargeback", "Full Refund", "Partial Refund", "PayPal Refund", "Stripe Connect Refund", "Affiliate Credit", "PayPal Connect Affiliate Fees", "Stripe Connect Affiliate Fees", "PayPal Payouts", "Stripe Connect Payouts", "Credit", "Payout Fee", and "Technical Adjustment".
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.

gumroad-cli get-upcoming-payout --help
gumroad-cli schema get-upcoming-payout

{
  "type": "object",
  "properties": {
    "include_sales": {
      "type": "boolean",
      "description": "(optional, default: \"true\") - Set to \"false\" to exclude the \"sales\", \"refunded_sales\", and \"disputed_sales\" details from the response."
    },
    "include_transactions": {
      "type": "boolean",
      "description": "(optional, default: \"false\") - Set to \"true\" to include the same transaction details in the response as exported payout CSV. All balance-affecting transactions included in the payout will be listed in a \"transactions\" array. Each transaction will have these keys: { type:, date:, purchase_id:, item_name:, buyer_name:, buyer_email:, taxes:, shipping:, sale_price:, gumroad_fees:, net_total: }. The \"type\" of transactions can be \"Sale\", \"Chargeback\", \"Full Refund\", \"Partial Refund\", \"PayPal Refund\", \"Stripe Connect Refund\", \"Affiliate Credit\", \"PayPal Connect Affiliate Fees\", \"Stripe Connect Affiliate Fees\", \"PayPal Payouts\", \"Stripe Connect Payouts\", \"Credit\", \"Payout Fee\", and \"Technical Adjustment\"."
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    }
  },
  "required": [],
  "additionalProperties": false
}

Native request: GET /payouts/upcoming. Authentication/scope: view_payouts. Pinned official source. Native fields are URL query for GET or form fields for effects. Private license credentials and forced verify increment flag are supplied internally; account/confirm/full_refund/output_file are local controls.

{
  "name": "get_upcoming_payout",
  "title": "Get upcoming payout",
  "description": "Get upcoming payout. Reviewed native GET /payouts/upcoming; scope: view_payouts. Read only; no local effect approval required.",
  "group": "Payouts",
  "method": "GET",
  "path": "/payouts/upcoming",
  "pathKeys": {},
  "properties": {
    "include_sales": {
      "type": "boolean",
      "description": "(optional, default: \"true\") - Set to \"false\" to exclude the \"sales\", \"refunded_sales\", and \"disputed_sales\" details from the response."
    },
    "include_transactions": {
      "type": "boolean",
      "description": "(optional, default: \"false\") - Set to \"true\" to include the same transaction details in the response as exported payout CSV. All balance-affecting transactions included in the payout will be listed in a \"transactions\" array. Each transaction will have these keys: { type:, date:, purchase_id:, item_name:, buyer_name:, buyer_email:, taxes:, shipping:, sale_price:, gumroad_fees:, net_total: }. The \"type\" of transactions can be \"Sale\", \"Chargeback\", \"Full Refund\", \"Partial Refund\", \"PayPal Refund\", \"Stripe Connect Refund\", \"Affiliate Credit\", \"PayPal Connect Affiliate Fees\", \"Stripe Connect Affiliate Fees\", \"PayPal Payouts\", \"Stripe Connect Payouts\", \"Credit\", \"Payout Fee\", and \"Technical Adjustment\"."
    }
  },
  "required": [],
  "nativeFields": [
    "include_sales",
    "include_transactions"
  ],
  "risk": "read",
  "scope": "view_payouts",
  "licenseAPI": false,
  "privateOutput": false,
  "collection": null,
  "sourceFile": "app/javascript/components/ApiDocumentation/Endpoints/Payouts.tsx"
}

increment_license_uses

Verify the intended private license and increment its native usage counter. Explicit confirmation required; no OAuth required.

Argument	Type	Required	Meaning and constraints
`product_id`	string	Required	Current native product ID, never deprecated permalink. {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.

gumroad-cli increment-license-uses --help
gumroad-cli schema increment-license-uses

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Current native product ID, never deprecated permalink.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    },
    "confirm": {
      "type": "boolean",
      "description": "Explicit approval of this exact native effect or private file output."
    }
  },
  "required": [
    "product_id"
  ],
  "additionalProperties": false
}

{
  "name": "increment_license_uses",
  "title": "Verify and increment license uses",
  "description": "Verify the intended private license and increment its native usage counter. Explicit confirmation required; no OAuth required.",
  "group": "Licenses",
  "method": "POST",
  "path": "/licenses/verify",
  "pathKeys": {},
  "properties": {
    "product_id": {
      "type": "string",
      "maxLength": 256,
      "description": "Current native product ID, never deprecated permalink.",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9_=-]+$"
    }
  },
  "required": [
    "product_id"
  ],
  "nativeFields": [
    "product_id"
  ],
  "risk": "destructive",
  "scope": "No OAuth required",
  "licenseAPI": true,
  "privateOutput": false,
  "collection": null,
  "sourceFile": "app/javascript/components/ApiDocumentation/Endpoints/Licenses.tsx"
}

get_custom_field

Compatibility read using documented list_custom_fields then exact field-name match. There is no native single-custom-field GET endpoint.

Argument	Type	Required	Meaning and constraints
`product_id`	string	Required	Reviewed current contract value. {"minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9_=-]+$"}
`name`	string	Required	Reviewed current contract value. {"minLength": 1, "maxLength": 256}
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.

gumroad-cli get-custom-field --help
gumroad-cli schema get-custom-field

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_=-]+$",
      "minLength": 1,
      "maxLength": 256
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 256
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    }
  },
  "required": [
    "product_id",
    "name"
  ],
  "additionalProperties": false
}

list_accounts

Local profile labels/default and credential availability only. No secrets, file paths, provider identity or network.

This local command takes no arguments.

gumroad-cli list-accounts --help
gumroad-cli schema list-accounts

{
  "type": "object",
  "properties": {},
  "required": [],
  "additionalProperties": false
}

get_operation_schema

Local native method/path, fields, scopes and pinned provenance. Field subset, not an official OpenAPI document or permission proof.

Argument	Type	Required	Meaning and constraints
`operation`	string	Required	Reviewed current contract value. {"enum": ["get_user", "list_categories", "list_products", "get_product", "create_product", "update_product", "delete_product", "enable_product", "disable_product", "list_sales", "get_sale", "mark_sale_as_shipped", "refund_sale", "revoke_sale_access", "restore_sale_access", "resend_sale_receipt", "list_subscribers", "get_subscriber", "verify_license", "enable_license", "disable_license", "decrement_license_uses", "rotate_license", "create_variant_category", "get_variant_category", "update_variant_category", "delete_variant_category", "list_variant_categories", "create_variant", "get_variant", "update_variant", "delete_variant", "list_variants", "list_offer_codes", "get_offer_code", "create_offer_code", "update_offer_code", "delete_offer_code", "list_custom_fields", "create_custom_field", "update_custom_field", "delete_custom_field", "create_resource_subscription", "list_resource_subscriptions", "delete_resource_subscription", "get_refund_policy", "update_refund_policy", "list_payouts", "get_payout", "get_upcoming_payout", "increment_license_uses"]}

gumroad-cli get-operation-schema --help
gumroad-cli schema get-operation-schema

{
  "type": "object",
  "properties": {
    "operation": {
      "type": "string",
      "enum": [
        "get_user",
        "list_categories",
        "list_products",
        "get_product",
        "create_product",
        "update_product",
        "delete_product",
        "enable_product",
        "disable_product",
        "list_sales",
        "get_sale",
        "mark_sale_as_shipped",
        "refund_sale",
        "revoke_sale_access",
        "restore_sale_access",
        "resend_sale_receipt",
        "list_subscribers",
        "get_subscriber",
        "verify_license",
        "enable_license",
        "disable_license",
        "decrement_license_uses",
        "rotate_license",
        "create_variant_category",
        "get_variant_category",
        "update_variant_category",
        "delete_variant_category",
        "list_variant_categories",
        "create_variant",
        "get_variant",
        "update_variant",
        "delete_variant",
        "list_variants",
        "list_offer_codes",
        "get_offer_code",
        "create_offer_code",
        "update_offer_code",
        "delete_offer_code",
        "list_custom_fields",
        "create_custom_field",
        "update_custom_field",
        "delete_custom_field",
        "create_resource_subscription",
        "list_resource_subscriptions",
        "delete_resource_subscription",
        "get_refund_policy",
        "update_refund_policy",
        "list_payouts",
        "get_payout",
        "get_upcoming_payout",
        "increment_license_uses"
      ]
    }
  },
  "required": [
    "operation"
  ],
  "additionalProperties": false
}

preview_commerce_batch

Local validation/hash binding exact ordered requests/profile label/native snapshot. No provider requests, secret loading, ownership/state validation or financial guarantee.

Argument	Type	Required	Meaning and constraints
`tasks`	array	Required	One to twenty exact ordered native effects. No replacement-key output. Nested arguments cannot override profile/confirmation or carry credentials/files. {"minItems": 1, "maxItems": 20}
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.

gumroad-cli preview-commerce-batch --help
gumroad-cli schema preview-commerce-batch

{
  "type": "object",
  "properties": {
    "tasks": {
      "type": "array",
      "minItems": 1,
      "maxItems": 20,
      "description": "One to twenty exact ordered native effects. No replacement-key output. Nested arguments cannot override profile/confirmation or carry credentials/files.",
      "items": {
        "type": "object",
        "properties": {
          "tool": {
            "type": "string",
            "enum": [
              "create_product",
              "update_product",
              "delete_product",
              "enable_product",
              "disable_product",
              "mark_sale_as_shipped",
              "refund_sale",
              "revoke_sale_access",
              "restore_sale_access",
              "resend_sale_receipt",
              "enable_license",
              "disable_license",
              "decrement_license_uses",
              "create_variant_category",
              "update_variant_category",
              "delete_variant_category",
              "create_variant",
              "update_variant",
              "delete_variant",
              "create_offer_code",
              "update_offer_code",
              "delete_offer_code",
              "create_custom_field",
              "update_custom_field",
              "delete_custom_field",
              "create_resource_subscription",
              "delete_resource_subscription",
              "update_refund_policy",
              "increment_license_uses"
            ]
          },
          "arguments": {
            "type": "object"
          }
        },
        "required": [
          "tool",
          "arguments"
        ],
        "additionalProperties": false
      }
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    }
  },
  "required": [
    "tasks"
  ],
  "additionalProperties": false
}

submit_commerce_batch

Confirmed ordered native effects, all prevalidated before first request, exact hash checked, stops first failure with known/unattempted receipts. No retry or implicit continuation.

Argument	Type	Required	Meaning and constraints
`tasks`	array	Required	One to twenty exact ordered native effects. No replacement-key output. Nested arguments cannot override profile/confirmation or carry credentials/files. {"minItems": 1, "maxItems": 20}
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.
`review_sha256`	string	Required	Reviewed current contract value. {"pattern": "^[a-f0-9]{64}$"}

gumroad-cli submit-commerce-batch --help
gumroad-cli schema submit-commerce-batch

{
  "type": "object",
  "properties": {
    "tasks": {
      "type": "array",
      "minItems": 1,
      "maxItems": 20,
      "description": "One to twenty exact ordered native effects. No replacement-key output. Nested arguments cannot override profile/confirmation or carry credentials/files.",
      "items": {
        "type": "object",
        "properties": {
          "tool": {
            "type": "string",
            "enum": [
              "create_product",
              "update_product",
              "delete_product",
              "enable_product",
              "disable_product",
              "mark_sale_as_shipped",
              "refund_sale",
              "revoke_sale_access",
              "restore_sale_access",
              "resend_sale_receipt",
              "enable_license",
              "disable_license",
              "decrement_license_uses",
              "create_variant_category",
              "update_variant_category",
              "delete_variant_category",
              "create_variant",
              "update_variant",
              "delete_variant",
              "create_offer_code",
              "update_offer_code",
              "delete_offer_code",
              "create_custom_field",
              "update_custom_field",
              "delete_custom_field",
              "create_resource_subscription",
              "delete_resource_subscription",
              "update_refund_policy",
              "increment_license_uses"
            ]
          },
          "arguments": {
            "type": "object"
          }
        },
        "required": [
          "tool",
          "arguments"
        ],
        "additionalProperties": false
      }
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    },
    "confirm": {
      "type": "boolean",
      "description": "Explicit approval of this exact native effect or private file output."
    },
    "review_sha256": {
      "type": "string",
      "pattern": "^[a-f0-9]{64}$"
    }
  },
  "required": [
    "tasks",
    "review_sha256"
  ],
  "additionalProperties": false
}

export_resources

Confirmed cursor-based JSON export into a new exclusive 0600 private file, with page/item/byte budgets and explicit continuation. No URL following, digital files or atomic backup.

Argument	Type	Required	Meaning and constraints
`operation`	string	Required	Reviewed current contract value. {"enum": ["list_products", "list_sales", "list_subscribers", "list_payouts"]}
`arguments`	object	Optional	Actual list filters/page_key, no account override.
`account`	string	Optional	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	boolean	Optional	Set true only when the user asked for exactly this action.
`start_offset`	integer	Optional	Reviewed current contract value. {"minimum": 0, "maximum": 9999}
`max_pages`	integer	Optional	Reviewed current contract value. {"minimum": 1, "maximum": 100}
`max_items`	integer	Optional	Reviewed current contract value. {"minimum": 1, "maximum": 10000}
`output_file`	string	Required	Reviewed current contract value. {"minLength": 1}

gumroad-cli export-resources --help
gumroad-cli schema export-resources

{
  "type": "object",
  "properties": {
    "operation": {
      "type": "string",
      "enum": [
        "list_products",
        "list_sales",
        "list_subscribers",
        "list_payouts"
      ]
    },
    "arguments": {
      "type": "object",
      "description": "Actual list filters/page_key, no account override."
    },
    "account": {
      "type": "string",
      "description": "Exact private profile label; never inherited credentials, ownership or scope proof."
    },
    "confirm": {
      "type": "boolean",
      "description": "Explicit approval of this exact native effect or private file output."
    },
    "start_offset": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9999
    },
    "max_pages": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "max_items": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10000
    },
    "output_file": {
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "operation",
    "output_file"
  ],
  "additionalProperties": false
}

9. Commerce and license workflows

Inspect products, sales and subscribers before changing anything

gumroad-cli list-products --agent
gumroad-cli get-product --product-id REVIEWED_PRODUCT_ID --agent
gumroad-cli list-sales --after 2026-01-01 --before 2026-10-03 --product-id REVIEWED_PRODUCT_ID --agent
gumroad-cli list-subscribers --product-id REVIEWED_PRODUCT_ID --agent
gumroad-cli schema update-product

Review refunds, shipping and access separately

gumroad-cli get-sale --sale-id REVIEWED_SALE_ID --agent
gumroad-cli refund-sale --help
gumroad-cli schema refund-sale
gumroad-cli mark-sale-as-shipped --help
gumroad-cli revoke-sale-access --help
gumroad-cli resend-sale-receipt --help

Read a license without consuming a use

gumroad-cli verify-license --product-id REVIEWED_PRODUCT_ID --agent
gumroad-cli increment-license-uses --help
gumroad-cli disable-license --help
gumroad-cli rotate-license --help

Manage variants, discounts and checkout fields

gumroad-cli list-variant-categories --product-id REVIEWED_PRODUCT_ID --agent
gumroad-cli create-variant --help
gumroad-cli create-offer-code --help
gumroad-cli list-custom-fields --product-id REVIEWED_PRODUCT_ID --agent
gumroad-cli get-custom-field --product-id REVIEWED_PRODUCT_ID --name "Phone number" --agent

Payouts, refund policy and webhooks

gumroad-cli list-payouts --agent
gumroad-cli get-refund-policy --agent
gumroad-cli list-resource-subscriptions --resource-name sale --agent
gumroad-cli create-resource-subscription --help

10. Exact reviewed batches and private exports

Review exact ordered effects locally

preview_commerce_batch accepts 1–20 ordered native effects, excluding rotated-key output. Every task has tool and arguments. Nested arguments cannot override account/confirm, supply credentials, or reference mutable output/payload files. All schemas and native semantics are checked before any network call. The returned reviewSha256 binds exact ordered requests, profile label and reviewed snapshot digest. It does not hash loaded private credentials, freeze upstream state, expire, guarantee single use or confer provider authority.

gumroad-cli preview-commerce-batch --tasks '{"tool":"disable_product","arguments":{"product_id":"REVIEWED_PRODUCT_ID"}}' --agent
gumroad-cli submit-commerce-batch --help

Each repeated --tasks flag carries one JSON task object. To execute only requested work, explicitly confirm and supply the identical review_sha256 with unchanged tasks/profile/schema. Re-review after credential rotation or provider changes. Execution prevalidates the whole batch and stops at the first failure, returning knownResults, failedIndex and unattemptedIndices. It never retries, rolls back or silently continues. Failed effects can have unknown outcomes. Inspect native state and request a deliberate follow-up only for the intended unresolved work.

Export private metadata with bounded continuation

export_resources supports list_products/list_sales/list_subscribers/list_payouts and only their actual filters. Defaults are 10 pages/1,000 items; accepted maxima are 100 pages/10,000 items with a 5 MiB final file cap. The output file is exclusively created with 0600 on POSIX before native reads; no existing file is overwritten and the final target symlink is not followed. The parent directory and Windows ACLs require separate private configuration.

gumroad-cli export-resources --help
gumroad-cli schema export-resources

The export uses fixed-host native requests and next_page_key, never next_page_url. Item caps can stop partway through a page: continuation preserves exact filters/cursor and start_offset. Resume deliberately into another new file. Missing native cursors, repeated cursors, malformed collections or changing offsets fail and remove only this export's new partial file. Customer data remains private; license/token/signed credential fields are redacted. A metadata export is not an atomic snapshot, digital-file backup or guaranteed financial reconciliation. The API can change between requests.

11. Several private profiles

gumroad-cli list-accounts --agent
gumroad-cli get-user --account intended-seller --agent
gumroad-cli verify-license --product-id REVIEWED_PRODUCT_ID --account intended-license --agent

12. Writing safely

All 32 native/local effects require explicit confirm. GUMROAD_READ_ONLY=1 hides them and directly refuses hidden confirmed calls through the actual server handler. GUMROAD_ALLOW_DESTRUCTIVE=0 refuses them even with confirm. --agent and --yes affect output/prompt formatting only, never approval. The same guard protects CLI and MCP, including counter changes, receipts, product publication, refunds and private export file writes.

Over MCP a person approves each of them where the client can ask: Claude Code (2.1.246 and later) shows its own prompt, and a client that can show forms asks with an approval form whose one box starts unticked. Each approval is signed, bound to that exact call and works once. Where a client can do neither, the model's confirm:true counts. GUMROAD_CONFIRM=model makes confirm:true enough everywhere, for an agent with no person to ask.

Native authorization remains with Gumroad. A local profile, filter, confirmation or request-review hash does not prove seller ownership, customer consent, entitlement or financial correctness. No automatic retry, redirects or guessed continuation is allowed. A failure after a write can mean an unknown outcome; investigate before deliberately repeating. Default pacing is 1,000ms/request with 30,000ms timeout, 1 MiB request and 5 MiB response caps. Other processes share provider quotas; this is conservative local pacing, not a global rate-limit guarantee.

13. How the two surfaces work

src/tools/index.ts exports one shared array. The native reviewed operations.json and provenance.json define the selected typed field subset. Slipway builds the MCP server, over stdio or --http, and the CLI from it; both use identical validation, profiles, native compiler and write guard. This is not an official OpenAPI export. No generic request passthrough or arbitrary host is exposed.

14. Your data

Known configured credentials, license_key fields, signed credential URLs and sensitive download/content fields are redacted from ordinary output/errors. Other customer/sale/subscriber/payout fields remain private data and are not anonymized. Do not paste them into public issues, screenshots or unrelated agent context. Raw rotated-license receipts are intentionally saved only in a requested new owner-private file.

The package has no telemetry, browser-cookie import, arbitrary host or digital-file download. Returned HTML, customer text and URLs are untrusted data. Optional best-effort audit logs record static guard decisions, not credentials/arguments, and are not verified settlement ledgers. Removing the package does not revoke credentials, refund a payment, restore a deleted product, cancel webhooks or delete private exports.

15. Environment variables

Variable	Purpose
GUMROAD_ACCESS_TOKEN	Private seller Bearer token; choose this OR TOKEN_FILE
GUMROAD_TOKEN_FILE	Absolute owner-private seller token-only file
GUMROAD_LICENSE_KEY	Independent private customer license; choose this OR LICENSE_FILE
GUMROAD_LICENSE_FILE	Absolute owner-private license-only file
GUMROAD_ACCOUNTS	Private named array: name, access_token/token_file, license_key/license_file; no fallback
GUMROAD_DEFAULT_ACCOUNT	Exact configured default profile label
GUMROAD_READ_ONLY	1/true hides/directly refuses 32 effects
GUMROAD_ALLOW_DESTRUCTIVE	0/false refuses effects even with confirm
GUMROAD_AUDIT_LOG	Optional private best-effort static guard decisions
GUMROAD_REQUEST_TIMEOUT_MS	Default 30000; accepted 100–300000 milliseconds
GUMROAD_MIN_REQUEST_INTERVAL_MS	Default 1000; accepted 0–10000 milliseconds; not distributed quota enforcement
GUMROAD_CONFIRM	human by default; model lets confirm:true alone approve over MCP, for an agent with no person to ask
GUMROAD_SURFACE	full by default; search lists three tools that find, describe and run the rest
GUMROAD_TOOL_TIMEOUT_MS	Give up on any tool after this long
GUMROAD_HTTP_PORT, GUMROAD_HTTP_HOST, GUMROAD_HTTP_TOKEN	For --http: port 8787 and host 127.0.0.1 by default; any other host needs the bearer token
GUMROAD_HTTP_ALLOWED_ORIGINS	Comma-separated browser origins allowed to call --http; a page from any other site is refused
GUMROAD_DEBUG	1 prints debug lines on stderr

16. Updates and removal

Restart npx@latest to resolve updates; update global installs with npm install -g @thenavidm/gumroad-mcp-cli@latest. Reconnect clients after changes. Download/install the new desktop archive manually. Remove only the requested package/client registration/skill/extension. Revoke intended provider credentials separately; uninstall does not undo effects or private files.

npm install -g @thenavidm/gumroad-mcp-cli@latest
gumroad-cli --version
# Only when removal is requested
npm uninstall -g @thenavidm/gumroad-mcp-cli

17. Troubleshooting

Symptom	What to check
Missing package/Node	Node 22+ and runtime PATH; Windows may need npm.cmd
Exit 10/no credentials	Intended credential type/profile/private file; login prints setup only
401/403	Seller credential expiry/revocation and correct native scope; admin token is separate
License verify failed	Current product_id, intended private license and native purchase/refund/revocation/subscription context
Use counter changed	Use verify-license for explicit false; increment-license-uses is a separate confirmed effect
Unreadable file	Absolute regular non-symlink owner-private token-only path, <=64 KiB; restrict Windows ACLs
Unknown URL/preview field	Use current flat selected schema; legacy guessed fields are rejected
Custom field GET 404	Use compatibility get-custom-field or native list; no guessed single GET route
Refund refused	Positive amount_cents OR full_refund=true, never both; actual listed currency/units; confirm
Missing write	READ_ONLY hides effects and direct calls still refuse; ALLOW_DESTRUCTIVE can disable
Webhook creation failed	Current PUT/event/HTTPS callback and provider scopes; no delivery guarantee
Review mismatch	Preview identical requests/order/profile/schema; re-review after changes
Batch failure	Known/unattempted indices; no rollback/retry; inspect unknown outcome
Incomplete export	Budget/cursor/start_offset; resume deliberately in a NEW private file
Output exists	Choose a new file; never overwrite another private receipt
429/timeout	No automatic retry; inspect provider state and current limits
Desktop install	Host/organization support, Node 22+, manual update; bundle discovery is not GUI proof

18. API coverage and comparisons

Official tooling already covers CLI and MCP

Gumroad's official CLI and local gumroad mcp exist, as does the hosted OAuth MCP advertised through Gumroad discovery. Our comparison pins official release 2026.10.02 and source 7c202ea43c47b66b46e633b4e2c8d69376372ff2. The actual checksum-verified release exposes 105 local tools; this is protocol discovery, not 105 individually completed provider tasks. Hosted anonymous discovery was verified separately; authenticated account discovery/financial outcomes were not tested.

Official CLI strengths include device/browser OAuth, JSON/jq/plain output, native pagination, sales summaries, currency-aware refunds, dry-run previews and explicit CLI confirmations. Marketing workflows already use reviewed confirmation tokens. The pinned local MCP source auto-approves most other CLI confirmations and delegates action approval to its client. That observation does not prove hosted clients lack human consent or that our wrapper is universally safer.

Community alternatives

Printing Press Library's Gumroad implementation, declared 2026.9.1, already offers dedicated CLI/local MCP/desktop packaging, SQLite sync/search/analytics, monitoring, output selection and dry-run behavior. Its source declares 52 native tools. The reviewed --agent implies --yes and its license handler omits false on the wire despite defaulting its increment setting to false; native omission increments. These are pinned source observations, not authenticated competitor tests. No runtime/financial superiority is claimed.

rmarescu/gumroad-mcp declares 11 tools in reviewed source. Its runtime is not verified here. Generic MCP-to-terminal clients remain legitimate alternatives; a dedicated task binary alone is not proof that ours is better.

Why build this companion

Use ours when consistent mandatory per-call guards across CLI/MCP, isolated private seller/license profiles, explicitly non-incrementing verification, exact locally reviewed effects and bounded private exports fit your work. Use official tools for their broader CLI/OAuth/native feature coverage or community tooling for its SQLite/analytics/monitoring capabilities. This is a selected commerce companion, not full parity with the official 105 tools or all 81 documented native endpoints. It does not implement admin, marketing, media, file-upload, hosted OAuth or custom storefront HTML actions.

Capability	Our companion	Existing alternatives
Surfaces	Shared task CLI/local MCP/desktop bundle	Official CLI/local MCP/hosted OAuth MCP already exist
Native scope	51 reviewed native tool contracts/50 distinct routes, plus 6 compatibility/local helpers	Official local MCP 105 discovered tools; broader scopes differ
Approval	32 effects require explicit per-call confirmation and direct read-only enforcement	Official CLI confirmations/marketing review tokens; local MCP delegates most approvals to client
Private accounts	Named isolated seller/license credentials, no fallback	Official OAuth and community credentials already exist
License reads	Explicit false transmitted; increment is separate confirmed effect	Compare the actual on-wire behavior, not just a default flag
Review	Ordered requests/profile label/snapshot hash, stop first failure	No transaction, credential/state lock, expiry or single use
Export	Cursor/page/item/byte budgets; private file and resume offset	Official pagination and community SQLite sync already exist
Token costs	Equivalent completed Codex tasks unmeasured	No schema-count, character estimate or borrowed benchmark

19. Versions and migration

Component	Version and evidence
Package and desktop	3.0.0; public installation verified in release evidence
Native API	v2; selected 51 tool contracts/50 distinct routes checked 2026-10-03
Official CLI/local MCP	2026.10.02;105 actual discovered tools
Official app source	0feb9b02b45efffc4ea4c7f8dea5c18a7f58ec0f
Printing Press	Declared 2026.9.1; pinned source only
Slipway	0.1.20
MCP TypeScript SDK, through Slipway	2.3.0
Node	>=22
Private legacy	1.0.0;34 names preserved, current major arguments apply
Matched Codex usage	Measured against 2.0.1 in README section 7

Legacy behavior	Contract since 2.0.0
One MCP binary/startup global token	Scoped package, both binaries, credential-free discovery
Tokens in query URL	Private Bearer seller auth
product_permalink/license_key in arguments	Current product_id plus private license settings
Verification omission increments	verify_license explicitly sends false; separate confirmed increment
Guessed custom-field GET	Documented list plus exact matching compatibility helper
POST resource subscription	Current native PUT, required resource_name and HTTPS post_url
Legacy guessed product url/preview	Selected current custom_permalink and native field subset
No common effect confirmation	All 32 native/local effects confirmed and read-only enforced
Unbounded subscribers	Native paginated=true
No review/export controls	Exact ordered review and bounded private cursor continuation
Private source history	Intact private history retained; sanitized new public snapshot

See CHANGELOG.md. No old private refs or credentials are published.

20. FAQ

It provides 57 shared commerce tasks through a local stdio MCP, dedicated task CLI and desktop bundle. Current selected product/sale/subscriber/payout/license/webhook work uses the same contracts and approval policy across both interfaces.

Yes. Official CLI/local MCP release 2026.10.02 exposes 105 tools in actual protocol discovery, and hosted OAuth MCP exists. Official pagination, summaries, OAuth, previews and marketing confirmations remain useful; this companion targets specific private-profile and effect-policy workflows.

57 shared tools include 25 reads/helpers and 32 confirmed effects. There are 51 native tool contracts covering 50 distinct routes, plus six compatibility/local helpers. READ_ONLY exposes 25; counts alone do not compare native capability depth.

Use the intended Gumroad seller advanced/application settings or application OAuth. Store seller credentials privately in ACCESS_TOKEN or TOKEN_FILE, never public repositories or tool arguments. Current requests use Bearer headers and endpoint-specific scopes.

No. Configure the customer license privately and pass the current product_id. verify_license sends no seller authorization and explicitly sends increment_uses_count=false. License management effects require seller authority too; increment verification is its own confirmed command.

No. Its shared handler explicitly transmits false instead of omitting the native parameter. increment_license_uses deliberately transmits true and requires confirmation. This behavior is verified with request fixtures, not a live customer-license test.

Use named private ACCOUNTS profiles, unique labels and explicit credential sources. DEFAULT_ACCOUNT or --account chooses one. Named profiles never inherit global/other-profile credentials; missing selected credentials fail before sending the request.

No. Native tokens/scopes and seller/license ownership govern provider authority. A label or product_id filter is selection, not an account security boundary or entitlement proof. Review exact intended records and least privilege.

No. Both use the same tool definitions, JSON schemas, native compiler, private profiles and write guard. Slipway builds both from each tool's one definition, so supported arguments and guards remain aligned.

Explicitly confirm only the requested native/local action. --agent and --yes never grant approval. READ_ONLY or ALLOW_DESTRUCTIVE=0 refuses effects even with confirmation; approval does not prove consent, amount correctness or authority.

Partial refunds use positive integer amount_cents in the sale listed currency minor units; JPY uses whole yen. A full refund requires explicit full_refund=true with no amount. Omission alone and mixed intent are refused. No currency conversion or independent settlement proof is supplied.

The selected native create/update/enable/disable commands can change products only with confirmation. Current selected fields include custom_permalink and tags, not guessed legacy URL fields or file/rich-content editing. Inspect returned published/warning state; HTTP success is not proof of full publication.

Current native API has no single-custom-field GET route. The compatibility helper makes one documented list_custom_fields request and matches the exact name, returning not found when absent. Update/delete use the existing field name as an encoded path segment.

rotate_license reserves a new absolute private output_file before the effect, then saves the complete native receipt there. Chat/stdout receives only file metadata. The old license becomes invalid; no retry or rollback is promised after an uncertain response.

It binds exact ordered native requests, selected profile label and snapshot digest. It does not bind loaded credentials, lock provider state, expire, guarantee single use or provide financial approval. Re-review after credential/upstream changes; execution stops first failure.

Exports are bounded private metadata with native cursor and partial-page offset receipts. They never follow returned URLs or download digital files, and are not atomic backups or independent accounting reconciliation. Sensitive key/signed fields are redacted; other customer data stays private.

No automatic retry is performed, including429, timeout or unknown effect outcomes. Default pacing is 1,000 milliseconds per request with a 30-second timeout. Inspect native state and known/unattempted results before deliberately repeating requested work.

Codex is prioritized; setup also covers Claude Code, Claude Desktop, Cursor, VS Code/Copilot, Windsurf, Zed, Gemini CLI, Docker and compatible local stdio clients on their supported macOS/Windows/Linux runtimes. Remote-only clients need a remote connector. Desktop GUI acceptance is separate from bundle discovery.

In Claude Code the CLI costs nothing until it is used, plus about 4,500 tokens for SKILL.md once, where the server costs about 1,140 tokens a message with tool search and 22,100 with every tool loaded. In Codex, finding the command that refunds a sale and its flags took a median of 82,764 input tokens over the CLI and 76,542 over MCP. Section 7 has how each was measured.

Restart npx@latest, update global CLI packages and manually install the latest desktop bundle. Remove only requested registrations/skills/packages; revoke credentials separately. Uninstall cannot undo effects or delete exports. Report reproducible secret-free issues; sensitive reports use private security reporting.

Questions

Open a secret-free issue. Read SECURITY.md and CONTRIBUTING.md.

About the author

Navid Moazzez is a leading AI business strategist, and the host of the AI Creator Summit, watched by 100,000+ creators. He helps creators and founders master AI and build their own AI Operating System (AI OS) to automate their business and life. He creates useful free tools, MCP servers and CLIs that creators and founders can use in their own workflows.

Links

Personal website: navid.me
Link in bio: navid.bio
Navid Media: navid.media
YouTube: @thenavidm and @thenavidai
X: @thenavidm
Instagram: @thenavidm
LinkedIn: thenavidm

If this is useful, star the repo and come say hi on X.

Dependencies

Library	License	Purpose
Slipway	Apache-2.0	The MCP server and the CLI from one definition of each tool
MCP TypeScript SDK	Apache-2.0	The MCP protocol and its transports, through Slipway
Ajv	MIT	Typed input contracts
ajv-formats	MIT	Native date/URI/email validation

Pinned official documentation/controller source informs selected contracts; it is not an extra runtime SDK. See THIRD_PARTY_NOTICES.md.

License

AGPL-3.0, preserving the existing project license. Not affiliated with or endorsed by Gumroad.

Available Tools

57 tools

create_custom_fieldCreate custom fieldA

Destructive

Create custom field. Reviewed native POST /products/:product_id/custom_fields; scope: edit_products. Requires explicit per-call confirmation.

ParametersJSON Schema

Name	Required	Description
`name`	Yes
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`required`	Yes	(true or false)
`product_id`	Yes	Exact opaque provider ID, including native = padding.

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, readOnlyHint=false, and non-idempotent, so the mutation profile is known. The description adds the required scope (edit_products) and the per-call confirmation requirement, which go beyond the annotations. It does not state side effects on existing fields or what gets returned.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three brief clauses, front-loaded with the action, then scope, then the critical confirmation requirement. No filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers the action, the underlying API, the required scope, and confirmation, which is solid for a mutation without an output schema. However, with destructiveHint=true and no output schema, it doesn't explain reversibility, effect on existing products, or the shape of the created field.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 80%, so the schema largely documents parameters including the confirm flag's meaning. The description mentions per-call confirmation but adds no new semantics for the 5 parameters beyond what the schema provides. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clear verb+resource ('Create custom field') and the description adds the native API endpoint (POST /products/:product_id/custom_fields) which confirms scope. Siblings like update_custom_field and delete_custom_field are distinguishable by the verb, though no sibling is named explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implicit usage only – 'Requires explicit per-call confirmation' hints at when confirmation is needed, but there is no explicit when-to-use vs alternatives guidance (e.g., vs update_custom_field). The scopes hint narrows applicability but doesn't state exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_offer_codeCreate offer codeA

Destructive

Create offer code. Reviewed native POST /products/:product_id/offer_codes; scope: edit_products. Requires explicit per-call confirmation.

ParametersJSON Schema

Name	Required	Description
`name`	Yes	(the coupon code used at checkout)
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`universal`	No	(optional, true or false) Default: false
`amount_off`	Yes
`offer_type`	No	(optional, "cents" or "percent") Default: "cents"
`product_id`	Yes	Exact opaque provider ID, including native = padding.
`max_purchase_count`	No	(optional)
`minimum_amount_cents`	No	(optional) Minimum order total in cents required for the offer code to apply

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, non-idempotent, and open-world, so the safety profile is covered. The description adds value beyond them by disclosing the required OAuth/API scope (edit_products) and the mandatory per-call confirmation, both of which materially affect whether and how the agent should call it.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three terse clauses with no padding, and the core action is front-loaded. The telegraphic style ('Reviewed native POST...; scope: edit_products') is efficient, though slightly clipped for readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive create tool with full annotation coverage, 89% schema coverage and no output schema, the definition supplies the missing key facts: the underlying endpoint, the required scope, and the confirmation requirement. Return-value behavior is not described, but no output schema exists to lean on and this is a minor gap for a create operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is high (89%), so the schema already documents name, account, confirm, offer_type and others. The description only reinforces the confirm parameter ('explicit per-call confirmation') and adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear verb+resource ('Create offer code') and backs it with the native endpoint (POST /products/:product_id/offer_codes), so it is unambiguously the creation tool among siblings like update_offer_code and delete_offer_code. It does not, however, explicitly contrast itself with those siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Requires explicit per-call confirmation' gives a concrete precondition for invoking the tool, and the stated scope (edit_products) tells the agent what authorization is needed. It never states when to prefer this tool over alternatives or when not to use it, leaving usage largely implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_productCreate productB

Destructive

Create product. Reviewed native POST /products; scope: edit_products. Requires explicit per-call confirmation.

ParametersJSON Schema

Name	Required	Description
`name`	Yes	(required)
`tags`	No	(optional) array of tag strings
`draft`	No	(optional, true or false, default false) save as an unpublished draft instead of publishing
`price`	Yes	(required) in the smallest currency unit (e.g. cents)
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`category`	No	(optional) full category path from GET /v2/categories, e.g. "design/ui-and-web/figma"; cannot be sent with taxonomy_id
`published`	No	(optional, true or false, default true) false saves as an unpublished draft, same as draft=true
`description`	No	(optional) HTML
`native_type`	No	(optional, "digital" (default), "course", "ebook", "membership", "bundle", "coffee", "call", or "commission") cannot be changed later
`taxonomy_id`	No	(optional) numeric category ID; alias for category, cannot be sent with category
`refund_period`	No	(optional, "inherit", "none", "7", "14", "30", or "183") sets a product-level refund policy; "inherit" uses the account default. Only available when the account-level refund policy is not in effect; otherwise use PUT /v2/refund_policy
`custom_summary`	No	(optional)
`custom_permalink`	No	(optional)
`refund_fine_print`	No	(optional) fine print for the product-level refund policy; requires refund_period unless the product already has one enabled, and cannot be combined with refund_period "inherit". Empty string clears it
`customizable_price`	No	(optional, true or false) pay-what-you-want
`max_purchase_count`	No	(optional)
`price_currency_type`	No	(optional) ISO currency code; defaults to your account currency
`subscription_duration`	No	(optional, membership only, "monthly", "quarterly", "biannually", "yearly", or "every_two_years")
`suggested_price_cents`	No	(optional)

TDQS

B3.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover safety (readOnlyHint=false, destructiveHint=true, idempotentHint=false, openWorldHint=true), so the bar is lower. The description still adds value by disclosing the required OAuth scope (edit_products) and the mandatory per-call confirmation requirement, which the annotations do not convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three terse clauses, front-loaded with the action, and nothing wasted. "Reviewed native POST /products" is slightly cryptic but still informative rather than filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 20-parameter creation tool with no output schema, the description is thin, though the annotations plus fully documented schema compensate heavily. It conveys scope and confirmation but says nothing about return behavior or side effects like product creation limits, leaving an agent to infer the rest.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% with rich inline constraints (mutual exclusions, enums, defaults), so the schema carries the parameter burden. The description adds no parameter detail at all, making the baseline 3 correct.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

"Create product" is essentially a restatement of the tool name/title, so the core purpose is tautological. The added "native POST /products; scope: edit_products" pins the underlying endpoint and required scope, which is useful, but there is no differentiation from sibling creators like create_variant or create_offer_code.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

"Requires explicit per-call confirmation" gives a real usage rule (only invoke when the user asked for exactly this action), which is more than nothing. However, no alternatives are named and no when-not conditions are given beyond the confirmation gate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_resource_subscriptionCreate resource subscriptionA

Destructive

Create resource subscription. Reviewed native PUT /resource_subscriptions; scope: view_sales for sale event; provider authorization for other events. Requires explicit per-call confirmation.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`post_url`	Yes	Intended HTTPS callback; provider posts private customer events.
`resource_name`	Yes	Exact native event to subscribe to.

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already flag destructiveHint=true, openWorldHint=true, and idempotentHint=false, but the description adds real value: it names the underlying reviewed endpoint and states the authorization scope (view_sales for sale, provider authorization for other events) plus the per-call confirmation requirement. It stops short of describing post_url validation or what happens on re-subscription.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short declarative sentences, front-loaded with the operation and followed by scope and confirmation constraints. Slightly telegraphic, but nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, open-world mutation with no output schema, the description supplies endpoint identity, authorization scope, and the confirmation contract. Given 100% schema coverage, the remaining gaps (failure modes, idempotency on repeat calls) are minor.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3: the schema already documents resource_name as the exact native event, post_url as the HTTPS callback, account as a private profile label, and confirm as the confirmation flag. The description's scope note ('view_sales for sale event') loosely complements the enum but adds no per-parameter syntax beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Create resource subscription') and clarifies it maps to the reviewed native PUT /resource_subscriptions endpoint. It is distinguishable from list_resource_subscriptions and delete_resource_subscription by the 'Create' verb, though it does not explicitly contrast itself with those siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides important preconditions ('Requires explicit per-call confirmation', scope needs), which implies when the call is legitimate, but never names alternatives or says when to prefer this over the list/delete siblings. Usage context is implied rather than spelled out.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_variantCreate variantA

Destructive

Create variant. Reviewed native POST /products/:product_id/variant_categories/:variant_category_id/variants; scope: edit_products. Requires explicit per-call confirmation.

ParametersJSON Schema

Name	Required	Description
`name`	Yes
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`product_id`	Yes	Exact opaque provider ID, including native = padding.
`max_purchase_count`	No	(optional)
`variant_category_id`	Yes	Exact opaque provider ID, including native = padding.
`price_difference_cents`	Yes

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds genuine value beyond them: the required edit_products scope and the explicit per-call confirmation requirement, both of which are operational constraints an agent cannot infer from the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two terse sentences with the action, endpoint, scope, and confirmation requirement front-loaded; no filler. It is telegraphic but every clause carries weight.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive mutation with no output schema, the description covers the endpoint, auth scope, and the confirmation gate, and the annotations cover reversibility. Return-value behavior is unspecified, but that is the only notable gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 71% and the description contributes nothing about the seven parameters (product_id, variant_category_id, name, price_difference_cents, confirm, account, max_purchase_count). With most parameters already documented in the schema, the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource (create a product variant) and pins the exact native endpoint, which separates it from create_variant_category and create_product. It does not explicitly name those siblings, but the resource path makes the distinction unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description states the required OAuth scope (edit_products) and that explicit per-call confirmation is mandatory, which is useful context for deciding to call it. However, it never states when to prefer this over update_variant or create_variant_category, nor any preconditions beyond the confirmation flag.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_variant_categoryCreate variant categoryA

Destructive

Create variant category. Reviewed native POST /products/:product_id/variant_categories; scope: edit_products. Requires explicit per-call confirmation.

ParametersJSON Schema

Name	Required	Description
`title`	Yes
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`product_id`	Yes	Exact opaque provider ID, including native = padding.

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true. The description goes beyond them by disclosing the auth scope (edit_products) and a non-obvious per-call confirmation gate, both of which the agent would otherwise not know.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, front-loaded with the action, then endpoint/scope, then the confirmation constraint. Efficient, though the opening sentence restates the title with little added information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with no output schema and annotations that already cover the safety profile, the description supplies the key missing pieces: auth scope, the underlying API route, and the confirmation requirement. It stops short of explaining what a variant category is or what the response returns.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 75% and the description names no parameters directly, so the schema does the heavy lifting. The 'explicit per-call confirmation' sentence loosely reinforces the confirm parameter, but no syntax, ID format, or account semantics are added beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb+resource ('Create variant category') and grounds it in the concrete API operation ('native POST /products/:product_id/variant_categories'), which distinguishes it from update_variant_category and delete_variant_category. It does not explicitly name those siblings, but the create semantics are unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides the required scope (edit_products) and a per-call confirmation requirement, which are useful preconditions. However, it never states when to choose this over update_variant_category or create_variant, so the routing guidance is implied rather than explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

decrement_license_usesDecrement license usesA

Destructive

Decrement license uses. Reviewed native PUT /licenses/decrement_uses_count; scope: edit_products. Requires explicit per-call confirmation.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`product_id`	Yes	(the unique ID of the product — copy it from the license key block on the product's Content tab, or use the id field returned by the GET /products endpoint)

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already disclose destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds real value beyond that: the required edit_products scope and the mandatory per-call confirmation requirement, both of which affect whether an agent can invoke it.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two terse sentences, front-loaded with the action, followed by endpoint and scope. No filler; every clause carries operational meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, non-idempotent mutation with full schema coverage, no output schema, and annotations covering the safety profile, the description supplies the key extras (scope, confirmation requirement). It is nearly complete, with only the increment/decrement routing left implicit.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the schema already documents account, confirm, and product_id thoroughly (including where to copy the product_id from). The description adds no parameter-level detail, so the baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Decrement license uses') naming the exact operation, plus the backing endpoint PUT /licenses/decrement_uses_count. It is clearly distinguishable from increment_license_uses by name, though it does not explicitly reference that sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The required scope 'edit_products' and the 'requires explicit per-call confirmation' clause give useful preconditions, but there is no explicit when-to-use guidance or routing versus the obvious alternative increment_license_uses.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

delete_custom_fieldDelete custom fieldA

Destructive

Delete custom field. Reviewed native DELETE /products/:product_id/custom_fields/:name; scope: edit_products. Requires explicit per-call confirmation.

ParametersJSON Schema

Name	Required	Description
`name`	Yes	Exact existing field name; encoded as one URL segment.
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`product_id`	Yes	Exact opaque provider ID, including native = padding.

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false. The description adds value beyond those: the native endpoint, the edit_products scope requirement, and the explicit per-call confirmation gate. It still doesn't say what deletion destroys (field values on existing products) or whether it's recoverable, keeping it below 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, action and resource front-loaded, followed by endpoint, scope, and the confirmation requirement. No filler text; every clause carries information an agent can act on.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, non-idempotent tool with no output schema, the description supplies the endpoint, authorization scope, and a confirmation gate, and annotations cover the safety profile. It is largely complete, though it omits any statement of irreversibility or post-delete effect on existing product data.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all four parameters (name, account, confirm, product_id) are already documented in the schema with formats and constraints. The description only echoes product_id and name via the endpoint path, adding no new parameter meaning; baseline 3 applies when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Delete custom field') and reinforces it with the exact native endpoint DELETE /products/:product_id/custom_fields/:name, which distinguishes it from create_custom_field, update_custom_field, get_custom_field and list_custom_fields. It does not name siblings explicitly, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides real usage constraints: the required OAuth scope (edit_products) and the requirement for explicit per-call confirmation. It never names alternatives or states when *not* to call it (e.g., use update_custom_field to modify instead), so usage is implied rather than fully guided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

delete_offer_codeDelete offer codeA

Destructive

Delete offer code. Reviewed native DELETE /products/:product_id/offer_codes/:id; scope: edit_products. Requires explicit per-call confirmation.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`product_id`	Yes	Exact opaque provider ID, including native = padding.
`offer_code_id`	Yes	Exact opaque provider ID, including native = padding.

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, readOnlyHint=false, and non-idempotent, so the safety profile is covered. The description adds real value beyond that: the required OAuth scope (edit_products), the underlying native endpoint, and the mandatory per-call confirmation requirement, which is not derivable from annotations or schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with the action front-loaded and no filler. The scope and confirmation constraint are packed into a single clause; nothing is redundant, though the phrasing is slightly telegraphic.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, non-idempotent tool with no output schema, the definition covers the essential operational facts: required scope, confirmation gate, and target endpoint. It does not describe side effects (e.g., whether the code can be restored) but annotations already flag the destruction.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with each parameter (account, confirm, product_id, offer_code_id) already documented in the schema. The description adds no syntax or format detail about the IDs or the confirm flag, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Delete) and resource (offer code), which is unambiguous against siblings like delete_product, delete_variant, and delete_custom_field. It does not explicitly name a sibling, but the resource noun alone is sufficient to disambiguate.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a prerequisite ('Requires explicit per-call confirmation') and the required scope ('edit_products'), which implies when the call is permitted. However, it offers no guidance on when to delete versus disable or update an offer code, nor any exclusions, so the usage context is only partially covered.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

delete_productDelete productA

Destructive

Delete product. Reviewed native DELETE /products/:id; scope: edit_products. Requires explicit per-call confirmation.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`product_id`	Yes	Exact opaque provider ID, including native = padding.

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the safety profile is covered structurally. The description adds genuinely non-redundant context: the underlying native endpoint (DELETE /products/:id), the required OAuth scope (edit_products), and a mandatory per-call confirmation step. It stops short of saying whether deletion is reversible or what happens to dependent licenses/sales.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three compact clauses, front-loaded with the action, then scope, then precondition. No filler. It could be marginally tighter but nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-required-param destructive tool with full schema coverage, complete annotations, and no output schema, the description supplies the two things structure cannot: the auth scope and the confirmation requirement. The missing piece is reversibility/soft-delete contrast with disable_product.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all three parameters (account, confirm, product_id) are already documented in the schema, including the confirm semantics and the opaque ID format. The description adds no parameter-level detail beyond that, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Delete product') that an agent can act on immediately. It does not, however, distinguish itself from the sibling disable_product, which is the natural ambiguity for a destructive-vs-soft-delete pair.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Requires explicit per-call confirmation' is real usage guidance about a precondition, but the description never says when to choose this over disable_product or enable_product. The most consequential routing decision for this tool family is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

delete_resource_subscriptionDelete resource subscriptionA

Destructive

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`resource_subscription_id`	Yes	Exact opaque provider ID, including native = padding.

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description still adds real value beyond that: the authorization scope needed and the explicit per-call confirmation requirement, which an agent must honor before invoking.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the action, then clauses on scope and confirmation. No filler or repetition; every sentence carries an operative constraint, though the endpoint and scope phrasing is slightly dense.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, non-idempotent, open-world delete with no output schema, the description supplies the key auth scope and confirmation requirements. It is adequate, though it says nothing about return behavior or failure modes.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all three parameters are already documented in the schema, making 3 the baseline. The description only touches on the confirmation requirement generically and adds no format or syntax detail beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Delete resource subscription") and even cites the underlying native DELETE endpoint, so an agent knows exactly what this does. It doesn't explicitly distinguish itself from sibling delete tools like delete_product or delete_variant, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It notes the required scope (view_sales for sale events, provider authorization otherwise) and a per-call confirmation requirement, which are useful preconditions. But it never says when to choose this over an alternative or when not to use it, leaving usage only implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

delete_variantDelete variantA

Destructive

Delete variant. Reviewed native DELETE /products/:product_id/variant_categories/:variant_category_id/variants/:id; scope: edit_products. Requires explicit per-call confirmation.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`product_id`	Yes	Exact opaque provider ID, including native = padding.
`variant_id`	Yes	Exact opaque provider ID, including native = padding.
`variant_category_id`	Yes	Exact opaque provider ID, including native = padding.

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, so the destructive nature is known. The description adds real context beyond annotations: the required OAuth scope (edit_products) and the per-call confirmation requirement, which matter given the non-idempotent destructive hint.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, front-loaded with the core action and then the operational constraints. Slightly terse but every sentence carries weight; no padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers action, scope, and confirmation for a destructive mutation tool with no output schema. It leaves out what happens to dependent variants/categories on delete and whether the operation is reversible, which would matter given idempotentHint=false.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so parameter meaning (opaque IDs, confirm, account) is already fully documented. The description adds nothing on parameters beyond the endpoint path, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (delete) and resource (variant) and even names the underlying native endpoint, so an agent can distinguish it from delete_variant_category, delete_product, and update_variant without ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Specifies the required scope (edit_products) and the confirmation requirement, which effectively route agents away from calling it casually. However, it doesn't explicitly reference sibling alternatives like delete_variant_category or explain when to prefer a disable over a delete.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

delete_variant_categoryDelete variant categoryA

Destructive

Delete variant category. Reviewed native DELETE /products/:product_id/variant_categories/:id; scope: edit_products. Requires explicit per-call confirmation.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`product_id`	Yes	Exact opaque provider ID, including native = padding.
`variant_category_id`	Yes	Exact opaque provider ID, including native = padding.

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: the authorization scope (edit_products) and a mandatory per-call confirmation gate, which an agent needs in order to invoke correctly.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences, front-loaded with the action, then endpoint, scope and confirmation requirement. No filler, though the 'Reviewed native ...' phrasing is slightly telegraphic rather than purely functional.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, non-idempotent mutation with no output schema, the description supplies the endpoint, required scope and the confirmation gate, and annotations supply the destructive/idempotency profile. It is essentially complete, missing only an explicit statement of irreversibility or error behavior, which is minor.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3, and the description adds meaning beyond it by explaining that 'confirm' is a per-call explicit confirmation gate rather than an ordinary boolean, matching the schema's 'Set true only when the user asked for exactly this action'. It does not add anything for product_id/variant_category_id, but the schema already documents those opaque IDs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource (delete a variant category) and pins it to the native endpoint DELETE /products/:product_id/variant_categories/:id, which clearly separates it from delete_variant, delete_product and the other delete_* siblings. An agent can identify the target entity without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Adds a real prerequisite — 'Requires explicit per-call confirmation' — and names the required scope (edit_products). However it never states when to choose this over alternatives (e.g. update_variant_category, disable/delete at a different level), so usage is implied rather than guided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

disable_licenseDisable licenseA

Destructive

Disable license. Reviewed native PUT /licenses/disable; scope: edit_products. Requires explicit per-call confirmation.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`product_id`	Yes	(the unique ID of the product — copy it from the license key block on the product's Content tab, or use the id field returned by the GET /products endpoint)

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds genuinely new context beyond the annotations: the underlying native PUT endpoint and the required 'edit_products' scope, plus the per-call confirmation requirement.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short clauses, front-loaded with the action, then endpoint/scope, then the confirmation constraint. No wasted words, though it is telegraphic rather than explanatory.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive mutation with no output schema, the description covers auth scope and the confirmation prerequisite, which is what an agent needs before invoking. It stops short of describing the effect on already-issued license keys, which is the main remaining gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so account, confirm, and product_id are already fully documented in the schema. The description's mention of per-call confirmation lightly reinforces the confirm parameter but adds no syntax or format detail beyond the schema baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Disable license') that clearly separates it from siblings like enable_license, rotate_license, and disable_product. It does not explicitly name those siblings, but the action is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The line 'Requires explicit per-call confirmation' implies usage context and ties to the confirm parameter, but there is no guidance on when to disable vs. rotate or revoke, nor any named alternative among the many license-related siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

disable_productDisable productA

Destructive

Disable product. Reviewed native PUT /products/:id/disable; scope: edit_products. Requires explicit per-call confirmation.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`product_id`	Yes	Exact opaque provider ID, including native = padding.

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely non-schema information: the underlying native PUT endpoint and the required edit_products scope, which an agent needs for authorization planning.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short clauses, action stated first, followed by scope and confirmation requirement. No filler, though the phrasing is terse enough that it reads more like metadata than guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema needed and annotations covering the destructive/non-idempotent profile, the description supplies the missing operational facts: required scope and explicit confirmation. Only the interaction with sibling operations (enable/delete) is left unaddressed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents account, confirm, and product_id in detail. The description's mention of per-call confirmation loosely maps to the confirm parameter but adds no format or syntax detail beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (disable product), which an agent can distinguish from enable_product and delete_product by name alone. It does not explicitly differentiate itself from those close siblings, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives the precondition (scope: edit_products) and a per-call confirmation requirement, which is useful context. But it never says when to prefer this over delete_product or what happens if the product is already disabled, so the routing guidance is implied rather than explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

enable_licenseEnable licenseA

Destructive

Enable license. Reviewed native PUT /licenses/enable; scope: edit_products. Requires explicit per-call confirmation.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`product_id`	Yes	(the unique ID of the product — copy it from the license key block on the product's Content tab, or use the id field returned by the GET /products endpoint)

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already flag destructiveHint=true, idempotentHint=false, and openWorldHint=true. The description adds concrete value beyond annotations: the scope requirement (edit_products) and the explicit per-call confirmation requirement. It does not contradict annotations (it is a mutation, matching readOnlyHint=false). Missing details on what exactly gets enabled or side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short clauses, front-loaded with the action, then scope, then constraint. No filler sentences; every phrase (endpoint, scope, confirmation) carries operational weight.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers the key agent needs: what it does, required scope, and the confirmation gate. No output schema exists, but a simple enable action likely returns a status that the agent can infer. Minor gap: no explicit statement of state change effect or error conditions.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all three parameters thoroughly (including copying product_id from the Content tab). The description adds nothing new about parameters beyond the confirmation requirement, which is also reflected in the confirm field. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a clear verb+resource ('Enable license') and adds the underlying native endpoint (PUT /licenses/enable). It doesn't explicitly differentiate from sibling disable_license or enable_product, but the verb+resource is specific enough for an agent to distinguish this from related license tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The 'Requires explicit per-call confirmation' note implies when to use it (only on explicit user request), which is reinforced by the confirm parameter. However, no when-not-to-use guidance or explicit alternative routing (e.g., vs disable_license) is given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

enable_productEnable productA

Destructive

Enable product. Reviewed native PUT /products/:id/enable; scope: edit_products. Requires explicit per-call confirmation.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`product_id`	Yes	Exact opaque provider ID, including native = padding.

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds genuinely new operational context: the required OAuth scope (edit_products) and the mandatory per-call confirmation, both of which the annotations do not convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short clauses, front-loaded with the action and then the endpoint, scope, and confirmation constraint in descending order of importance. No filler, though the opening 'Enable product' duplicates the tool title and could have been merged into the more informative second clause.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a three-parameter mutation tool with no output schema, the description plus rich annotations cover the action, the required permission scope, and the confirmation gate. The main omission is any statement of what enabling actually changes on the product or how it relates to disable_product, but the essentials for correct invocation are present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so account, confirm, and product_id are all documented in the schema itself, which sets the baseline at 3. The description's 'Requires explicit per-call confirmation' mildly reinforces the confirm parameter's purpose but adds no format or syntax detail beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear verb+resource ('Enable product') and grounds it in the underlying native endpoint PUT /products/:id/enable, so an agent knows exactly what operation runs. It does not, however, distinguish this from sibling operations such as enable_license or the inverse disable_product, leaving the agent to infer scope from the name alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the verb and reinforced by the stated prerequisite scope (edit_products) and the explicit per-call confirmation requirement. No alternative tool is named and no when-not condition is given, so an agent must infer that this is the inverse of disable_product rather than being told.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

export_resourcesExport bounded private metadataB

Destructive

Confirmed cursor-based JSON export into a new exclusive0600 private file, with page/item/byte budgets and explicit continuation. No URL following, digital files or atomic backup.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`arguments`	No	Actual list filters/page_key, no account override.
`max_items`	No
`max_pages`	No
`operation`	Yes
`output_file`	Yes
`start_offset`	No

TDQS

B3.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, openWorldHint=true, non-idempotent and non-readOnly. On top of that the description adds real behavioral context: writes a new file with mode 0600, enforces page/item/byte budgets, supports explicit continuation, follows no URLs, and is not an atomic backup (so partial output is possible). That is meaningful beyond the annotations, though the byte budget and 'exclusive0600' phrasing are cryptic.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

It is a single front-loaded sentence with no filler, which is good. But it is dense with unglossed jargon ('exclusive0600', 'page/item/byte budgets', 'no atomic backup') that hurts parseability, and the trailing exclusion list is hard to map to concrete behavior.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, 8-parameter tool with nested arguments, low schema coverage, and no output schema, the description leaves gaps: it does not say what the exported file contains per operation, how errors/partial writes should be handled, or how account/arguments interact. Adequate as a minimum-viable sketch but not complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is low (38%) across 8 parameters, so the description must compensate. It clarifies budgets (page/item) and continuation semantics, but says nothing about account, arguments, start_offset, or confirm beyond the schema's own terse hints. Partial compensation only.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb (export), the payload format (cursor-based JSON), and the output target (a new private file), so the core action is identifiable. However, it never says which resources are exported (the operation enum lists products/sales/subscribers/payouts), and it does nothing to distinguish this bounded export from the many sibling list_* tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit when-to-use guidance or named alternative. 'Confirmed' and the confirm parameter imply a user-approval precondition, but the description never states when this export should be chosen over, e.g., list_sales or list_products directly. Usage context is only weakly implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_custom_fieldGet exact custom checkout fieldA

Read-onlyIdempotent

Compatibility read using documented list_custom_fields then exact field-name match. There is no native single-custom-field GET endpoint.

ParametersJSON Schema

Name	Required	Description
`name`	Yes
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.
`product_id`	Yes

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile. The description adds meaningful behavioral context: this is not a native GET endpoint and implements the read via list_custom_fields followed by exact matching, which helps an agent understand performance and implementation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences, front-loaded with the core behavior and then the key constraint. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Purpose and implementation caveat are well covered, and annotations handle safety. However, for a three-parameter read tool with low schema description coverage and no output schema, the description leaves meaningful parameter gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is low at 33%. The description only indirectly clarifies the name parameter through 'exact field-name match' and says nothing about product_id or the account parameter, so it does not compensate for the schema's missing parameter documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: gets an exact custom checkout field. It also distinguishes this from list_custom_fields by describing the exact field-name match and noting there is no native single-custom-field GET endpoint.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Names the relevant alternative (list_custom_fields) and explains this tool is a compatibility read when an exact field is needed. Usage context is clear, though explicit when-not-to-use conditions are not stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_offer_codeGet offer codeB

Read-onlyIdempotent

Get offer code. Reviewed native GET /products/:product_id/offer_codes/:id; scope: edit_products. Read only; no local effect approval required.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.
`product_id`	Yes	Exact opaque provider ID, including native = padding.
`offer_code_id`	Yes	Exact opaque provider ID, including native = padding.

TDQS

B3.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the description's 'Read only' is redundant. However, it adds real value beyond the structured fields by disclosing the required auth scope ('scope: edit_products') and the native endpoint, which help an agent understand access prerequisites.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two compact sentences with the action front-loaded and no padding. The endpoint and scope details are appended efficiently, though the first sentence slightly restates the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries some burden for return semantics but says nothing about what the offer code object contains or the response shape. It does cover the read-only nature, endpoint, and required scope, which is adequate for a single-resource GET but leaves the return format undocumented.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with all three parameters documented (account, product_id, offer_code_id) including the opaque-ID format. The description adds no parameter-level meaning beyond that, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The name and first sentence ('Get offer code') state a verb+resource, and the native endpoint 'GET /products/:product_id/offer_codes/:id' clarifies this retrieves a single offer code scoped to a product. The ':id' path distinguishes it implicitly from the list_offer_codes sibling, though no sibling is named explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description never states when to use this tool versus alternatives like list_offer_codes or get_product. 'Read only; no local effect approval required' is a safety note, not usage guidance, so the agent must infer routing on its own.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_operation_schemaInspect reviewed native contractB

Read-onlyIdempotent

Local native method/path, fields, scopes and pinned provenance. Field subset, not an official OpenAPI document or permission proof.

ParametersJSON Schema

Name	Required	Description	Default
`operation`	Yes

TDQS

B3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already establish read-only, idempotent, non-destructive, and closed-world behavior. The description adds useful limitations by calling the result a 'field subset' and not a permission proof, but it does not describe return format, scope of omitted data, or authorization requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two short sentences with no wasted text. It is compact and front-loads the main content, though the first sentence is a terse noun fragment rather than a clear action statement.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only schema-inspection tool with one enum parameter and no output schema, the description gives only a high-level list of returned categories and a limitation disclaimer. It omits usage guidance, parameter meaning, and return-value detail, leaving clear gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 0%, and the description never mentions the required 'operation' parameter or how to choose among its many enum values. The enum itself supplies valid values, but the description adds no semantic meaning beyond that.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description identifies the resource as a reviewed native contract with method/path, fields, scopes, and provenance. It is clear enough to separate this metadata-lookup tool from the sibling operation tools, though it does not explicitly say it retrieves a contract for a supplied operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to call this tool versus invoking a sibling operation tool. The disclaimer 'not an official OpenAPI document or permission proof' is a caveat, not usage direction.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_payoutGet payoutB

Read-onlyIdempotent

Get payout. Reviewed native GET /payouts/:id; scope: view_payouts. Read only; no local effect approval required.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.
`payout_id`	Yes	Exact opaque provider ID, including native = padding.
`include_sales`	No	(optional, default: "true") - Set to "false" to exclude the "sales", "refunded_sales", and "disputed_sales" details from the response.
`include_transactions`	No	(optional, default: "false") - Set to "true" to include the same transaction details in the response as exported payout CSV. All balance-affecting transactions included in the payout will be listed in a "transactions" array. Each transaction will have these keys: { type:, date:, purchase_id:, item_name:, buyer_name:, buyer_email:, taxes:, shipping:, sale_price:, gumroad_fees:, net_total: }. The "type" of transactions can be "Sale", "Chargeback", "Full Refund", "Partial Refund", "PayPal Refund", "Stripe Connect Refund", "Affiliate Credit", "PayPal Connect Affiliate Fees", "Stripe Connect Affiliate Fees", "PayPal Payouts", "Stripe Connect Payouts", "Credit", "Payout Fee", and "Technical Adjustment".

TDQS

B3.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds value beyond that by disclosing the required auth scope (view_payouts) and that no local effect approval is needed, which is real operational context an agent cannot get from the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Very short and front-loaded, with the resource, scope and read-only nature stated up front. Nothing is wasted, though the opening sentence duplicates the name and the approval clause is slightly cryptic.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple single-resource GET with no output schema, full schema coverage and annotations covering safety, the description supplies the remaining essentials: the endpoint and the required scope. It is adequate, though it omits error/not-found behavior and sibling differentiation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the four parameters (account, payout_id, include_sales, include_transactions) are already fully documented, including defaults and response-shaping behavior. The description adds nothing about parameters, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence 'Get payout' merely restates the name and title, which is tautological. The second clause adds the native endpoint GET /payouts/:id, confirming this is an ID-based fetch, but it never distinguishes itself from close siblings like list_payouts or get_upcoming_payout.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description names the required scope (view_payouts), which implies a precondition, but it gives no guidance on when to use this tool versus get_upcoming_payout or list_payouts. There is no when/when-not framing at all.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_productGet productB

Read-onlyIdempotent

Get product. Reviewed native GET /products/:id; scope: view_profile. Read only; no local effect approval required.

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.
`product_id`	Yes	Exact opaque provider ID, including native = padding.

TDQS

B3.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new context: the required scope (view_profile), the 'reviewed native' status of the endpoint, and that no local effect approval is needed — details annotations cannot express.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short clauses, front-loaded with the core action, with no filler. The scope/approval notes are compact, though they read as internal compliance boilerplate rather than agent-facing guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read tool with full schema coverage and no output schema, the description covers the action and auth scope but says nothing about the returned product shape or error behavior (e.g., missing ID). The permission and approval notes are useful, but the return-value gap keeps this at an adequate-but-incomplete level.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already defines both parameters (account label semantics and the opaque product_id with its pattern/length constraints). The description adds nothing about parameter meaning, making the baseline 3 appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description pairs the verb with the resource and anchors it to a concrete native endpoint (GET /products/:id), so an agent knows exactly what is retrieved. It does not, however, distinguish this from siblings like get_variant or list_products beyond the resource name.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance or mention of alternatives (e.g., list_products for enumeration, get_variant for variants). The only usage-relevant information is the implied precondition 'scope: view_profile', which is a permission note rather than routing guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_refund_policyGet refund policyC

Read-onlyIdempotent

Get refund policy. Reviewed native GET /refund_policy; scope: account. Read only; no local effect approval required.

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.

TDQS

C2.7/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, non-destructiveHint and openWorldHint, so the safety profile is covered; 'Read only' merely repeats it. The added 'no local effect approval required' is a genuine workflow trait not present in the annotations, which earns modest credit.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loads the operation. However, the internal jargon ('Reviewed native GET /refund_policy', 'local effect approval') is implementation boilerplate that is not useful to an agent selecting the tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple, single-parameter read tool with full annotation coverage and no output schema, the definition is essentially complete; an agent has enough to invoke it. It falls short only on routing guidance against the sibling update tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single 'account' parameter is already fully documented in the schema, so the baseline of 3 applies. The description's 'scope: account' does not add syntax or meaning beyond what the schema states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose2/5

Does the description clearly state what the tool does and how it differs from similar tools?

The lead sentence 'Get refund policy' is an exact restatement of the tool title, which fits the rubric's tautology case. The trailing 'Reviewed native GET /refund_policy; scope: account' adds only internal endpoint trivia and does not differentiate it from the sibling update_refund_policy.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to call this versus update_refund_policy or any other sibling, no prerequisites, and no scenario framing. 'scope: account' hints at a filter but not at usage timing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_saleGet saleA

Read-onlyIdempotent

Get sale. Reviewed native GET /sales/:id; scope: view_sales. Read only; no local effect approval required.

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.
`sale_id`	Yes	Exact opaque provider ID, including native = padding.

TDQS

A3.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description still adds real context beyond them: the required OAuth scope (view_sales) and the native endpoint mapping, plus the note that no local effect approval is needed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Very short and front-loaded: action and endpoint first, then scope and safety. The telegraphic, semicolon-chained phrasing is slightly terse but wastes no words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-resource GET with no output schema, the description could state what a sale record contains or what a not-found/lack-of-scope response looks like. It covers auth scope but leaves the return shape entirely unspecified.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters (account, sale_id) are already fully documented including the opaque-ID and credential-inheritance caveats. The description adds only the implicit 'GET /sales/:id' mapping, which is marginal; baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States the specific verb+resource (get a single sale) and pins it to the native endpoint 'GET /sales/:id', which distinguishes it from list_sales. It doesn't explicitly contrast with other retrieval siblings, but the resource and scope are unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Adds a prerequisite ('scope: view_sales') and the read-only/no-approval condition, which is useful context. However, it never says when to prefer this over list_sales or how it relates to mark_sale_as_shipped/refund_sale workflows, so usage is only implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_subscriberGet subscriberB

Read-onlyIdempotent

Get subscriber. Reviewed native GET /subscribers/:id; scope: view_sales. Read only; no local effect approval required.

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.
`subscriber_id`	Yes	Exact opaque provider ID, including native = padding.

TDQS

B3.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the bar is lower. The description still adds value beyond them by naming the required scope (view_sales) and the 'no local effect approval required' workflow fact, neither of which is captured in the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short clauses, front-loaded with the operation and followed by endpoint, scope, and approval facts. Slightly telegraphic ('Reviewed native') but no wasted sentences.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-resource read with full schema coverage, no output schema, and annotations covering the safety profile, the description supplies enough (endpoint, scope, approval behavior) for correct invocation. Only the relationship to list_subscribers is left unaddressed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and both parameters (account, subscriber_id) are documented in the schema with pattern and length constraints. The description adds no parameter-level detail, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence 'Get subscriber' merely restates the tool name and title. The added 'native GET /subscribers/:id' mapping identifies the concrete operation, but the description never differentiates this from list_subscribers or get_user, so the agent gets a resource but no scoping distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit when-to-use or when-not-to-use statement, and no sibling (e.g. list_subscribers) is named as an alternative. The 'scope: view_sales' note implies the required permission context, which is the only usage signal present.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_upcoming_payoutGet upcoming payoutB

Read-onlyIdempotent

Get upcoming payout. Reviewed native GET /payouts/upcoming; scope: view_payouts. Read only; no local effect approval required.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.
`include_sales`	No	(optional, default: "true") - Set to "false" to exclude the "sales", "refunded_sales", and "disputed_sales" details from the response.
`include_transactions`	No	(optional, default: "false") - Set to "true" to include the same transaction details in the response as exported payout CSV. All balance-affecting transactions included in the payout will be listed in a "transactions" array. Each transaction will have these keys: { type:, date:, purchase_id:, item_name:, buyer_name:, buyer_email:, taxes:, shipping:, sale_price:, gumroad_fees:, net_total: }. The "type" of transactions can be "Sale", "Chargeback", "Full Refund", "Partial Refund", "PayPal Refund", "Stripe Connect Refund", "Affiliate Credit", "PayPal Connect Affiliate Fees", "Stripe Connect Affiliate Fees", "PayPal Payouts", "Stripe Connect Payouts", "Credit", "Payout Fee", and "Technical Adjustment".

TDQS

B3.4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so 'Read only; no local effect approval required' largely restates structured data. The added value is the endpoint provenance and the required scope token, but nothing is said about response shape or edge cases (e.g., no upcoming payout existing).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One compact sentence-pair with the purpose front-loaded and no padding. The scope/clause syntax is terse but dense with useful facts rather than filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description ideally would hint at what a payout response contains, but the rich parameter descriptions partially compensate. Annotations plus 100% schema coverage mean the agent can call it correctly, though the return-value side is left unaddressed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all three parameters are fully documented in the schema itself, including defaults and the transaction key list. The description adds nothing beyond that, which is the baseline 3 case.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Get upcoming payout'), which is distinguishable from the sibling read tools get_payout and list_payouts by the 'upcoming' qualifier. However, it does not explicitly contrast itself with those siblings, leaving the agent to infer the distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It discloses the required scope ('view_payouts') and confirms the native endpoint, which is real invocation guidance, but it never says when to prefer this over list_payouts or get_payout. Usage is implied rather than directed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_userGet userB

Read-onlyIdempotent

Get user. Reviewed native GET /user; scope: view_profile. Read only; no local effect approval required.

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.

TDQS

B3.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: the required 'view_profile' scope and the note that no local effect approval is needed. These are useful auth/workflow disclosures, though the 'Reviewed native GET /user' phrasing is cryptic jargon.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short and front-loads the core action before the scope/approval details. It is efficient, though the internal-sounding 'Reviewed native GET /user' fragment is low-value phrasing that a caller gains little from.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter read tool with no output schema and annotations that already cover safety, the description is roughly adequate. However, it never clarifies what a 'user' resource is relative to sibling concepts like accounts or subscribers, which is the main ambiguity an agent would face.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the single 'account' parameter is already fully documented in the schema, including the caveat about credentials/ownership. The description adds no parameter meaning on top of that, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Get user', which essentially restates the tool name and title. It does add the underlying endpoint ('native GET /user') and the required scope ('view_profile'), giving some concreteness, but it never distinguishes this tool from nearby siblings like list_accounts or get_subscriber. Purpose is understandable but not sharpened.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use get_user versus alternatives, no prerequisites, and no named sibling for contrast. The only routing hint is the 'scope: view_profile' phrase, which is an authorization detail rather than usage guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_variantGet variantA

Read-onlyIdempotent

Get variant. Reviewed native GET /products/:product_id/variant_categories/:variant_category_id/variants/:id; scope: edit_products. Read only; no local effect approval required.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.
`product_id`	Yes	Exact opaque provider ID, including native = padding.
`variant_id`	Yes	Exact opaque provider ID, including native = padding.
`variant_category_id`	Yes	Exact opaque provider ID, including native = padding.

TDQS

A3.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely new context: the required OAuth scope (edit_products) and the note that no local effect approval is required, which is behavior an agent cannot derive from the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

It is a single tight sentence with the endpoint and scope front-loaded and no filler. The leading 'Get variant.' is slightly redundant with the title but costs almost nothing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only single-entity fetch with full schema coverage, rich annotations and no output schema, the description supplies the endpoint, scope and safety context an agent needs. It omits what the response contains and the not-found behavior, which is a minor gap given no output schema exists.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all four parameters are already documented in the schema, including the 'exact opaque provider ID' semantics and the account label caveat. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the resource (variant) and pins it down with the exact native endpoint path including the product_id / variant_category_id / variant_id hierarchy, so an agent knows precisely what entity is fetched. It is more than a restatement of the name, though it never explicitly contrasts itself with get_variant_category or list_variants.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no statement of when to prefer list_variants over this single-fetch tool, and no mention of prerequisites or failure cases. Usage must be inferred entirely from the endpoint path.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_variant_categoryGet variant categoryA

Read-onlyIdempotent

Get variant category. Reviewed native GET /products/:product_id/variant_categories/:id; scope: edit_products. Read only; no local effect approval required.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.
`product_id`	Yes	Exact opaque provider ID, including native = padding.
`variant_category_id`	Yes	Exact opaque provider ID, including native = padding.

TDQS

A3.6/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true. The description adds the required scope (edit_products) and notes 'no local effect approval required,' which is useful context about auth requirements. However it doesn't describe return format, error behavior, or other behavioral traits beyond what annotations cover.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short clauses: purpose, native endpoint/scope, read-only safety note. Extremely dense, front-loaded, and every clause adds distinct information with zero waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only single-resource GET with a fully documented schema and four annotations already covering the safety profile, the description is nearly complete. It adds the scope requirement, which is valuable for auth. It lacks output format info, but no output schema exists and reads are relatively predictable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all three parameters (account, product_id, variant_category_id) with patterns and descriptions. The description adds no parameter-level detail, so the baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Get variant category') and even cites the underlying native endpoint GET /products/:product_id/variant_categories/:id, which disambiguates it from siblings like list_variant_categories or get_variant. It's clear but the resource is fairly self-explanatory from the name, so it doesn't reach the discrimination level of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies a read of a single variant category via the native GET endpoint, but it never states when to use this vs. list_variant_categories or get_variant. Usage context is only implied, not spelled out with alternatives or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

increment_license_usesVerify and increment license usesA

Destructive

Verify the intended private license and increment its native usage counter. Explicit confirmation required; no OAuth required.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`product_id`	Yes	Current native product ID, never deprecated permalink.

TDQS

A3.5/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is known. The description's genuine addition is the auth disclosure ('no OAuth required') and the confirmation requirement, but the latter duplicates the schema's confirm parameter and it does not explain the consequences of the non-idempotent counter increment.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the action and followed by the constraints; no filler. 'The intended private license' is slightly vague phrasing but does not bloat the text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with rich annotations and no output schema, the description covers the action, the confirmation requirement, and auth needs. It stops short of describing reversibility or how the counter change can be undone (e.g., via decrement_license_uses), which would fully close the loop.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so account, confirm, and product_id are all fully documented in the schema with strong constraints (pattern, maxLength, 'never inherited credentials'). The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific compound action (verify + increment a license's native usage counter), which is clearer than a tautology. It does not explicitly differentiate itself from close siblings like verify_license or decrement_license_uses, so the agent must infer the distinction from the verb 'increment' alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Explicit confirmation required' gives a precondition, and the action is clearly a license mutation, so usage is implied. But there is no explicit when-to-use versus verify_license (read-only verify) or decrement_license_uses (the inverse operation), which are the obvious alternatives an agent would weigh.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_accountsList configured accountsB

Read-onlyIdempotent

Local profile labels/default and credential availability only. No secrets, file paths, provider identity or network.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

B3.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the bar is low, yet the description adds real value by enumerating what is NOT returned (no secrets, file paths, provider identity, or network). This privacy/scope disclosure goes beyond the structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single compact sentence, front-loaded with what the tool returns and followed by its exclusions. It is terse but each clause carries content; the telegraphic style borders on fragmentary but stays within reasonable conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With zero parameters and no output schema, the description must carry the return-value burden, and it does describe the returned fields (labels, default flag, credential availability) and the notable omissions. Format details are not given, but for a trivial no-arg list tool this is largely complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters (empty object schema), so there is nothing to document and the baseline of 4 applies. The description correctly implies a no-argument listing call.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description reads as a content/scope specification ('Local profile labels/default and credential availability only') rather than a clear verb+resource statement; the verb 'list' only appears in the name and title. An agent can infer it enumerates locally configured account profiles, but the purpose is implied rather than stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance is provided; the text is purely a scope disclaimer about returned fields. There is no mention of prerequisites, conditions, or how this relates to other listing tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_categoriesList categoriesA

Read-onlyIdempotent

List categories. Reviewed native GET /categories; scope: view_profile. Read only; no local effect approval required.

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.

TDQS

A3.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly=true, idempotent=true, destructive=false, so safety is covered. The description goes further by naming the required scope (view_profile) and confirming no approval gate, which is real operational context an agent can act on.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three terse sentences, front-loaded with the action and endpoint before the scope/safety notes. The phrasing 'no local effect approval required' is somewhat internal jargon but it is compact and does not pad.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-optional-param read-only list tool with no output schema or nesting, the description supplies endpoint, scope requirement, and safety confirmation. Nothing critical is missing, though it never says what a category record contains or whether results are paginated.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single optional 'account' parameter is fully documented in the schema, so the baseline is 3. The description adds nothing about the account parameter or omission behavior, so no credit above baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource (list categories) and pins it to the native GET /categories endpoint, which helps separate it from the similar list_variant_categories sibling. However, it never names that sibling or clarifies which category type is returned, so an agent still has to infer differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no indication of when list_variant_categories would be the better choice, and no preconditions beyond the scope note. The scope string reads as an internal auth detail rather than actionable selection guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_custom_fieldsList custom fieldsA

Read-onlyIdempotent

List custom fields. Reviewed native GET /products/:product_id/custom_fields; scope: edit_products. Read only; no local effect approval required.

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.
`product_id`	Yes	Exact opaque provider ID, including native = padding.

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description still adds genuine context beyond that: the required edit_products scope (an auth need) and the native endpoint mapping, plus the 'no local effect approval required' note. Only the 'Read only' clause is redundant with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded in the first clause and the whole definition is a compact two-sentence block with no filler. Minor redundancy ('Read only' overlapping with destructiveHint=false) keeps it from a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only list tool with full annotation coverage and 100% schema coverage, the description supplies the key missing operational detail (required scope) and the endpoint mapping. Return format and pagination are unaddressed, but that is minor given no output schema is expected.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters (account, product_id) are already fully documented in the schema. The description adds no additional meaning about parameter format or the account-vs-product_id distinction, making the correct baseline 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb+resource ('List custom fields') that clearly distinguishes it from the singular get_custom_field and the write siblings (create/update/delete_custom_field). It also maps to the native endpoint GET /products/:product_id/custom_fields, but stops short of naming any sibling it must not be confused with.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The 'scope: edit_products' note implies the prerequisite under which the tool is callable, and 'Read only' implies a safe read path. However, there is no explicit when-to-use vs when-not-to-use guidance or named alternative (e.g., get_custom_field for a single field), so usage is only implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_offer_codesList offer codesA

Read-onlyIdempotent

List offer codes. Reviewed native GET /products/:product_id/offer_codes; scope: edit_products. Read only; no local effect approval required.

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.
`product_id`	Yes	Exact opaque provider ID, including native = padding.

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so safety is covered. The description adds meaningful context beyond that: the OAuth scope required (edit_products) and that no local effect approval is needed, both of which affect how an agent may invoke it.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight clauses with the purpose front-loaded, then endpoint/scope, then approval note. Nothing is padded, though 'Reviewed native GET' is slightly jargon-heavy for an agent that only needs the operation semantics.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, so return-value detail is not required, and annotations carry the safety profile. The scope and approval notes round out what an agent needs, though pagination or result-volume behavior for a list endpoint is not mentioned.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with both parameters (account, product_id) documented in the schema including pattern and length constraints. The description adds no parameter syntax or format detail beyond the endpoint path, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('List offer codes') and identifies the native endpoint GET /products/:product_id/offer_codes, which clarifies it is a product-scoped collection listing. It is distinguishable from siblings like get_offer_code, create_offer_code, and delete_offer_code, though it never explicitly names those alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description supplies a required scope (edit_products) and notes no local approval is needed, which is useful precondition context. However, it never says when to use this versus get_offer_code (single) or the create/update/delete siblings, so usage is only implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_payoutsList payoutsA

Read-onlyIdempotent

List payouts. Reviewed native GET /payouts; scope: view_payouts. Read only; no local effect approval required.

ParametersJSON Schema

Name	Required	Description
`after`	No	(optional, date in form YYYY-MM-DD) - Only return payouts after this date
`before`	No	(optional, date in form YYYY-MM-DD) - Only return payouts before this date
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.
`page_key`	No	(optional) - A key representing a page of results. It is given in the response as `next_page_key`.
`include_upcoming`	No	(optional, default: "true") - Set to "false" to exclude the upcoming payout from the response.

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety bar is low. The description adds genuinely non-structured context: the required OAuth scope 'view_payouts', the underlying native GET endpoint, and the absence of an approval workflow. That is meaningful auth/operational detail beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short fragments with no filler, and the core purpose is front-loaded in the first two words. The endpoint/scope clauses are dense but each carries distinct information, though they read as clipped notes rather than polished prose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-required-param list tool with full schema coverage and no output schema, the description covers purpose, auth scope, and read-only status. The one gap is pagination behavior, which the schema hints at via page_key/next_page_key but the description never mentions.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all five parameters (after, before, account, page_key, include_upcoming) are already documented in the schema, including formats and defaults. The description adds no parameter-level meaning, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('List payouts') and grounds it in the concrete native endpoint 'GET /payouts', so the agent knows this is the collection-level read. It does not explicitly differentiate from siblings like get_payout or get_upcoming_payout, but the plural 'list' plus the GET path makes the distinction inferable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage via 'scope: view_payouts' and 'no local effect approval required', which tells the agent this is a safe, pre-approved read path. However, it never states when to choose this over get_payout/get_upcoming_payout or whether filters should be applied. Guidance is present but implicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_productsList productsB

Read-onlyIdempotent

List products. Reviewed native GET /products; scope: view_profile. Read only; no local effect approval required.

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.
`page_key`	No	Opaque native continuation cursor; never an arbitrary URL.

TDQS

B3.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the description need not restate those. It adds genuinely non-annotation context: the required scope (view_profile), the native endpoint reviewed, and the fact that no local effect approval is needed — useful for an agent deciding whether it can invoke this.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short, front-loaded clauses with no filler; the scope and safety facts are stated compactly. Slightly terse but each sentence carries content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only, zero-required-parameter list tool whose annotations cover the safety profile and whose schema covers both params, this is adequate. It is thin on return-value/listing behavior (what the list contains, how the cursor paginates), but no output schema exists and annotations handle the read-only signal.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters (account, page_key) are already documented in the schema. The description adds nothing about parameter syntax or format, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the verb and resource ("List products") and adds the native endpoint (GET /products) and scope (view_profile), which gives more than pure tautology. However, it does not distinguish this from the many sibling list_* tools (list_categories, list_variants, list_accounts, etc.), so an agent gets no differentiation signal.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

"Read only; no local effect approval required" is a safety/approval note rather than usage guidance. There is no statement of when to use this tool versus alternatives such as get_product or list_categories, and no prerequisites described.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_resource_subscriptionsList resource subscriptionsA

Read-onlyIdempotent

List resource subscriptions. Reviewed native GET /resource_subscriptions; scope: view_sales for sale event; provider authorization for other events. Read only; no local effect approval required.

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.
`resource_name`	Yes	(string) - Currently there are 8 supported values - "sale", "refund", "dispute", "dispute_won", "cancellation", "subscription_updated", "subscription_ended", and "subscription_restarted".

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint. The description goes beyond them by naming the underlying native GET /resource_subscriptions, the required authorization scope for resource types, and that no local effect approval is required. It still omits pagination/rate-limit behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short and front-loads the core purpose before technical auth details. The sentences are dense but each adds some operational context; there is no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter, read-only list tool with rich annotations and full schema descriptions, the definition is mostly complete: it covers auth scope and read-only behavior. It does not describe return format or pagination, but no output schema exists and none is required for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the enum values and account parameter are already documented. The description adds only a small amount of meaning by contrasting 'sale event' authorization with 'other events,' but it does not explain the optional account parameter or enum selection mechanics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('List resource subscriptions') so the agent can identify it as the read counterpart to create/delete_resource_subscription. It does not explicitly call out those siblings or differentiate conditions beyond the name.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implied usage is clear from the list verb, and the description adds authorization context: view_sales for sale events, provider authorization for other events. However, it does not state when to prefer this over siblings or any exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_salesList salesB

Read-onlyIdempotent

List sales. Reviewed native GET /sales; scope: view_sales. Read only; no local effect approval required.

ParametersJSON Schema

Name	Required	Description
`name`	No	(optional) - Filter sales by customer name
`after`	No	(optional, date in form YYYY-MM-DD) - Only return sales after this date
`email`	No	(optional) - Filter sales by this email
`before`	No	(optional, date in form YYYY-MM-DD) - Only return sales before this date
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.
`order_id`	No	(optional) - Filter sales by this Order ID
`page_key`	No	(optional) - A key representing a page of results. It is given in the response as `next_page_key`.
`product_id`	No	(optional) - Filter sales by this product

TDQS

B3.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds genuinely new context beyond annotations: the required scope (view_sales) and that no local effect approval is needed. It stops short of 5 because pagination behavior and return shape are left unmentioned.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short clauses, front-loaded with the action and followed by the endpoint and permission facts. No filler, though the semicolon-chained jargon is slightly dense.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an eight-parameter, zero-required list tool with no output schema, the description covers the action, endpoint, and permission scope, but says nothing about pagination semantics or result shape. Annotations handle the safety dimension, leaving this adequate but not complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all eight parameters are documented in the schema itself, including the page_key/next_page_key pagination contract. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

"List sales" largely restates the tool name, but the addition of "Reviewed native GET /sales; scope: view_sales" gives the agent a concrete backend operation and permission scope. It does not distinguish this from the sibling get_sale (single sale) or explain the relationship to list_products, so it stops short of a 4.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this versus get_sale, mark_sale_as_shipped, or refund_sale, and no stated conditions for filtering. The scope mention hints at a prerequisite but is not framed as usage guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_subscribersList subscribersB

Read-onlyIdempotent

List subscribers. Reviewed native GET /products/:product_id/subscribers; scope: view_sales. Read only; no local effect approval required.

ParametersJSON Schema

Name	Required	Description
`email`	No	(optional) - Filter subscribers by this email
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.
`page_key`	No	(optional) - A key representing a page of results. It is given in the paginated response of the previous page as `next_page_key`.
`product_id`	Yes	Exact opaque provider ID, including native = padding.

TDQS

B3.4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description's added value is the auth scope ('view_sales') and the note that no local approval is needed; the 'read only' clause merely repeats the annotation, and no pagination or return behavior is described.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

It is compact and front-loads the purpose before the endpoint and scope details. The clause about approval is slightly opaque jargon, but nothing is padded or repeated verbatim.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description could reasonably say more about the returned subscriber shape or pagination contract, though page_key is documented in the schema. Endpoint and auth scope are given, which covers the essentials for a filtered list read, but gaps remain.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all four parameters (email filter, account, page_key, product_id) are already documented in the schema. The description adds no parameter-level syntax, format, or interaction detail beyond restating the endpoint path, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource ('List subscribers') and pins it to the concrete endpoint GET /products/:product_id/subscribers, which tells an agent exactly what data class it returns. It does not, however, distinguish itself from the sibling get_subscriber beyond the implicit singular/plural split.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The stated scope ('view_sales') is a real prerequisite that tells the agent what authorization the call needs, which is useful context. Beyond that there is no when-to-use guidance, no mention of when to prefer get_subscriber, and no exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_variant_categoriesList variant categoriesA

Read-onlyIdempotent

List variant categories. Reviewed native GET /products/:product_id/variant_categories; scope: edit_products. Read only; no local effect approval required.

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.
`product_id`	Yes	Exact opaque provider ID, including native = padding.

TDQS

A3.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint/ idempotentHint/destructiveHint=false, so the safety profile is covered. The description adds genuinely new context: the required OAuth scope (edit_products), the fact that it's a reviewed native endpoint, and that no local effect approval is required — useful operational detail beyond the structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One compact sentence plus a dense second sentence covering endpoint, scope and approval posture. Front-loaded with the verb+resource; no wasted prose, though the sentence style is somewhat telegraphic.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter read tool with no output schema, the description supplies endpoint, required scope, and approval posture, covering what an agent needs beyond the schema and annotations. Return-shape details are absent but a list tool needs little more.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with both parameters fully documented (account, product_id with pattern/padding notes), so the schema carries the semantics. The description adds nothing about parameter formatting beyond the endpoint placeholder, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb 'List' plus resource 'variant categories', reinforced by the native endpoint GET /products/:product_id/variant_categories which clarifies it is per-product nesting. It does not explicitly distinguish itself from the sibling list_categories (product categories), so an agent must infer the difference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use or when-not-to-use guidance, and no mention of alternatives like list_variants or list_categories. The only contextual cue is the 'scope: edit_products' permission note, which helps the agent know it needs edit_products scope but says nothing about selecting this tool over siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_variantsList variantsA

Read-onlyIdempotent

List variants. Reviewed native GET /products/:product_id/variant_categories/:variant_category_id/variants; scope: edit_products. Read only; no local effect approval required.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.
`product_id`	Yes	Exact opaque provider ID, including native = padding.
`variant_category_id`	Yes	Exact opaque provider ID, including native = padding.

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral context: the required scope 'edit_products' and the note that no local effect approval is required, which an agent cannot derive from the structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Compact and front-loaded: identification first, then endpoint and scope. Dense but every clause carries weight; only the title-like restatement 'List variants' is redundant with the tool name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a scoped read-only list tool with full schema coverage and annotations declaring the safety profile, the description covers identification, endpoint, and authorization scope. Pagination or result-shape guidance is absent, but no output schema exists and this is a low-complexity operation, so the gap is minor.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all three parameters including required product_id/variant_category_id and the account selector. The description adds no parameter-level detail beyond what the schema provides; baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List variants') and pins it to the native endpoint GET /products/:product_id/variant_categories/:variant_category_id/variants, which unambiguously separates it from get_variant, list_variant_categories, and list_products. It does not explicitly name a sibling to contrast with, so it falls short of the top mark.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description discloses the required scope ('edit_products'), which is real usage context for authorization. However, it gives no when-to-use/when-not guidance or routing to alternatives such as get_variant for a single variant or list_variant_categories for the parent level.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mark_sale_as_shippedMark sale as shippedA

Destructive

Mark sale as shipped. Reviewed native PUT /sales/:id/mark_as_shipped; scope: mark_sales_as_shipped. Requires explicit per-call confirmation.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`sale_id`	Yes	Exact opaque provider ID, including native = padding.
`tracking_url`	No	(optional) Full http:// or https:// URL

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false, openWorldHint=true, covering the safety profile. The description adds valuable context beyond annotations: a required scope ('mark_sales_as_shipped') and a confirmation requirement, which tells the agent this mutation must be deliberate and permissioned. It does not spell out irreversibility, but the destructiveHint covers that.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with no filler: the action is front-loaded, followed by the implementation detail and scope. Every clause carries weight and nothing is redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the annotations already specify safety and idempotency, and the schema fully documents parameters, the description supplies the missing operational context (required scope, explicit confirmation). There is no output schema, but the description need not explain return values. It is nearly complete, though it could note any side effects or rate limits.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all four parameters (account, confirm, sale_id, tracking_url) are documented in the schema itself, giving a baseline of 3. The description adds no parameter-specific meaning beyond the schema, which is acceptable when schema coverage is complete.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('mark as shipped') and resource ('sale'), and the name/title are unambiguous. It also identifies the native endpoint (PUT /sales/:id/mark_as_shipped), which distinguishes it from siblings like refund_sale or revoke_sale_access.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description makes clear this is a status-changing action requiring explicit per-call confirmation ('Requires explicit per-call confirmation'), which implicitly defines when to use it (only when the user asked for exactly this action). It doesn't name alternatives (e.g., refund_sale) or exclusions, but the confirmation requirement gives solid usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

preview_commerce_batchReview exact ordered effectsB

Read-onlyIdempotent

Local validation/hash binding exact ordered requests/profile label/native snapshot. No provider requests, secret loading, ownership/state validation or financial guarantee.

ParametersJSON Schema

Name	Required	Description	Default
`tasks`	Yes	One to twenty exact ordered native effects. No replacement-key output. Nested arguments cannot override profile/confirmation or carry credentials/files.
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.

TDQS

B3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint/idempotent/openWorldHint=false/destructive=false, so safety is covered. The description adds real negative-space disclosure beyond the annotations: no secret loading, no ownership/state validation, no financial guarantee, establishing that this is a purely local pre-flight check.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no obvious filler, but the telegraphic slash-fragment style ('Local validation/hash binding exact ordered requests/profile label/native snapshot') sacrifices readability for brevity and is not cleanly front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a preview/dry-run tool with no output schema, the description should explain what the preview returns (the snapshot/hash it mentions only in passing). It also omits the 20-item batch cap and any note on how the result pairs with submit_commerce_batch, leaving meaningful gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%; both the tasks array and account label are documented in the schema itself. The description adds no parameter syntax or format detail, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The name preview_commerce_batch and title 'Review exact ordered effects' convey a dry-run of ordered commerce operations, and the description adds 'Local validation/hash binding exact ordered requests'. But the telegraphic slash-separated phrasing makes the actual purpose hard to parse, and it never cleanly states verb+resource.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit when-to-use guidance and no mention of the obvious alternative submit_commerce_batch, despite it being a sibling. The phrase 'No provider requests' weakly implies a dry-run, but the agent must infer the preview-before-submit workflow.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

refund_saleRefund saleA

Destructive

Refund sale. Reviewed native PUT /sales/:id/refund; scope: edit_sales. Requires explicit per-call confirmation.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`sale_id`	Yes	Exact opaque provider ID, including native = padding.
`full_refund`	No	Deliberate full refund. Must be true if amount_cents is omitted, and cannot coexist with it.
`amount_cents`	No	(optional) - Amount to refund, in minor units of the sale's listed currency — the `currency` field on the sale object, not the buyer's local currency. Every listed currency has 100 minor units except `jpy`, which has none (whole yen), so for most sales 200 means 2.00 of that currency, but for a JPY sale 200 means ¥200. If set, issue partial refund by this amount. If not set, issue full refund. You can issue multiple partial refunds per sale until it is fully refunded.

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is partly covered. The description adds genuinely new context beyond that: the required scope (edit_sales) and the mandatory per-call confirmation, both of which affect whether an agent should attempt the call.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short clauses, front-loaded with the purpose, then scope, then the confirmation requirement. No filler, no redundancy with the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, non-idempotent mutation with no output schema, the description supplies the key preconditions (scope, confirmation) that an agent needs before invoking. It does not describe post-refund effects or rate limits, but nothing critical for correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already fully documents account, confirm, sale_id, full_refund, and amount_cents in detail (including the JPY minor-unit nuance). The description only gestures at the confirm parameter via 'per-call confirmation' and adds no syntax or format detail beyond the schema, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Refund sale') and pins it to the native endpoint PUT /sales/:id/refund, so the agent knows exactly what operation this is. It does not explicitly contrast itself with siblings (e.g., revoke_sale_access, resend_sale_receipt), but the resource is distinctive enough to distinguish it.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies a usage precondition with 'Requires explicit per-call confirmation,' which tells the agent a confirmation step is mandatory. However, it gives no when-to-use vs. when-not guidance relative to siblings like revoke_sale_access or update_refund_policy, so usage is only partially implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

resend_sale_receiptResend sale receiptA

Destructive

Resend sale receipt. Reviewed native POST /sales/:id/resend_receipt; scope: edit_sales. Requires explicit per-call confirmation.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`sale_id`	Yes	Exact opaque provider ID, including native = padding.

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, readOnlyHint=false, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds non-obvious operational context the annotations cannot express: the required edit_sales scope, the native endpoint mapping, and the mandatory per-call confirmation. It could say more about side effects (does resending invalidate prior links?), hence not 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences, front-loaded with the action and then the operational constraints; no filler. The telegraphic 'Reviewed native POST...' phrasing is slightly opaque but still earns its place by pinning the endpoint.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 3-parameter, no-output-schema tool, the definition covers action, scope, endpoint, and the confirmation gate. The only missing element is guidance on when to choose this over adjacent sale tools, which is a minor gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so account, confirm, and sale_id are already documented in the schema (including the confirm semantics and the sale_id pattern/padding note). The description adds nothing beyond the schema here, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Resend sale receipt') and even names the underlying native endpoint POST /sales/:id/resend_receipt, so the action is unambiguous. It does not explicitly contrast itself with nearby siblings like refund_sale or mark_sale_as_shipped, so it stops short of 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives real prerequisites ('scope: edit_sales', 'Requires explicit per-call confirmation'), which tells the agent when it may call but not when it should prefer this over alternatives. No when-not or alternative-tool guidance is offered.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

restore_sale_accessRestore sale accessA

Destructive

Restore sale access. Reviewed native PUT /sales/:id/undo_revoke_access; scope: edit_sales. Requires explicit per-call confirmation.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`sale_id`	Yes	Exact opaque provider ID, including native = padding.

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare destructiveHint=true, idempotentHint=false, openWorldHint=true; the description adds the required scope (edit_sales), the native endpoint, and the explicit per-call confirmation requirement, which is meaningful beyond the annotations. It doesn't, however, disclose side effects or reversibility in more detail.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences, front-loaded with the action and followed by scope and confirmation requirements. Slightly terse but wastes no words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with rich annotations and full schema descriptions, the description covers the essential prerequisites (scope, confirmation). It could mention side effects or the access model, but is largely complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents all three parameters. The description adds no parameter-level detail beyond what the schema provides; baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (restore) and resource (sale access), and the title matches. It distinguishes itself from the inverse sibling revoke_sale_access by verb, but the description doesn't explicitly name siblings or clarify the access model (what was revoked, from whom).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implied usage: restore access, requiring confirmation. It alludes to prerequisites ('requires explicit per-call confirmation') but doesn't say when to use it vs alternatives like revoke_sale_access or refund_sale, nor when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

revoke_sale_accessRevoke sale accessA

Destructive

Revoke sale access. Reviewed native PUT /sales/:id/revoke_access; scope: edit_sales. Requires explicit per-call confirmation.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`sale_id`	Yes	Exact opaque provider ID, including native = padding.

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description adds value by disclosing the required scope (edit_sales) and the confirmation requirement, both of which are not in the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short clauses, front-loaded with the action, then endpoint/scope, then a safety-relevant constraint. No filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, non-idempotent, open-world mutation with no output schema, the description supplies scope, confirmation requirement, and native endpoint mapping, which is solid. It could go further by noting the inverse relationship to restore_sale_access or the irreversibility implication, but the essentials are present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents account, confirm, and sale_id with meaningful descriptions including the confirmation guidance. The description's note about explicit per-call confirmation reinforces the schema's confirm parameter but adds no syntax or format detail beyond it. Baseline 3 is correct.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Revoke) and resource (sale access), which is clear enough to distinguish from close siblings like restore_sale_access and refund_sale. It doesn't explicitly name those siblings, but the inverse relationship is obvious from the verb.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Adds 'Requires explicit per-call confirmation,' which is a genuine usage condition, and the mapping to the native endpoint helps the agent place the call. It doesn't name restore_sale_access as the inverse action or state when NOT to use this, so it falls short of an explicit alternatives statement.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

rotate_licenseRotate licenseB

Destructive

Rotate license. Reviewed native PUT /licenses/rotate; scope: edit_products. Requires explicit per-call confirmation.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`product_id`	Yes	(the unique ID of the product — copy it from the license key block on the product's Content tab, or use the id field returned by the GET /products endpoint)
`output_file`	Yes	Required absolute NEW owner-private file for the replacement license receipt; no overwrite.

TDQS

B3.1/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the risk profile is covered. The description adds genuinely new context beyond those fields: the required scope (edit_products) and the mandatory per-call confirmation. It still omits the core behavioral consequence for a destructive rotation — whether the previously issued key stops working.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short clauses, front-loaded with the action and then the endpoint, scope, and confirmation constraint. No filler. The telegraphic style ('Reviewed native PUT') is dense but each fragment carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, non-idempotent, non-idempotent tool with no output schema, the description covers scope and confirmation but leaves the key question unanswered: what rotation does to the existing license key and whether it is recoverable. With a fully documented schema, the remaining gap is behavioral rather than parameter-related, keeping it at minimum-viable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all four parameters (account, confirm, product_id, output_file) are already documented, including the note that output_file must be a new non-overwritten path. The description adds no parameter-level detail beyond the schema, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

Names a specific verb and resource ('Rotate license') and identifies the underlying operation (PUT /licenses/rotate), so the action is identifiable. However, it never explains what 'rotate' actually does (issue a replacement key, invalidate the old one) and gives no differentiation from siblings like enable_license, disable_license, or verify_license that also operate on licenses.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

States two real preconditions: the edit_products scope and that explicit per-call confirmation is required, which is actionable guidance. It does not say when to choose rotation over disable_license/revoke_sale_access, or under what circumstances rotation is the right remedy, leaving alternative selection to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

submit_commerce_batchExecute exact reviewed effectsB

Destructive

Confirmed ordered native effects, all prevalidated before first request, exact hash checked, stops first failure with known/unattempted receipts. No retry or implicit continuation.

ParametersJSON Schema

Name	Required	Description
`tasks`	Yes	One to twenty exact ordered native effects. No replacement-key output. Nested arguments cannot override profile/confirmation or carry credentials/files.
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`review_sha256`	Yes

TDQS

B3.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructive=true, idempotent=false, openWorld=true, so the safety profile is covered; the description adds genuinely new behavior: first-failure stop, ordered execution, known/unattempted receipts, and an explicit no-retry/no-implicit-continuation guarantee. It still omits auth/scope requirements and whether already-executed tasks in the same batch are rolled back or left applied.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two dense sentences with no filler, and the failure/no-retry guarantees are front-loaded. The extreme compression, however, borders on cryptic and costs some immediate comprehension.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description must carry return semantics, yet 'known/unattempted receipts' is never explained (format, per-task status, ordering). For a destructive, up-to-20-effect batch with no idempotency, the description should also mention auth/prerequisite context and the preview/naming relationship, which it does not.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 75%, so the schema already documents tasks, account, and confirm. The description adds only the 'exact hash checked' constraint for review_sha256 and the 'ordered' property of tasks, but does not clarify account inheritance/credential rules or the confirm flag's interaction with review_sha256.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description conveys the operation — submitting a batch of confirmed native effects — but never uses an explicit verb like 'execute' or 'submit', relying on the telegraphic phrase 'Confirmed ordered native effects.' It does not differentiate itself from the obvious sibling preview_commerce_batch, which is the natural counterpoint to a review_sha256-gated batch tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'all prevalidated before first request' implies a prior validation step (likely preview_commerce_batch) as a prerequisite, and 'confirmed' plus the schema's 'Set true only when the user asked for exactly this action' hints at the confirmation gate. However, the when-to-use versus the preview sibling and the semantics of the confirm flag are left to inference rather than stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_custom_fieldUpdate custom fieldA

Destructive

Update custom field. Reviewed native PUT /products/:product_id/custom_fields/:name; scope: edit_products. Requires explicit per-call confirmation.

ParametersJSON Schema

Name	Required	Description
`name`	Yes	Exact existing field name; encoded as one URL segment.
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`required`	Yes	(true or false)
`product_id`	Yes	Exact opaque provider ID, including native = padding.

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so safety is partly covered. The description adds genuinely useful non-obvious context: the OAuth scope needed (edit_products) and that per-call confirmation is mandatory, which is not derivable from the annotations. It still doesn't say what is overwritten or whether the change is reversible.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three compact sentences, front-loaded with the action before the endpoint and scope details. No filler, though the statement 'Reviewed native PUT ...' is somewhat internal jargon rather than agent-facing guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive mutation with no output schema, the description supplies the endpoint, required scope, and confirmation obligation, which is most of what an agent needs to invoke it safely. Missing only an explicit statement of the sibling boundary (create/delete counterparts) and the reversibility of the update.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all five parameters are already documented in the schema. The sentence 'Requires explicit per-call confirmation' loosely reinforces the purpose of the confirm flag, but no format, encoding, or constraint detail is added beyond what the schema already provides. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Update custom field') and pins it to the native endpoint PUT /products/:product_id/custom_fields/:name, which removes ambiguity about what is being mutated. It does not explicitly distinguish itself from sibling create_custom_field or delete_custom_field, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Mentions the required scope (edit_products) and a confirmation requirement, which implies context, but never states when to reach for this tool versus create_custom_field, delete_custom_field, or get_custom_field. No explicit when-not guidance is given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_offer_codeUpdate offer codeA

Destructive

Update offer code. Reviewed native PUT /products/:product_id/offer_codes/:id; scope: edit_products. Requires explicit per-call confirmation.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`product_id`	Yes	Exact opaque provider ID, including native = padding.
`offer_code_id`	Yes	Exact opaque provider ID, including native = padding.
`max_purchase_count`	No
`minimum_amount_cents`	No	(optional) Minimum order total in cents required for the offer code to apply

TDQS

A3.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructive=true, idempotent=false, and readOnly=false, so the safety profile is covered. The description adds genuinely new context: the required OAuth scope (edit_products) and the explicit confirmation mandate, both of which an agent needs before invoking. It stops short of saying what gets overwritten or what the response contains.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two compact sentences with no padding, and the operation identity plus endpoint are front-loaded. The only wasted words are the leading 'Update offer code', which duplicates the title with no added information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, non-idempotent mutation with 6 parameters and no output schema, auth scope and confirmation are covered but key questions remain unanswered: whether omitted fields are cleared or preserved, and what happens to redeemers of the code. Adequate but with meaningful gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 83%, so the schema already documents nearly all parameters (including the confirm and account semantics). The description adds nothing about parameter meaning, formats, or the partial-vs-full update behavior for max_purchase_count and minimum_amount_cents. Baseline 3 applies when the schema carries the load.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The second sentence pins down the exact operation as a native PUT to /products/:product_id/offer_codes/:id, which is a specific verb+resource. However, the opening sentence 'Update offer code' merely restates the name and title, and the description never distinguishes this from siblings like create_offer_code, delete_offer_code, or update_product. Clear purpose, no sibling differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Requires explicit per-call confirmation' and 'scope: edit_products' give a real prerequisite and permission gate, which is more than most updates offer. But it never states when to reach for this tool versus editing offer codes through other flows, nor any exclusions, leaving usage largely implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_productUpdate productB

Destructive

Update product. Reviewed native PUT /products/:id; scope: edit_products. Requires explicit per-call confirmation.

ParametersJSON Schema

Name	Required	Description
`name`	No	(optional)
`tags`	No	(optional) array of tag strings; full replacement
`price`	No	(optional) in the smallest currency unit; not allowed for tiered memberships — use the variant endpoints to manage tier pricing
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`category`	No	(optional) full category path from GET /v2/categories, e.g. "design/ui-and-web/figma"; cannot be sent with taxonomy_id
`is_adult`	No	(optional, true or false)
`product_id`	Yes	Exact opaque provider ID, including native = padding.
`description`	No	(optional) HTML
`taxonomy_id`	No	(optional) numeric category ID; alias for category, cannot be sent with category
`refund_period`	No	(optional, "inherit", "none", "7", "14", "30", or "183") sets a product-level refund policy; "inherit" switches the product back to the account default. Only available when the account-level refund policy is not in effect; otherwise use PUT /v2/refund_policy
`custom_receipt`	No	(optional)
`custom_summary`	No	(optional)
`custom_permalink`	No	(optional)
`quantity_enabled`	No	(optional, true or false)
`refund_fine_print`	No	(optional) fine print for the product-level refund policy; requires refund_period unless the product already has one enabled, and cannot be combined with refund_period "inherit". Empty string clears it
`customizable_price`	No	(optional, true or false)
`max_purchase_count`	No	(optional)
`price_currency_type`	No	(optional) ISO currency code
`suggested_price_cents`	No	(optional)
`display_product_reviews`	No	(optional, true or false)
`should_show_sales_count`	No	(optional, true or false)
`has_same_rich_content_for_all_variants`	No	(optional, true or false) switches between product-level and per-variant rich content

TDQS

B3.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true. The description adds genuinely new context beyond those flags: the required auth scope (edit_products) and the mandatory per-call confirmation, plus the PUT semantics implying replacement behavior. It stops short of stating what happens to omitted fields, which for a destructive PUT would be valuable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences, front-loaded, with no filler. Minor waste in the opening 'Update product' sentence that duplicates the title rather than stating anything new, but overall efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 23-parameter destructive mutation with no output schema, the description covers auth scope and confirmation but omits the practical consequence of a PUT-style update (whether unspecified fields are cleared or preserved) and any response behavior. Adequate but leaves meaningful gaps an agent would want before calling a destructive tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the schema already documents all 23 parameters richly, including mutual exclusions (category vs taxonomy_id), enum values, and edge cases like refund_period. The description adds no parameter-level meaning, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence 'Update product' essentially restates the name and title, adding little on its own. The follow-up 'Reviewed native PUT /products/:id; scope: edit_products' does clarify that this is a product-level update tied to a specific endpoint and scope, but it never distinguishes this tool from sibling mutators like update_variant, update_offer_code, or create_product.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Requires explicit per-call confirmation' gives one concrete usage prerequisite. However, there is no guidance on when to prefer this over create_product, update_variant, or the variant endpoints (which the schema itself references for tiered pricing), so the agent must infer routing from siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_refund_policyUpdate refund policyB

Destructive

Update refund policy. Reviewed native PUT /refund_policy; scope: account. Requires explicit per-call confirmation.

ParametersJSON Schema

Name	Required	Description
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`fine_print`	No	Optional. Max 3000 characters. HTML is stripped. Send an empty value to clear it.
`refund_period`	Yes	Required. One of "none", "7", "14", "30", or "183".

TDQS

B3.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: that this maps to a native PUT /refund_policy, that it operates at account scope, and that per-call confirmation is required. It still omits what specifically gets overwritten when the policy is replaced.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short, front-loaded fragments with no filler; the confirmation requirement is stated early. The 'Reviewed native PUT /refund_policy' fragment is more provenance than actionable information, which slightly dilutes the otherwise tight structure.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, non-idempotent write with four parameters and no output schema, the description covers confirmation and scope but never states which settings are mutable or what happens to unspecified fields. It is adequate alongside the annotations and rich schema, but leaves the mutation semantics thin.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, including enum values for refund_period, the fine_print length/HTML-stripping/clearing semantics, and the account label caveat, so the schema carries the load. The description adds no parameter-level meaning beyond that, which is the expected baseline when coverage is high.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Update refund policy', which largely restates the tool name/title rather than adding a distinct verb+resource framing. The 'scope: account' note and the PUT provenance hint at the affected resource, but there is no differentiation from the sibling get_refund_policy or from other update_* tools. Purpose is inferable but not enriched.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Requires explicit per-call confirmation' gives one concrete precondition for invoking the tool, and the confirm parameter reinforces it. However, there is no guidance on when to prefer this over get_refund_policy or how it relates to the wider refund/policy siblings, so usage is only implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_variantUpdate variantC

Destructive

Update variant. Reviewed native PUT /products/:product_id/variant_categories/:variant_category_id/variants/:id; scope: edit_products. Requires explicit per-call confirmation.

ParametersJSON Schema

Name	Required	Description
`name`	No
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`product_id`	Yes	Exact opaque provider ID, including native = padding.
`variant_id`	Yes	Exact opaque provider ID, including native = padding.
`max_purchase_count`	No	(optional)
`variant_category_id`	Yes	Exact opaque provider ID, including native = padding.
`price_difference_cents`	No

TDQS

C2.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the risk profile is covered structurally. The description adds two genuinely useful facts beyond the annotations: the required OAuth scope (edit_products) and the explicit confirmation requirement, which is meaningful for a destructive mutation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Compact and front-loaded: identity, endpoint, scope, and confirmation requirement in two short clauses. It wastes little space, though the opening verb+resource pair duplicates the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, non-idempotent mutation with no output schema, the agent gets scope and confirmation but not the consequences of the update (what changes persist, reversibility, or error behavior on missing IDs). Adequate but with real gaps given the tool's risk level.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 75%, so the schema carries most parameter meaning (IDs, account label, confirm semantics). The description adds nothing about the mutable fields (name, price_difference_cents, max_purchase_count) nor about how the three IDs are scoped relative to each other, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence 'Update variant' essentially restates the name and title, adding no distinguishing detail. The endpoint mapping (PUT .../variants/:id) confirms the resource and mutation type, but there is no differentiation from sibling mutations like update_variant_category or create_variant.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The only usage rule is 'Requires explicit per-call confirmation,' which is a precondition rather than a when-to-use signal. There is no guidance on when to prefer this over update_variant_category, create_variant, or delete_variant, leaving the agent to infer selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_variant_categoryUpdate variant categoryA

Destructive

Update variant category. Reviewed native PUT /products/:product_id/variant_categories/:id; scope: edit_products. Requires explicit per-call confirmation.

ParametersJSON Schema

Name	Required	Description
`title`	Yes
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.
`confirm`	No	Set true only when the user asked for exactly this action.
`product_id`	Yes	Exact opaque provider ID, including native = padding.
`variant_category_id`	Yes	Exact opaque provider ID, including native = padding.

TDQS

A3.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructive=true, idempotent=false and openWorld=true, so the safety profile is covered. The description adds non-obvious context the annotations do not: the required edit_products scope and the mandatory per-call confirmation, both of which directly affect whether an agent should call it.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short, front-loaded sentences with no filler. Slight redundancy between the name, title, and the first sentence, but the endpoint, scope and confirmation facts each earn their place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, non-idempotent mutation with no output schema, the description covers scope, confirmation and target endpoint, which is a reasonable minimum. It still omits what is actually mutated (title only?), whether unspecified fields are preserved, and failure behavior, leaving gaps an agent must infer.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 80%, so most parameters are documented in the schema itself; the description adds no parameter-level detail. The one gap is 'title', whose schema description is empty, and the description does not compensate by indicating which fields are updatable or whether updates are partial.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence merely restates the tool name, but the endpoint reference 'native PUT /products/:product_id/variant_categories/:id' supplies a specific verb+resource and implicitly distinguishes this from create_variant_category and delete_variant_category. An agent can tell it is the mutating update operation on a specific variant category.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'scope: edit_products' and 'Requires explicit per-call confirmation' give real preconditions for invocation, which is more than most siblings offer. However, there is no explicit when-to-use-vs-alternative guidance (e.g., when to update vs. delete vs. recreate a category).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

verify_licenseVerify licenseB

Read-onlyIdempotent

Verify license. Reviewed native POST /licenses/verify; scope: No OAuth required. Read only; no local effect approval required.

ParametersJSON Schema

Name	Required	Description	Default
`account`	No	Exact private profile label; never inherited credentials, ownership or scope proof.
`product_id`	Yes	Current native product ID, never deprecated permalink.

TDQS

B3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already establish readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint. The description adds genuinely new context beyond that: 'No OAuth required' discloses auth requirements, and 'no local effect approval required' discloses that no approval gate applies. It does not, however, explain the verification outcome or error behavior, and 'Read only' merely restates the annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

It is short, but the first two words are pure title restatement and the remaining text is a telegraphic list of endpoint and policy fragments rather than front-loaded prose. There is little waste, but the structure is cryptic rather than efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a simple, idempotent, read-only lookup with a fully documented 2-parameter schema and complete annotations, so the bar is relatively low. Still, with no output schema, the description never indicates what verification returns (a boolean, a status, failure modes) or how a failed verification is surfaced, leaving an agent to guess.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents both parameters (including the 'never inherited credentials' note on account and the 'never deprecated permalink' note on product_id). The description adds nothing about parameters, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence 'Verify license' simply restates the tool title and name, which by itself would be tautological. The follow-up adds some specificity by naming the underlying endpoint (POST /licenses/verify), but it never says what 'verify' means operationally (validity check? signature check?) or how it differs from siblings like enable_license, disable_license, or rotate_license.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives. The clauses 'Read only; no local effect approval required' describe behavior, not the conditions under which an agent should pick this tool over its many license-related siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

32 tool updatesv3.0.0Oct 5, 2026

Changedcreate_custom_field1 field changed

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval of this exact native effect or private file output."New value: +"Set true only when the user asked for exactly this action."

Changedcreate_offer_code4 fields changed
- removedInput schema / properties / amount_off / maximum
```
Removed value: -9007199254740991
```
- changedInput schema / properties / confirm / description
```
Previous value: -"Explicit approval of this exact native effect or private file output."New value: +"Set true only when the user asked for exactly this action."
```
- removedInput schema / properties / max_purchase_count / maximum
```
Removed value: -9007199254740991
```
- removedInput schema / properties / minimum_amount_cents / maximum
```
Removed value: -9007199254740991
```
Changedcreate_product4 fields changed
- changedInput schema / properties / confirm / description
```
Previous value: -"Explicit approval of this exact native effect or private file output."New value: +"Set true only when the user asked for exactly this action."
```
- removedInput schema / properties / max_purchase_count / maximum
```
Removed value: -9007199254740991
```
- removedInput schema / properties / price / maximum
```
Removed value: -9007199254740991
```
- removedInput schema / properties / suggested_price_cents / maximum
```
Removed value: -9007199254740991
```

Changedcreate_resource_subscription1 field changed

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval of this exact native effect or private file output."New value: +"Set true only when the user asked for exactly this action."

Changedcreate_variant4 fields changed
- changedInput schema / properties / confirm / description
```
Previous value: -"Explicit approval of this exact native effect or private file output."New value: +"Set true only when the user asked for exactly this action."
```
- removedInput schema / properties / max_purchase_count / maximum
```
Removed value: -9007199254740991
```
- removedInput schema / properties / price_difference_cents / maximum
```
Removed value: -9007199254740991
```
- removedInput schema / properties / price_difference_cents / minimum
```
Removed value: --9007199254740991
```

Changedcreate_variant_category1 field changed

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval of this exact native effect or private file output."New value: +"Set true only when the user asked for exactly this action."

Changeddecrement_license_uses1 field changed

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval of this exact native effect or private file output."New value: +"Set true only when the user asked for exactly this action."

Changeddelete_custom_field1 field changed

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval of this exact native effect or private file output."New value: +"Set true only when the user asked for exactly this action."

Changeddelete_offer_code1 field changed

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval of this exact native effect or private file output."New value: +"Set true only when the user asked for exactly this action."

Changeddelete_product1 field changed

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval of this exact native effect or private file output."New value: +"Set true only when the user asked for exactly this action."

Changeddelete_resource_subscription1 field changed

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval of this exact native effect or private file output."New value: +"Set true only when the user asked for exactly this action."

Changeddelete_variant1 field changed

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval of this exact native effect or private file output."New value: +"Set true only when the user asked for exactly this action."

Changeddelete_variant_category1 field changed

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval of this exact native effect or private file output."New value: +"Set true only when the user asked for exactly this action."

Changeddisable_license1 field changed

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval of this exact native effect or private file output."New value: +"Set true only when the user asked for exactly this action."

Changeddisable_product1 field changed

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval of this exact native effect or private file output."New value: +"Set true only when the user asked for exactly this action."

Changedenable_license1 field changed

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval of this exact native effect or private file output."New value: +"Set true only when the user asked for exactly this action."

Changedenable_product1 field changed

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval of this exact native effect or private file output."New value: +"Set true only when the user asked for exactly this action."

Changedexport_resources1 field changed

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval of this exact native effect or private file output."New value: +"Set true only when the user asked for exactly this action."

Changedincrement_license_uses1 field changed

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval of this exact native effect or private file output."New value: +"Set true only when the user asked for exactly this action."

Changedmark_sale_as_shipped1 field changed

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval of this exact native effect or private file output."New value: +"Set true only when the user asked for exactly this action."

Changedrefund_sale2 fields changed

removedInput schema / properties / amount_cents / maximum
```
Removed value: -9007199254740991
```

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval of this exact native effect or private file output."New value: +"Set true only when the user asked for exactly this action."

Changedresend_sale_receipt1 field changed

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval of this exact native effect or private file output."New value: +"Set true only when the user asked for exactly this action."

Changedrestore_sale_access1 field changed

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval of this exact native effect or private file output."New value: +"Set true only when the user asked for exactly this action."

Changedrevoke_sale_access1 field changed

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval of this exact native effect or private file output."New value: +"Set true only when the user asked for exactly this action."

Changedrotate_license1 field changed

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval of this exact native effect or private file output."New value: +"Set true only when the user asked for exactly this action."

Changedsubmit_commerce_batch1 field changed

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval of this exact native effect or private file output."New value: +"Set true only when the user asked for exactly this action."

Changedupdate_custom_field1 field changed

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval of this exact native effect or private file output."New value: +"Set true only when the user asked for exactly this action."

Changedupdate_offer_code3 fields changed

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval of this exact native effect or private file output."New value: +"Set true only when the user asked for exactly this action."

removedInput schema / properties / max_purchase_count / maximum
```
Removed value: -9007199254740991
```
removedInput schema / properties / minimum_amount_cents / maximum
```
Removed value: -9007199254740991
```

Changedupdate_product4 fields changed
- changedInput schema / properties / confirm / description
```
Previous value: -"Explicit approval of this exact native effect or private file output."New value: +"Set true only when the user asked for exactly this action."
```
- removedInput schema / properties / max_purchase_count / maximum
```
Removed value: -9007199254740991
```
- removedInput schema / properties / price / maximum
```
Removed value: -9007199254740991
```
- removedInput schema / properties / suggested_price_cents / maximum
```
Removed value: -9007199254740991
```

Changedupdate_refund_policy1 field changed

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval of this exact native effect or private file output."New value: +"Set true only when the user asked for exactly this action."

Changedupdate_variant4 fields changed
- changedInput schema / properties / confirm / description
```
Previous value: -"Explicit approval of this exact native effect or private file output."New value: +"Set true only when the user asked for exactly this action."
```
- removedInput schema / properties / max_purchase_count / maximum
```
Removed value: -9007199254740991
```
- removedInput schema / properties / price_difference_cents / maximum
```
Removed value: -9007199254740991
```
- removedInput schema / properties / price_difference_cents / minimum
```
Removed value: --9007199254740991
```

Changedupdate_variant_category1 field changed

changedInput schema / properties / confirm / description

Previous value: -"Explicit approval of this exact native effect or private file output."New value: +"Set true only when the user asked for exactly this action."

57 tool updatesv2.0.0Oct 3, 2026
- First observedcreate_custom_field
- First observedcreate_offer_code
- First observedcreate_product
- First observedcreate_resource_subscription
- First observedcreate_variant
- First observedcreate_variant_category
- First observeddecrement_license_uses
- First observeddelete_custom_field
- First observeddelete_offer_code
- First observeddelete_product
- First observeddelete_resource_subscription
- First observeddelete_variant
- First observeddelete_variant_category
- First observeddisable_license
- First observeddisable_product
- First observedenable_license
- First observedenable_product
- First observedexport_resources
- First observedget_custom_field
- First observedget_offer_code
- First observedget_operation_schema
- First observedget_payout
- First observedget_product
- First observedget_refund_policy
- First observedget_sale
- First observedget_subscriber
- First observedget_upcoming_payout
- First observedget_user
- First observedget_variant
- First observedget_variant_category
- First observedincrement_license_uses
- First observedlist_accounts
- First observedlist_categories
- First observedlist_custom_fields
- First observedlist_offer_codes
- First observedlist_payouts
- First observedlist_products
- First observedlist_resource_subscriptions
- First observedlist_sales
- First observedlist_subscribers
- First observedlist_variant_categories
- First observedlist_variants
- First observedmark_sale_as_shipped
- First observedpreview_commerce_batch
- First observedrefund_sale
- First observedresend_sale_receipt
- First observedrestore_sale_access
- First observedrevoke_sale_access
- First observedrotate_license
- First observedsubmit_commerce_batch
- First observedupdate_custom_field
- First observedupdate_offer_code
- First observedupdate_product
- First observedupdate_refund_policy
- First observedupdate_variant
- First observedupdate_variant_category
- First observedverify_license

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.4/5.0

Scored 2026-10-05 22:45 across 57 tools

Disambiguation4/5

Tools are well-differentiated by resource and action (e.g., list_products vs get_product, create_variant vs update_variant). A few potential overlaps exist, such as enable_product/disable_product vs update_product, and increment_license_uses vs decrement_license_uses, but descriptions clarify scope. The local meta-tools (preview_commerce_batch, submit_commerce_batch, export_resources) are distinct from native API tools.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern (list_products, create_product, get_sale, etc.), with no mixing of camelCase or other styles. Even special tools like preview_commerce_batch and submit_commerce_batch fit the pattern. This makes the set highly predictable.

Tool Count2/5

With 57 tools, the server is heavily over-provisioned for typical agent use. While each tool may earn its place individually, the sheer number increases selection complexity and cognitive load. A smaller, more focused set would likely suffice for most workflows.

Completeness5/5

The tool set provides comprehensive CRUD and lifecycle coverage across all major Gumroad resources: products, sales, licenses, variants, offer codes, custom fields, payouts, subscriptions, and account settings. Even edge cases like license rotation and refund policy updates are included. No obvious gaps remain.

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Related MCP Connectors

XGuard — Agent Execution Gateway B
io.github.moelayyan90
Scoped agent execution. Server-side credentials, policy, budgets and verifiable receipts.
Finance Security
81
VibeCart A
io.github.runjohnray2-lgtm
Agent-native commerce with trusted catalog, durable carts, and Stripe Checkout via MCP and UCP.
E-commerce & Retail Payments & Billing
41
FinCore Agentic Commerce A
io.github.athenalion
Agentic commerce with 58 MCP tools for product search, checkout, A2A negotiation, C-Suite analytics.
E-commerce & Retail Autonomous Agents
2
universalcartmerchantgate-mcp
com.clauxel.universalcartmerchantgate
Remote MCP for Universal Cart merchant readiness MCP, structured receipts, audit logs, and reviewer-
E-commerce & Retail Payments & Billing
2

Related MCP Servers

aimai-mcp-server
Security Databases Customer Support
fport
A
license
Not graded
quality
B
maintenance
Publishes a read-only data handle exposing SQL querying and URL fetching, plus a separately scoped read-write handle for actions like issuing refunds and sending customer email. Every call is checked against a permission set frozen before any untrusted text is read, with irreversible actions held behind one or two human approval signatures.
Updated 25 days ago (2026-09-11 13:34 UTC)
MIT
Qomviaofficial
E-commerce & Retail Marketing
qomvia
A
license
Not graded
quality
B
maintenance
Lets AI agents search merchant product catalogs, obtain signed offers with agent pricing, and run checkout sessions that always settle on the merchant's own payment page. It also scores any website's agent-readiness and exposes the published rubric checks.
Updated 5 days ago (2026-10-01 15:38 UTC)
MIT
io.github.zkp2p/peerofficial
Blockchain Cryptocurrency Payments & Billing
zkp2p
A
license
Not graded
quality
A
maintenance
Exposes protocol, indexer, market, checkout, and cash-flow operations to agents through read-only, cash-preparation, and full operator profiles, with state-changing actions previewed before execution unless explicitly authorized.
Updated 16 days ago (2026-09-21 05:59 UTC)
43 npm
MIT
Lemon Squeezy MCP Server
Payments & Billing E-commerce & Retail Finance
thenavidm
A
license
C
quality
B
maintenance
Enables AI agents to perform commerce and license operations—such as orders, subscriptions, refunds, checkouts, invoices, and webhooks—through shared MCP/CLI tasks with private profiles, explicit confirmations, reviewed batches, and bounded exports.
Updated 2 days ago (2026-10-05 09:37 UTC)
65
221 npm
AGPL 3.0

Gumroad MCP Server & CLI

Two ways to use it

Command line

MCP server, for your AI app

Which one

Features

Contents

1. What you can ask it

Inspect products, sales and subscribers before changing anything

Review refunds, shipping and access separately

Read a license without consuming a use

Manage variants, discounts and checkout fields

Payouts, refund policy and webhooks

2. Quick install

3. Set up Gumroad access

Seller authentication and independent license credentials

Scopes and provider authority

Several private seller and license profiles

4. Connect your client

Codex

Claude Code

Claude Desktop

Install the .mcpb extension

Manual config

Cursor

VS Code and Copilot

Windsurf

Zed

Gemini CLI

Docker

Cline and other local MCP clients

5. Check it works

6. Output, flags and exit codes

7. MCP or CLI and token cost

8. Every tool and argument

get_user

list_categories

list_products

get_product

create_product

update_product

delete_product

enable_product

disable_product

list_sales

get_sale

mark_sale_as_shipped

refund_sale

revoke_sale_access

restore_sale_access

resend_sale_receipt

list_subscribers

get_subscriber

verify_license

enable_license

disable_license

decrement_license_uses

rotate_license

create_variant_category

get_variant_category

update_variant_category

delete_variant_category

list_variant_categories

create_variant

get_variant

update_variant

delete_variant

list_variants

list_offer_codes

get_offer_code

create_offer_code

update_offer_code

delete_offer_code

list_custom_fields

create_custom_field

update_custom_field

delete_custom_field

create_resource_subscription

list_resource_subscriptions

delete_resource_subscription