Skip to main content
Glama

Fourthwall MCP Server & CLI

npm License YouTube X LinkedIn

Fourthwall MCP server and CLI for Codex and AI agents. 86 shared tasks for shop operations, isolated private profiles, reviewed batches, bounded metadata exports and private uploads.

One install, the same tools and guard on both surfaces. Fourthwall's official hosted OAuth MCP already provides broader coverage. This companion adds specific local workflows; read the comparison before choosing.

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

Two ways to use it

Command line

fourthwall-cli tools
fourthwall-cli list-products --page 0 --size 25 --agent
fourthwall-cli get-operation-schema --operation toggle_product_availability --agent
fourthwall-cli <command> --help

Use it directly or let your shell agent call it. Configure the intended private shop first. Every effect requires --confirm; output flags never grant approval.

MCP server, for your AI app

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

An MCP client launches the local stdio server and discovers the same tasks. Forward private credential settings through your client runtime. The full client/OS setup is in INSTALL.md.

Which one

Where you work

Surface

Codex or another agent with shell access

CLI, local MCP, or both

A supported local MCP app

Local MCP; desktop extension where supported

A script or CI task

CLI with private secrets supplied by the runtime

A URL-only hosted MCP client

Fourthwall's official hosted MCP is an alternative

Related MCP server: Shopify Store MCP Server

Features

Capability

CLI command

MCP tool

Get a webhook

fourthwall-cli get-webhook

get_webhook

Update a webhook

fourthwall-cli update-webhook

update_webhook

Delete a webhook

fourthwall-cli delete-webhook

delete_webhook

Set streaming status to started

fourthwall-cli start-streaming

start_streaming

Set streaming status to ended

fourthwall-cli end-streaming

end_streaming

Get or create a public token

fourthwall-cli get-public-token

get_public_token

Get a promotion by id

fourthwall-cli get-promotion

get_promotion

Update a promotion

fourthwall-cli update-promotion

update_promotion

Update product (offer) lifecycle state

fourthwall-cli update-product-state

update_product_state

Update product (offer) availability by id

fourthwall-cli toggle-product-availability

toggle_product_availability

Mark digital download as downloaded

fourthwall-cli mark-download-complete

mark_download_complete

Finish giveaway

fourthwall-cli finish-giveaway

finish_giveaway

Create or update giveaway

fourthwall-cli create-giveaway-checkout

create_giveaway_checkout

Disable giveaway config

fourthwall-cli disable-giveaway-checkout

disable_giveaway_checkout

Finish draw

fourthwall-cli finish-giveaway-draw

finish_giveaway_draw

Get gifting config

fourthwall-cli get-gifting-config

get_gifting_config

Update gifting config

fourthwall-cli update-gifting-config

update_gifting_config

Update a collection

fourthwall-cli update-collection

update_collection

Get products in a collection

fourthwall-cli get-collection-products

get_collection_products

Set collection products

fourthwall-cli update-collection-products

update_collection_products

Update collection availability

fourthwall-cli update-collection-availability

update_collection_availability

Get webhooks

fourthwall-cli list-webhooks

list_webhooks

Create a webhook

fourthwall-cli create-webhook

create_webhook

Get all promotions

fourthwall-cli list-promotions

list_promotions

Create a promotion

fourthwall-cli create-promotion

create_promotion

Get all products (offers)

fourthwall-cli list-products

list_products

Create a product

fourthwall-cli create-product

create_product

Attach images to a product

fourthwall-cli attach-product-images

attach_product_images

Remove images from a product

fourthwall-cli remove-product-images

remove_product_images

Confirm and link an uploaded digital file

fourthwall-cli confirm-digital-file-upload

confirm_digital_file_upload

Remove a digital file from a product

fourthwall-cli remove-digital-file

remove_digital_file

Request a presigned upload URL for a digital file

fourthwall-cli request-digital-file-upload-url

request_digital_file_upload_url

Request a pre-signed upload URL

fourthwall-cli request-media-upload-url

request_media_upload_url

List media library images

fourthwall-cli list-media-images

list_media_images

Save an uploaded image to the media library

fourthwall-cli save-media-image

save_media_image

Create a new giveaway

fourthwall-cli create-giveaway

create_giveaway

Create giveaway links

fourthwall-cli create-giveaway-links

create_giveaway_links

Create a gifting checkout

fourthwall-cli create-gifting-checkout

create_gifting_checkout

Create a fulfillment for an order

fourthwall-cli create-fulfillment

create_fulfillment

Validate DNS records

fourthwall-cli validate-dns

validate_dns

Get all collections

fourthwall-cli list-collections

list_collections

Create a new collection

fourthwall-cli create-collection

create_collection

Get webhook events

fourthwall-cli list-webhook-events

list_webhook_events

Get a webhook event

fourthwall-cli get-webhook-event

get_webhook_event

Get Thank You by id

fourthwall-cli get-thank-you

get_thank_you

Get contributions awaiting thank you

fourthwall-cli list-contributions

list_contributions

Get streaming status

fourthwall-cli get-streaming-status

get_streaming_status

Get current shop

fourthwall-cli get-shop

get_shop

Get current shop contact info

fourthwall-cli get-shop-contact

get_shop_contact

Get sample credit balance

fourthwall-cli get-sample-balance

get_sample_balance

List available reports

fourthwall-cli list-reports

list_reports

Get a report

fourthwall-cli get-report

get_report

Get product (offer) by id

fourthwall-cli get-product

get_product

Archive a product (offer)

fourthwall-cli archive-product

archive_product

Get product (offer) inventory by id

fourthwall-cli get-product-inventory

get_product_inventory

List product templates

fourthwall-cli list-product-templates

list_product_templates

Get product template details

fourthwall-cli get-product-template

get_product_template

Search product templates

fourthwall-cli search-product-templates

search_product_templates

Search product templates by page

fourthwall-cli search-product-templates-paged

search_product_templates_paged

Search product templates grouped by product family

fourthwall-cli search-product-templates-grouped

search_product_templates_grouped

Search product templates grouped by product family by page

fourthwall-cli search-product-templates-grouped-paged

search_product_templates_grouped_paged

List product templates by page

fourthwall-cli list-product-templates-paged

list_product_templates_paged

Browse product templates by category

fourthwall-cli list-product-templates-by-category

list_product_templates_by_category

Browse product templates by category by page

fourthwall-cli list-product-templates-by-category-paged

list_product_templates_by_category_paged

Get Pro subscription status

fourthwall-cli get-pro-subscription

get_pro_subscription

Get all orders

fourthwall-cli list-orders

list_orders

Get order by id

fourthwall-cli get-order

get_order

Get order by friendly id

fourthwall-cli get-order-by-friendly-id

get_order_by_friendly_id

List membership tiers

fourthwall-cli list-membership-tiers

list_membership_tiers

List members

fourthwall-cli list-members

list_members

Get member

fourthwall-cli get-member

get_member

Get all mailing list entries

fourthwall-cli list-mailing-list

list_mailing_list

Get all giveaway packages

fourthwall-cli list-giveaway-packages

list_giveaway_packages

Get giveaway links

fourthwall-cli get-giveaway-package

get_giveaway_package

Get draw

fourthwall-cli get-giveaway-draw

get_giveaway_draw

Get gift purchase by id

fourthwall-cli get-gift-purchase

get_gift_purchase

Get all donations

fourthwall-cli list-donations

list_donations

Get donation by id

fourthwall-cli get-donation

get_donation

Get DNS configuration status

fourthwall-cli get-dns-status

get_dns_status

Get collection by ID or slug

fourthwall-cli get-collection

get_collection

List private shop profiles

fourthwall-cli list-accounts

list_accounts

Inspect native contract

fourthwall-cli get-operation-schema

get_operation_schema

Review ordered shop effects

fourthwall-cli preview-shop-batch

preview_shop_batch

Execute reviewed shop effects

fourthwall-cli submit-shop-batch

submit_shop_batch

Export bounded private metadata

fourthwall-cli export-resources

export_resources

Upload exact bytes from a private receipt

fourthwall-cli upload-file

upload_file

Contents

1. What you can ask it

Ask for a bounded shop task, then review any change before execution:

  • List the first 25 products in the intended shop and report their state and availability separately.

  • Read this order and check the native fulfillment contract before preparing a tracking update.

  • Review these exact product availability changes, then execute only the batch I approve.

  • Export up to ten pages of order metadata into a new private file and report continuation.

  • Prepare a hidden digital product from this reviewed native payload. Do not publish it implicitly.

  • Upload this local image from a private receipt, then show the separate registration step.

These prompts name implemented operations. The terminal animation illustrates a reviewed workflow, rather than an authenticated shop recording.

2. Set up your account

A Fourthwall SUPER ADMIN can create shop API credentials in Settings > For Developers. Follow Fourthwall authentication. Shop Basic credentials grant full shop access; never describe them as a read-only key.

Choose exactly one private source: FOURTHWALL_USERNAME and FOURTHWALL_PASSWORD, an existing FOURTHWALL_ACCESS_TOKEN, or FOURTHWALL_CREDENTIALS_FILE. OAuth permission comes from the provider. This package does not implement consent, exchange or refresh.

The credential file is a JSON object containing either username/password or access_token. It must be an absolute regular non-symlink file, at most 64 KiB, outside repositories. On POSIX the process user must own it and permissions must be owner-only, normally 0600; restrict Windows ACLs separately. Never paste credentials into chat, command transcripts, issues, payloads or project configuration.

fourthwall-cli login
fourthwall-cli list-accounts --agent
fourthwall-cli doctor
fourthwall-cli doctor --network

Login prints instructions. Doctor checks local profiles and policy; the deliberate network option reads the current shop and validates its id. One successful read does not prove every permission, every task or resource ownership. File credentials are cached for the process: restart clients after rotating or revoking them.

Settings

Variable

Default

Meaning

FOURTHWALL_USERNAME, FOURTHWALL_PASSWORD

None

Shop API Basic credentials

FOURTHWALL_ACCESS_TOKEN

None

An existing scoped access token, in place of a username and password

FOURTHWALL_CREDENTIALS_FILE

None

Absolute owner-only JSON file holding a username and password or an access token

FOURTHWALL_ACCOUNTS

None

Named isolated profiles, each with one credential source

FOURTHWALL_DEFAULT_ACCOUNT

First profile

The profile a call uses when it names none

FOURTHWALL_READ_ONLY

0

1 hides and refuses every effect

FOURTHWALL_ALLOW_DESTRUCTIVE

1

0 refuses every effect, even confirmed

FOURTHWALL_CONFIRM

human

model lets confirm:true alone approve over MCP, for an agent with no person to ask

FOURTHWALL_AUDIT_LOG

None

File that records every attempted effect, without payloads or credentials

FOURTHWALL_REQUEST_TIMEOUT_MS

30000

Each request's deadline; no retries

FOURTHWALL_MIN_REQUEST_INTERVAL_MS

1000

Pacing between requests; Fourthwall's tighter limits are paced too

FOURTHWALL_SURFACE

full

search lists three tools that find, describe and run the rest

FOURTHWALL_TOOL_TIMEOUT_MS

None

Give up on any tool after this long

FOURTHWALL_HTTP_PORT, FOURTHWALL_HTTP_HOST, FOURTHWALL_HTTP_TOKEN

8787, 127.0.0.1, none

For --http; any host but 127.0.0.1 needs the bearer token

FOURTHWALL_HTTP_ALLOWED_ORIGINS

None

Comma-separated browser origins allowed to call --http; a page from any other site is refused

FOURTHWALL_DEBUG

0

1 prints debug lines on stderr

3. Install

Install Node 22+ in the runtime that launches the server. Use the complete INSTALL.md for Codex, Claude Code, Claude Desktop, Cursor, VS Code/Copilot, Windsurf, Zed, Gemini CLI, Docker and all three desktop OSes.

npm install -g @thenavidm/fourthwall-mcp-cli@latest
fourthwall-cli --version
fourthwall-cli tools
fourthwall-cli schema list-products

After configuring credentials privately, register the local server in Codex:

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

The MCP executable speaks stdio; it is not a hosted URL. The desktop extension is fourthwall-3.0.0.mcpb. Manual installation and updates use the host's supported extension screen. Choose one auth source, leave unused inputs empty and reconnect. GUI installation and authenticated provider tasks require their own validation.

4. Output and exit codes

Both binaries use the same schemas, handlers, validation and confirmation guard. --json prints JSON, --compact prints a single line, and --agent gives compact JSON with no prompts and never confirms a write. fourthwall-cli which <words> finds the command for a task. --select projects requested output fields. Errors go to stderr. --yes suppresses interactive presentation; it never replaces --confirm.

Exit

Meaning

0

Successful command

1

Unexpected error

2

Usage, invalid arguments, a refused effect, an unknown command or a hidden write

3

Not found

4

Provider authentication/permission failure

5

Other API/network failure

7

Provider quota/rate limit

10

Missing/invalid local configuration

fourthwall-cli list-products --page 0 --size 25 --agent
fourthwall-cli get-shop --account intended-shop --json
fourthwall-cli schema create-promotion

Tool path/query snake_case arguments become dash flags. Native body fields retain their exact camelCase flags, such as --fileName and --contentType; inspect --help instead of guessing a spelling. Objects and arrays use JSON. Use a private --payload-file for larger native bodies. Do not mix payload, payload-file and flat body fields.

5. Which surface and what each costs

Use CLI for scripts, shell agents and selected tasks. Use MCP where your app discovers tools and calls them directly. Both surfaces reach the same 86 tasks and enforce the same approval policy.

Surface

Context and task considerations

CLI

Command help and results enter context on demand; agent shell access is needed

MCP

Tool schemas may be loaded or deferred depending on the client; result content still costs context

Read-only MCP

Exposes 49 reads and excludes 37 effects locally

Official hosted MCP

Broad OAuth tooling with its own schemas, previews and confirmation flow

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

43,696

39,922

Claude Code's default, tool search, every message

1,610

1,608

SKILL.md, read once

518

662

Codex over the CLI, one task, median of five

130,541

108,648

Codex over MCP, the same task, median of five

77,214

77,915

The task was "find the command that creates a promotion, and the flags it requires". Every tool loaded costs less because parts that several tools repeated are written once. Over the CLI, every 3.0.0 run asked which, whose answer carries the command's help, where three 2.0.1 runs tried schema without a command and then read the whole command list; the schema both versions read next is half the size on 3.0.0. Over MCP, Codex now prints create_promotion's payload with every promotion type and its fields, where it printed 2.0.1's as unknown, about 700 tokens more. SKILL.md costs 144 more because it says how approval works over MCP and how which finds a command, and lists every exit code.

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

6. Tools

49 reads and 37 confirmed effects. All 86 tasks follow below; nested native JSON fields come from the selected reviewed schema.

get_webhook

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Get a webhook

CLI: fourthwall-cli get-webhook. Policy: read.

Native: GET /open-api/v1.0/webhooks/{webhookConfigurationId}. Current source.

Argument

Type or constraint

Requirement

Meaning

webhook_configuration_id

string (minLength=1, maxLength=256)

Required

Native webhookConfigurationId

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

update_webhook

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Update a webhook

CLI: fourthwall-cli update-webhook. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/webhooks/{webhookConfigurationId}. Current source.

Argument

Type or constraint

Requirement

Meaning

webhook_configuration_id

string (minLength=1, maxLength=256)

Required

Native webhookConfigurationId

url

string

Optional

Native field

allowedTypes

array

Optional

Native field

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

confirm

boolean

Optional

Set true only when the user asked for exactly this action.

payload

object

Optional

Complete current native JSON body; cannot mix with native body flags or payload_file.

payload_file

string (minLength=1)

Optional

Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native body fields below must also satisfy their required fields/oneOf branch. Supply native flat fields, payload OR payload_file. The entire machine-readable schema is available through the CLI and get_operation_schema.

Native JSON field

Type or constraint

Requirement

Meaning

url

string

Required

Native field

allowedTypes

array

Required

Native field

delete_webhook

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Delete a webhook

CLI: fourthwall-cli delete-webhook. Policy: explicit confirmation.

Native: DELETE /open-api/v1.0/webhooks/{webhookConfigurationId}. Current source.

Argument

Type or constraint

Requirement

Meaning

webhook_configuration_id

string (minLength=1, maxLength=256)

Required

Native webhookConfigurationId

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

confirm

boolean

Optional

Set true only when the user asked for exactly this action.

start_streaming

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Sets streaming status to started for specified services

CLI: fourthwall-cli start-streaming. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/streaming/start. Current source.

Argument

Type or constraint

Requirement

Meaning

services

array

Optional

Native field

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

confirm

boolean

Optional

Set true only when the user asked for exactly this action.

payload

object

Optional

Complete current native JSON body; cannot mix with native body flags or payload_file.

payload_file

string (minLength=1)

Optional

Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native body fields below must also satisfy their required fields/oneOf branch. Supply native flat fields, payload OR payload_file. The entire machine-readable schema is available through the CLI and get_operation_schema.

Native JSON field

Type or constraint

Requirement

Meaning

services

array

Required

Native field

services.[].variant 1

value

Choose one

Native oneOf

services.[].variant1.type

string

Required

Native field

services.[].variant1.broadcasterId

string

Optional

Native field

services.[].variant1.broadcasterLogin

string

Optional

Native field

services.[].variant1.thumbnailUrl

string

Optional

Native field

end_streaming

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Sets streaming status to ended for specified services

CLI: fourthwall-cli end-streaming. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/streaming/end. Current source.

Argument

Type or constraint

Requirement

Meaning

services

array

Optional

Native field

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

confirm

boolean

Optional

Set true only when the user asked for exactly this action.

payload

object

Optional

Complete current native JSON body; cannot mix with native body flags or payload_file.

payload_file

string (minLength=1)

Optional

Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native body fields below must also satisfy their required fields/oneOf branch. Supply native flat fields, payload OR payload_file. The entire machine-readable schema is available through the CLI and get_operation_schema.

Native JSON field

Type or constraint

Requirement

Meaning

services

array

Required

Native field

get_public_token

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns an existing public token for the shop, or creates a new one if none exists

CLI: fourthwall-cli get-public-token. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/public-token. Current source.

Argument

Type or constraint

Requirement

Meaning

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

confirm

boolean

Optional

Set true only when the user asked for exactly this action.

output_file

string (minLength=1)

Required

Absolute NEW owner-private receipt file; exclusive0600 creation, no overwrite. Upload/public-token URLs never enter ordinary output.

get_promotion

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns a promotion by id

CLI: fourthwall-cli get-promotion. Policy: read.

Native: GET /open-api/v1.0/promotions/{promotionId}. Current source.

Argument

Type or constraint

Requirement

Meaning

promotion_id

string (minLength=1, maxLength=256)

Required

Native promotionId

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

update_promotion

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Updates an existing promotion's configuration. Only provided fields are updated; omitted fields remain unchanged. Status changes (activate/deactivate) are part of the same update call.

CLI: fourthwall-cli update-promotion. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/promotions/{promotionId}. Current source.

Argument

Type or constraint

Requirement

Meaning

promotion_id

string (minLength=1, maxLength=256)

Required

Native promotionId

limits

object

Optional

Native field

requirements

object

Optional

Native field

appliesTo

union

Optional

Native field

status

LIVE, ENDED

Optional

Native field

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

confirm

boolean

Optional

Set true only when the user asked for exactly this action.

payload

object

Optional

Complete current native JSON body; cannot mix with native body flags or payload_file.

payload_file

string (minLength=1)

Optional

Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native body fields below must also satisfy their required fields/oneOf branch. Supply native flat fields, payload OR payload_file. The entire machine-readable schema is available through the CLI and get_operation_schema.

Native JSON field

Type or constraint

Requirement

Meaning

limits

object

Optional

Native field

limits.maximumUse

integer (format=int32)

Optional

Native field

limits.oneUsePerCustomer

boolean

Required

Native field

requirements

object

Optional

Native field

requirements.minimumOrderValue

object

Optional

Native field

requirements.minimumOrderValue.value

number (minimum=0)

Required

Native field

requirements.minimumOrderValue.currency

string

Required

Native field

appliesTo

union

Optional

Native field

appliesTo.variant 1

value

Choose one

Native oneOf

appliesTo.variant1.type

string

Optional

Native field

appliesTo.variant 2

value

Choose one

Native oneOf

appliesTo.variant2.productIds

array

Optional

Native field

appliesTo.variant2.oncePerOrder

boolean

Optional

Native field

status

LIVE, ENDED

Optional

Native field

update_product_state

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Transitions the product between PUBLIC and HIDDEN. Use DELETE /products/{productId} to archive — ARCHIVED is not reachable here. The sold-out (available) flag is preserved; flip it via PUT /products/{productId}/availability. Idempotent: no-op if the product is already in the requested state.

CLI: fourthwall-cli update-product-state. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/products/{productId}/state. Current source.

Argument

Type or constraint

Requirement

Meaning

product_id

string (minLength=1, maxLength=256)

Required

Native productId

state

PUBLIC, HIDDEN

Optional

Target lifecycle state. PUBLIC makes the product visible on the storefront; HIDDEN keeps it unlisted. The sold-out (available) flag is preserved across the transition — use PUT /products/{productId}/availability to flip it.

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

confirm

boolean

Optional

Set true only when the user asked for exactly this action.

payload

object

Optional

Complete current native JSON body; cannot mix with native body flags or payload_file.

payload_file

string (minLength=1)

Optional

Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native body fields below must also satisfy their required fields/oneOf branch. Supply native flat fields, payload OR payload_file. The entire machine-readable schema is available through the CLI and get_operation_schema.

Native JSON field

Type or constraint

Requirement

Meaning

state

PUBLIC, HIDDEN

Required

Target lifecycle state. PUBLIC makes the product visible on the storefront; HIDDEN keeps it unlisted. The sold-out (available) flag is preserved across the transition — use PUT /products/{productId}/availability to flip it.

toggle_product_availability

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Updates a product (offer) availability

CLI: fourthwall-cli toggle-product-availability. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/products/{productId}/availability. Current source.

Argument

Type or constraint

Requirement

Meaning

product_id

string (minLength=1, maxLength=256)

Required

Native productId

available

boolean

Optional

Native field

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

confirm

boolean

Optional

Set true only when the user asked for exactly this action.

payload

object

Optional

Complete current native JSON body; cannot mix with native body flags or payload_file.

payload_file

string (minLength=1)

Optional

Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native body fields below must also satisfy their required fields/oneOf branch. Supply native flat fields, payload OR payload_file. The entire machine-readable schema is available through the CLI and get_operation_schema.

Native JSON field

Type or constraint

Requirement

Meaning

available

boolean

Required

Native field

mark_download_complete

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Marks digital download as downloaded. If no downloads exist for a digital order and defaultFileUrl is provided in the request body, creates a download with that URL and marks it as downloaded.

CLI: fourthwall-cli mark-download-complete. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/order/{orderId}/downloaded. Current source.

Argument

Type or constraint

Requirement

Meaning

order_id

string (minLength=1, maxLength=256)

Required

Native orderId

defaultFileUrl

string

Optional

Native field

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

confirm

boolean

Optional

Set true only when the user asked for exactly this action.

payload

object

Optional

Complete current native JSON body; cannot mix with native body flags or payload_file.

payload_file

string (minLength=1)

Optional

Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native body fields below must also satisfy their required fields/oneOf branch. Supply native flat fields, payload OR payload_file. The entire machine-readable schema is available through the CLI and get_operation_schema.

Native JSON field

Type or constraint

Requirement

Meaning

defaultFileUrl

string

Optional

Native field

finish_giveaway

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Finish giveaway and select winners

CLI: fourthwall-cli finish-giveaway. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/giveaways/giveaways/{id}/finish/twitch. Current source.

Argument

Type or constraint

Requirement

Meaning

id

string (minLength=1, maxLength=256)

Required

Native id

participants

array

Optional

Native field

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

confirm

boolean

Optional

Set true only when the user asked for exactly this action.

payload

object

Optional

Complete current native JSON body; cannot mix with native body flags or payload_file.

payload_file

string (minLength=1)

Optional

Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native body fields below must also satisfy their required fields/oneOf branch. Supply native flat fields, payload OR payload_file. The entire machine-readable schema is available through the CLI and get_operation_schema.

Native JSON field

Type or constraint

Requirement

Meaning

participants

array

Required

Native field

participants.[].userId

string

Required

Native field

participants.[].userName

string

Required

Native field

create_giveaway_checkout

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Creates a new giveaway or updates existing one

CLI: fourthwall-cli create-giveaway-checkout. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/giveaways/giveaway-checkout. Current source.

Argument

Type or constraint

Requirement

Meaning

heading

string

Optional

Native field

description

string

Optional

Native field

iconUrl

string

Optional

Native field

buttonText

string

Optional

Native field

disabled

boolean

Optional

Native field

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

confirm

boolean

Optional

Set true only when the user asked for exactly this action.

payload

object

Optional

Complete current native JSON body; cannot mix with native body flags or payload_file.

payload_file

string (minLength=1)

Optional

Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native body fields below must also satisfy their required fields/oneOf branch. Supply native flat fields, payload OR payload_file. The entire machine-readable schema is available through the CLI and get_operation_schema.

Native JSON field

Type or constraint

Requirement

Meaning

heading

string

Required

Native field

description

string

Required

Native field

iconUrl

string

Required

Native field

buttonText

string

Required

Native field

disabled

boolean

Optional

Native field

disable_giveaway_checkout

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

disables a giveaway config

CLI: fourthwall-cli disable-giveaway-checkout. Policy: explicit confirmation.

Native: DELETE /open-api/v1.0/giveaways/giveaway-checkout. Current source.

Argument

Type or constraint

Requirement

Meaning

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

confirm

boolean

Optional

Set true only when the user asked for exactly this action.

finish_giveaway_draw

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Finish draw and select winners

CLI: fourthwall-cli finish-giveaway-draw. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/gifting/draw/{id}/finish. Current source.

Argument

Type or constraint

Requirement

Meaning

id

string (minLength=1, maxLength=256)

Required

Native id

participants

array

Optional

Native field

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

confirm

boolean

Optional

Set true only when the user asked for exactly this action.

payload

object

Optional

Complete current native JSON body; cannot mix with native body flags or payload_file.

payload_file

string (minLength=1)

Optional

Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native body fields below must also satisfy their required fields/oneOf branch. Supply native flat fields, payload OR payload_file. The entire machine-readable schema is available through the CLI and get_operation_schema.

Native JSON field

Type or constraint

Requirement

Meaning

participants

array

Required

Native field

participants.[].variant 1

value

Choose one

Native oneOf

participants.[].variant1.service

string

Required

Native field

participants.[].variant1.userId

string

Optional

Native field

participants.[].variant1.userName

string

Optional

Native field

get_gifting_config

Returns the calling shop's saved gifting rules. Returns a default-shaped config when none is persisted yet.

CLI: fourthwall-cli get-gifting-config. Policy: read.

Native: GET /open-api/v1.0/gifting/config. Current source.

Argument

Type or constraint

Requirement

Meaning

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

update_gifting_config

Writes the four creator-controlled gifting rule fields. Validation (duration 20-180s, valid shipping/products) and the one-platform-per-shop mutex are enforced server-side. Upserts: a first-ever PUT materializes the config row.

CLI: fourthwall-cli update-gifting-config. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/gifting/config. Current source.

Argument

Type or constraint

Requirement

Meaning

enabled

boolean

Optional

Master flag. Off pauses purchasability without losing the rest.

entryTimeLimitSeconds

integer (format=int32)

Optional

Entry time limit in seconds. Validated 20-180.

shipping

union

Optional

Native field

products

union

Optional

Native field

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

confirm

boolean

Optional

Set true only when the user asked for exactly this action.

payload

object

Optional

Complete current native JSON body; cannot mix with native body flags or payload_file.

payload_file

string (minLength=1)

Optional

Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native body fields below must also satisfy their required fields/oneOf branch. Supply native flat fields, payload OR payload_file. The entire machine-readable schema is available through the CLI and get_operation_schema.

Native JSON field

Type or constraint

Requirement

Meaning

enabled

boolean

Required

Master flag. Off pauses purchasability without losing the rest.

entryTimeLimitSeconds

integer (format=int32)

Required

Entry time limit in seconds. Validated 20-180.

shipping

union

Required

Native field

shipping.variant 1

value

Choose one

Native oneOf

shipping.variant1.type

string

Required

Native field

shipping.variant1.type

ALL_CREATOR

Optional

Native field

shipping.variant 2

value

Choose one

Native oneOf

shipping.variant2.type

string

Required

Native field

shipping.variant2.type

ALL_WINNER

Optional

Native field

shipping.variant 3

value

Choose one

Native oneOf

shipping.variant3.type

string

Required

Native field

shipping.variant3.max

number (format=double)

Optional

Native field

shipping.variant3.type

MAX_CREATOR

Optional

Native field

products

union

Required

Native field

products.variant 1

value

Choose one

Native oneOf

products.variant1.type

string

Required

Native field

products.variant1.type

ALL

Optional

Native field

products.variant 2

value

Choose one

Native oneOf

products.variant2.type

string

Required

Native field

products.variant2.offerIds

array

Optional

Native field

products.variant2.type

EXCLUDED

Optional

Native field

products.variant 3

value

Choose one

Native oneOf

products.variant3.type

string

Required

Native field

products.variant3.offerIds

array

Optional

Native field

products.variant3.type

SELECTED

Optional

Native field

update_collection

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Updates collection name, description, and/or product list

CLI: fourthwall-cli update-collection. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/collections/{collectionId}. Current source.

Argument

Type or constraint

Requirement

Meaning

collection_id

string (minLength=1, maxLength=256)

Required

Native collectionId

name

string

Optional

Native field

description

string

Optional

Native field

offerIds

array

Optional

List of product IDs to set in the collection

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

confirm

boolean

Optional

Set true only when the user asked for exactly this action.

payload

object

Optional

Complete current native JSON body; cannot mix with native body flags or payload_file.

payload_file

string (minLength=1)

Optional

Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native body fields below must also satisfy their required fields/oneOf branch. Supply native flat fields, payload OR payload_file. The entire machine-readable schema is available through the CLI and get_operation_schema.

Native JSON field

Type or constraint

Requirement

Meaning

name

string

Optional

Native field

description

string

Optional

Native field

offerIds

array

Optional

List of product IDs to set in the collection

get_collection_products

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns paginated products in a collection with optional status filtering. The maximum page size is 100 - larger values are capped at 100.

CLI: fourthwall-cli get-collection-products. Policy: read.

Native: GET /open-api/v1.0/collections/{collectionId}/products. Current source.

Argument

Type or constraint

Requirement

Meaning

collection_id

string (minLength=1, maxLength=256)

Required

Native collectionId

page

integer (minimum=0, format=int32, default=0)

Optional

Native page

size

integer (minimum=1, maximum=100, format=int32, default=20)

Optional

Number of elements per page. The maximum page size is 100 - larger values are capped at 100.

status

PUBLIC, AVAILABLE, SOLD_OUT, HIDDEN, ARCHIVED

Optional

Filter by product status

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

update_collection_products

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Sets the full list of product IDs in the collection

CLI: fourthwall-cli update-collection-products. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/collections/{collectionId}/products. Current source.

Argument

Type or constraint

Requirement

Meaning

collection_id

string (minLength=1, maxLength=256)

Required

Native collectionId

offerIds

array

Optional

Full list of product IDs to set in the collection

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

confirm

boolean

Optional

Set true only when the user asked for exactly this action.

payload

object

Optional

Complete current native JSON body; cannot mix with native body flags or payload_file.

payload_file

string (minLength=1)

Optional

Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native body fields below must also satisfy their required fields/oneOf branch. Supply native flat fields, payload OR payload_file. The entire machine-readable schema is available through the CLI and get_operation_schema.

Native JSON field

Type or constraint

Requirement

Meaning

offerIds

array

Required

Full list of product IDs to set in the collection

update_collection_availability

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Toggle collection availability (available/unavailable)

CLI: fourthwall-cli update-collection-availability. Policy: explicit confirmation.

Native: PUT /open-api/v1.0/collections/{collectionId}/availability. Current source.

Argument

Type or constraint

Requirement

Meaning

collection_id

string (minLength=1, maxLength=256)

Required

Native collectionId

available

boolean

Optional

Native field

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

confirm

boolean

Optional

Set true only when the user asked for exactly this action.

payload

object

Optional

Complete current native JSON body; cannot mix with native body flags or payload_file.

payload_file

string (minLength=1)

Optional

Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native body fields below must also satisfy their required fields/oneOf branch. Supply native flat fields, payload OR payload_file. The entire machine-readable schema is available through the CLI and get_operation_schema.

Native JSON field

Type or constraint

Requirement

Meaning

available

boolean

Required

Native field

list_webhooks

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Get webhooks

CLI: fourthwall-cli list-webhooks. Policy: read.

Native: GET /open-api/v1.0/webhooks. Current source.

Argument

Type or constraint

Requirement

Meaning

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

create_webhook

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Create a webhook

CLI: fourthwall-cli create-webhook. Policy: explicit confirmation.

Native: POST /open-api/v1.0/webhooks. Current source.

Argument

Type or constraint

Requirement

Meaning

url

string

Optional

Native field

allowedTypes

array

Optional

Native field

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

confirm

boolean

Optional

Set true only when the user asked for exactly this action.

payload

object

Optional

Complete current native JSON body; cannot mix with native body flags or payload_file.

payload_file

string (minLength=1)

Optional

Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native body fields below must also satisfy their required fields/oneOf branch. Supply native flat fields, payload OR payload_file. The entire machine-readable schema is available through the CLI and get_operation_schema.

Native JSON field

Type or constraint

Requirement

Meaning

url

string

Required

Native field

allowedTypes

array

Required

Native field

list_promotions

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns all promotions. The maximum page size is 100 - larger values are capped at 100.

CLI: fourthwall-cli list-promotions. Policy: read.

Native: GET /open-api/v1.0/promotions. Current source.

Argument

Type or constraint

Requirement

Meaning

page

integer (minimum=0, format=int32, default=0)

Optional

Native page

size

integer (minimum=1, maximum=100, format=int32, default=20)

Optional

Number of elements per page. The maximum page size is 100 - larger values are capped at 100.

codes

array

Optional

Filter by promotion code(s)

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

create_promotion

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Creates a promotion

CLI: fourthwall-cli create-promotion. Policy: explicit confirmation.

Native: POST /open-api/v1.0/promotions. Current source.

Argument

Type or constraint

Requirement

Meaning

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

confirm

boolean

Optional

Set true only when the user asked for exactly this action.

payload

union

Optional

Complete current native JSON body; cannot mix with native body flags or payload_file.

payload_file

string (minLength=1)

Optional

Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native body fields below must also satisfy their required fields/oneOf branch. Supply native flat fields, payload OR payload_file. The entire machine-readable schema is available through the CLI and get_operation_schema.

Native JSON field

Type or constraint

Requirement

Meaning

variant 1

value

Choose one

Native oneOf

variant1.type

string

Required

Native field

variant1.codes

array

Optional

Native field

variant1.discount

union

Optional

Native field

variant1.discount.variant 1

value

Choose one

Native oneOf

variant1.discount.variant1.type

string

Required

Native field

variant1.discount.variant1.percentage

number

Optional

Native field

variant1.discount.variant1.type

PERCENTAGE

Optional

Native field

variant1.requirements

object

Optional

Native field

variant1.requirements.newMembersOnly

boolean

Required

Native field

variant1.subscriptionType

union

Optional

Native field

variant1.subscriptionType.variant 1

value

Choose one

Native oneOf

variant1.subscriptionType.variant1.type

string

Required

Native field

variant1.subscriptionType.variant1.type

ALL

Optional

Native field

variant1.subscriptionType.variant 2

value

Choose one

Native oneOf

variant1.subscriptionType.variant2.type

string

Required

Native field

variant1.subscriptionType.variant2.type

ANNUAL

Optional

Native field

variant1.subscriptionType.variant 3

value

Choose one

Native oneOf

variant1.subscriptionType.variant3.type

string

Required

Native field

variant1.subscriptionType.variant3.type

MONTHLY

Optional

Native field

variant1.tiers

union

Optional

Native field

variant1.tiers.variant 1

value

Choose one

Native oneOf

variant1.tiers.variant1.type

string

Required

Native field

variant1.tiers.variant1.type

ALL

Optional

Native field

variant1.tiers.variant 2

value

Choose one

Native oneOf

variant1.tiers.variant2.type

string

Required

Native field

variant1.tiers.variant2.ids

array

Optional

Native field

variant1.tiers.variant2.type

SELECTED

Optional

Native field

variant1.type

MEMBERSHIPS_MULTI

Optional

Native field

variant 2

value

Choose one

Native oneOf

variant2.type

string

Required

Native field

variant2.code

string

Optional

Native field

variant2.discount

union

Optional

Native field

variant2.discount.variant 1

value

Choose one

Native oneOf

variant2.discount.variant1.type

string

Required

Native field

variant2.discount.variant1.percentage

number

Optional

Native field

variant2.discount.variant1.type

PERCENTAGE

Optional

Native field

variant2.requirements

object

Optional

Native field

variant2.requirements.newMembersOnly

boolean

Required

Native field

variant2.subscriptionType

union

Optional

Native field

variant2.subscriptionType.variant 1

value

Choose one

Native oneOf

variant2.subscriptionType.variant1.type

string

Required

Native field

variant2.subscriptionType.variant1.type

ALL

Optional

Native field

variant2.subscriptionType.variant 2

value

Choose one

Native oneOf

variant2.subscriptionType.variant2.type

string

Required

Native field

variant2.subscriptionType.variant2.type

ANNUAL

Optional

Native field

variant2.subscriptionType.variant 3

value

Choose one

Native oneOf

variant2.subscriptionType.variant3.type

string

Required

Native field

variant2.subscriptionType.variant3.type

MONTHLY

Optional

Native field

variant2.tiers

union

Optional

Native field

variant2.tiers.variant 1

value

Choose one

Native oneOf

variant2.tiers.variant1.type

string

Required

Native field

variant2.tiers.variant1.type

ALL

Optional

Native field

variant2.tiers.variant 2

value

Choose one

Native oneOf

variant2.tiers.variant2.type

string

Required

Native field

variant2.tiers.variant2.ids

array

Optional

Native field

variant2.tiers.variant2.type

SELECTED

Optional

Native field

variant2.type

MEMBERSHIPS_SINGLE

Optional

Native field

variant 3

value

Choose one

Native oneOf

variant3.type

string

Required

Native field

variant3.codes

array

Optional

Native field

variant3.discount

union

Optional

Native field

variant3.discount.variant 1

value

Choose one

Native oneOf

variant3.discount.variant1.type

string

Required

Native field

variant3.discount.variant1.money

object

Optional

Native field

variant3.discount.variant1.money.value

number (minimum=0)

Required

Native field

variant3.discount.variant1.money.currency

string

Required

Native field

variant3.discount.variant1.freeShipping

boolean

Optional

Native field

variant3.discount.variant1.type

FLAT_RATE

Optional

Native field

variant3.discount.variant 2

value

Choose one

Native oneOf

variant3.discount.variant2.type

string

Required

Native field

variant3.discount.variant2.type

FREE_SHIPPING

Optional

Native field

variant3.discount.variant 3

value

Choose one

Native oneOf

variant3.discount.variant3.type

string

Required

Native field

variant3.discount.variant3.percentage

number

Optional

Native field

variant3.discount.variant3.shipping

Excluded, Included, FreeLowestOnly, Free

Optional

Native field

variant3.discount.variant3.type

PERCENTAGE

Optional

Native field

variant3.requirements

object

Optional

Native field

variant3.requirements.minimumOrderValue

object

Optional

Native field

variant3.requirements.minimumOrderValue.value

number (minimum=0)

Required

Native field

variant3.requirements.minimumOrderValue.currency

string

Required

Native field

variant3.appliesToProducts

object

Optional

Native field

variant3.appliesToProducts.productIds

array

Required

Native field

variant3.appliesToProducts.oncePerOrder

boolean

Optional

Native field

variant3.limits

object

Optional

Native field

variant3.limits.maximumUse

integer (format=int32)

Optional

Native field

variant3.limits.oneUsePerCustomer

boolean

Required

Native field

variant3.type

SHOP_MULTI

Optional

Native field

variant 4

value

Choose one

Native oneOf

variant4.type

string

Required

Native field

variant4.code

string

Optional

Native field

variant4.discount

union

Optional

Native field

variant4.discount.variant 1

value

Choose one

Native oneOf

variant4.discount.variant1.type

string

Required

Native field

variant4.discount.variant1.money

object

Optional

Native field

variant4.discount.variant1.money.value

number (minimum=0)

Required

Native field

variant4.discount.variant1.money.currency

string

Required

Native field

variant4.discount.variant1.freeShipping

boolean

Optional

Native field

variant4.discount.variant1.type

FLAT_RATE

Optional

Native field

variant4.discount.variant 2

value

Choose one

Native oneOf

variant4.discount.variant2.type

string

Required

Native field

variant4.discount.variant2.type

FREE_SHIPPING

Optional

Native field

variant4.discount.variant 3

value

Choose one

Native oneOf

variant4.discount.variant3.type

string

Required

Native field

variant4.discount.variant3.percentage

number

Optional

Native field

variant4.discount.variant3.shipping

Excluded, Included, FreeLowestOnly, Free

Optional

Native field

variant4.discount.variant3.type

PERCENTAGE

Optional

Native field

variant4.requirements

object

Optional

Native field

variant4.requirements.minimumOrderValue

object

Optional

Native field

variant4.requirements.minimumOrderValue.value

number (minimum=0)

Required

Native field

variant4.requirements.minimumOrderValue.currency

string

Required

Native field

variant4.appliesToProducts

object

Optional

Native field

variant4.appliesToProducts.productIds

array

Required

Native field

variant4.appliesToProducts.oncePerOrder

boolean

Optional

Native field

variant4.limits

object

Optional

Native field

variant4.limits.maximumUse

integer (format=int32)

Optional

Native field

variant4.limits.oneUsePerCustomer

boolean

Required

Native field

variant4.type

SHOP_SINGLE

Optional

Native field

list_products

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns all products with pagination. The maximum page size is 100 - larger values are capped at 100.

CLI: fourthwall-cli list-products. Policy: read.

Native: GET /open-api/v1.0/products. Current source.

Argument

Type or constraint

Requirement

Meaning

page

integer (minimum=0, format=int32, default=0)

Optional

Native page

size

integer (minimum=1, maximum=100, format=int32, default=20)

Optional

Number of elements per page. The maximum page size is 100 - larger values are capped at 100.

search

string

Optional

Native search

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

create_product

Rate limit: 5 requests / minute per shop. See Rate limiting.

Creates a product from a design or a digital product.

CLI: fourthwall-cli create-product. Policy: explicit confirmation.

Native: POST /open-api/v1.0/products. Current source.

Argument

Type or constraint

Requirement

Meaning

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

confirm

boolean

Optional

Set true only when the user asked for exactly this action.

payload

object

Optional

Complete current native JSON body; cannot mix with native body flags or payload_file.

payload_file

string (minLength=1)

Optional

Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native body fields below must also satisfy their required fields/oneOf branch. Supply native flat fields, payload OR payload_file. The entire machine-readable schema is available through the CLI and get_operation_schema.

Native JSON field

Type or constraint

Requirement

Meaning

type

string

Required

Native field

variant 1

value

Choose one

Native oneOf

variant1.type

string

Required

Native field

variant1.productTemplateId

string

Optional

Id of the product template to render the design onto, from GET /open-api/v1.0/product-templates.

variant1.regions

array

Optional

Design regions to place on the product. Each region references a registered media image by id (register it via POST /open-api/v1.0/media/images and pass the returned id as imageId).

variant1.regions.[].region

string

Required

Name of the product region to place the image on, e.g. front or back.

variant1.regions.[].imageId

string

Required

Id of a registered media-library image to render on the region. Register the image first via POST /open-api/v1.0/media/images and pass the returned id here.

variant1.regions.[].placementId

string

Optional

Placement to target when placementStrategy is PLACEMENT_ID. Required for that strategy and ignored by the others.

variant1.regions.[].placementStrategy

AUTO, FILL_ALL, FULL_REGION, PLACEMENT_ID

Optional

How the image is placed on the region. Defaults to AUTO when omitted, and takes precedence over placementId/fillAllPlacements. - AUTO — let the renderer decide using the product's automation defaults (its preferred placement, or fill-all for products like mugs/stickers). - FILL_ALL — apply the image to every placement in the region. - FULL_REGION — render the image across the full region, skipping the preferred placement. - PLACEMENT_ID — target the single placement named by placementId (required for this strategy).

variant1.colors

array

Optional

Colors to render. Defaults to all available product colors when omitted. Values not offered by the product are ignored; the request is rejected with 400 if none of the supplied colors are available.

variant1.sizes

array

Optional

Sizes to include. Defaults to all available product sizes when omitted. Values not offered by the product are ignored; the request is rejected with 400 if none of the supplied sizes are available. When both colors and sizes are supplied, the request is also rejected with 400 if no requested color/size combination is an available variant.

variant1.name

string

Optional

Product name

variant1.description

string

Optional

Product description

variant1.profitMargin

number

Optional

Profit margin in USD applied on top of the base cost.

variant1.publishOnCreate

boolean

Optional

Publish the product immediately on creation. Defaults to false (product stays hidden).

variant1.type

design

Optional

Native field

variant 2

value

Choose one

Native oneOf

variant2.type

string

Required

Native field

variant2.name

string

Optional

Product name

variant2.description

string

Optional

Product description

variant2.price

number

Optional

Price set by the creator, in USD.

variant2.publishOnCreate

boolean

Optional

Publish the product immediately on creation. Defaults to false (product stays hidden).

variant2.type

digital

Optional

Native field

attach_product_images

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Attaches images to a product. Images should be uploaded first via the media upload endpoint.

CLI: fourthwall-cli attach-product-images. Policy: explicit confirmation.

Native: POST /open-api/v1.0/products/{productId}/images. Current source.

Argument

Type or constraint

Requirement

Meaning

product_id

string (minLength=1, maxLength=256)

Required

Native productId

images

array

Optional

List of images to attach

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

confirm

boolean

Optional

Set true only when the user asked for exactly this action.

payload

object

Optional

Complete current native JSON body; cannot mix with native body flags or payload_file.

payload_file

string (minLength=1)

Optional

Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native body fields below must also satisfy their required fields/oneOf branch. Supply native flat fields, payload OR payload_file. The entire machine-readable schema is available through the CLI and get_operation_schema.

Native JSON field

Type or constraint

Requirement

Meaning

images

array

Required

List of images to attach

images.[].url

string

Required

Image URL

images.[].width

integer (format=int32)

Required

Image width in pixels

images.[].height

integer (format=int32)

Required

Image height in pixels

remove_product_images

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Removes specified images from a product by their URLs.

CLI: fourthwall-cli remove-product-images. Policy: explicit confirmation.

Native: DELETE /open-api/v1.0/products/{productId}/images. Current source.

Argument

Type or constraint

Requirement

Meaning

product_id

string (minLength=1, maxLength=256)

Required

Native productId

imageUrls

array

Optional

List of image URLs to remove

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

confirm

boolean

Optional

Set true only when the user asked for exactly this action.

payload

object

Optional

Complete current native JSON body; cannot mix with native body flags or payload_file.

payload_file

string (minLength=1)

Optional

Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native body fields below must also satisfy their required fields/oneOf branch. Supply native flat fields, payload OR payload_file. The entire machine-readable schema is available through the CLI and get_operation_schema.

Native JSON field

Type or constraint

Requirement

Meaning

imageUrls

array

Required

List of image URLs to remove

confirm_digital_file_upload

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

After uploading a file to the presigned URL, call this endpoint to link the file to the product. The file must exist in storage before calling this endpoint.

CLI: fourthwall-cli confirm-digital-file-upload. Policy: explicit confirmation.

Native: POST /open-api/v1.0/products/{productId}/digital-files. Current source.

Argument

Type or constraint

Requirement

Meaning

product_id

string (minLength=1, maxLength=256)

Required

Native productId

fileUrl

string

Optional

The file URL returned from the upload-url endpoint

fileName

string

Optional

Display name for the file

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

confirm

boolean

Optional

Set true only when the user asked for exactly this action.

payload

object

Optional

Complete current native JSON body; cannot mix with native body flags or payload_file.

payload_file

string (minLength=1)

Optional

Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native body fields below must also satisfy their required fields/oneOf branch. Supply native flat fields, payload OR payload_file. The entire machine-readable schema is available through the CLI and get_operation_schema.

Native JSON field

Type or constraint

Requirement

Meaning

fileUrl

string

Required

The file URL returned from the upload-url endpoint

fileName

string

Required

Display name for the file

remove_digital_file

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Removes a digital file from the product by its file URL.

CLI: fourthwall-cli remove-digital-file. Policy: explicit confirmation.

Native: DELETE /open-api/v1.0/products/{productId}/digital-files. Current source.

Argument

Type or constraint

Requirement

Meaning

product_id

string (minLength=1, maxLength=256)

Required

Native productId

fileUrl

string

Optional

Native field

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

confirm

boolean

Optional

Set true only when the user asked for exactly this action.

payload

object

Optional

Complete current native JSON body; cannot mix with native body flags or payload_file.

payload_file

string (minLength=1)

Optional

Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native body fields below must also satisfy their required fields/oneOf branch. Supply native flat fields, payload OR payload_file. The entire machine-readable schema is available through the CLI and get_operation_schema.

Native JSON field

Type or constraint

Requirement

Meaning

fileUrl

string

Required

Native field

request_digital_file_upload_url

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns a presigned URL to upload a digital file to. After receiving the response, PUT the file bytes directly to the uploadUrl, then call the confirm endpoint to link the file to the product.

CLI: fourthwall-cli request-digital-file-upload-url. Policy: explicit confirmation.

Native: POST /open-api/v1.0/products/{productId}/digital-files/upload-url. Current source.

Argument

Type or constraint

Requirement

Meaning

product_id

string (minLength=1, maxLength=256)

Required

Native productId

fileName

string

Optional

Name of the file

contentType

string

Optional

MIME type of the file

size

integer (format=int64)

Optional

Size of the file in bytes. Must match the x-goog-content-length-range header sent when uploading the bytes to uploadUrl.

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

confirm

boolean

Optional

Set true only when the user asked for exactly this action.

payload

object

Optional

Complete current native JSON body; cannot mix with native body flags or payload_file.

payload_file

string (minLength=1)

Optional

Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

output_file

string (minLength=1)

Required

Absolute NEW owner-private receipt file; exclusive0600 creation, no overwrite. Upload/public-token URLs never enter ordinary output.

Native body fields below must also satisfy their required fields/oneOf branch. Supply native flat fields, payload OR payload_file. The entire machine-readable schema is available through the CLI and get_operation_schema.

Native JSON field

Type or constraint

Requirement

Meaning

fileName

string

Required

Name of the file

contentType

string

Required

MIME type of the file

size

integer (format=int64)

Required

Size of the file in bytes. Must match the x-goog-content-length-range header sent when uploading the bytes to uploadUrl.

request_media_upload_url

Rate limit: 20 requests / minute per shop. See Rate limiting.

Returns a pre-signed upload URL for uploading a new image. After receiving the response, PUT the image bytes directly to the uploadUrl.

CLI: fourthwall-cli request-media-upload-url. Policy: explicit confirmation.

Native: POST /open-api/v1.0/media/upload-url. Current source.

Argument

Type or constraint

Requirement

Meaning

fileName

string

Optional

Name of the file

contentType

string

Optional

MIME type of the file

size

integer (format=int64)

Optional

Size of the file in bytes. Must match the x-goog-content-length-range header sent when uploading the bytes to uploadUrl.

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

confirm

boolean

Optional

Set true only when the user asked for exactly this action.

payload

object

Optional

Complete current native JSON body; cannot mix with native body flags or payload_file.

payload_file

string (minLength=1)

Optional

Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

output_file

string (minLength=1)

Required

Absolute NEW owner-private receipt file; exclusive0600 creation, no overwrite. Upload/public-token URLs never enter ordinary output.

Native body fields below must also satisfy their required fields/oneOf branch. Supply native flat fields, payload OR payload_file. The entire machine-readable schema is available through the CLI and get_operation_schema.

Native JSON field

Type or constraint

Requirement

Meaning

fileName

string

Required

Name of the file

contentType

string

Required

MIME type of the file

size

integer (format=int64)

Required

Size of the file in bytes. Must match the x-goog-content-length-range header sent when uploading the bytes to uploadUrl.

list_media_images

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Retrieves all images from the shop's media library

CLI: fourthwall-cli list-media-images. Policy: read.

Native: GET /open-api/v1.0/media/images. Current source.

Argument

Type or constraint

Requirement

Meaning

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

save_media_image

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Persists an uploaded image in the media library after the client has PUT it to the signed URL

CLI: fourthwall-cli save-media-image. Policy: explicit confirmation.

Native: POST /open-api/v1.0/media/images. Current source.

Argument

Type or constraint

Requirement

Meaning

fileUrl

string

Optional

Native field

width

integer (format=int32)

Optional

Native field

height

integer (format=int32)

Optional

Native field

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

confirm

boolean

Optional

Set true only when the user asked for exactly this action.

payload

object

Optional

Complete current native JSON body; cannot mix with native body flags or payload_file.

payload_file

string (minLength=1)

Optional

Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native body fields below must also satisfy their required fields/oneOf branch. Supply native flat fields, payload OR payload_file. The entire machine-readable schema is available through the CLI and get_operation_schema.

Native JSON field

Type or constraint

Requirement

Meaning

fileUrl

string

Required

Native field

width

integer (format=int32)

Required

Native field

height

integer (format=int32)

Required

Native field

create_giveaway

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Creates a new giveaway

CLI: fourthwall-cli create-giveaway. Policy: explicit confirmation.

Native: POST /open-api/v1.0/giveaways/giveaways. Current source.

Argument

Type or constraint

Requirement

Meaning

offerId

string (format=uuid)

Optional

Native field

quantity

integer (format=int32)

Optional

Native field

username

string

Optional

Native field

message

string

Optional

Native field

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

confirm

boolean

Optional

Set true only when the user asked for exactly this action.

payload

object

Optional

Complete current native JSON body; cannot mix with native body flags or payload_file.

payload_file

string (minLength=1)

Optional

Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native body fields below must also satisfy their required fields/oneOf branch. Supply native flat fields, payload OR payload_file. The entire machine-readable schema is available through the CLI and get_operation_schema.

Native JSON field

Type or constraint

Requirement

Meaning

offerId

string (format=uuid)

Required

Native field

quantity

integer (format=int32)

Required

Native field

username

string

Optional

Native field

message

string

Optional

Native field

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Creates a new package with specified number of giveaway links

CLI: fourthwall-cli create-giveaway-links. Policy: explicit confirmation.

Native: POST /open-api/v1.0/giveaway-links. Current source.

Argument

Type or constraint

Requirement

Meaning

productId

string (format=uuid)

Optional

Native field

number

integer (format=int32)

Optional

Native field

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

confirm

boolean

Optional

Set true only when the user asked for exactly this action.

payload

object

Optional

Complete current native JSON body; cannot mix with native body flags or payload_file.

payload_file

string (minLength=1)

Optional

Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native body fields below must also satisfy their required fields/oneOf branch. Supply native flat fields, payload OR payload_file. The entire machine-readable schema is available through the CLI and get_operation_schema.

Native JSON field

Type or constraint

Requirement

Meaning

productId

string (format=uuid)

Required

Native field

number

integer (format=int32)

Required

Native field

create_gifting_checkout

Creates a paid checkout for gifting a product to live chat

CLI: fourthwall-cli create-gifting-checkout. Policy: explicit confirmation.

Native: POST /open-api/v1.0/gifting/checkout. Current source.

Argument

Type or constraint

Requirement

Meaning

offerId

string

Optional

The product offer to gift to live chat.

quantity

integer (minimum=1, maximum=10000, format=int32)

Optional

How many gifts to purchase.

currency

USD, EUR, CAD, GBP, AUD, NZD, SEK, NOK, DKK, PLN, INR, JPY, MYR, SGD, MXN, BRL, CHF

Optional

Display currency for the checkout. Defaults to the shop's currency.

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

confirm

boolean

Optional

Set true only when the user asked for exactly this action.

payload

object

Optional

Complete current native JSON body; cannot mix with native body flags or payload_file.

payload_file

string (minLength=1)

Optional

Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native body fields below must also satisfy their required fields/oneOf branch. Supply native flat fields, payload OR payload_file. The entire machine-readable schema is available through the CLI and get_operation_schema.

Native JSON field

Type or constraint

Requirement

Meaning

offerId

string

Required

The product offer to gift to live chat.

quantity

integer (minimum=1, maximum=10000, format=int32)

Required

How many gifts to purchase.

currency

USD, EUR, CAD, GBP, AUD, NZD, SEK, NOK, DKK, PLN, INR, JPY, MYR, SGD, MXN, BRL, CHF

Optional

Display currency for the checkout. Defaults to the shop's currency.

create_fulfillment

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Creates a fulfillment with a shipment tracker for provided order items. When trackers change their state, order.status will change to IN_PRODUCTION, PARTIALLY_IN_PRODUCTION, PARTIALLY_SHIPPED, SHIPPED depending on the shipping tracker info. Order updated webhooks will be triggered.

CLI: fourthwall-cli create-fulfillment. Policy: explicit confirmation.

Native: POST /open-api/v1.0/fulfillments. Current source.

Argument

Type or constraint

Requirement

Meaning

orderId

string (format=uuid)

Optional

Native field

items

array (minItems=1)

Optional

Native field

shippingLabel

object

Optional

Native field

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

confirm

boolean

Optional

Set true only when the user asked for exactly this action.

payload

object

Optional

Complete current native JSON body; cannot mix with native body flags or payload_file.

payload_file

string (minLength=1)

Optional

Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native body fields below must also satisfy their required fields/oneOf branch. Supply native flat fields, payload OR payload_file. The entire machine-readable schema is available through the CLI and get_operation_schema.

Native JSON field

Type or constraint

Requirement

Meaning

orderId

string (format=uuid)

Required

Native field

items

array (minItems=1)

Required

Native field

items.[].variantId

string (format=uuid)

Required

Native field

items.[].quantity

integer (minimum=1, format=int32)

Required

Native field

shippingLabel

object

Required

Native field

shippingLabel.trackingNumber

string (minLength=1)

Required

Native field

shippingLabel.trackingCompany

string (minLength=1)

Required

Native field

validate_dns

Rate limit: 20 requests / minute per shop. See Rate limiting.

Triggers a live DNS validation by checking all configured records against actual DNS servers and updates their verification status

CLI: fourthwall-cli validate-dns. Policy: explicit confirmation.

Native: POST /open-api/v1.0/dns/validate. Current source.

Argument

Type or constraint

Requirement

Meaning

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

confirm

boolean

Optional

Set true only when the user asked for exactly this action.

list_collections

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns all collections with pagination. The maximum page size is 100 - larger values are capped at 100.

CLI: fourthwall-cli list-collections. Policy: read.

Native: GET /open-api/v1.0/collections. Current source.

Argument

Type or constraint

Requirement

Meaning

page

integer (minimum=0, format=int32, default=0)

Optional

Native page

size

integer (minimum=1, maximum=100, format=int32, default=20)

Optional

Number of elements per page. The maximum page size is 100 - larger values are capped at 100.

search

string

Optional

Native search

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

create_collection

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Creates a new collection with name, description, and optional product list

CLI: fourthwall-cli create-collection. Policy: explicit confirmation.

Native: POST /open-api/v1.0/collections. Current source.

Argument

Type or constraint

Requirement

Meaning

name

string

Optional

Native field

description

string

Optional

Native field

offerIds

array

Optional

List of product IDs to include in the collection

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

confirm

boolean

Optional

Set true only when the user asked for exactly this action.

payload

object

Optional

Complete current native JSON body; cannot mix with native body flags or payload_file.

payload_file

string (minLength=1)

Optional

Absolute regular non-symlink native JSON body file, at most1MiB. Cannot mix with payload or body flags.

Native body fields below must also satisfy their required fields/oneOf branch. Supply native flat fields, payload OR payload_file. The entire machine-readable schema is available through the CLI and get_operation_schema.

Native JSON field

Type or constraint

Requirement

Meaning

name

string

Required

Native field

description

string

Required

Native field

offerIds

array

Required

List of product IDs to include in the collection

list_webhook_events

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Get webhook events with pagination and optional filtering by one or more webhook types (repeat or comma-separate the type param). The maximum page size is 100 - larger values are capped at 100.

CLI: fourthwall-cli list-webhook-events. Policy: read.

Native: GET /open-api/v1.0/webhook-events. Current source.

Argument

Type or constraint

Requirement

Meaning

type

array

Optional

Native type

page

integer (minimum=0, format=int32, default=0)

Optional

Native page

size

integer (minimum=1, maximum=100, format=int32, default=50)

Optional

Number of elements per page. The maximum page size is 100 - larger values are capped at 100.

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

get_webhook_event

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Get a single webhook event by ID

CLI: fourthwall-cli get-webhook-event. Policy: read.

Native: GET /open-api/v1.0/webhook-events/{webhookEventId}. Current source.

Argument

Type or constraint

Requirement

Meaning

webhook_event_id

string (minLength=1, maxLength=256)

Required

Native webhookEventId

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

get_thank_you

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Get Thank You details

CLI: fourthwall-cli get-thank-you. Policy: read.

Native: GET /open-api/v1.0/thank-yous/{thankYouId}. Current source.

Argument

Type or constraint

Requirement

Meaning

thank_you_id

string (minLength=1, maxLength=256)

Required

Native thankYouId

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

list_contributions

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns paginated list of orders, donations, and other contributions that can be thanked. The maximum page size is 100 - larger values are capped at 100.

CLI: fourthwall-cli list-contributions. Policy: read.

Native: GET /open-api/v1.0/thank-you-contributions. Current source.

Argument

Type or constraint

Requirement

Meaning

page

integer (minimum=0, format=int32, default=0)

Optional

Native page

size

integer (minimum=1, maximum=100, format=int32, default=50)

Optional

Number of elements per page. The maximum page size is 100 - larger values are capped at 100.

state

array

Optional

Native state

search

string

Optional

Native search

min_value

number (format=double)

Optional

Native minValue

contains_msg

boolean

Optional

Native containsMsg

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

get_streaming_status

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns streaming status for all services

CLI: fourthwall-cli get-streaming-status. Policy: read.

Native: GET /open-api/v1.0/streaming. Current source.

Argument

Type or constraint

Requirement

Meaning

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

get_shop

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns the current shop

CLI: fourthwall-cli get-shop. Policy: read.

Native: GET /open-api/v1.0/shops/current. Current source.

Argument

Type or constraint

Requirement

Meaning

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

get_shop_contact

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns the current shop contact info

CLI: fourthwall-cli get-shop-contact. Policy: read.

Native: GET /open-api/v1.0/shops/current/contact-info. Current source.

Argument

Type or constraint

Requirement

Meaning

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

get_sample_balance

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns the current sample credit balance for the shop

CLI: fourthwall-cli get-sample-balance. Policy: read.

Native: GET /open-api/v1.0/samples/balance. Current source.

Argument

Type or constraint

Requirement

Meaning

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

list_reports

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns the list of available report IDs with metadata including name, columns, and supported precisions

CLI: fourthwall-cli list-reports. Policy: read.

Native: GET /open-api/v1.0/reports. Current source.

Argument

Type or constraint

Requirement

Meaning

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

get_report

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Fetches a specific analytics report for a date range

CLI: fourthwall-cli get-report. Policy: read.

Native: GET /open-api/v1.0/reports/{reportId}. Current source.

Argument

Type or constraint

Requirement

Meaning

report_id

string (minLength=1, maxLength=256)

Required

Native reportId

from

string (format=date-time)

Required

Native from

to

string (format=date-time)

Required

Native to

aggregation_timezone

string

Required

Timezone in ISO-8601 format (e.g., Europe/Warsaw for Warsaw)

aggregation_precision

hour, day, week, month, quarter, year

Required

Native aggregationPrecision

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

get_product

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns product by id

CLI: fourthwall-cli get-product. Policy: read.

Native: GET /open-api/v1.0/products/{productId}. Current source.

Argument

Type or constraint

Requirement

Meaning

product_id

string (minLength=1, maxLength=256)

Required

Native productId

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

archive_product

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Soft-archives the product — sets it to Archived. Terminal at this surface: once archived, the product cannot be returned to PUBLIC/HIDDEN through the open-api (restoration stays admin-only). Idempotent: re-DELETE on an already-archived product also returns 204.

CLI: fourthwall-cli archive-product. Policy: explicit confirmation.

Native: DELETE /open-api/v1.0/products/{productId}. Current source.

Argument

Type or constraint

Requirement

Meaning

product_id

string (minLength=1, maxLength=256)

Required

Native productId

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

confirm

boolean

Optional

Set true only when the user asked for exactly this action.

get_product_inventory

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns product (offer) inventory by id

CLI: fourthwall-cli get-product-inventory. Policy: read.

Native: GET /open-api/v1.0/products/{productId}/inventory. Current source.

Argument

Type or constraint

Requirement

Meaning

product_id

string (minLength=1, maxLength=256)

Required

Native productId

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

list_product_templates

List available product templates. Returns 25 results. To paginate, use the /page/{N} variant of this endpoint (1-indexed). Use the total field in the response to calculate total pages. Pagination is path-based for HTTP cacheability.

CLI: fourthwall-cli list-product-templates. Policy: read.

Native: GET /open-api/v1.0/product-templates. Current source.

Argument

Type or constraint

Requirement

Meaning

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

get_product_template

        Get detailed information about a specific product template.

        This endpoint is public and does not require authentication.
        Returns full product details including variants, customizable areas,
        size guide, and images.

CLI: fourthwall-cli get-product-template. Policy: read.

Native: GET /open-api/v1.0/product-templates/{productId}. Current source.

Argument

Type or constraint

Requirement

Meaning

product_id

string (minLength=1, maxLength=256)

Required

Product template ID

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

search_product_templates

Search product templates by name, brand, description, sizes, categories, colors, or production method. Returns 25 results. To paginate, use the /search/{query}/page/{N} variant of this endpoint (1-indexed). Use the total field in the response to calculate total pages. Pagination is path-based for HTTP cacheability.

CLI: fourthwall-cli search-product-templates. Policy: read.

Native: GET /open-api/v1.0/product-templates/search/{query}. Current source.

Argument

Type or constraint

Requirement

Meaning

query

string (minLength=1, maxLength=256)

Required

Search query (e.g., 'hoodie', 'black%20t-shirt')

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

search_product_templates_paged

Search product templates with pagination. This endpoint is public and does not require authentication.

CLI: fourthwall-cli search-product-templates-paged. Policy: read.

Native: GET /open-api/v1.0/product-templates/search/{query}/page/{page}. Current source.

Argument

Type or constraint

Requirement

Meaning

query

string (minLength=1, maxLength=256)

Required

Search query (e.g., 'hoodie', 'black%20t-shirt')

page

integer (minimum=1, format=int32)

Required

Page number (1-indexed)

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

search_product_templates_grouped

Search product templates and group results by product family (libraryId). Products sharing the same physical item but with different production methods (e.g. DTG, Embroidery, DTFX) are collapsed into a single result with a variants list. Returns 25 grouped results. To paginate, use the /search-grouped/{query}/page/{N} variant (1-indexed). Pagination is path-based for HTTP cacheability.

CLI: fourthwall-cli search-product-templates-grouped. Policy: read.

Native: GET /open-api/v1.0/product-templates/search-grouped/{query}. Current source.

Argument

Type or constraint

Requirement

Meaning

query

string (minLength=1, maxLength=256)

Required

Search query (e.g., 'hoodie', 'black%20t-shirt')

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

search_product_templates_grouped_paged

Search product templates grouped by product family with pagination. This endpoint is public and does not require authentication.

CLI: fourthwall-cli search-product-templates-grouped-paged. Policy: read.

Native: GET /open-api/v1.0/product-templates/search-grouped/{query}/page/{page}. Current source.

Argument

Type or constraint

Requirement

Meaning

query

string (minLength=1, maxLength=256)

Required

Search query (e.g., 'hoodie', 'black%20t-shirt')

page

integer (minimum=1, format=int32)

Required

Page number (1-indexed)

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

list_product_templates_paged

List available product templates with pagination. This endpoint is public and does not require authentication.

CLI: fourthwall-cli list-product-templates-paged. Policy: read.

Native: GET /open-api/v1.0/product-templates/page/{page}. Current source.

Argument

Type or constraint

Requirement

Meaning

page

integer (minimum=1, format=int32)

Required

Page number (1-indexed)

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

list_product_templates_by_category

Browse product templates filtered by category. Category matches by prefix (e.g., 'Apparel' matches 'Apparel/T-Shirts'). Returns 25 results. To paginate, use the /category/{category}/page/{N} variant of this endpoint (1-indexed). Use the total field in the response to calculate total pages. Pagination is path-based for HTTP cacheability.

CLI: fourthwall-cli list-product-templates-by-category. Policy: read.

Native: GET /open-api/v1.0/product-templates/category/{category}. Current source.

Argument

Type or constraint

Requirement

Meaning

category

Apparel, Accessories, Home & Living

Required

Category path. Top-level: Apparel, Accessories, Home & Living. Subcategory paths like 'Apparel/T-Shirts' are also valid.

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

list_product_templates_by_category_paged

Browse product templates by category with pagination. This endpoint is public and does not require authentication.

CLI: fourthwall-cli list-product-templates-by-category-paged. Policy: read.

Native: GET /open-api/v1.0/product-templates/category/{category}/page/{page}. Current source.

Argument

Type or constraint

Requirement

Meaning

category

Apparel, Accessories, Home & Living

Required

Category path. Top-level: Apparel, Accessories, Home & Living. Subcategory paths like 'Apparel/T-Shirts' are also valid.

page

integer (minimum=1, format=int32)

Required

Page number (1-indexed)

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

get_pro_subscription

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns the current Fourthwall Pro platform subscription status, plan, and usage against plan limits

CLI: fourthwall-cli get-pro-subscription. Policy: read.

Native: GET /open-api/v1.0/pro-subscription. Current source.

Argument

Type or constraint

Requirement

Meaning

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

list_orders

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns all orders with pagination. The maximum page size is 100 - larger values are capped at 100.

CLI: fourthwall-cli list-orders. Policy: read.

Native: GET /open-api/v1.0/order. Current source.

Argument

Type or constraint

Requirement

Meaning

page

integer (minimum=0, format=int32, default=0)

Optional

Native page

size

integer (minimum=1, maximum=100, format=int32, default=20)

Optional

Number of elements per page. The maximum page size is 100 - larger values are capped at 100.

email

string

Optional

Native email

created_at_gt

string (format=date-time)

Optional

Native createdAt[gt]

created_at_lt

string (format=date-time)

Optional

Native createdAt[lt]

updated_at_gt

string (format=date-time)

Optional

Native updatedAt[gt]

updated_at_lt

string (format=date-time)

Optional

Native updatedAt[lt]

status

array

Optional

Native status

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

get_order

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns order by id

CLI: fourthwall-cli get-order. Policy: read.

Native: GET /open-api/v1.0/order/{orderId}. Current source.

Argument

Type or constraint

Requirement

Meaning

order_id

string (minLength=1, maxLength=256)

Required

Native orderId

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

get_order_by_friendly_id

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns order by friendly id

CLI: fourthwall-cli get-order-by-friendly-id. Policy: read.

Native: GET /open-api/v1.0/order/by-friendly-id/{friendlyId}. Current source.

Argument

Type or constraint

Requirement

Meaning

friendly_id

string (minLength=1, maxLength=256)

Required

Native friendlyId

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

list_membership_tiers

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Lists all tiers for the current shop

CLI: fourthwall-cli list-membership-tiers. Policy: read.

Native: GET /open-api/v1.0/memberships/tiers. Current source.

Argument

Type or constraint

Requirement

Meaning

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

list_members

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Lists all members for the current shop. The maximum page size is 100 - larger values are capped at 100.

CLI: fourthwall-cli list-members. Policy: read.

Native: GET /open-api/v1.0/memberships/members. Current source.

Argument

Type or constraint

Requirement

Meaning

page

integer (minimum=0, format=int32, default=0)

Optional

Native page

size

integer (minimum=1, maximum=100, format=int32, default=20)

Optional

Number of elements per page. The maximum page size is 100 - larger values are capped at 100.

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

get_member

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Gets a member by id

CLI: fourthwall-cli get-member. Policy: read.

Native: GET /open-api/v1.0/memberships/members/{id}. Current source.

Argument

Type or constraint

Requirement

Meaning

id

string (minLength=1, maxLength=256)

Required

Native id

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

list_mailing_list

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns all mailing list entries. The maximum page size is 100 - larger values are capped at 100.

CLI: fourthwall-cli list-mailing-list. Policy: read.

Native: GET /open-api/v1.0/mailing-list-entries. Current source.

Argument

Type or constraint

Requirement

Meaning

page

integer (minimum=0, format=int32, default=0)

Optional

Native page

size

integer (minimum=1, maximum=100, format=int32, default=20)

Optional

Number of elements per page. The maximum page size is 100 - larger values are capped at 100.

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

list_giveaway_packages

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns all packages with giveaway links

CLI: fourthwall-cli list-giveaway-packages. Policy: read.

Native: GET /open-api/v1.0/giveaway-links/packages. Current source.

Argument

Type or constraint

Requirement

Meaning

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

get_giveaway_package

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns all giveaway links for packageId

CLI: fourthwall-cli get-giveaway-package. Policy: read.

Native: GET /open-api/v1.0/giveaway-links/packages/{packageId}. Current source.

Argument

Type or constraint

Requirement

Meaning

package_id

string (minLength=1, maxLength=256)

Required

Native packageId

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

get_giveaway_draw

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Get draw details

CLI: fourthwall-cli get-giveaway-draw. Policy: read.

Native: GET /open-api/v1.0/gifting/draw/{id}. Current source.

Argument

Type or constraint

Requirement

Meaning

id

string (minLength=1, maxLength=256)

Required

Native id

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

get_gift_purchase

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns gift purchase details by id

CLI: fourthwall-cli get-gift-purchase. Policy: read.

Native: GET /open-api/v1.0/gift-purchase/{giftPurchaseId}. Current source.

Argument

Type or constraint

Requirement

Meaning

gift_purchase_id

string (minLength=1, maxLength=256)

Required

Native giftPurchaseId

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

list_donations

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns all donations with pagination. The maximum page size is 100 - larger values are capped at 100.

CLI: fourthwall-cli list-donations. Policy: read.

Native: GET /open-api/v1.0/donations. Current source.

Argument

Type or constraint

Requirement

Meaning

page

integer (minimum=0, format=int32, default=0)

Optional

Native page

size

integer (minimum=1, maximum=100, format=int32, default=20)

Optional

Number of elements per page. The maximum page size is 100 - larger values are capped at 100.

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

get_donation

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns donation by id

CLI: fourthwall-cli get-donation. Policy: read.

Native: GET /open-api/v1.0/donations/{donationId}. Current source.

Argument

Type or constraint

Requirement

Meaning

donation_id

string (minLength=1, maxLength=256)

Required

Native donationId

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

get_dns_status

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns the cached DNS configuration and record status for the shop's custom domain

CLI: fourthwall-cli get-dns-status. Policy: read.

Native: GET /open-api/v1.0/dns. Current source.

Argument

Type or constraint

Requirement

Meaning

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

get_collection

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns a collection by its ID or slug

CLI: fourthwall-cli get-collection. Policy: read.

Native: GET /open-api/v1.0/collections/{collectionIdOrSlug}. Current source.

Argument

Type or constraint

Requirement

Meaning

collection_id_or_slug

string (minLength=1, maxLength=256)

Required

Native collectionIdOrSlug

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

list_accounts

Local labels/default/auth source availability only. No credential values, paths, provider identity or network.

CLI: fourthwall-cli list-accounts. Policy: read.

Argument

Type or constraint

Requirement

Meaning

get_operation_schema

Local reviewed native method/path/query/body/scopes/rate limit and pinned schema provenance. No provider access or authority proof.

CLI: fourthwall-cli get-operation-schema. Policy: read.

Argument

Type or constraint

Requirement

Meaning

operation

get_webhook, update_webhook, delete_webhook, start_streaming, end_streaming, get_public_token, get_promotion, update_promotion, update_product_state, toggle_product_availability, mark_download_complete, finish_giveaway, create_giveaway_checkout, disable_giveaway_checkout, finish_giveaway_draw, get_gifting_config, update_gifting_config, update_collection, get_collection_products, update_collection_products, update_collection_availability, list_webhooks, create_webhook, list_promotions, create_promotion, list_products, create_product, attach_product_images, remove_product_images, confirm_digital_file_upload, remove_digital_file, request_digital_file_upload_url, request_media_upload_url, list_media_images, save_media_image, create_giveaway, create_giveaway_links, create_gifting_checkout, create_fulfillment, validate_dns, list_collections, create_collection, list_webhook_events, get_webhook_event, get_thank_you, list_contributions, get_streaming_status, get_shop, get_shop_contact, get_sample_balance, list_reports, get_report, get_product, archive_product, get_product_inventory, list_product_templates, get_product_template, search_product_templates, search_product_templates_paged, search_product_templates_grouped, search_product_templates_grouped_paged, list_product_templates_paged, list_product_templates_by_category, list_product_templates_by_category_paged, get_pro_subscription, list_orders, get_order, get_order_by_friendly_id, list_membership_tiers, list_members, get_member, list_mailing_list, list_giveaway_packages, get_giveaway_package, get_giveaway_draw, get_gift_purchase, list_donations, get_donation, get_dns_status, get_collection

Required

Native field

preview_shop_batch

Validate every exact request and hash order/profile label/schema locally. No native request, credential loading, ownership check or provider preview.

CLI: fourthwall-cli preview-shop-batch. Policy: read.

Argument

Type or constraint

Requirement

Meaning

tasks

array (minItems=1, maxItems=20)

Required

One to twenty exact ordered native effects. No signed receipts or mutable payload files. Cannot override account/confirm/output settings.

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

submit_shop_batch

Confirmed ordered effects; all validated/hash checked before first request. Stop on first failure with known and unattempted receipts; no retry, rollback or implicit continuation.

CLI: fourthwall-cli submit-shop-batch. Policy: explicit confirmation.

Argument

Type or constraint

Requirement

Meaning

tasks

array (minItems=1, maxItems=20)

Required

One to twenty exact ordered native effects. No signed receipts or mutable payload files. Cannot override account/confirm/output settings.

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

confirm

boolean

Optional

Set true only when the user asked for exactly this action.

review_sha256

string

Required

Native field

export_resources

Confirmed native page/size/results export into a new exclusive0600 file with page/item/5MiB budgets and explicit page/offset continuation. No links followed, binary downloads or atomic-backup guarantee.

CLI: fourthwall-cli export-resources. Policy: explicit confirmation.

Argument

Type or constraint

Requirement

Meaning

operation

get_collection_products, list_promotions, list_products, list_collections, list_webhook_events, list_contributions, list_orders, list_members, list_mailing_list, list_donations

Required

Native field

arguments

object

Optional

Current list query/path arguments; cannot override profile/policy/output.

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

confirm

boolean

Optional

Set true only when the user asked for exactly this action.

start_offset

integer (minimum=0, maximum=99)

Optional

Native field

max_pages

integer (minimum=1, maximum=100)

Optional

Native field

max_items

integer (minimum=1, maximum=10000)

Optional

Native field

output_file

string (minLength=1)

Required

Native field

upload_file

Explicitly confirmed Google Storage PUT using a selected private upload receipt and a bounded local regular file. Exact size/Content-Type and x-goog-content-length-range are preserved. No Fourthwall credentials or redirects, no automatic registration/publishing.

CLI: fourthwall-cli upload-file. Policy: explicit confirmation.

Argument

Type or constraint

Requirement

Meaning

account

string

Optional

Exact private shop profile label; not a provider identity or authorization proof.

confirm

boolean

Optional

Set true only when the user asked for exactly this action.

receipt_file

string (minLength=1)

Required

Native field

input_file

string (minLength=1)

Required

Native field

7. Writing safely

Every one of the 37 effects requires confirm:true in MCP or --confirm in the CLI. This includes new checkouts, public-token PUT, uploads and local export file writes. Read-only hides and directly refuses effects. FOURTHWALL_ALLOW_DESTRUCTIVE=0 refuses them even when confirmed. Local guard approval is separate from provider authorization and customer consent.

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. FOURTHWALL_CONFIRM=model makes confirm:true enough everywhere, for an agent with no person to ask.

Read the intended record and inspect get_operation_schema before writing. Validate IDs, quantities, callback events and the exact profile. Product creation defaults to hidden. Availability is not lifecycle state: available:false and state:HIDDEN are separate native changes.

No effect retries automatically. A timeout, malformed receipt or partial batch can mean an unknown outcome. Inspect native state before deliberately repeating. The default pacing is 1,000 ms per request; tighter documented operation buckets are respected locally. Other processes share provider quotas.

8. Products media and fulfillment

The pinned contract uses /open-api/v1.0 and current native typed bodies. Product creation supports selected design/digital variants, not every custom production workflow. Digital price is a nonnegative USD amount; publishOnCreate defaults false.

fourthwall-cli create-product --payload-file /absolute/private/digital-product.json --account intended-shop --confirm --agent
fourthwall-cli toggle-product-availability --product-id REVIEWED_PRODUCT_ID --available false --confirm --agent
fourthwall-cli update-product-state --product-id REVIEWED_PRODUCT_ID --state HIDDEN --confirm --agent

The digital tutorial describes admin publishing while the current state endpoint documents PUBLIC/HIDDEN. Check actual authorization and storefront visibility before claiming a live publication outcome. These examples are placeholders, not successful shop receipts.

Media workflow: request_media_upload_url saves a signed receipt to a NEW private file; upload_file sends exact local bytes; save_media_image registers the uploaded reference separately. Digital-file workflow uses request_digital_file_upload_url, upload_file and confirm_digital_file_upload. Use private payload files for fileUrl; never paste signed receipts into agent context.

fourthwall-cli request-media-upload-url --fileName reviewed.png --contentType image/png --size 4096 --output-file /absolute/private/upload-receipt.json --account intended-shop --confirm --agent
fourthwall-cli upload-file --receipt-file /absolute/private/upload-receipt.json --input-file /absolute/private/reviewed.png --account intended-shop --confirm --agent
fourthwall-cli save-media-image --payload-file /absolute/private/register-image.json --account intended-shop --confirm --agent

Replace 4096 with the exact file byte count. The helper's local cap is 64 MiB, not a Fourthwall plan entitlement. HTTPS Google Storage signed hosts only, no redirects, exact Content-Type and x-goog-content-length-range; no Fourthwall Authorization header reaches storage. Upload acknowledgement is not registration, storefront publication or access proof. Receipts bind a profile label and metadata, not cryptographic ownership.

Fulfillment requires native orderId, nonempty items with variantId/quantity, and shippingLabel with trackingCompany/trackingNumber. Giveaway links require productId and number, not the old quantity wrapper. Promotions retain four native variants and their nested discount shapes. Streaming services are native typed objects, not strings. Inspect schema before submitting any of these.

9. Several accounts and reviewed batches

FOURTHWALL_ACCOUNTS is a private JSON array of unique name plus one username/password, access_token or credentials_file source. Named profiles never inherit globals. FOURTHWALL_DEFAULT_ACCOUNT selects an exact default; --account selects another label. Discovery reports labels and source availability only, never secret values or paths.

Preview validates 1–20 ordered native effects locally before any provider call. Signed-output operations and mutable payload files are excluded. Every nested argument is validated; account/confirm/output overrides are forbidden. Preview returns reviewSha256 and providerValidated:false.

fourthwall-cli preview-shop-batch --tasks '{"tool":"toggle_product_availability","arguments":{"product_id":"REVIEWED_PRODUCT_ID","available":false}}' --account intended-shop --agent
fourthwall-cli submit-shop-batch --tasks '{"tool":"toggle_product_availability","arguments":{"product_id":"REVIEWED_PRODUCT_ID","available":false}}' --review-sha256 REVIEWED_64_CHARACTER_HASH --account intended-shop --confirm --agent

The repeatable JSON flag becomes the tasks array. Use the exact hash from your local preview. It binds prepared requests, task order, profile label and selected schema, not credentials, provider state, expiry or single-use execution. Re-review after credential/state changes. Execution stops on the first failure and reports known results and unattempted indices. No transaction or rollback is promised.

10. Pagination and private exports

Query pagination uses native zero-based page/size, with size capped locally at 100. Product-template path pagination is one-based. The old cursor/limit wrappers are obsolete. Native date filter names and repeated status values are preserved by the request encoder; inspect the actual list schema.

export_resources supports the ten selected lists whose current schema exposes results/page/size/totalPages. It validates counters, limits pages/items/bytes, and returns continuation with a page and start_offset when needed. Default budgets are ten pages and 1,000 items; maxima are 100 pages, 10,000 items and 5 MiB.

fourthwall-cli export-resources --operation list_orders --arguments '{"page":0,"size":100}' --max-pages 10 --max-items 1000 --output-file /absolute/private/orders.json --account intended-shop --confirm --agent

A new file is reserved exclusively before fetching; existing files and symlinks are not overwritten. POSIX output mode is 0600; Windows ACLs require separate restriction. Errors remove the partial new file. Exports redact known credentials/signed URLs, but other customer metadata remains private. This is bounded filtered metadata, not an atomic backup, binary download or stable snapshot while data changes.

11. How it works

Slipway builds the MCP server, over stdio or --http, and the CLI from each tool's one definition, and both call the same handlers. Ajv validates discovered input schemas and current native body variants. A shared guard applies confirmation and read-only policy before effects. Native method/path allowlists prevent arbitrary provider requests; query arrays and date names retain their native representation.

Six local helpers add private profile discovery, contract inspection, reviewed batches, bounded exports and exact byte uploads. No vendor or community runtime is copied. Official schema provenance and the 39-name migration mapping are checked by scripts.

npm ci
npm run typecheck
npm run build
npm test
npm run check:counts
npm run check:discovery
npm run sync:api -- --check
npm run build:mcpb

CI runs macOS, Windows and Linux on Node 22/24 plus desktop packaging. These checks prove local contracts, policy, transports and artifacts; authenticated provider outcomes, desktop GUI installation and matched Codex tokens remain separate. See RELEASE-CHECKLIST.md.

12. Your data

Credentials live in private process settings or owner-private files; there is no hosted service or telemetry. Provider API requests go only to api.fourthwall.com. Storage uploads are separately scoped to the documented Google Storage HTTPS hosts and carry no provider credentials.

Raw signed upload receipts and generated public tokens are intentionally written only to a requested new private output_file. Known credentials, sensitive token/file fields and signed credential URLs are redacted from ordinary output and errors. Customer names, emails, order contents and other legitimate native metadata are not automatically anonymized.

Treat provider content and URLs as untrusted data. Optional best-effort audit logs contain static guard decisions, not payloads or credentials; they are not financial ledgers. Keep exports and receipts private. Uninstalling does not revoke provider credentials or reverse effects. Revoke or rotate in Fourthwall and restart dependent runtimes.

13. Official and community comparison

Fourthwall's official MCP already exists. It provides hosted OAuth, broad shop tooling, confirmations and documented previews, with 123 documented tools at review. This package is a selected local companion, with 80 native operations and six workflows. Neither count proves greater coverage or efficiency.

Requirement

This companion

Existing tooling

Authentication

Private shop Basic pair or existing OAuth bearer/file

Official hosted OAuth with shop selection

Coverage

Selected reviewed Platform API routes

Official broader shop, brand, merch and analytics tools

Terminal

Dedicated task CLI over the exact same MCP handlers

Generic MCP terminal clients also exist

Local approvals

Mandatory per-call approval and direct read-only refusal on both surfaces

Official confirmations and previews already exist

Repeated work

Exact local ordered batch review and failure receipts

No claim of transaction or state locking

Export

Bounded private native metadata export with resume offset

Not an atomic backup or binary download

Upload

Private signed receipts and explicit bounded byte helper

Native upload services remain the authority

Cost

No measured task-token saving yet

Equivalent completed tasks must be measured

The reviewed generic wong2/mcp-cli source at 7d12b464 already supports remote interactive OAuth. Its noninteractive JSON call path in that snapshot uses stdio; HTTP noninteractive equivalence was not verified. A bounded GitHub community search found no additional dedicated Fourthwall MCP repository, which is not proof none exists. See COMPARISON.md for review evidence and exclusions.

14. Versions and migration

Component

Version or evidence

Package and desktop

3.0.0

Slipway

0.1.20

MCP TypeScript SDK, through Slipway

2.3.0

Runtime

Node >=22

Native API

Current Platform v1.0 schema checked 2026-10-04

Selected operations

80 of 95 native operations, 80 distinct method/path routes

Legacy

39 actual tool names preserved; breaking argument refresh

Task/token, provider and GUI outcomes

Separate acceptance work; not inferred from local tests

3.0.0 moves both surfaces onto Slipway and keeps every tool's name and arguments; CHANGELOG.md lists what changed for scripts. In 2.0, old cursor/limit fields became page/size, availability uses available, fulfillment uses items/shippingLabel, giveaway uses productId/number, webhooks require url and allowedTypes, promotions use native oneOf variants, and streaming services use typed objects. Effects now require explicit approval. Token/upload receipts need new private output_file. Product creation stays hidden by default. Use schema/help before migrating scripts.

The current official source SHA-256 is 77de1061d5c9273927fd3cf4cac1375c4bb684bed4cc4c0f22252ea6b0e203fe. Provenance, excluded operations and sanitized snapshot checksum ship in src/tools/provenance.json. CHANGELOG.md records the full refresh; private legacy history remains separate.

15. Risks

Full-access Basic credentials make careful profile and permission selection necessary. Local approval cannot prove ownership, customer consent, fulfillment delivery or storefront state. There are no automatic retries, rollbacks, refunds or cleanup workflows beyond the explicitly documented tools.

Fixed local bounds are 1 MiB request/body file, 5 MiB API response/export and 64 MiB byte upload. Timeout defaults to 30 seconds and local pacing to one second, with tighter native buckets. These are conservative process controls, not global quota guarantees. Sandbox verification uses fixtures and makes no real shop changes.

16. Troubleshooting

Symptom

Check

Missing configuration

Choose one complete private auth source; confirm the launching runtime inherits it

API 401/403

Check revoked credentials, OAuth scopes, shop permissions and intended resource

Unknown profile

Use exact list_accounts labels; named profiles never inherit globals

429

Respect shared provider quotas; do not repeatedly retry a possibly completed effect

Invalid arguments

Run schema/--help; old wrappers and guessed body fields are rejected

Upload byte mismatch

Request a new receipt for the exact file size; preserve required headers

Existing output file

Pick a new private path; outputs never overwrite

Empty or malformed receipt

Inspect native state before deliberately repeating

GUI launcher cannot find npx

Check the client's PATH or use absolute node/package paths

Hidden write absent

Read-only intentionally removes it and refuses direct calls

Report sanitized reproducible details through GitHub issues, or use private security reporting. Never attach credentials, upload URLs or customer exports.

17. FAQ

A local program that lets an MCP app call selected Fourthwall Platform API operations. It exposes 86 shared tasks, including six local workflows, through one implementation also used by the CLI.

The same tasks as terminal commands. Tool names use underscores in MCP and dashes in commands, such as list_products and fourthwall-cli list-products. Shell agents and scripts can use JSON output without configuring an MCP connection.

Yes. Fourthwall offers a hosted OAuth MCP at https://mcp.fourthwall.com with broader shop, brand, merchandising and analytics coverage. Its documentation listed 123 tools when reviewed on October 4, 2026; that is a documentation count, not authenticated discovery.

Choose it for hosted OAuth, broad dashboard coverage and its own native previews and confirmations. Choose this companion when you need a dedicated shared task CLI, exact local request reviews, isolated profile selection or bounded private metadata exports.

No. Generic MCP terminal clients also exist, and the official MCP already confirms changes. The useful additions here are specific local workflows and consistent per-call policy across CLI and MCP. There is no universal superiority or total-coverage claim.

Codex, Claude Code, Claude Desktop, Cursor, VS Code/Copilot, Windsurf, Zed and Gemini CLI can launch a local stdio server where supported. Other stdio clients can use the same executable. URL-only hosted connectors cannot connect directly to this local package.

The npm package and manifest require Node 22 or newer. The desktop bundle includes production JavaScript dependencies; a compatible host must provide the required runtime. macOS, Windows and Linux are declared; CI and actual GUI installation are separate checks.

A Fourthwall SUPER ADMIN can create shop API credentials in Settings > For Developers. Configure the complete private username/password pair, an existing OAuth access token, or a private credential JSON file. Basic credentials grant full shop access.

No. fourthwall-cli login prints the private setup instructions. It does not create credentials, open browser consent, exchange tokens or refresh an existing OAuth token. Use the official provider flow separately if you need OAuth.

Yes. FOURTHWALL_ACCOUNTS contains independently configured named profiles, and --account selects one exact label. Named profiles never inherit global credentials. Labels and review hashes do not establish shop ownership or lock credential contents.

FOURTHWALL_READ_ONLY=1 exposes only the 49 read operations and directly refuses the 37 hidden effects, even if confirm is supplied. This is a local runtime policy; it does not reduce permissions on Fourthwall credentials or govern another client.

All 37 provider and local effects need confirm:true in MCP or --confirm in the CLI. That includes product changes, checkout creation, token generation, upload URL requests, byte uploads, reviewed batches and exports. --yes and --agent do not grant permission.

Creation defaults publishOnCreate to false, keeping the product hidden. Publishing is a separate deliberate choice. The current state endpoint documents PUBLIC/HIDDEN, while the digital-product tutorial also describes admin publishing; authorization and live visibility must be checked in the intended shop.

No. Preview validates every request locally and hashes exact requests, order, profile label and pinned contract. Submit verifies that hash and stops on the first failure. There is no rollback, state lock, expiry or single-use promise; failed effect outcomes can be unknown.

No. Exports save selected native page/size/results metadata with explicit page, item and byte budgets and continuation. They are not atomic snapshots, binary downloads or a guarantee of completeness while shop data changes.

Request a signed upload receipt into a new private file, then explicitly upload matching local bytes to the documented Google Storage host. Registration or attachment is separate. The upload sends no Fourthwall Authorization header and never automatically publishes a product.

Credentials remain in private environment settings or owner-only regular files outside repositories. Signed upload URLs and public tokens are saved only to requested new private files. Ordinary output redacts known credentials and signed URLs; other shop/customer fields remain private data.

Download fourthwall-3.0.0.mcpb from GitHub Releases and install it through a supported Claude Desktop Extensions screen. Choose one credential source and leave others empty. The release includes production dependencies and no credentials. Archive/protocol checks do not prove GUI installation in every client build.

The software is free under AGPL-3.0. Fourthwall service fees, plans and usage still apply. In Claude Code the CLI costs nothing until it is used, plus about 660 tokens for SKILL.md once, where the server costs about 1,610 tokens a message with tool search and 39,900 with every tool loaded. In Codex, finding the command that creates a promotion and its flags took a median of 108,648 input tokens over the CLI and 77,915 over MCP. Section 5 has how each was measured.

All 39 actual legacy tool names remain, but native arguments and pagination were corrected. The new package adds a CLI, desktop bundle, 80 selected native operations, six local workflows, explicit effect approval and stronger private output handling. Version 2.0.0 is a breaking contract refresh; old private history is preserved separately.

Questions

Use issues with sanitized reproduction steps. Security reports belong in the private advisory form.

Built by

Navid Moazzez

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.

Dependencies

Slipway, which brings the MCP TypeScript SDK, and Ajv with ajv-formats power the shared runtime. TypeScript, Vitest and the desktop packer are build/test tools. Dependency licenses are retained in the bundle; see THIRD_PARTY_NOTICES.md.

License

AGPL-3.0. Preserve the license and applicable source obligations. Fourthwall is a separate provider; this community companion is not its official MCP.

© 2026 Navid Media. Made with ❤️ by Navid Moazzez.

Available Tools

86 tools
archive_productArchive a product (offer)B
Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Soft-archives the product — sets it to Archived. Terminal at this surface: once archived, the product cannot be returned to PUBLIC/HIDDEN through the open-api (restoration stays admin-only). Idempotent: re-DELETE on an already-archived product also returns 204.

Inputs: product_id (required), account, confirm.

attach_product_imagesAttach images to a productA
Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Attaches images to a product. Images should be uploaded first via the media upload endpoint.

Inputs: product_id (required), images, account, confirm, +2 more.

confirm_digital_file_uploadConfirm and link an uploaded digital fileA
Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

After uploading a file to the presigned URL, call this endpoint to link the file to the product. The file must exist in storage before calling this endpoint.

Inputs: product_id (required), account, confirm, fileUrl, +3 more.

create_collectionCreate a new collectionB
Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Creates a new collection with name, description, and optional product list

Inputs: name, account, confirm, payload, +3 more.

create_fulfillmentCreate a fulfillment for an orderA
Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Creates a fulfillment with a shipment tracker for provided order items. When trackers change their state, order.status will change to IN_PRODUCTION, PARTIALLY_IN_PRODUCTION, PARTIALLY_SHIPPED, SHIPPED depending on the shipping tracker info. Order updated webhooks will be triggered.

Inputs: items, account, confirm, orderId, +3 more.

create_gifting_checkoutCreate a gifting checkoutC
Destructive

Creates a paid checkout for gifting a product to live chat

Inputs: account, confirm, offerId, payload, +3 more.

create_giveawayCreate a new giveawayC
Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Creates a new giveaway

Inputs: account, confirm, message, offerId, +4 more.

create_giveaway_checkoutCreate or update giveawayC
Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Creates a new giveaway or updates existing one

Inputs: account, confirm, heading, iconUrl, +5 more.

create_productCreate a productB
Destructive

Rate limit: 5 requests / minute per shop. See Rate limiting.

Creates a product from a design or a digital product.

Inputs: account, confirm, payload, payload_file.

create_promotionCreate a promotionB
Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Creates a promotion

Inputs: account, confirm, payload, payload_file.

create_webhookCreate a webhookC
Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Create a webhook

Inputs: url, account, confirm, payload, +2 more.

delete_webhookDelete a webhookC
Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Delete a webhook

Inputs: webhook_configuration_id (required), account, confirm.

disable_giveaway_checkoutDisable giveaway configC
Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

disables a giveaway config

Inputs: account, confirm.

end_streamingSet streaming status to endedB
Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Sets streaming status to ended for specified services

Inputs: account, confirm, payload, services, +1 more.

export_resourcesExport bounded private metadataB
Destructive

Confirmed native page/size/results export into a new exclusive0600 file with page/item/5MiB budgets and explicit page/offset continuation. No links followed, binary downloads or atomic-backup guarantee.

Inputs: operation (required), output_file (required), account, confirm, +4 more.

finish_giveawayFinish giveawayB
Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Finish giveaway and select winners

Inputs: id (required), account, confirm, payload, +2 more.

finish_giveaway_drawFinish drawB
Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Finish draw and select winners

Inputs: id (required), account, confirm, payload, +2 more.

get_collectionGet collection by ID or slugB
Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns a collection by its ID or slug

Inputs: collection_id_or_slug (required), account.

get_collection_productsGet products in a collectionA
Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns paginated products in a collection with optional status filtering. The maximum page size is 100 - larger values are capped at 100.

Inputs: collection_id (required), page, size, status, +1 more.

get_dns_statusGet DNS configuration statusA
Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns the cached DNS configuration and record status for the shop's custom domain

Inputs: account.

get_donationGet donation by idB
Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns donation by id

Inputs: donation_id (required), account.

get_gifting_configGet gifting configA
Read-onlyIdempotent

Returns the calling shop's saved gifting rules. Returns a default-shaped config when none is persisted yet.

Inputs: account.

get_gift_purchaseGet gift purchase by idB
Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns gift purchase details by id

Inputs: gift_purchase_id (required), account.

get_giveaway_drawGet drawB
Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Get draw details

Inputs: id (required), account.

get_giveaway_packageGet giveaway linksB
Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns all giveaway links for packageId

Inputs: package_id (required), account.

get_memberGet memberA
Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Gets a member by id

Inputs: id (required), account.

get_operation_schemaInspect native contractC
Read-onlyIdempotent

Local reviewed native method/path/query/body/scopes/rate limit and pinned schema provenance. No provider access or authority proof.

Inputs: operation (required).

get_orderGet order by idB
Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns order by id

Inputs: order_id (required), account.

get_order_by_friendly_idGet order by friendly idB
Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns order by friendly id

Inputs: friendly_id (required), account.

get_productGet product (offer) by idB
Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns product by id

Inputs: product_id (required), account.

get_product_inventoryGet product (offer) inventory by idB
Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns product (offer) inventory by id

Inputs: product_id (required), account.

get_product_templateGet product template detailsB
Read-onlyIdempotent

Get detailed information about a specific product template.

This endpoint is public and does not require authentication. Returns full product details including variants, customizable areas, size guide, and images.

Inputs: product_id (required), account.

get_promotionGet a promotion by idB
Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns a promotion by id

Inputs: promotion_id (required), account.

get_pro_subscriptionGet Pro subscription statusA
Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns the current Fourthwall Pro platform subscription status, plan, and usage against plan limits

Inputs: account.

get_public_tokenGet or create a public tokenB
Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns an existing public token for the shop, or creates a new one if none exists

Inputs: output_file (required), account, confirm.

get_reportGet a reportA
Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Fetches a specific analytics report for a date range

Inputs: to (required), from (required), report_id (required), aggregation_timezone (required), +2 more.

get_sample_balanceGet sample credit balanceA
Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns the current sample credit balance for the shop

Inputs: account.

get_shopGet current shopB
Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns the current shop

Inputs: account.

get_shop_contactGet current shop contact infoA
Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns the current shop contact info

Inputs: account.

get_streaming_statusGet streaming statusB
Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns streaming status for all services

Inputs: account.

get_thank_youGet Thank You by idB
Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Get Thank You details

Inputs: thank_you_id (required), account.

get_webhookGet a webhookC
Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Get a webhook

Inputs: webhook_configuration_id (required), account.

get_webhook_eventGet a webhook eventA
Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Get a single webhook event by ID

Inputs: webhook_event_id (required), account.

list_accountsList private shop profilesC
Read-onlyIdempotent

Local labels/default/auth source availability only. No credential values, paths, provider identity or network.

Inputs: no named parameters.

list_collectionsGet all collectionsA
Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns all collections with pagination. The maximum page size is 100 - larger values are capped at 100.

Inputs: page, size, search, account.

list_contributionsGet contributions awaiting thank youB
Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns paginated list of orders, donations, and other contributions that can be thanked. The maximum page size is 100 - larger values are capped at 100.

Inputs: page, size, state, search, +3 more.

list_donationsGet all donationsB
Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns all donations with pagination. The maximum page size is 100 - larger values are capped at 100.

Inputs: page, size, account.

list_giveaway_packagesGet all giveaway packagesA
Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns all packages with giveaway links

Inputs: account.

list_mailing_listGet all mailing list entriesA
Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns all mailing list entries. The maximum page size is 100 - larger values are capped at 100.

Inputs: page, size, account.

list_media_imagesList media library imagesA
Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Retrieves all images from the shop's media library

Inputs: account.

list_membersList membersA
Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Lists all members for the current shop. The maximum page size is 100 - larger values are capped at 100.

Inputs: page, size, account.

list_membership_tiersList membership tiersA
Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Lists all tiers for the current shop

Inputs: account.

list_ordersGet all ordersB
Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns all orders with pagination. The maximum page size is 100 - larger values are capped at 100.

Inputs: page, size, email, status, +5 more.

list_productsGet all products (offers)A
Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns all products with pagination. The maximum page size is 100 - larger values are capped at 100.

Inputs: page, size, search, account.

list_product_templatesList product templatesA
Read-onlyIdempotent

List available product templates. Returns 25 results. To paginate, use the /page/{N} variant of this endpoint (1-indexed). Use the total field in the response to calculate total pages. Pagination is path-based for HTTP cacheability.

Inputs: account.

list_product_templates_by_categoryBrowse product templates by categoryA
Read-onlyIdempotent

Browse product templates filtered by category. Category matches by prefix (e.g., 'Apparel' matches 'Apparel/T-Shirts'). Returns 25 results. To paginate, use the /category/{category}/page/{N} variant of this endpoint (1-indexed). Use the total field in the response to calculate total pages. Pagination is path-based for HTTP cacheability.

Inputs: category (required), account.

list_product_templates_by_category_pagedBrowse product templates by category by pageA
Read-onlyIdempotent

Browse product templates by category with pagination. This endpoint is public and does not require authentication.

Inputs: page (required), category (required), account.

list_product_templates_pagedList product templates by pageA
Read-onlyIdempotent

List available product templates with pagination. This endpoint is public and does not require authentication.

Inputs: page (required), account.

list_promotionsGet all promotionsA
Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns all promotions. The maximum page size is 100 - larger values are capped at 100.

Inputs: page, size, codes, account.

list_reportsList available reportsA
Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns the list of available report IDs with metadata including name, columns, and supported precisions

Inputs: account.

list_webhook_eventsGet webhook eventsA
Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Get webhook events with pagination and optional filtering by one or more webhook types (repeat or comma-separate the type param). The maximum page size is 100 - larger values are capped at 100.

Inputs: page, size, type, account.

list_webhooksGet webhooksB
Read-onlyIdempotent

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Get webhooks

Inputs: account.

mark_download_completeMark digital download as downloadedA
Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Marks digital download as downloaded. If no downloads exist for a digital order and defaultFileUrl is provided in the request body, creates a download with that URL and marks it as downloaded.

Inputs: order_id (required), account, confirm, payload, +2 more.

preview_shop_batchReview ordered shop effectsB
Read-onlyIdempotent

Validate every exact request and hash order/profile label/schema locally. No native request, credential loading, ownership check or provider preview.

Inputs: tasks (required), account.

remove_digital_fileRemove a digital file from a productB
Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Removes a digital file from the product by its file URL.

Inputs: product_id (required), account, confirm, fileUrl, +2 more.

remove_product_imagesRemove images from a productB
Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Removes specified images from a product by their URLs.

Inputs: product_id (required), account, confirm, payload, +2 more.

request_digital_file_upload_urlRequest a presigned upload URL for a digital fileA
Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Returns a presigned URL to upload a digital file to. After receiving the response, PUT the file bytes directly to the uploadUrl, then call the confirm endpoint to link the file to the product.

Inputs: product_id (required), output_file (required), size, account, +5 more.

request_media_upload_urlRequest a pre-signed upload URLB
Destructive

Rate limit: 20 requests / minute per shop. See Rate limiting.

Returns a pre-signed upload URL for uploading a new image. After receiving the response, PUT the image bytes directly to the uploadUrl.

Inputs: output_file (required), size, account, confirm, +4 more.

save_media_imageSave an uploaded image to the media libraryB
Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Persists an uploaded image in the media library after the client has PUT it to the signed URL

Inputs: width, height, account, confirm, +3 more.

search_product_templatesSearch product templatesA
Read-onlyIdempotent

Search product templates by name, brand, description, sizes, categories, colors, or production method. Returns 25 results. To paginate, use the /search/{query}/page/{N} variant of this endpoint (1-indexed). Use the total field in the response to calculate total pages. Pagination is path-based for HTTP cacheability.

Inputs: query (required), account.

search_product_templates_groupedSearch product templates grouped by product familyA
Read-onlyIdempotent

Search product templates and group results by product family (libraryId). Products sharing the same physical item but with different production methods (e.g. DTG, Embroidery, DTFX) are collapsed into a single result with a variants list. Returns 25 grouped results. To paginate, use the /search-grouped/{query}/page/{N} variant (1-indexed). Pagination is path-based for HTTP cacheability.

Inputs: query (required), account.

search_product_templates_grouped_pagedSearch product templates grouped by product family by pageB
Read-onlyIdempotent

Search product templates grouped by product family with pagination. This endpoint is public and does not require authentication.

Inputs: page (required), query (required), account.

search_product_templates_pagedSearch product templates by pageB
Read-onlyIdempotent

Search product templates with pagination. This endpoint is public and does not require authentication.

Inputs: page (required), query (required), account.

start_streamingSet streaming status to startedB
Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Sets streaming status to started for specified services

Inputs: account, confirm, payload, services, +1 more.

submit_shop_batchExecute reviewed shop effectsB
Destructive

Confirmed ordered effects; all validated/hash checked before first request. Stop on first failure with known and unattempted receipts; no retry, rollback or implicit continuation.

Inputs: tasks (required), review_sha256 (required), account, confirm.

toggle_product_availabilityUpdate product (offer) availability by idB
Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Updates a product (offer) availability

Inputs: product_id (required), account, confirm, payload, +2 more.

update_collectionUpdate a collectionB
Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Updates collection name, description, and/or product list

Inputs: collection_id (required), name, account, confirm, +4 more.

update_collection_availabilityUpdate collection availabilityB
Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Toggle collection availability (available/unavailable)

Inputs: collection_id (required), account, confirm, payload, +2 more.

update_collection_productsSet collection productsA
Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Sets the full list of product IDs in the collection

Inputs: collection_id (required), account, confirm, payload, +2 more.

update_gifting_configUpdate gifting configA
Destructive

Writes the four creator-controlled gifting rule fields. Validation (duration 20-180s, valid shipping/products) and the one-platform-per-shop mutex are enforced server-side. Upserts: a first-ever PUT materializes the config row.

Inputs: account, confirm, enabled, payload, +4 more.

update_product_stateUpdate product (offer) lifecycle stateA
Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Transitions the product between PUBLIC and HIDDEN. Use DELETE /products/{productId} to archive — ARCHIVED is not reachable here. The sold-out (available) flag is preserved; flip it via PUT /products/{productId}/availability. Idempotent: no-op if the product is already in the requested state.

Inputs: product_id (required), state, account, confirm, +2 more.

update_promotionUpdate a promotionA
Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Updates an existing promotion's configuration. Only provided fields are updated; omitted fields remain unchanged. Status changes (activate/deactivate) are part of the same update call.

Inputs: promotion_id (required), limits, status, account, +5 more.

update_webhookUpdate a webhookC
Destructive

Rate limit: 100 requests / 10 seconds per shop. See Rate limiting.

Update a webhook

Inputs: webhook_configuration_id (required), url, account, confirm, +3 more.

upload_fileUpload exact bytes from a private receiptA
Destructive

Explicitly confirmed Google Storage PUT using a selected private upload receipt and a bounded local regular file. Exact size/Content-Type and x-goog-content-length-range are preserved. No Fourthwall credentials or redirects, no automatic registration/publishing.

Inputs: input_file (required), receipt_file (required), account, confirm.

validate_dnsValidate DNS recordsA
Destructive

Rate limit: 20 requests / minute per shop. See Rate limiting.

Triggers a live DNS validation by checking all configured records against actual DNS servers and updates their verification status

Inputs: account, confirm.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.9/5.0

    Scored across 86 tools

    Disambiguation2/5

    Many tools have overlapping purposes, especially the eight product-template tools (e.g., list_product_templates vs list_product_templates_paged vs search_product_templates_grouped) and the giveaway/gifting cluster (create_giveaway, create_giveaway_checkout, create_giveaway_links, finish_giveaway, finish_giveaway_draw). An agent could easily misselect among these.

    Naming Consistency5/5

    All tool names use consistent snake_case with a verb_noun structure (get_, list_, create_, update_, delete_, etc.). Minor suffixes like _paged or _grouped are predictable and the pattern holds throughout.

    Tool Count1/5

    86 tools is far beyond the recommended 3-15 range for an MCP server and indicates an extreme mismatch. The surface is unwieldy and significantly increases selection complexity.

    Completeness3/5

    While many lifecycles are covered (promotions, webhooks, collections partially), there are notable gaps: no delete_collection, no general product update for name/description, no create/update for members or mailing list, and no shop settings update. These gaps may force workarounds.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      A Shopify-focused MCP server that enables AI agents to manage store operations like order tracking, product discovery, and checkout link generation. It facilitates customer-facing interactions including shipping estimates and real-time inventory searches.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to interact with live Shopify stores through Admin and Storefront APIs for tasks like GraphQL execution, bulk operations, and file uploads. It includes built-in rate limiting and operation logging to manage store data and schema discovery securely.
      25 npm
      3
      ISC
    • A
      license
      Not graded
      quality
      B
      maintenance
      A production-grade MCP server and CLI tool that enables AI agents to manage Shopify stores through 49 built-in tools across products, orders, inventory, and analytics. It supports natural language workflows for tasks like inventory tracking, customer support, and sales reporting.
      888 npm
      18
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Production-grade MCP server for the Shopify Admin GraphQL API, exposing typed tools for AI agents to manage products, orders, customers, and more.
      41 npm
      MIT