analyze-image
ChatGPTInternal helper for the media-library widget. Run a vision analysis on an image that already has a URL (a selected media-library image) and return its description plus the analyzed URL. Not a user-facing action — the widget calls it when the user confirms a selected image. Safe to re-call: results are cached by image identity. Parameters: - imageUrl: The image to analyze — a media-library CDN URL or a GCS object URL in Omni's bucket.
analyze-image
ChatGPTInternal helper for the media-library widget. Run a vision analysis on an image that already has a URL (a selected media-library image) and return its description plus the analyzed URL. Not a user-facing action — the widget calls it when the user confirms a selected image. Safe to re-call: results are cached by image identity. Parameters: - imageUrl: The image to analyze — a media-library CDN URL or a GCS object URL in Omni's bucket.
brand_analyze
ChatGPTStage 1 of brand extraction: analyze a brand sheet and stash a checkpoint. Runs the vision analyzer on the image. Does NOT extract a logo or run any image generation — that happens in brand_extract_assets. Returns a checkpoint_uri that the follow-up call uses to pull only the artworks/logo it actually needs. Parameters: - image_path: Source brand sheet (PNG/JPEG) or brand deck (PDF). For PDF input a cheap text-only selector picks the most informative pages (at most 6), rasterizes them, and sends them to the vision model in one call — useful for multi-page merch decks or brand guidelines. When pages were dropped, checkpoint_md carries a NOTE saying so. Accepts a local filesystem path, an http(s):// URL (fetched anonymously), or a gs://bucket/key URI (fetched via the gateway's Workload Identity SA). The https://storage.googleapis.com/<bucket>/<key> form (and its storage.cloud.google.com / virtual-hosted variants) is also accepted and routed through the SA. Returns a dict with: - checkpoint_uri: opaque URI (gs:// in prod, file:// in local dev) that pins this analysis run; pass back as the first argument to brand_extract_assets. - brand_name: confirm with the user before spending image-gen calls. - checkpoint_md: a markdown summary of the brand (mood, palette, typography, logo description, products, and the artwork "menu" with ids and descriptions). Use this to decide which want_artwork_ids to request next. - artwork_candidates: structured list of {id, kind, name, description} for the same menu — the id values are what brand_extract_assets accepts in want_artwork_ids. - logo_description: verbal description of the primary logo, helpful for confirming "yes this is the right brand" before extraction. Typical flow: r1 = brand_analyze(image_path="...") confirm r1["brand_name"] with the user, pick artwork ids from r1["artwork_candidates"], then: r2 = brand_extract_assets( checkpoint_uri=r1["checkpoint_uri"], want_logo=True, want_artwork_ids=["main_logo", "side_heart"], ) For long brand decks where the synchronous round-trip risks an MCP proxy timeout, use brand_analyze_start + brand_analyze_status instead — they expose the same pipeline behind a job_id poll loop.
brand_analyze
ChatGPTStage 1 of brand extraction: analyze a brand sheet and stash a checkpoint. Runs the vision analyzer on the image. Does NOT extract a logo or run any image generation — that happens in brand_extract_assets. Returns a checkpoint_uri that the follow-up call uses to pull only the artworks/logo it actually needs. Parameters: - image_path: Source brand sheet (PNG/JPEG) or brand deck (PDF). For PDF input a cheap text-only selector picks the most informative pages (at most 6), rasterizes them, and sends them to the vision model in one call — useful for multi-page merch decks or brand guidelines. When pages were dropped, checkpoint_md carries a NOTE saying so. Accepts a local filesystem path, an http(s):// URL (fetched anonymously), or a gs://bucket/key URI (fetched via the gateway's Workload Identity SA). The https://storage.googleapis.com/<bucket>/<key> form (and its storage.cloud.google.com / virtual-hosted variants) is also accepted and routed through the SA. Returns a dict with: - checkpoint_uri: opaque URI (gs:// in prod, file:// in local dev) that pins this analysis run; pass back as the first argument to brand_extract_assets. - brand_name: confirm with the user before spending image-gen calls. - checkpoint_md: a markdown summary of the brand (mood, palette, typography, logo description, products, and the artwork "menu" with ids and descriptions). Use this to decide which want_artwork_ids to request next. - artwork_candidates: structured list of {id, kind, name, description} for the same menu — the id values are what brand_extract_assets accepts in want_artwork_ids. - logo_description: verbal description of the primary logo, helpful for confirming "yes this is the right brand" before extraction. Typical flow: r1 = brand_analyze(image_path="...") confirm r1["brand_name"] with the user, pick artwork ids from r1["artwork_candidates"], then: r2 = brand_extract_assets( checkpoint_uri=r1["checkpoint_uri"], want_logo=True, want_artwork_ids=["main_logo", "side_heart"], ) For long brand decks where the synchronous round-trip risks an MCP proxy timeout, use brand_analyze_start + brand_analyze_status instead — they expose the same pipeline behind a job_id poll loop.
brand_analyze_start
ChatGPTAsync variant of brand_analyze. Enqueues the analysis and returns immediately, or returns the inline result if the job finishes inside the ~50s budget. Parameters: - image_path: same shape as brand_analyze (local path, http(s) URL, gs:// URI, or storage.googleapis.com URL). Returns either: - {"status": "done", "result": {...}} — the analysis finished inside the inline wait window; treat result exactly like brand_analyze would have returned. - {"job_id": "ba_...", "status": "pending" | "running", "progress": {...}} — the job is still in flight. Poll brand_analyze_status(job_id) every 5–10 seconds. Typical brand-deck jobs take 120–180s; very short single-image inputs may return inline. On failure surfaces {"job_id": "ba_...", "status": "failed", "error": "..."} rather than raising, so the model can decide whether to retry.
brand_analyze_start
ChatGPTAsync variant of brand_analyze. Enqueues the analysis and returns immediately, or returns the inline result if the job finishes inside the ~50s budget. Parameters: - image_path: same shape as brand_analyze (local path, http(s) URL, gs:// URI, or storage.googleapis.com URL). Returns either: - {"status": "done", "result": {...}} — the analysis finished inside the inline wait window; treat result exactly like brand_analyze would have returned. - {"job_id": "ba_...", "status": "pending" | "running", "progress": {...}} — the job is still in flight. Poll brand_analyze_status(job_id) every 5–10 seconds. Typical brand-deck jobs take 120–180s; very short single-image inputs may return inline. On failure surfaces {"job_id": "ba_...", "status": "failed", "error": "..."} rather than raising, so the model can decide whether to retry.
brand_analyze_status
ChatGPTPoll the status of a brand_analyze_start job. Parameters: - job_id: the id returned by brand_analyze_start. Returns: - {"job_id", "status": "pending" | "running" | "done" | "failed", ...} - progress (optional): {stage, pct} while running. - result present when status=="done" — same shape as brand_analyze. - error present when status=="failed". Returns within ~1s. Raises if job_id is unknown or has aged out of the 24h TTL.
brand_analyze_status
ChatGPTPoll the status of a brand_analyze_start job. Parameters: - job_id: the id returned by brand_analyze_start. Returns: - {"job_id", "status": "pending" | "running" | "done" | "failed", ...} - progress (optional): {stage, pct} while running. - result present when status=="done" — same shape as brand_analyze. - error present when status=="failed". Returns within ~1s. Raises if job_id is unknown or has aged out of the 24h TTL.
brand_extract_assets
ChatGPTStage 2 of brand extraction: produce just the assets you actually need. Reads the checkpoint produced by brand_analyze, then runs the logo stage and/or a focused per-artwork extraction for only the requested ids. Outputs are uploaded back into the same checkpoint, so calling this again with a different want_artwork_ids set extracts more without re-running analysis. Parameters: - checkpoint_uri: the URI returned by brand_analyze. - want_logo: extract the pixel-faithful 2048x2048 transparent logo PNG. Default True — flip to False on follow-up calls when you only want additional artworks. - want_artwork_ids: list of artwork ids (from brand_analyze's artwork_candidates) to extract as transparent PNGs. Each id costs one medium-quality parallel gpt-image-2 call. Pass an empty list (or omit) to skip artwork extraction. Unknown ids raise — the message lists what's available so you can correct. At least one of want_logo=True or a non-empty want_artwork_ids must be set; otherwise the call has nothing to do and raises. Returns a dict with: - checkpoint_uri: echoed back so the model can chain another call. - brand_name - logo_compact: gs:// URI of a downsized, <512 KB transparent logo PNG. Pass it as data to storefront_update-draft-theme-logo (and to any downstream tool that wants the brand logo — there is no high-res variant; this is the canonical logo asset). None if want_logo=False or the checkpoint bucket is unset. - favicon: gs:// URI of a square <512 KB favicon PNG derived from the same logo. Pass it as data to storefront_update-draft-theme-favicon. None if want_logo=False or the checkpoint bucket is unset. - artworks: list of {id, kind, name, upload, media} for every successfully extracted id. upload is the gs:// URI; media is the media-library entry — pass media[].media_url to ecommerce tools like ecommerce_generate-product-design-previews so they can resolve the asset without a separate upload step. - failed_artworks: list of {id, kind, name, error_kind, message} for ids the model service refused. error_kind is one of moderation_blocked, rate_limited, bad_request, api_error, other — moderation_blocked means OpenAI's safety system rejected that specific artwork prompt; the caller should drop or rephrase that id and retry without it. - cost: usage summary for the artwork stage — {input_text_tokens, input_image_tokens, output_image_tokens, total_tokens, estimated_usd, calls}. Estimate uses published gpt-image rates; the OpenAI invoice is authoritative. For long extractions where the synchronous round-trip risks an MCP proxy timeout, use brand_extract_assets_start + brand_extract_assets_status — same pipeline behind a job_id poll.
brand_extract_assets
ChatGPTStage 2 of brand extraction: produce just the assets you actually need. Reads the checkpoint produced by brand_analyze, then runs the logo stage and/or a focused per-artwork extraction for only the requested ids. Outputs are uploaded back into the same checkpoint, so calling this again with a different want_artwork_ids set extracts more without re-running analysis. Parameters: - checkpoint_uri: the URI returned by brand_analyze. - want_logo: extract the pixel-faithful 2048x2048 transparent logo PNG. Default True — flip to False on follow-up calls when you only want additional artworks. - want_artwork_ids: list of artwork ids (from brand_analyze's artwork_candidates) to extract as transparent PNGs. Each id costs one medium-quality parallel gpt-image-2 call. Pass an empty list (or omit) to skip artwork extraction. Unknown ids raise — the message lists what's available so you can correct. At least one of want_logo=True or a non-empty want_artwork_ids must be set; otherwise the call has nothing to do and raises. Returns a dict with: - checkpoint_uri: echoed back so the model can chain another call. - brand_name - logo_compact: gs:// URI of a downsized, <512 KB transparent logo PNG. Pass it as data to storefront_update-draft-theme-logo (and to any downstream tool that wants the brand logo — there is no high-res variant; this is the canonical logo asset). None if want_logo=False or the checkpoint bucket is unset. - favicon: gs:// URI of a square <512 KB favicon PNG derived from the same logo. Pass it as data to storefront_update-draft-theme-favicon. None if want_logo=False or the checkpoint bucket is unset. - artworks: list of {id, kind, name, upload, media} for every successfully extracted id. upload is the gs:// URI; media is the media-library entry — pass media[].media_url to ecommerce tools like ecommerce_generate-product-design-previews so they can resolve the asset without a separate upload step. - failed_artworks: list of {id, kind, name, error_kind, message} for ids the model service refused. error_kind is one of moderation_blocked, rate_limited, bad_request, api_error, other — moderation_blocked means OpenAI's safety system rejected that specific artwork prompt; the caller should drop or rephrase that id and retry without it. - cost: usage summary for the artwork stage — {input_text_tokens, input_image_tokens, output_image_tokens, total_tokens, estimated_usd, calls}. Estimate uses published gpt-image rates; the OpenAI invoice is authoritative. For long extractions where the synchronous round-trip risks an MCP proxy timeout, use brand_extract_assets_start + brand_extract_assets_status — same pipeline behind a job_id poll.
brand_extract_assets_start
ChatGPTAsync variant of brand_extract_assets. Enqueues the extraction and returns immediately, or returns the inline result if the job finishes inside the ~50s budget. Parameters: same as brand_extract_assets. Returns either: - {"status": "done", "result": {...}} — the extraction finished inline; treat result exactly like brand_extract_assets would have returned. - {"job_id": "bx_...", "status": "pending" | "running", "progress": {...}} — the job is still in flight. Poll brand_extract_assets_status(job_id) every 5–10 seconds. Typical extractions take 60–180s depending on how many artwork ids you requested. On failure surfaces {"job_id": "bx_...", "status": "failed", "error": "..."}.
brand_extract_assets_start
ChatGPTAsync variant of brand_extract_assets. Enqueues the extraction and returns immediately, or returns the inline result if the job finishes inside the ~50s budget. Parameters: same as brand_extract_assets. Returns either: - {"status": "done", "result": {...}} — the extraction finished inline; treat result exactly like brand_extract_assets would have returned. - {"job_id": "bx_...", "status": "pending" | "running", "progress": {...}} — the job is still in flight. Poll brand_extract_assets_status(job_id) every 5–10 seconds. Typical extractions take 60–180s depending on how many artwork ids you requested. On failure surfaces {"job_id": "bx_...", "status": "failed", "error": "..."}.
brand_extract_assets_status
ChatGPTPoll the status of a brand_extract_assets_start job. Parameters: - job_id: the id returned by brand_extract_assets_start. Returns: - {"job_id", "status": "pending" | "running" | "done" | "failed", ...} - progress (optional): {stage, pct} while running. - result present when status=="done" — same shape as brand_extract_assets. - error present when status=="failed". Returns within ~1s. Raises if job_id is unknown or has aged out of the 24h TTL.
brand_extract_assets_status
ChatGPTPoll the status of a brand_extract_assets_start job. Parameters: - job_id: the id returned by brand_extract_assets_start. Returns: - {"job_id", "status": "pending" | "running" | "done" | "failed", ...} - progress (optional): {stage, pct} while running. - result present when status=="done" — same shape as brand_extract_assets. - error present when status=="failed". Returns within ~1s. Raises if job_id is unknown or has aged out of the 24h TTL.
confirm-image-upload
ChatGPTInternal helper for the show-upload widget. Confirm that an image finished uploading and return a vision analysis of it. Not a user-facing action — the widget calls it after PUTting the file. Safe to re-call: an already-confirmed upload returns the cached analysis. Returns two URLs for the same image, used for different purposes: - url: the stable internal GCS URL — use this for any further processing (handing the image to the model, chaining into other tools). Never expires, but the browser can't fetch it. - publicUrl: a time-limited signed read URL — use this only to show the image to the user (e.g. the widget's preview). Don't pass it on for further processing; it expires after ~60 minutes. Parameters: - uploadId: The id returned by request-upload-url.
confirm-image-upload
ChatGPTInternal helper for the show-upload widget. Confirm that an image finished uploading and return a vision analysis of it. Not a user-facing action — the widget calls it after PUTting the file. Safe to re-call: an already-confirmed upload returns the cached analysis. Returns two URLs for the same image, used for different purposes: - url: the stable internal GCS URL — use this for any further processing (handing the image to the model, chaining into other tools). Never expires, but the browser can't fetch it. - publicUrl: a time-limited signed read URL — use this only to show the image to the user (e.g. the widget's preview). Don't pass it on for further processing; it expires after ~60 minutes. Parameters: - uploadId: The id returned by request-upload-url.
ecommerce_activate-promotion
ChatGPTReactivate a promotion (set status to LIVE). Only works for ENDED promotions. Cannot activate ARCHIVED or ALL_USED promotions. Use when a shop owner wants to re-enable a previously deactivated discount code.
ecommerce_activate-promotion
ChatGPTReactivate a promotion (set status to LIVE). Only works for ENDED promotions. Cannot activate ARCHIVED or ALL_USED promotions. Use when a shop owner wants to re-enable a previously deactivated discount code.
ecommerce_add-design-region
ChatGPTAdds a new print region to an existing customization's design state with an initial image. Use this when the user wants to place artwork on a region that the catalog product supports (availableRegions from inspect-design) but the current customization doesn't yet contain. edit-design cannot add new regions — it only mutates regions already present in the state. BEFORE calling: - inspect-design to confirm the regionId is in availableRegions and not already in the state's sizes[*].regions[*].regionId list (i.e. not already added). - The image must already be saved (use ecommerce_save-media-library-image first); pass its CDN href plus natural width/height in pixels. AFTER calling: use rerender-design-previews with customizationId to regenerate preview images. Returns the updated inspect summary plus the same availableRegions list inspect-design exposes. Errors: - DESIGN_PIPELINE_INVALID_REGIONS — regionId is not on the catalog product. Surface validRegions to the user. - DESIGN_PIPELINE_BAD_REQUEST with "already part of this design" — the region is already in the state; use edit-design instead.
ecommerce_add-design-region
ChatGPTAdds a new print region to an existing customization's design state with an initial image. Use this when the user wants to place artwork on a region that the catalog product supports (availableRegions from inspect-design) but the current customization doesn't yet contain. edit-design cannot add new regions — it only mutates regions already present in the state. BEFORE calling: - inspect-design to confirm the regionId is in availableRegions and not already in the state's sizes[*].regions[*].regionId list (i.e. not already added). - The image must already be saved (use ecommerce_save-media-library-image first); pass its CDN href plus natural width/height in pixels. AFTER calling: use rerender-design-previews with customizationId to regenerate preview images. Returns the updated inspect summary plus the same availableRegions list inspect-design exposes. Errors: - DESIGN_PIPELINE_INVALID_REGIONS — regionId is not on the catalog product. Surface validRegions to the user. - DESIGN_PIPELINE_BAD_REQUEST with "already part of this design" — the region is already in the state; use edit-design instead.
ecommerce_add-draft-colors
ChatGPTAdds colors to the draft's color selection. Does NOT affect the live product. Each color must appear in the product's availableColors (case-sensitive). Read availableColors from get-draft-attributes before calling. Passing an unknown color throws CUSTOMIZATION_INVALID_COLORS with the valid set — surface the valid options to the user and stop; do not retry with guessed spellings (e.g. "heather grey" vs "Heather Gray"). Use rerender-design-previews after to see updated previews. Use apply-draft-to-product when the creator confirms changes.
ecommerce_add-draft-colors
ChatGPTAdds colors to the draft's color selection. Does NOT affect the live product. Each color must appear in the product's availableColors (case-sensitive). Read availableColors from get-draft-attributes before calling. Passing an unknown color throws CUSTOMIZATION_INVALID_COLORS with the valid set — surface the valid options to the user and stop; do not retry with guessed spellings (e.g. "heather grey" vs "Heather Gray"). Use rerender-design-previews after to see updated previews. Use apply-draft-to-product when the creator confirms changes.
ecommerce_add-draft-sizes
ChatGPTAdds sizes to the draft's size selection. Does NOT affect the live product. Each size must appear in the product's availableSizes (case-sensitive). Read availableSizes from get-draft-attributes before calling. Passing an unknown size throws CUSTOMIZATION_INVALID_SIZES with the valid set — surface the valid options to the user and stop; do not retry with guessed sizes (e.g. requesting "3XL" when the product caps at "2XL"). Use rerender-design-previews after to see updated previews. Use apply-draft-to-product when the creator confirms changes.
ecommerce_add-draft-sizes
ChatGPTAdds sizes to the draft's size selection. Does NOT affect the live product. Each size must appear in the product's availableSizes (case-sensitive). Read availableSizes from get-draft-attributes before calling. Passing an unknown size throws CUSTOMIZATION_INVALID_SIZES with the valid set — surface the valid options to the user and stop; do not retry with guessed sizes (e.g. requesting "3XL" when the product caps at "2XL"). Use rerender-design-previews after to see updated previews. Use apply-draft-to-product when the creator confirms changes.
ecommerce_apply-draft-to-product
ChatGPTSyncs the current draft state to the live product. Call this ONLY when the creator explicitly confirms the changes. This atomically: 1. Reads the draft's current attributes and design state 2. Rebuilds the product's variants from the draft 3. Recalculates pricing Use rerender-design-previews after to see final product previews.
ecommerce_apply-draft-to-product
ChatGPTSyncs the current draft state to the live product. Call this ONLY when the creator explicitly confirms the changes. This atomically: 1. Reads the draft's current attributes and design state 2. Rebuilds the product's variants from the draft 3. Recalculates pricing Use rerender-design-previews after to see final product previews.
ecommerce_bulk-update-offer-variant-prices
ChatGPTBulk-update prices across an offer's variants. Call get-offers-by-ids first to see current variants and prices. Pick ONE mode: - UNIFORM — omit groupBy. Set price (and optional compareAtPrice) on every active variant. - BY ATTRIBUTE — set groupBy to SIZE/COLOR/CUSTOM and pass priceUpdates as an array of {attributeValue, price, compareAtPrice?} entries. Variants whose attribute value is not in the array are left unchanged. Example priceUpdates: [{"attributeValue":"S","price":10.00},{"attributeValue":"L","price":20.00,"compareAtPrice":30.00}] Rules: - price and priceUpdates are mutually exclusive — pass exactly one. - All prices are set in USD dollars, NOT cents (9.99 = $9.99). Shops price in USD; checkout handles currency conversion automatically. - priceUpdates is a plain JSON array, NOT a stringified JSON string.
ecommerce_bulk-update-offer-variant-prices
ChatGPTBulk-update prices across an offer's variants. Call get-offers-by-ids first to see current variants and prices. Pick ONE mode: - UNIFORM — omit groupBy. Set price (and optional compareAtPrice) on every active variant. - BY ATTRIBUTE — set groupBy to SIZE/COLOR/CUSTOM and pass priceUpdates as an array of {attributeValue, price, compareAtPrice?} entries. Variants whose attribute value is not in the array are left unchanged. Example priceUpdates: [{"attributeValue":"S","price":10.00},{"attributeValue":"L","price":20.00,"compareAtPrice":30.00}] Rules: - price and priceUpdates are mutually exclusive — pass exactly one. - All prices are set in USD dollars, NOT cents (9.99 = $9.99). Shops price in USD; checkout handles currency conversion automatically. - priceUpdates is a plain JSON array, NOT a stringified JSON string.
ecommerce_cancel-giveaway-links
ChatGPTCancel giveaway links. IRREVERSIBLE. Always confirm with the user first. Provide EITHER giftId (cancel one link) OR packageId (cancel all available links in package). Only AVAILABLE links are cancelled. Already redeemed links are unaffected.
ecommerce_cancel-giveaway-links
ChatGPTCancel giveaway links. IRREVERSIBLE. Always confirm with the user first. Provide EITHER giftId (cancel one link) OR packageId (cancel all available links in package). Only AVAILABLE links are cancelled. Already redeemed links are unaffected.
ecommerce_cancel-order
ChatGPTCancel a full or partial order. IRREVERSIBLE. ALWAYS confirm with the user before calling. Before calling, use get-order-cancellation-by-ids to check eligibility: - For a full cancellation: fullyCancellable must be true. - For a partial cancellation: partiallyCancellable must be true; pass an itemsToCancel subset of cancellableItems (variantId + quantity). Omit itemsToCancel (or pass empty) to cancel the whole order. Payment handling — done automatically, no separate confirmation step: - If the shop's balance covers the refund, the refund is issued immediately (status = CANCELLED). - If the balance is insufficient, the shortfall is charged to the shop's card and the cancellation is queued (status = CHARGE_INITIATED). A background job finalizes the cancellation once the charge settles. If the charge fails, the cancellation is abandoned and the order stays open. The response fields fromBalance, chargeAmount, and status make this explicit. Always surface these to the user — especially chargeAmount when > 0. Permission: requires ORDER_WRITE role on the shop. Typical rejection reasons (returned as errors from the endpoint): - STATUS: order already cancelled, failed, etc. - IN_PRODUCTION_OR_DELIVERING: items in fulfillment - OLDER_THAN_ALLOWED_CANCELLATION_TIMEFRAME - CONTAINS_DIGITAL_ITEMS / GIFT_CARD_ALREADY_USED - REFUND_IN_PROGRESS: an existing refund is pending; wait or resolve first - ExpectedChargeAmountChanged: a rare race where the required charge changed between our estimate and submission; just retry.
ecommerce_cancel-order
ChatGPTCancel a full or partial order. IRREVERSIBLE. ALWAYS confirm with the user before calling. Before calling, use get-order-cancellation-by-ids to check eligibility: - For a full cancellation: fullyCancellable must be true. - For a partial cancellation: partiallyCancellable must be true; pass an itemsToCancel subset of cancellableItems (variantId + quantity). Omit itemsToCancel (or pass empty) to cancel the whole order. Payment handling — done automatically, no separate confirmation step: - If the shop's balance covers the refund, the refund is issued immediately (status = CANCELLED). - If the balance is insufficient, the shortfall is charged to the shop's card and the cancellation is queued (status = CHARGE_INITIATED). A background job finalizes the cancellation once the charge settles. If the charge fails, the cancellation is abandoned and the order stays open. The response fields fromBalance, chargeAmount, and status make this explicit. Always surface these to the user — especially chargeAmount when > 0. Permission: requires ORDER_WRITE role on the shop. Typical rejection reasons (returned as errors from the endpoint): - STATUS: order already cancelled, failed, etc. - IN_PRODUCTION_OR_DELIVERING: items in fulfillment - OLDER_THAN_ALLOWED_CANCELLATION_TIMEFRAME - CONTAINS_DIGITAL_ITEMS / GIFT_CARD_ALREADY_USED - REFUND_IN_PROGRESS: an existing refund is pending; wait or resolve first - ExpectedChargeAmountChanged: a rare race where the required charge changed between our estimate and submission; just retry.
ecommerce_change-order-shipping-address
ChatGPTUpdate the shipping address on an order. Only allowed before items enter production or shipping. The use case verifies: - Order status permits address changes (not in production/shipped/delivered/cancelled) - All items have canUpdateAddress == true for this issuer - Third-party fulfillment systems accept the update If the address is identical to the current one, the call is a no-op and returns the order unchanged. Emits OrderAddressChangedEvent on change. Permission: requires ORDER_WRITE role on the shop. Required fields: firstName, lastName, address1, city, country. Optional fields: address2, state, zip, phone. Returns the updated order summary (same shape as get-order-details-by-ids).
ecommerce_change-order-shipping-address
ChatGPTUpdate the shipping address on an order. Only allowed before items enter production or shipping. The use case verifies: - Order status permits address changes (not in production/shipped/delivered/cancelled) - All items have canUpdateAddress == true for this issuer - Third-party fulfillment systems accept the update If the address is identical to the current one, the call is a no-op and returns the order unchanged. Emits OrderAddressChangedEvent on change. Permission: requires ORDER_WRITE role on the shop. Required fields: firstName, lastName, address1, city, country. Optional fields: address2, state, zip, phone. Returns the updated order summary (same shape as get-order-details-by-ids).
ecommerce_create-bundle
ChatGPTCreate a new bundle offer — a group of existing offers sold together at a combined price. The bundle starts in HIDDEN state. Use update-bundle to change status to PUBLIC when ready.
ecommerce_create-bundle
ChatGPTCreate a new bundle offer — a group of existing offers sold together at a combined price. The bundle starts in HIDDEN state. Use update-bundle to change status to PUBLIC when ready.
ecommerce_create-collection
ChatGPTCreate a new collection for the shop. Collections group products (offers) together for display on the storefront. Required fields: - name: Collection display name (max 200 chars) - description: Collection description (HTML allowed) - available: Whether the collection is available - offerIds: List of Offer IDs to include in the collection Optional fields: - availableFrom/availableTo: Schedule when the collection becomes visible (ISO 8601 datetime) The collection is created in HIDDEN state. Use update-collection-state to make it PUBLIC. Returns the created collection with: - Identity: id (CollectionId), shopId (ShopId), name, slug, description - Visibility: available (boolean), state (PUBLIC/HIDDEN/ARCHIVED) - Time-based availability: availableFrom (nullable ISO 8601), availableTo (nullable ISO 8601) - Products: offerIds (list of OfferIds) - Sorting: sortingStrategy (MANUAL/BEST_SELLING/NEWEST/OLDEST/NAME_ASC/NAME_DESC)
ecommerce_create-collection
ChatGPTCreate a new collection for the shop. Collections group products (offers) together for display on the storefront. Required fields: - name: Collection display name (max 200 chars) - description: Collection description (HTML allowed) - available: Whether the collection is available - offerIds: List of Offer IDs to include in the collection Optional fields: - availableFrom/availableTo: Schedule when the collection becomes visible (ISO 8601 datetime) The collection is created in HIDDEN state. Use update-collection-state to make it PUBLIC. Returns the created collection with: - Identity: id (CollectionId), shopId (ShopId), name, slug, description - Visibility: available (boolean), state (PUBLIC/HIDDEN/ARCHIVED) - Time-based availability: availableFrom (nullable ISO 8601), availableTo (nullable ISO 8601) - Products: offerIds (list of OfferIds) - Sorting: sortingStrategy (MANUAL/BEST_SELLING/NEWEST/OLDEST/NAME_ASC/NAME_DESC)
ecommerce_create-combined-listing
ChatGPTCreate a combined listing — merges color variants from multiple offers (same product library) into one storefront product. Unlike bundles, combined listings share the same product library. All offers must have compatible colors (no duplicates). The listing starts in HIDDEN state. Use update-combined-listing to change status to PUBLIC when ready. Use validate-combined-listing first to check if offers are compatible.
ecommerce_create-combined-listing
ChatGPTCreate a combined listing — merges color variants from multiple offers (same product library) into one storefront product. Unlike bundles, combined listings share the same product library. All offers must have compatible colors (no duplicates). The listing starts in HIDDEN state. Use update-combined-listing to change status to PUBLIC when ready. Use validate-combined-listing first to check if offers are compatible.
ecommerce_create-gift-cards
ChatGPTCreate gift cards (store credit) with an amount, optionally with custom codes. Skip the codes parameter unless the user explicitly asks for specific codes — random 12-character friendly codes (e.g., "L3WQNU1MV4W9") will be generated automatically. Use numberOfCards to control how many cards to create with auto-generated codes (defaults to 1, max 50). When codes IS provided: single code = single card, multiple codes = bulk group (1-50). All cards share the same amount and expiration. Codes are auto-uppercased, 8-36 chars, alphanumeric. Returns created card details (single) or group ID (bulk). Use get-gift-cards to browse. All amounts are set in USD dollars (NOT cents) — gift cards are priced in the shop's USD, and checkout handles currency conversion for non-USD customers. Examples: • Auto-generated single: amount=50 • Auto-generated bulk: numberOfCards=10, amount=25 • Single with custom code: codes=["GIFT50"], amount=50 • Bulk with custom codes: codes=["VIP1","VIP2","VIP3"], amount=25, expiresAt="2026-12-31T23:59:59Z"
ecommerce_create-gift-cards
ChatGPTCreate gift cards (store credit) with an amount, optionally with custom codes. Skip the codes parameter unless the user explicitly asks for specific codes — random 12-character friendly codes (e.g., "L3WQNU1MV4W9") will be generated automatically. Use numberOfCards to control how many cards to create with auto-generated codes (defaults to 1, max 50). When codes IS provided: single code = single card, multiple codes = bulk group (1-50). All cards share the same amount and expiration. Codes are auto-uppercased, 8-36 chars, alphanumeric. Returns created card details (single) or group ID (bulk). Use get-gift-cards to browse. All amounts are set in USD dollars (NOT cents) — gift cards are priced in the shop's USD, and checkout handles currency conversion for non-USD customers. Examples: • Auto-generated single: amount=50 • Auto-generated bulk: numberOfCards=10, amount=25 • Single with custom code: codes=["GIFT50"], amount=50 • Bulk with custom codes: codes=["VIP1","VIP2","VIP3"], amount=25, expiresAt="2026-12-31T23:59:59Z"
ecommerce_create-giveaway-links
ChatGPTCreate a package of giveaway links (free product URLs) for a product. Each link is a unique URL someone can use to claim a free product. Links are grouped into a package. REQUIRED: • offerId: product ID (UUID). Use get-offers to find IDs. • numberOfGifts: how many links to generate (1-50) Returns: packageId + list of created gift IDs. Use get-giveaway-links to see URLs.
ecommerce_create-giveaway-links
ChatGPTCreate a package of giveaway links (free product URLs) for a product. Each link is a unique URL someone can use to claim a free product. Links are grouped into a package. REQUIRED: • offerId: product ID (UUID). Use get-offers to find IDs. • numberOfGifts: how many links to generate (1-50) Returns: packageId + list of created gift IDs. Use get-giveaway-links to see URLs.
ecommerce_create-membership-promotion
ChatGPTCreate a membership discount code (percentage off membership subscription). ⚠ NOT SUPPORTED — do NOT promise these to the user: expiration / end date / start date / scheduled activation. There is no time-based field. durationCharges is the number of BILLING CYCLES the discount applies for (not a calendar date). To stop a code, use deactivate-promotion. DELIVERY MODE — provide exactly one: • code: single promo code (e.g. "MEMBER20") — most common • codes: list of bulk codes for multi-code promotions REQUIRED: • percentage (1-100): discount percentage • subscriptionType: ALL_MEMBERS | MONTHLY_ONLY | ANNUAL_ONLY OPTIONAL: • tierIds: restrict to specific membership tier IDs (null = all tiers). • durationCharges: how many billing cycles the discount lasts (1-1000). Null = lifetime (discount applies to every cycle, never auto-stops). • newMembersOnly: only new members can use this code (default false) • limitToSingleUse: limit code to one total redemption (default false) Examples: • 20% off all members for life: code="MEMBER20", percentage=20, subscriptionType="ALL_MEMBERS" • 50% off first 3 cycles, annual only: code="ANNUAL50", percentage=50, subscriptionType="ANNUAL_ONLY", durationCharges=3 • Bulk codes for new monthly members: codes=["NEW1","NEW2"], percentage=30, subscriptionType="MONTHLY_ONLY", newMembersOnly=true
ecommerce_create-membership-promotion
ChatGPTCreate a membership discount code (percentage off membership subscription). ⚠ NOT SUPPORTED — do NOT promise these to the user: expiration / end date / start date / scheduled activation. There is no time-based field. durationCharges is the number of BILLING CYCLES the discount applies for (not a calendar date). To stop a code, use deactivate-promotion. DELIVERY MODE — provide exactly one: • code: single promo code (e.g. "MEMBER20") — most common • codes: list of bulk codes for multi-code promotions REQUIRED: • percentage (1-100): discount percentage • subscriptionType: ALL_MEMBERS | MONTHLY_ONLY | ANNUAL_ONLY OPTIONAL: • tierIds: restrict to specific membership tier IDs (null = all tiers). • durationCharges: how many billing cycles the discount lasts (1-1000). Null = lifetime (discount applies to every cycle, never auto-stops). • newMembersOnly: only new members can use this code (default false) • limitToSingleUse: limit code to one total redemption (default false) Examples: • 20% off all members for life: code="MEMBER20", percentage=20, subscriptionType="ALL_MEMBERS" • 50% off first 3 cycles, annual only: code="ANNUAL50", percentage=50, subscriptionType="ANNUAL_ONLY", durationCharges=3 • Bulk codes for new monthly members: codes=["NEW1","NEW2"], percentage=30, subscriptionType="MONTHLY_ONLY", newMembersOnly=true
ecommerce_create-offers-from-designs
ChatGPTCreates offers from previously generated design previews — processes multiple designs concurrently. Each design is processed independently — failures for one do not affect others. IMPORTANT: You must call generate-product-design-previews first to get customizationIds. Waits up to 1 minute per design for completion, then returns results. Each result contains: - customizationId: the input customization ID - pipelineId, status, type, offerId?, images[], priceSuggestions?, error? — present on success - bulkError?: string — present on failure Use this tool to: - Create offers after the user approves the preview images Offer names default to the product name when omitted. Offer descriptions default to empty when omitted. Offers are created in HIDDEN state — use update-offer-status to publish. WORKFLOW after creation: tell the user the default price that was applied (read it from priceSuggestions in the result) and that it can be changed any time, then offer to order a physical sample (create-sample-checkout — charged at manufacturing cost only).
ecommerce_create-offers-from-designs
ChatGPTCreates offers from previously generated design previews — processes multiple designs concurrently. Each design is processed independently — failures for one do not affect others. IMPORTANT: You must call generate-product-design-previews first to get customizationIds. Waits up to 1 minute per design for completion, then returns results. Each result contains: - customizationId: the input customization ID - pipelineId, status, type, offerId?, images[], priceSuggestions?, error? — present on success - bulkError?: string — present on failure Use this tool to: - Create offers after the user approves the preview images Offer names default to the product name when omitted. Offer descriptions default to empty when omitted. Offers are created in HIDDEN state — use update-offer-status to publish. WORKFLOW after creation: tell the user the default price that was applied (read it from priceSuggestions in the result) and that it can be changed any time, then offer to order a physical sample (create-sample-checkout — charged at manufacturing cost only).
ecommerce_create-offers-from-products
ChatGPTOne-shot: creates offers directly from product designs in a single call. Skips the preview→approve step — use this when the user pre-approved (e.g. "create offers for all of these") or already saw mockups and just wants offers made. Products are processed concurrently — no polling needed, results returned directly. Each product is processed independently — failures for one product do not affect others. For the preview-first flow (review mockups, then create offers from approved ones), use generate-product-design-previews followed by create-offers-from-designs. regionUrls MUST be URLs from the shop's media library (use get-media-library-images, or upload via request-media-upload-link → PUT file → save-media-library-image). BEFORE calling this tool, use get-catalog-product-details to check: 1. supportsBackendRendering must be true for the product 2. Only use regions from printAreas where supportsBackendRendering=true 3. If a print area has placements, pass the desired placementId for that region Each result contains: - productId: the input product ID - pipelineId, status, type, customizationId, offerId, images[], priceSuggestions?, error? — present on success - bulkError?: string — present on failure WORKFLOW after creation: tell the user the default price that was applied (read it from priceSuggestions in the result) and that it can be changed any time, then offer to order a physical sample (create-sample-checkout — charged at manufacturing cost only).
ecommerce_create-offers-from-products
ChatGPTOne-shot: creates offers directly from product designs in a single call. Skips the preview→approve step — use this when the user pre-approved (e.g. "create offers for all of these") or already saw mockups and just wants offers made. Products are processed concurrently — no polling needed, results returned directly. Each product is processed independently — failures for one product do not affect others. For the preview-first flow (review mockups, then create offers from approved ones), use generate-product-design-previews followed by create-offers-from-designs. regionUrls MUST be URLs from the shop's media library (use get-media-library-images, or upload via request-media-upload-link → PUT file → save-media-library-image). BEFORE calling this tool, use get-catalog-product-details to check: 1. supportsBackendRendering must be true for the product 2. Only use regions from printAreas where supportsBackendRendering=true 3. If a print area has placements, pass the desired placementId for that region Each result contains: - productId: the input product ID - pipelineId, status, type, customizationId, offerId, images[], priceSuggestions?, error? — present on success - bulkError?: string — present on failure WORKFLOW after creation: tell the user the default price that was applied (read it from priceSuggestions in the result) and that it can be changed any time, then offer to order a physical sample (create-sample-checkout — charged at manufacturing cost only).
ecommerce_create-sample-checkout
ChatGPTCreates a checkout session to order product samples at cost. Use get-offers or get-offers-by-ids to find variant IDs for the items to order. Returns: - checkoutPath: Relative path to the checkout page (e.g., "/checkout/ch_abc123") Sample credits are applied automatically at checkout when available; if the balance is zero or insufficient, the buyer pays the remaining amount on the checkout page. You do NOT need to check the balance beforehand — never gate this call on get-sample-credit-balance. Examples: - Order 2 units of a variant: items="8d79c46d-9a56-4266-885b-4b02a21aacd2:2" - Order multiple variants: items="aaa-uuid:1,bbb-uuid:3"
ecommerce_create-sample-checkout
ChatGPTCreates a checkout session to order product samples at cost. Use get-offers or get-offers-by-ids to find variant IDs for the items to order. Returns: - checkoutPath: Relative path to the checkout page (e.g., "/checkout/ch_abc123") Sample credits are applied automatically at checkout when available; if the balance is zero or insufficient, the buyer pays the remaining amount on the checkout page. You do NOT need to check the balance beforehand — never gate this call on get-sample-credit-balance. Examples: - Order 2 units of a variant: items="8d79c46d-9a56-4266-885b-4b02a21aacd2:2" - Order multiple variants: items="aaa-uuid:1,bbb-uuid:3"
ecommerce_create-shop-promotion
ChatGPTCreate a shop discount promotion. ⚠ Use ONLY the parameter names declared on this tool — do not invent or paraphrase. For an entire-order discount, OMIT productIds (there is no appliesTo parameter). ⚠ NOT SUPPORTED — do NOT promise these to the user, even if help articles imply otherwise: • Expiration / end date / start date / scheduled activation — there is no time-based field. To stop a promotion, use deactivate-promotion. To cap total usage, set maxUses. • Stacking rules, per-product discount tiers, BOGO without using FREE_PRODUCTS. All monetary amounts are set in USD dollars (NOT cents) — shops price in USD; checkout handles per-customer currency conversion automatically. RECIPES (each line shows the required fields per discountType): • 10% off all orders: { discountType: "PERCENTAGE", code: "SAVE10", percentage: 10 } • $10 off + free shipping: { discountType: "FIXED_AMOUNT", code: "TAKE10", amount: 10, freeShipping: true } • Free shipping: { discountType: "FREE_SHIPPING", code: "SHIPFREE" } • Free product: { discountType: "FREE_PRODUCTS", code: "FREEGIFT", freeVariantId: "<variant-uuid>" } • Bulk codes: replace code with codes: ["VIP1","VIP2"]. Auto-apply: replace code with autoApplyTitle: "Summer Sale". COMMON OPTIONS (all types): • productIds: restrict to specific offer IDs. OMIT for entire-order (default). • freeShipping: bundle free shipping (PERCENTAGE, FIXED_AMOUNT, FREE_PRODUCTS) • minimumOrderAmount: USD dollars (e.g. 50 = $50) • allowedCountries: ISO 3166-1 alpha-2 codes (e.g. ["US","CA"]). Omit = all. • maxUses (1-1000, omit = unlimited), onePerCustomer (default false) • shippingOption (PERCENTAGE only): EXCLUDED | FREE | FREE_LOWEST_ONLY • lowestShippingOnly (FREE_SHIPPING only); freeProductQuantity (FREE_PRODUCTS only, default 1)
ecommerce_create-shop-promotion
ChatGPTCreate a shop discount promotion. ⚠ Use ONLY the parameter names declared on this tool — do not invent or paraphrase. For an entire-order discount, OMIT productIds (there is no appliesTo parameter). ⚠ NOT SUPPORTED — do NOT promise these to the user, even if help articles imply otherwise: • Expiration / end date / start date / scheduled activation — there is no time-based field. To stop a promotion, use deactivate-promotion. To cap total usage, set maxUses. • Stacking rules, per-product discount tiers, BOGO without using FREE_PRODUCTS. All monetary amounts are set in USD dollars (NOT cents) — shops price in USD; checkout handles per-customer currency conversion automatically. RECIPES (each line shows the required fields per discountType): • 10% off all orders: { discountType: "PERCENTAGE", code: "SAVE10", percentage: 10 } • $10 off + free shipping: { discountType: "FIXED_AMOUNT", code: "TAKE10", amount: 10, freeShipping: true } • Free shipping: { discountType: "FREE_SHIPPING", code: "SHIPFREE" } • Free product: { discountType: "FREE_PRODUCTS", code: "FREEGIFT", freeVariantId: "<variant-uuid>" } • Bulk codes: replace code with codes: ["VIP1","VIP2"]. Auto-apply: replace code with autoApplyTitle: "Summer Sale". COMMON OPTIONS (all types): • productIds: restrict to specific offer IDs. OMIT for entire-order (default). • freeShipping: bundle free shipping (PERCENTAGE, FIXED_AMOUNT, FREE_PRODUCTS) • minimumOrderAmount: USD dollars (e.g. 50 = $50) • allowedCountries: ISO 3166-1 alpha-2 codes (e.g. ["US","CA"]). Omit = all. • maxUses (1-1000, omit = unlimited), onePerCustomer (default false) • shippingOption (PERCENTAGE only): EXCLUDED | FREE | FREE_LOWEST_ONLY • lowestShippingOnly (FREE_SHIPPING only); freeProductQuantity (FREE_PRODUCTS only, default 1)
ecommerce_deactivate-promotion
ChatGPTDeactivate a promotion (set status to ENDED). Customers can no longer use this code. To reactivate later, use activate-promotion. To permanently remove, use delete-promotion.
ecommerce_deactivate-promotion
ChatGPTDeactivate a promotion (set status to ENDED). Customers can no longer use this code. To reactivate later, use activate-promotion. To permanently remove, use delete-promotion.
ecommerce_duplicate-offer
ChatGPTCreate a copy of an existing offer (product). The duplicated offer will have a new ID and a modified slug (with a suffix). The duplicate starts in HIDDEN state so it won't be visible on the storefront until published.
ecommerce_duplicate-offer
ChatGPTCreate a copy of an existing offer (product). The duplicated offer will have a new ID and a modified slug (with a suffix). The duplicate starts in HIDDEN state so it won't be visible on the storefront until published.
ecommerce_edit-design
ChatGPTEdits an existing customization's design state and returns the updated layout. BEFORE calling: use inspect-design to understand the current layout (imageIds, indices, region dimensions) and to read availableRegions — the legal values for target.regionId. Passing a regionId not in availableRegions returns DESIGN_PIPELINE_INVALID_REGIONS with the valid set; surface that to the user and stop — do not retry with another guessed regionId. AFTER calling: use rerender-design-previews with customizationId to regenerate preview images. Operations: - scale-absolute: set size as fraction of region (regionFraction: 0.0-1.0) - scale-relative: multiply current size (factor: e.g. 1.5 = 150%) - move-absolute: snap to named position (anchor: top-left/top-center/top-right/center-left/center/center-right/bottom-left/bottom-center/bottom-right) - move-relative: offset by fraction of region (dx: -1.0 to 1.0, dy: -1.0 to 1.0) - rotate: set rotation (degrees) - replace-image: swap image URL (href, naturalWidth, naturalHeight) - remove: delete image from region - add-image: add new image (href, width, height, optional regionFraction, anchor) - reorder: change z-order (position: numeric z-index) Target filtering: sizes (e.g. ["S","M"]), regionId (e.g. "front"), imageId (dataId from inspect), imageIndex (0-based). Omit target fields to apply to all. Returns updated inspect summary with all image positions.
ecommerce_edit-design
ChatGPTEdits an existing customization's design state and returns the updated layout. BEFORE calling: use inspect-design to understand the current layout (imageIds, indices, region dimensions) and to read availableRegions — the legal values for target.regionId. Passing a regionId not in availableRegions returns DESIGN_PIPELINE_INVALID_REGIONS with the valid set; surface that to the user and stop — do not retry with another guessed regionId. AFTER calling: use rerender-design-previews with customizationId to regenerate preview images. Operations: - scale-absolute: set size as fraction of region (regionFraction: 0.0-1.0) - scale-relative: multiply current size (factor: e.g. 1.5 = 150%) - move-absolute: snap to named position (anchor: top-left/top-center/top-right/center-left/center/center-right/bottom-left/bottom-center/bottom-right) - move-relative: offset by fraction of region (dx: -1.0 to 1.0, dy: -1.0 to 1.0) - rotate: set rotation (degrees) - replace-image: swap image URL (href, naturalWidth, naturalHeight) - remove: delete image from region - add-image: add new image (href, width, height, optional regionFraction, anchor) - reorder: change z-order (position: numeric z-index) Target filtering: sizes (e.g. ["S","M"]), regionId (e.g. "front"), imageId (dataId from inspect), imageIndex (0-based). Omit target fields to apply to all. Returns updated inspect summary with all image positions.
ecommerce_edit-self-fulfilled-tracking
ChatGPTEdits tracking information on existing self-fulfilled (creator-fulfilled) order fulfillments. Supports batch updates (up to 10). WHEN TO USE: A creator has shipped one or more existing self-fulfilled orders and you need to update the carrier and tracking number on the existing fulfillment. This tool cannot create new fulfillments — it only edits existing ones. INPUT FORMAT: Each entry is a pipe-delimited string with exactly 3 parts: fulfillmentId|trackingCompany|trackingNumber All 3 parts are required: - fulfillmentId: starts with "ful_" prefix (get it from "get-fulfillment-details") - trackingCompany: carrier name — one of: USPS, UPS, FedEx, DHL, Canada Post, Royal Mail, or other carrier - trackingNumber: the tracking number provided by the carrier EXAMPLES: - ["ful_abc123|USPS|9400111899223100001234"] - ["ful_abc123|USPS|9400111899223100001234", "ful_def456|FedEx|794644790138"] WHAT HAPPENS: The fulfillment transitions to PACKAGED status. A shipment tracker with a customer-visible tracking page URL is created in the background (not in this response). RETURNS: List of updated fulfillments with id, orderId, status, items, and shippingLabels. RELATED: Use "get-fulfillment-details" first to look up fulfillment IDs for an order.
ecommerce_edit-self-fulfilled-tracking
ChatGPTEdits tracking information on existing self-fulfilled (creator-fulfilled) order fulfillments. Supports batch updates (up to 10). WHEN TO USE: A creator has shipped one or more existing self-fulfilled orders and you need to update the carrier and tracking number on the existing fulfillment. This tool cannot create new fulfillments — it only edits existing ones. INPUT FORMAT: Each entry is a pipe-delimited string with exactly 3 parts: fulfillmentId|trackingCompany|trackingNumber All 3 parts are required: - fulfillmentId: starts with "ful_" prefix (get it from "get-fulfillment-details") - trackingCompany: carrier name — one of: USPS, UPS, FedEx, DHL, Canada Post, Royal Mail, or other carrier - trackingNumber: the tracking number provided by the carrier EXAMPLES: - ["ful_abc123|USPS|9400111899223100001234"] - ["ful_abc123|USPS|9400111899223100001234", "ful_def456|FedEx|794644790138"] WHAT HAPPENS: The fulfillment transitions to PACKAGED status. A shipment tracker with a customer-visible tracking page URL is created in the background (not in this response). RETURNS: List of updated fulfillments with id, orderId, status, items, and shippingLabels. RELATED: Use "get-fulfillment-details" first to look up fulfillment IDs for an order.
ecommerce_generate-product-design-previews
ChatGPTCreates design preview pipelines for multiple products and generates mockup images. Use this when the user wants to review mockups BEFORE offers are created — then call create-offers-from-designs on approved customizationIds. If the user has already pre-approved (e.g. "create offers for all of these"), prefer create-offers-from-products instead — it goes straight to offer creation in one call and avoids re-rendering the previews. Products are processed concurrently — no polling needed, results returned directly. Each product is processed independently — failures for one product do not affect others. regionUrls MUST be URLs from the shop's media library (use get-media-library-images, or upload via request-media-upload-link → PUT file → save-media-library-image). BEFORE calling this tool, use get-catalog-product-details to check: 1. supportsBackendRendering must be true for the product 2. Only use regions from printAreas where supportsBackendRendering=true 3. If a print area has placements, pass the desired placementId for that region IMPORTANT: Each product has its own design settings (regions, placements) because different products have different print areas (e.g., 'front_large' vs 'front'). Use get-catalog-product-details for each product to determine the correct region names and placements. Each result contains: - productId: the input product ID - pipelineId, status, type, customizationId, images[], priceSuggestions?, error? — present on success - bulkError?: string — present on failure WORKFLOW: Show images to the user — do NOT quote priceSuggestions at this stage; pricing is applied at offer creation, not on previews. If approved, call create-offers-from-designs with customizationIds. To re-render an existing customization after edit-design, use rerender-design-previews instead.
ecommerce_generate-product-design-previews
ChatGPTCreates design preview pipelines for multiple products and generates mockup images. Use this when the user wants to review mockups BEFORE offers are created — then call create-offers-from-designs on approved customizationIds. If the user has already pre-approved (e.g. "create offers for all of these"), prefer create-offers-from-products instead — it goes straight to offer creation in one call and avoids re-rendering the previews. Products are processed concurrently — no polling needed, results returned directly. Each product is processed independently — failures for one product do not affect others. regionUrls MUST be URLs from the shop's media library (use get-media-library-images, or upload via request-media-upload-link → PUT file → save-media-library-image). BEFORE calling this tool, use get-catalog-product-details to check: 1. supportsBackendRendering must be true for the product 2. Only use regions from printAreas where supportsBackendRendering=true 3. If a print area has placements, pass the desired placementId for that region IMPORTANT: Each product has its own design settings (regions, placements) because different products have different print areas (e.g., 'front_large' vs 'front'). Use get-catalog-product-details for each product to determine the correct region names and placements. Each result contains: - productId: the input product ID - pipelineId, status, type, customizationId, images[], priceSuggestions?, error? — present on success - bulkError?: string — present on failure WORKFLOW: Show images to the user — do NOT quote priceSuggestions at this stage; pricing is applied at offer creation, not on previews. If approved, call create-offers-from-designs with customizationIds. To re-render an existing customization after edit-design, use rerender-design-previews instead.
ecommerce_get-affiliate-earnings-report
ChatGPTGet the Affiliate Earnings analytics report for the shop within a date range: confirmed affiliate referral bonus earnings. This report shows affiliate earnings over time with the following columns per row: - date: The time period - earnings: Total confirmed affiliate referral bonus earnings for this period (USD) - payout_count: Number of individual affiliate payout events in this period IMPORTANT - Aggregation precision selection: Each row represents one time unit. Choose the finest granularity that produces at most 31 rows: - HOUR: use only for ranges up to 31 hours (up to ~1 day) - DAY: use only for ranges up to 31 days (up to ~1 month) - WEEK: use only for ranges up to 31 weeks (up to ~7 months) - MONTH: use only for ranges up to 31 months (up to ~2.5 years) - QUARTER: use only for ranges up to 31 quarters (up to ~7 years) - YEAR: use for ranges longer than 31 quarters For example: "last 2 years" → MONTH (24 rows), "last week" → DAY (7 rows), "last 6 months" → WEEK (~26 rows), "today" → HOUR (24 rows), "last 5 years" → QUARTER (20 rows). Examples: - Monthly affiliate earnings for 2024: from="2024-01-01T00:00:00Z", to="2024-12-31T23:59:59Z", aggregationPrecision="MONTH" - Weekly affiliate earnings: from="2024-10-01T00:00:00Z", to="2024-12-31T23:59:59Z", aggregationPrecision="WEEK"
ecommerce_get-affiliate-earnings-report
ChatGPTGet the Affiliate Earnings analytics report for the shop within a date range: confirmed affiliate referral bonus earnings. This report shows affiliate earnings over time with the following columns per row: - date: The time period - earnings: Total confirmed affiliate referral bonus earnings for this period (USD) - payout_count: Number of individual affiliate payout events in this period IMPORTANT - Aggregation precision selection: Each row represents one time unit. Choose the finest granularity that produces at most 31 rows: - HOUR: use only for ranges up to 31 hours (up to ~1 day) - DAY: use only for ranges up to 31 days (up to ~1 month) - WEEK: use only for ranges up to 31 weeks (up to ~7 months) - MONTH: use only for ranges up to 31 months (up to ~2.5 years) - QUARTER: use only for ranges up to 31 quarters (up to ~7 years) - YEAR: use for ranges longer than 31 quarters For example: "last 2 years" → MONTH (24 rows), "last week" → DAY (7 rows), "last 6 months" → WEEK (~26 rows), "today" → HOUR (24 rows), "last 5 years" → QUARTER (20 rows). Examples: - Monthly affiliate earnings for 2024: from="2024-01-01T00:00:00Z", to="2024-12-31T23:59:59Z", aggregationPrecision="MONTH" - Weekly affiliate earnings: from="2024-10-01T00:00:00Z", to="2024-12-31T23:59:59Z", aggregationPrecision="WEEK"
ecommerce_get-all-integrations
ChatGPTRetrieves all connected integrations for the shop. This is a high-level overview — for TikTok or YouTube details, use get-tiktok-configuration or get-youtube-integrations. Returns a list of integrations, each with: - app: Integration identifier (TWITCH_GIFTING, TWITCH_DISCOUNTS_FOR_SUBS, YOUTUBE_PRODUCT_SHELF, TIKTOK_SHOP, INSTAGRAM_SHOP, INSTAGRAM_CHECKOUT, TWITTER_SHOP, STREAMELEMENTS, STREAMLABS, TIKTOK_FEED, INSTAGRAM_FEED, SHIPSTATION, LAYLO, KLAVIYO, MAILCHIMP, KIT, BEEHIIV, FWDISCORD, PLEDGE, BOOKFUNNEL) - status: CONNECTED, NOT_CONNECTED, NOT_CONFIGURED, IN_PROGRESS, COMING_SOON, EXTERNAL, BROKEN - categories: list of SOCIAL_COMMERCE, ALERTS, SOCIAL_FEED, EMAIL_MARKETING, SHIPPING, OTHER - recommendations: list of sales recommendations (e.g. "SALES (priority: 1)"), empty if none - channelName: Twitch channel name (nullable, only for Twitch integrations) - missingScopes: OAuth scopes that need to be granted (nullable, only for Twitch/StreamElements) Status values: - CONNECTED: Fully set up and active - NOT_CONNECTED: Not configured at all - NOT_CONFIGURED: Partial setup (e.g., OAuth connected but configuration incomplete) - IN_PROGRESS: Setup is being processed - COMING_SOON: Feature not yet available - EXTERNAL: Configured outside Fourthwall (e.g., TikTok Feed, Instagram Feed) - BROKEN: Needs attention (e.g., missing scopes, expired auth) Use this tool to: - See all available and connected integrations for a shop - Check which sales channels are set up (TikTok Shop, YouTube Merch Shelf) - Verify email marketing tool connections (Klaviyo, Mailchimp, Kit, Beehiiv, Laylo) - Identify integrations that need attention (BROKEN status) - Get sales recommendations based on connected integrations
ecommerce_get-all-integrations
ChatGPTRetrieves all connected integrations for the shop. This is a high-level overview — for TikTok or YouTube details, use get-tiktok-configuration or get-youtube-integrations. Returns a list of integrations, each with: - app: Integration identifier (TWITCH_GIFTING, TWITCH_DISCOUNTS_FOR_SUBS, YOUTUBE_PRODUCT_SHELF, TIKTOK_SHOP, INSTAGRAM_SHOP, INSTAGRAM_CHECKOUT, TWITTER_SHOP, STREAMELEMENTS, STREAMLABS, TIKTOK_FEED, INSTAGRAM_FEED, SHIPSTATION, LAYLO, KLAVIYO, MAILCHIMP, KIT, BEEHIIV, FWDISCORD, PLEDGE, BOOKFUNNEL) - status: CONNECTED, NOT_CONNECTED, NOT_CONFIGURED, IN_PROGRESS, COMING_SOON, EXTERNAL, BROKEN - categories: list of SOCIAL_COMMERCE, ALERTS, SOCIAL_FEED, EMAIL_MARKETING, SHIPPING, OTHER - recommendations: list of sales recommendations (e.g. "SALES (priority: 1)"), empty if none - channelName: Twitch channel name (nullable, only for Twitch integrations) - missingScopes: OAuth scopes that need to be granted (nullable, only for Twitch/StreamElements) Status values: - CONNECTED: Fully set up and active - NOT_CONNECTED: Not configured at all - NOT_CONFIGURED: Partial setup (e.g., OAuth connected but configuration incomplete) - IN_PROGRESS: Setup is being processed - COMING_SOON: Feature not yet available - EXTERNAL: Configured outside Fourthwall (e.g., TikTok Feed, Instagram Feed) - BROKEN: Needs attention (e.g., missing scopes, expired auth) Use this tool to: - See all available and connected integrations for a shop - Check which sales channels are set up (TikTok Shop, YouTube Merch Shelf) - Verify email marketing tool connections (Klaviyo, Mailchimp, Kit, Beehiiv, Laylo) - Identify integrations that need attention (BROKEN status) - Get sales recommendations based on connected integrations
ecommerce_get-available-plans
ChatGPTRetrieves all subscription plans available for the shop. To check the shop's current plan and usage, use get-current-subscription instead. Returns a list of plans, each with: - Identity: id, name, custom (boolean — true if specially configured for this shop), pro (boolean) - Pricing: priceAmount (BigDecimal), priceCurrency (String, e.g. "USD"), recurringPeriod (MONTHLY/YEARLY, nullable — null means one-time) - Limits: - offersLimit (Int): maximum number of products (-1 = unlimited) - membersLimit (Int): maximum team members (-1 = unlimited) - domainsLimit (Int): maximum custom domains (-1 = unlimited) - productDesignerArtworkStorageLimitBytes (Long): artwork storage for product designer - digitalProductsStorageLimitBytes (Long): storage for digital product files - Features: - digitalProductsFeePercent (Double): transaction fee percentage for digital products - creditForSamplesAmount (BigDecimal): monthly credit for ordering product samples - creditForSamplesCurrency (String): currency of sample credit - upgradable (boolean): whether the plan can be upgraded to a higher tier - tag (nullable): PRO, PRO_UNLIMITED, DEFAULT, DEFAULT_LEGACY, DEFAULT_UNLIMITED, CUSTOM
ecommerce_get-available-plans
ChatGPTRetrieves all subscription plans available for the shop. To check the shop's current plan and usage, use get-current-subscription instead. Returns a list of plans, each with: - Identity: id, name, custom (boolean — true if specially configured for this shop), pro (boolean) - Pricing: priceAmount (BigDecimal), priceCurrency (String, e.g. "USD"), recurringPeriod (MONTHLY/YEARLY, nullable — null means one-time) - Limits: - offersLimit (Int): maximum number of products (-1 = unlimited) - membersLimit (Int): maximum team members (-1 = unlimited) - domainsLimit (Int): maximum custom domains (-1 = unlimited) - productDesignerArtworkStorageLimitBytes (Long): artwork storage for product designer - digitalProductsStorageLimitBytes (Long): storage for digital product files - Features: - digitalProductsFeePercent (Double): transaction fee percentage for digital products - creditForSamplesAmount (BigDecimal): monthly credit for ordering product samples - creditForSamplesCurrency (String): currency of sample credit - upgradable (boolean): whether the plan can be upgraded to a higher tier - tag (nullable): PRO, PRO_UNLIMITED, DEFAULT, DEFAULT_LEGACY, DEFAULT_UNLIMITED, CUSTOM
ecommerce_get-average-order-value-report
ChatGPTGet the Average Order Value analytics report for the shop within a date range: average transaction metrics over time. This report shows average order metrics over time with the following columns per row: - date: The time period - total_orders: Total number of orders - unique_customers: Number of customers who placed orders - avg_tx_value: Average amount paid by customer per order - avg_gross_revenue: Average profit value per order - avg_product_revenue: Average product sales price per order - avg_product_cost: Average declared cost of self-produced products per order - avg_shipping_revenue: Average shipping cost per order - avg_donation_revenue: Average donation value per order - avg_discount_amount: Average discount value per order - avg_taxes_amount: Average taxes amount per order - avg_fourthwall_product_costs: Average cost of manufacturing of Fourthwall products per order - avg_payment_processing_fees: Average payment processing fees per order Precision: choose finest granularity producing <=31 rows (HOUR for ~1d, DAY for ~1mo, WEEK for ~7mo, MONTH for ~2.5y, QUARTER for ~7y, YEAR beyond).
ecommerce_get-average-order-value-report
ChatGPTGet the Average Order Value analytics report for the shop within a date range: average transaction metrics over time. This report shows average order metrics over time with the following columns per row: - date: The time period - total_orders: Total number of orders - unique_customers: Number of customers who placed orders - avg_tx_value: Average amount paid by customer per order - avg_gross_revenue: Average profit value per order - avg_product_revenue: Average product sales price per order - avg_product_cost: Average declared cost of self-produced products per order - avg_shipping_revenue: Average shipping cost per order - avg_donation_revenue: Average donation value per order - avg_discount_amount: Average discount value per order - avg_taxes_amount: Average taxes amount per order - avg_fourthwall_product_costs: Average cost of manufacturing of Fourthwall products per order - avg_payment_processing_fees: Average payment processing fees per order Precision: choose finest granularity producing <=31 rows (HOUR for ~1d, DAY for ~1mo, WEEK for ~7mo, MONTH for ~2.5y, QUARTER for ~7y, YEAR beyond).
ecommerce_get-catalog-product-details
ChatGPTGet comprehensive product details for one or more catalog products by slug. Fetches all products concurrently. Returns enriched data including material, weight, fabric weight, print area pricing, size guide, colors, sizes, reviews, and more. This is the go-to tool for answering detailed product FAQ questions. IMPORTANT: Only use slugs returned by get-catalog-products or search. Do NOT construct or guess slugs from product names — they will not match real catalog entries. Returns a list of products (one per slug, in the same order), each containing: - Identity: id, brand, brandModel, name, slug, fulfillmentType - Category: categoryPath (list of category names) - Pricing: priceFrom, priceTo (BigDecimal) - Production: productionMethod, otherProductionMethods (alternative methods for same product), minimumOrdersNumber - Print areas: printAreas — list of available print areas, each containing: - type: region identifier (e.g. "front", "back", "neck_label") - name: display name (e.g. "Front", "Back", "Neck Label") - required: boolean — when true this area MUST carry artwork or the product cannot be manufactured (the manufacturer rejects the sync). Always design every required area, even when the product name highlights a different (optional) one — e.g. a "Custom Background" sticker sheet has a required "Stickers" area plus an optional "Background". - salePrice: formatted price string (e.g. "$8.50") - supportsBackendRendering: boolean — whether this specific region can be used with generate-product-design-previews (regions like neck labels or embroidery regions will be false) - placements: list of placements within the region, each an object with id and name (e.g. [{"id": "leftChest", "name": "Left chest"}, {"id": "centerChest", "name": "Center chest"}]). Empty list when no placements. Pass the desired placement id to generate-product-design-previews. - Backend rendering: supportsBackendRendering (boolean) — whether this product supports design preview generation via generate-product-design-previews. When true, check each print area's supportsBackendRendering to determine which regions can be designed. - Colors: list of available color names - Sizes: list of available sizes - Size guide: sizeGuide — formatted string like "Chest: S=34-36, M=38-40 (inches)" - Fabric: fabricWeightGsm (GSM), material (primary), distinctMaterials (all unique materials across variants, e.g. heather vs solid differ) - Weight: weightRange — formatted string like "5.00-6.20 oz" - Origin: countryOfProduction - Description: description, moreDetails, sizeAndFitNotes - Returns: guaranteeAndReturns — guarantee and returns policy text - Legal: legalWarningSubstance — legal/safety warnings (e.g. Prop 65) - Reviews: reviewSummary — formatted string like "4.63/5 (119 reviews) - Creators love the softness..." - Stock issues: colorsWithStockIssues — only colors that have problems, each with the discontinuedSizes and outOfStockSizes for that color. Colors absent from this list are fully available across every size in sizes. - Shipping: shipsFrom — regions where the product is fulfilled from (e.g. ["US", "EU", "CA"]) - Badges: badges (e.g. ["OUR_PICK", "BESTSELLER"]) - favourite: boolean
ecommerce_get-catalog-product-details
ChatGPTGet comprehensive product details for one or more catalog products by slug. Fetches all products concurrently. Returns enriched data including material, weight, fabric weight, print area pricing, size guide, colors, sizes, reviews, and more. This is the go-to tool for answering detailed product FAQ questions. IMPORTANT: Only use slugs returned by get-catalog-products or search. Do NOT construct or guess slugs from product names — they will not match real catalog entries. Returns a list of products (one per slug, in the same order), each containing: - Identity: id, brand, brandModel, name, slug, fulfillmentType - Category: categoryPath (list of category names) - Pricing: priceFrom, priceTo (BigDecimal) - Production: productionMethod, otherProductionMethods (alternative methods for same product), minimumOrdersNumber - Print areas: printAreas — list of available print areas, each containing: - type: region identifier (e.g. "front", "back", "neck_label") - name: display name (e.g. "Front", "Back", "Neck Label") - required: boolean — when true this area MUST carry artwork or the product cannot be manufactured (the manufacturer rejects the sync). Always design every required area, even when the product name highlights a different (optional) one — e.g. a "Custom Background" sticker sheet has a required "Stickers" area plus an optional "Background". - salePrice: formatted price string (e.g. "$8.50") - supportsBackendRendering: boolean — whether this specific region can be used with generate-product-design-previews (regions like neck labels or embroidery regions will be false) - placements: list of placements within the region, each an object with id and name (e.g. [{"id": "leftChest", "name": "Left chest"}, {"id": "centerChest", "name": "Center chest"}]). Empty list when no placements. Pass the desired placement id to generate-product-design-previews. - Backend rendering: supportsBackendRendering (boolean) — whether this product supports design preview generation via generate-product-design-previews. When true, check each print area's supportsBackendRendering to determine which regions can be designed. - Colors: list of available color names - Sizes: list of available sizes - Size guide: sizeGuide — formatted string like "Chest: S=34-36, M=38-40 (inches)" - Fabric: fabricWeightGsm (GSM), material (primary), distinctMaterials (all unique materials across variants, e.g. heather vs solid differ) - Weight: weightRange — formatted string like "5.00-6.20 oz" - Origin: countryOfProduction - Description: description, moreDetails, sizeAndFitNotes - Returns: guaranteeAndReturns — guarantee and returns policy text - Legal: legalWarningSubstance — legal/safety warnings (e.g. Prop 65) - Reviews: reviewSummary — formatted string like "4.63/5 (119 reviews) - Creators love the softness..." - Stock issues: colorsWithStockIssues — only colors that have problems, each with the discontinuedSizes and outOfStockSizes for that color. Colors absent from this list are fully available across every size in sizes. - Shipping: shipsFrom — regions where the product is fulfilled from (e.g. ["US", "EU", "CA"]) - Badges: badges (e.g. ["OUR_PICK", "BESTSELLER"]) - favourite: boolean
ecommerce_get-catalog-products
ChatGPTBrowse source products from the product catalog with filtering and pagination. These are products available for customization — NOT the shop's own offers. To view products already added to the shop, use get-offers instead. Returns: - Pagination: pageNumber, pageSize, totalElements, totalPages - Per product: - Identity: id, brand, brandModel, name, slug - Category: categoryPath (list of category names) - Pricing: priceFrom (BigDecimal), priceTo (BigDecimal) - Production: productionMethod, minimumOrdersNumber (nullable Int) - Reviews: reviewsSummary with count and rating (nullable) - Metadata: customizationType (REQUESTABLE/INSTANT/DESIGNER_V3_READY/PRINTFUL_DESIGNER_READY), favourite (boolean), badges (OUR_PICK/BESTSELLER/NEW/SIGNATURE) - Print details (only when includePrintDetails=true): printDetails — { supportsBackendRendering (boolean), printAreas: [{ type, name, required, salePrice, supportsBackendRendering, placements: [{ id, name }] }] }. required=true means the area MUST carry artwork or the product cannot be manufactured. IMPORTANT: To find a specific catalog product by name, brand, or keyword, you MUST use the search tool. NEVER paginate through results to find a specific entity.
ecommerce_get-catalog-products
ChatGPTBrowse source products from the product catalog with filtering and pagination. These are products available for customization — NOT the shop's own offers. To view products already added to the shop, use get-offers instead. Returns: - Pagination: pageNumber, pageSize, totalElements, totalPages - Per product: - Identity: id, brand, brandModel, name, slug - Category: categoryPath (list of category names) - Pricing: priceFrom (BigDecimal), priceTo (BigDecimal) - Production: productionMethod, minimumOrdersNumber (nullable Int) - Reviews: reviewsSummary with count and rating (nullable) - Metadata: customizationType (REQUESTABLE/INSTANT/DESIGNER_V3_READY/PRINTFUL_DESIGNER_READY), favourite (boolean), badges (OUR_PICK/BESTSELLER/NEW/SIGNATURE) - Print details (only when includePrintDetails=true): printDetails — { supportsBackendRendering (boolean), printAreas: [{ type, name, required, salePrice, supportsBackendRendering, placements: [{ id, name }] }] }. required=true means the area MUST carry artwork or the product cannot be manufactured. IMPORTANT: To find a specific catalog product by name, brand, or keyword, you MUST use the search tool. NEVER paginate through results to find a specific entity.
ecommerce_get-catalog-products-by-slugs
ChatGPTGet details of one or more catalog products by their slugs. Fetches all products concurrently. This returns catalog source products — NOT shop offers. Use get-offers-by-ids for shop product details. IMPORTANT: Only use slugs returned by get-catalog-products or search. Do NOT construct or guess slugs from product names — they will not match real catalog entries. Returns a list of products, each containing: - Identity: id, brand, brandModel, name, slug - Category: categoryPath (list of category names from breadcrumbs) - Pricing: priceFrom (BigDecimal), priceTo (BigDecimal) - Production: productionMethod (SUBLIMATION/DTG/EMBROIDERY/SCREEN_PRINTING/PRINTED/STICKER/DTFX/UV/ALL_OVER_PRINT/KNITTING/DRINKWARE/GARMENT_PRINTED/ACRYLIC_CUTOUT/DIE_CUT_MAGNET/HOLO_STICKER/OTHER), minimumOrdersNumber (nullable Int) - Metadata: customizationType (REQUESTABLE/INSTANT/DESIGNER_V3_READY/PRINTFUL_DESIGNER_READY), favourite (boolean), badges (OUR_PICK/BESTSELLER/NEW/SIGNATURE) - Note: reviewsSummary is not available for single product lookups
ecommerce_get-catalog-products-by-slugs
ChatGPTGet details of one or more catalog products by their slugs. Fetches all products concurrently. This returns catalog source products — NOT shop offers. Use get-offers-by-ids for shop product details. IMPORTANT: Only use slugs returned by get-catalog-products or search. Do NOT construct or guess slugs from product names — they will not match real catalog entries. Returns a list of products, each containing: - Identity: id, brand, brandModel, name, slug - Category: categoryPath (list of category names from breadcrumbs) - Pricing: priceFrom (BigDecimal), priceTo (BigDecimal) - Production: productionMethod (SUBLIMATION/DTG/EMBROIDERY/SCREEN_PRINTING/PRINTED/STICKER/DTFX/UV/ALL_OVER_PRINT/KNITTING/DRINKWARE/GARMENT_PRINTED/ACRYLIC_CUTOUT/DIE_CUT_MAGNET/HOLO_STICKER/OTHER), minimumOrdersNumber (nullable Int) - Metadata: customizationType (REQUESTABLE/INSTANT/DESIGNER_V3_READY/PRINTFUL_DESIGNER_READY), favourite (boolean), badges (OUR_PICK/BESTSELLER/NEW/SIGNATURE) - Note: reviewsSummary is not available for single product lookups
ecommerce_get-collections
ChatGPTRetrieves all non-archived collections for the shop. NOTE: The system-level "All Products" collection (used internally to display all products on the Products page) is excluded from results. Only user-created collections are returned. Returns a list of collections, each with: - Identity: id (CollectionId), shopId (ShopId), name, slug, description - Visibility: available (boolean), state (PUBLIC/HIDDEN/ARCHIVED) - Time-based availability: availableFrom (nullable ISO 8601), availableTo (nullable ISO 8601) - Products: offerIds (list of OfferIds — use get-offers-by-ids to look up each product) - Sorting: sortingStrategy (MANUAL/BEST_SELLING/NEWEST/OLDEST/NAME_ASC/NAME_DESC) IMPORTANT: To find a specific collection by name or keyword, you MUST use the search tool. NEVER iterate through results to find a specific entity.
ecommerce_get-collections
ChatGPTRetrieves all non-archived collections for the shop. NOTE: The system-level "All Products" collection (used internally to display all products on the Products page) is excluded from results. Only user-created collections are returned. Returns a list of collections, each with: - Identity: id (CollectionId), shopId (ShopId), name, slug, description - Visibility: available (boolean), state (PUBLIC/HIDDEN/ARCHIVED) - Time-based availability: availableFrom (nullable ISO 8601), availableTo (nullable ISO 8601) - Products: offerIds (list of OfferIds — use get-offers-by-ids to look up each product) - Sorting: sortingStrategy (MANUAL/BEST_SELLING/NEWEST/OLDEST/NAME_ASC/NAME_DESC) IMPORTANT: To find a specific collection by name or keyword, you MUST use the search tool. NEVER iterate through results to find a specific entity.
ecommerce_get-collections-by-ids
ChatGPTGet details of one or more collections by their IDs. Fetches all collections concurrently. Use get-collections to discover collection IDs if you don't have any. Returns a list of collections, each containing: - Identity: id (CollectionId), shopId (ShopId), name, slug, description - Visibility: available (boolean), state (PUBLIC/HIDDEN/ARCHIVED) - Time-based availability: availableFrom (nullable ISO 8601), availableTo (nullable ISO 8601) - Products: offerIds (list of OfferIds — use get-offers-by-ids to look up each product) - Sorting: sortingStrategy (MANUAL/BEST_SELLING/NEWEST/OLDEST/NAME_ASC/NAME_DESC)
ecommerce_get-collections-by-ids
ChatGPTGet details of one or more collections by their IDs. Fetches all collections concurrently. Use get-collections to discover collection IDs if you don't have any. Returns a list of collections, each containing: - Identity: id (CollectionId), shopId (ShopId), name, slug, description - Visibility: available (boolean), state (PUBLIC/HIDDEN/ARCHIVED) - Time-based availability: availableFrom (nullable ISO 8601), availableTo (nullable ISO 8601) - Products: offerIds (list of OfferIds — use get-offers-by-ids to look up each product) - Sorting: sortingStrategy (MANUAL/BEST_SELLING/NEWEST/OLDEST/NAME_ASC/NAME_DESC)
ecommerce_get-contributions-per-type-report
ChatGPTGet the Contributions Per Type analytics report for the shop within a date range: transaction count breakdown by contribution type. This report shows contribution counts over time with the following columns per row: - date: The time period - shop_orders: Number of shop orders - sample_orders: Number of sample orders - orders_twitch_gifts_purchases: Number of Twitch gifts purchases - orders_twitch_gifts_redeems: Number of Twitch gifts redeems - donations: Number of donations - giveaway_links: Number of giveaway links - memberships_subscriptions: Subscriptions = New subscriptions + Renewals + Upgrades - memberships_message_tips: Number of message tips - memberships_locked_messages: Number of locked messages - memberships_paid_posts: Number of paid posts - memberships_subscription_gifts: Number of subscription gifts - memberships_twitch_gifts: Number of Twitch gifts - total: Total contributions across all types Precision: choose finest granularity producing <=31 rows (HOUR for ~1d, DAY for ~1mo, WEEK for ~7mo, MONTH for ~2.5y, QUARTER for ~7y, YEAR beyond). Filter groups (pass comma-separated keys to include only specific metrics): - shop_metrics: shop_orders, sample_orders, orders_twitch_gifts_purchases, orders_twitch_gifts_redeems, donations, giveaway_links - memberships_metrics: memberships_subscriptions, memberships_message_tips, memberships_locked_messages, memberships_paid_posts, memberships_subscription_gifts, memberships_twitch_gifts
ecommerce_get-contributions-per-type-report
ChatGPTGet the Contributions Per Type analytics report for the shop within a date range: transaction count breakdown by contribution type. This report shows contribution counts over time with the following columns per row: - date: The time period - shop_orders: Number of shop orders - sample_orders: Number of sample orders - orders_twitch_gifts_purchases: Number of Twitch gifts purchases - orders_twitch_gifts_redeems: Number of Twitch gifts redeems - donations: Number of donations - giveaway_links: Number of giveaway links - memberships_subscriptions: Subscriptions = New subscriptions + Renewals + Upgrades - memberships_message_tips: Number of message tips - memberships_locked_messages: Number of locked messages - memberships_paid_posts: Number of paid posts - memberships_subscription_gifts: Number of subscription gifts - memberships_twitch_gifts: Number of Twitch gifts - total: Total contributions across all types Precision: choose finest granularity producing <=31 rows (HOUR for ~1d, DAY for ~1mo, WEEK for ~7mo, MONTH for ~2.5y, QUARTER for ~7y, YEAR beyond). Filter groups (pass comma-separated keys to include only specific metrics): - shop_metrics: shop_orders, sample_orders, orders_twitch_gifts_purchases, orders_twitch_gifts_redeems, donations, giveaway_links - memberships_metrics: memberships_subscriptions, memberships_message_tips, memberships_locked_messages, memberships_paid_posts, memberships_subscription_gifts, memberships_twitch_gifts
ecommerce_get-conversion-rates-report
ChatGPTGet the Conversion Rates analytics report for the shop within a date range: checkout funnel conversion metrics. This report shows conversion funnel data over time with the following columns per row: - date: The time period - total_sessions: Total number of user sessions adjusted to be at least as large as the number of carts created (baseline for conversion percentages, always 100%) - cart_created_count: Number of shopping carts created by users, including carts from gift and giveaway checkouts - cart_created_percentage: Percentage of sessions that resulted in cart creation - checkout_created_count: Number of initiated checkouts - checkout_created_percentage: Percentage of sessions that resulted in checkout initiation - checkout_paid_count: Number of completed payments - checkout_paid_percentage: Percentage of sessions that resulted in completed payment Precision: HOUR for ranges <=1 day, DAY for longer.
ecommerce_get-conversion-rates-report
ChatGPTGet the Conversion Rates analytics report for the shop within a date range: checkout funnel conversion metrics. This report shows conversion funnel data over time with the following columns per row: - date: The time period - total_sessions: Total number of user sessions adjusted to be at least as large as the number of carts created (baseline for conversion percentages, always 100%) - cart_created_count: Number of shopping carts created by users, including carts from gift and giveaway checkouts - cart_created_percentage: Percentage of sessions that resulted in cart creation - checkout_created_count: Number of initiated checkouts - checkout_created_percentage: Percentage of sessions that resulted in checkout initiation - checkout_paid_count: Number of completed payments - checkout_paid_percentage: Percentage of sessions that resulted in completed payment Precision: HOUR for ranges <=1 day, DAY for longer.
ecommerce_get-current-shop
ChatGPTRetrieves the current shop's profile, configuration, and contact details. For user-level access permissions, use get-shop-permissions instead. Returns: - Identity: id (String, e.g. "sh_6c8684ef-..."), name, creatorName, description, logoUrl (nullable URL string) - Domains: primaryDomain (e.g. "myshop.fourthwall.com"), internalDomain (e.g. "myshop.fourthwall.com"), customDomains (list), baseUrl (full URL) - Status: status (LIVE/COMING_SOON/PASSWORD_PROTECTED/INACTIVE) - Contact info: - shopEmail, contactEmail, customerSupportEmail (nullable), transactionalEmail - location: name (nullable), address1 (nullable), address2 (nullable), city (nullable), state (nullable), zip (nullable), country (ISO code) - Settings: - currency (primary, e.g. USD), enabledCurrencies (list, e.g. [USD, EUR, GBP, CAD, AUD]) - membershipsEnabled (Boolean), membershipsUpsellingMinOrderValue (nullable BigDecimal), membershipsUpsellingMinOrderCurrency (nullable, e.g. "USD") - allowedPaymentProviders: list of Stripe, StripeDeferred, PayPal, Klarna, Afterpay, CKO - thankYouCardEnabled (Boolean), externalStoreUrl (nullable URL string) - socialLinks: map of platform key to URL/handle (only non-null entries). Possible keys: youtube, instagram, facebook, twitter, x, tiktok, snapchat, discord, twitch, spotify, reddit, kick, kofi, patreon, threads, pinterest, soundcloud, bluesky, linkedin - verificationRestrictions: list of feature names that require verification (empty list if none) - Timestamps: timezone (e.g. "America/New_York"), createdAt (ISO 8601), lastLiveAt (nullable ISO 8601)
ecommerce_get-current-shop
ChatGPTRetrieves the current shop's profile, configuration, and contact details. For user-level access permissions, use get-shop-permissions instead. Returns: - Identity: id (String, e.g. "sh_6c8684ef-..."), name, creatorName, description, logoUrl (nullable URL string) - Domains: primaryDomain (e.g. "myshop.fourthwall.com"), internalDomain (e.g. "myshop.fourthwall.com"), customDomains (list), baseUrl (full URL) - Status: status (LIVE/COMING_SOON/PASSWORD_PROTECTED/INACTIVE) - Contact info: - shopEmail, contactEmail, customerSupportEmail (nullable), transactionalEmail - location: name (nullable), address1 (nullable), address2 (nullable), city (nullable), state (nullable), zip (nullable), country (ISO code) - Settings: - currency (primary, e.g. USD), enabledCurrencies (list, e.g. [USD, EUR, GBP, CAD, AUD]) - membershipsEnabled (Boolean), membershipsUpsellingMinOrderValue (nullable BigDecimal), membershipsUpsellingMinOrderCurrency (nullable, e.g. "USD") - allowedPaymentProviders: list of Stripe, StripeDeferred, PayPal, Klarna, Afterpay, CKO - thankYouCardEnabled (Boolean), externalStoreUrl (nullable URL string) - socialLinks: map of platform key to URL/handle (only non-null entries). Possible keys: youtube, instagram, facebook, twitter, x, tiktok, snapchat, discord, twitch, spotify, reddit, kick, kofi, patreon, threads, pinterest, soundcloud, bluesky, linkedin - verificationRestrictions: list of feature names that require verification (empty list if none) - Timestamps: timezone (e.g. "America/New_York"), createdAt (ISO 8601), lastLiveAt (nullable ISO 8601)
ecommerce_get-current-subscription
ChatGPTRetrieves the current subscription for the shop with usage information. For full plan details (pricing, all limits, features), use get-available-plans. Returns: - Subscription: id, status, activeFrom (nullable ISO 8601), activeTo (nullable ISO 8601), scheduledCancelledAtTheEndOfPeriod (boolean) - Plan summary: plan.id, plan.name, plan.pro (boolean), plan.custom (boolean) - Usage vs limits (each with limit and usage as Long): - offers: product/offer count - members: team member count - domains: custom domain count - digitalProductsStorageBytes: digital file storage in bytes - pendingSubscription (nullable): subscriptionId, planId, planName — present when a plan change is scheduled status values: - PENDING: awaiting payment/activation - ACTIVE: subscription is active and in good standing - PAST_DUE: payment is overdue - CANCELED: subscription has been cancelled Understanding limits: - When usage >= limit, the resource is at capacity - limit = -1 means unlimited for that resource - Storage is in bytes (divide by 1073741824 for GB)
ecommerce_get-current-subscription
ChatGPTRetrieves the current subscription for the shop with usage information. For full plan details (pricing, all limits, features), use get-available-plans. Returns: - Subscription: id, status, activeFrom (nullable ISO 8601), activeTo (nullable ISO 8601), scheduledCancelledAtTheEndOfPeriod (boolean) - Plan summary: plan.id, plan.name, plan.pro (boolean), plan.custom (boolean) - Usage vs limits (each with limit and usage as Long): - offers: product/offer count - members: team member count - domains: custom domain count - digitalProductsStorageBytes: digital file storage in bytes - pendingSubscription (nullable): subscriptionId, planId, planName — present when a plan change is scheduled status values: - PENDING: awaiting payment/activation - ACTIVE: subscription is active and in good standing - PAST_DUE: payment is overdue - CANCELED: subscription has been cancelled Understanding limits: - When usage >= limit, the resource is at capacity - limit = -1 means unlimited for that resource - Storage is in bytes (divide by 1073741824 for GB)
ecommerce_get-customers-over-time-report
ChatGPTGet the Customers Over Time analytics report for the shop within a date range: customer acquisition and retention metrics. This report shows customer counts over time with the following columns per row: - date: The time period - customers_first_time: Number of customers making their first purchase in this period - customers_returning: Number of customers who have made purchases before this period - customers_total: Total unique customers (first-time + returning) Precision: choose finest granularity producing <=31 rows (HOUR for ~1d, DAY for ~1mo, WEEK for ~7mo, MONTH for ~2.5y, QUARTER for ~7y, YEAR beyond).
ecommerce_get-customers-over-time-report
ChatGPTGet the Customers Over Time analytics report for the shop within a date range: customer acquisition and retention metrics. This report shows customer counts over time with the following columns per row: - date: The time period - customers_first_time: Number of customers making their first purchase in this period - customers_returning: Number of customers who have made purchases before this period - customers_total: Total unique customers (first-time + returning) Precision: choose finest granularity producing <=31 rows (HOUR for ~1d, DAY for ~1mo, WEEK for ~7mo, MONTH for ~2.5y, QUARTER for ~7y, YEAR beyond).
ecommerce_get-customization-pricing
ChatGPTGets pricing preview for a customization sketch without creating an offer. Returns manufacturing costs per size with cost component breakdown (blank, print regions, etc.). Use this to show the user what the offer would cost before creating it.
ecommerce_get-customization-pricing
ChatGPTGets pricing preview for a customization sketch without creating an offer. Returns manufacturing costs per size with cost component breakdown (blank, print regions, etc.). Use this to show the user what the offer would cost before creating it.
ecommerce_get-design-pipeline-status
ChatGPTRetrieves the current status of a design pipeline. Returns: - pipelineId, status (PENDING, DONE, or ERROR), type - customizationId?: set when a customization exists - offerId?: present when type=OFFER and status=DONE - images[]: { url, width, height, style, color, size?, region? } - priceSuggestions?: { currency, singlePrice, perSize[]: { size, price, cost } } - error?: { step, message } Use this tool to: - Check if a design pipeline has completed - Get generated preview images or the offer ID after completion - Diagnose failures via error.step and error.message
ecommerce_get-design-pipeline-status
ChatGPTRetrieves the current status of a design pipeline. Returns: - pipelineId, status (PENDING, DONE, or ERROR), type - customizationId?: set when a customization exists - offerId?: present when type=OFFER and status=DONE - images[]: { url, width, height, style, color, size?, region? } - priceSuggestions?: { currency, singlePrice, perSize[]: { size, price, cost } } - error?: { step, message } Use this tool to: - Check if a design pipeline has completed - Get generated preview images or the offer ID after completion - Diagnose failures via error.step and error.message
ecommerce_get-dns-entries
ChatGPTRetrieves the DNS configuration and records for the shop's custom domain. This is a read-only check — it does NOT re-validate records against live DNS. To trigger a fresh validation, use validate-dns-entries instead. Returns null if no custom domain is configured, otherwise returns: - Domain: domainId, domain (e.g. "myshop.com") - Status: status (CONNECTED, NOT_CONNECTED, PARTIALLY_CONNECTED, SYNCING_YOUR_DOMAIN, REMOVAL_IN_PROGRESS) - Flags: areAllEntriesComplete (boolean), isSslSynced (boolean), retryAllowed (boolean) - Provider: dnsProvider (nullable String, e.g. "Cloudflare", "GoDaddy"), dnsProviderMode (MANUAL/AUTOMATIC, nullable) - Nameservers: nameservers (list of hostname strings) - Per record in records: - recordType (CNAME, TXT, MX, A) - host (nullable, e.g. "www", "@") - value (nullable, the expected DNS value) - status (VALID, INVALID, UNKNOWN) - validationError (nullable String — e.g. "RECORD_NOT_FOUND", "INCORRECT_TYPE_OR_VALUE (found: ...)", "DUPLICATED_BASE_DOMAIN (...)") - alias (identifies the record purpose, e.g. SHOP_IP_ADDRESS, SHOP_WWW_REDIRECT, SENDGRID_MAIL_CNAME, DMARC, SPF_RULE) - priority (nullable Int, for MX records) status values: - CONNECTED: All DNS records verified and SSL active - PARTIALLY_CONNECTED: Website records verified but other records (email, etc.) still pending - NOT_CONNECTED: Website DNS records not yet verified - SYNCING_YOUR_DOMAIN: Website records verified, waiting for SSL certificate provisioning - REMOVAL_IN_PROGRESS: Domain is being disconnected Use this tool to: - Check if a custom domain is set up for the shop - See the current domain connection status and SSL state - List DNS records that need to be configured at the domain registrar - Identify which specific records are failing (check record status + validationError) - Identify the DNS provider being used
ecommerce_get-dns-entries
ChatGPTRetrieves the DNS configuration and records for the shop's custom domain. This is a read-only check — it does NOT re-validate records against live DNS. To trigger a fresh validation, use validate-dns-entries instead. Returns null if no custom domain is configured, otherwise returns: - Domain: domainId, domain (e.g. "myshop.com") - Status: status (CONNECTED, NOT_CONNECTED, PARTIALLY_CONNECTED, SYNCING_YOUR_DOMAIN, REMOVAL_IN_PROGRESS) - Flags: areAllEntriesComplete (boolean), isSslSynced (boolean), retryAllowed (boolean) - Provider: dnsProvider (nullable String, e.g. "Cloudflare", "GoDaddy"), dnsProviderMode (MANUAL/AUTOMATIC, nullable) - Nameservers: nameservers (list of hostname strings) - Per record in records: - recordType (CNAME, TXT, MX, A) - host (nullable, e.g. "www", "@") - value (nullable, the expected DNS value) - status (VALID, INVALID, UNKNOWN) - validationError (nullable String — e.g. "RECORD_NOT_FOUND", "INCORRECT_TYPE_OR_VALUE (found: ...)", "DUPLICATED_BASE_DOMAIN (...)") - alias (identifies the record purpose, e.g. SHOP_IP_ADDRESS, SHOP_WWW_REDIRECT, SENDGRID_MAIL_CNAME, DMARC, SPF_RULE) - priority (nullable Int, for MX records) status values: - CONNECTED: All DNS records verified and SSL active - PARTIALLY_CONNECTED: Website records verified but other records (email, etc.) still pending - NOT_CONNECTED: Website DNS records not yet verified - SYNCING_YOUR_DOMAIN: Website records verified, waiting for SSL certificate provisioning - REMOVAL_IN_PROGRESS: Domain is being disconnected Use this tool to: - Check if a custom domain is set up for the shop - See the current domain connection status and SSL state - List DNS records that need to be configured at the domain registrar - Identify which specific records are failing (check record status + validationError) - Identify the DNS provider being used
ecommerce_get-draft-attributes
ChatGPTReturns the current and available colors and sizes for a draft customization. - selectedColors / selectedSizes: what the draft currently has selected. - availableColors / availableSizes: every legal value for this product blank — the only values that add-draft-colors / add-draft-sizes will accept. Call this before add-draft-colors or add-draft-sizes to learn what's legal. Color and size names are case-sensitive — pass them exactly as they appear in availableColors / availableSizes.
ecommerce_get-draft-attributes
ChatGPTReturns the current and available colors and sizes for a draft customization. - selectedColors / selectedSizes: what the draft currently has selected. - availableColors / availableSizes: every legal value for this product blank — the only values that add-draft-colors / add-draft-sizes will accept. Call this before add-draft-colors or add-draft-sizes to learn what's legal. Color and size names are case-sensitive — pass them exactly as they appear in availableColors / availableSizes.
ecommerce_get-fulfillment-details
ChatGPTRetrieves fulfillment details for one or more orders by their IDs. Fetches all orders concurrently. Returns a list of fulfillments associated with the orders, excluding cancelled fulfillments. An order may have multiple fulfillments when items are shipped from different fulfillment services (e.g., some items via a third-party provider and others self-fulfilled by the creator). Each fulfillment includes: - id: Unique fulfillment identifier (e.g., "ful_abc123") - shopId: The shop this fulfillment belongs to - orderId: The order being fulfilled - status: Current fulfillment status (OPEN, ACCEPTED, IN_PRODUCTION, PACKAGED, ON_HOLD) - isFulfilledByCreator: true when the creator ships it themselves (FBC / Gnarlywood / Bolt Stitch / Mogul Merch / etc.); false when Fourthwall or a third-party provider handles shipping. Only fulfillments with isFulfilledByCreator=true can have their tracking edited via "edit-self-fulfilled-tracking". - items[]: List of items being fulfilled, each with: - variantId: Product variant ID (UUID) - quantity: Number of units - shippingLabels[]: Shipping labels with tracking info, each with: - trackingCompany: Carrier name (e.g., "USPS", "FedEx") - trackingNumber: Tracking number (may be null if not yet assigned) - trackingService: Service level (e.g., "Priority Mail") - orderShipmentId: Shipment ID linking to order shipping details (may be null) - createdAt: When the fulfillment was created - updatedAt: When the fulfillment was last updated Fulfillment status meanings: - OPEN: Fulfillment created, awaiting processing (no label purchased yet) - ACCEPTED: Acknowledged by the fulfillment provider - IN_PRODUCTION: Items are being produced or prepared - PACKAGED: Items packaged with shipping label purchased, ready to ship or shipped - ON_HOLD: Fulfillment temporarily paused Related tools: - Use "get-order-details-by-ids" to get the full order context (customer info, amounts, address) - Use "get-unfulfilled-orders" to see how many orders still need fulfillment Use this tool to: - Check the fulfillment status for one or more orders - Get tracking information for shipped items - Understand what items are being fulfilled and their quantities
ecommerce_get-fulfillment-details
ChatGPTRetrieves fulfillment details for one or more orders by their IDs. Fetches all orders concurrently. Returns a list of fulfillments associated with the orders, excluding cancelled fulfillments. An order may have multiple fulfillments when items are shipped from different fulfillment services (e.g., some items via a third-party provider and others self-fulfilled by the creator). Each fulfillment includes: - id: Unique fulfillment identifier (e.g., "ful_abc123") - shopId: The shop this fulfillment belongs to - orderId: The order being fulfilled - status: Current fulfillment status (OPEN, ACCEPTED, IN_PRODUCTION, PACKAGED, ON_HOLD) - isFulfilledByCreator: true when the creator ships it themselves (FBC / Gnarlywood / Bolt Stitch / Mogul Merch / etc.); false when Fourthwall or a third-party provider handles shipping. Only fulfillments with isFulfilledByCreator=true can have their tracking edited via "edit-self-fulfilled-tracking". - items[]: List of items being fulfilled, each with: - variantId: Product variant ID (UUID) - quantity: Number of units - shippingLabels[]: Shipping labels with tracking info, each with: - trackingCompany: Carrier name (e.g., "USPS", "FedEx") - trackingNumber: Tracking number (may be null if not yet assigned) - trackingService: Service level (e.g., "Priority Mail") - orderShipmentId: Shipment ID linking to order shipping details (may be null) - createdAt: When the fulfillment was created - updatedAt: When the fulfillment was last updated Fulfillment status meanings: - OPEN: Fulfillment created, awaiting processing (no label purchased yet) - ACCEPTED: Acknowledged by the fulfillment provider - IN_PRODUCTION: Items are being produced or prepared - PACKAGED: Items packaged with shipping label purchased, ready to ship or shipped - ON_HOLD: Fulfillment temporarily paused Related tools: - Use "get-order-details-by-ids" to get the full order context (customer info, amounts, address) - Use "get-unfulfilled-orders" to see how many orders still need fulfillment Use this tool to: - Check the fulfillment status for one or more orders - Get tracking information for shipped items - Understand what items are being fulfilled and their quantities
ecommerce_get-gift-card
ChatGPTGet full details of a gift card by ID. Returns: code, status, balance (initial/used/remaining), currency, expiration, origin, recipient, available actions.
ecommerce_get-gift-card
ChatGPTGet full details of a gift card by ID. Returns: code, status, balance (initial/used/remaining), currency, expiration, origin, recipient, available actions.
ecommerce_get-gift-cards
ChatGPTList gift cards with pagination. Results are SINGLE cards or GROUPs (bulk-created). Statuses: UNUSED, PARTIALLY_USED, FULLY_USED, EXPIRED, DEACTIVATED, ARCHIVED. Origin: SINGLE_MANUAL, GROUP_MANUAL, ORDER (auto from purchase), GIFT (from giveaway).
ecommerce_get-gift-cards
ChatGPTList gift cards with pagination. Results are SINGLE cards or GROUPs (bulk-created). Statuses: UNUSED, PARTIALLY_USED, FULLY_USED, EXPIRED, DEACTIVATED, ARCHIVED. Origin: SINGLE_MANUAL, GROUP_MANUAL, ORDER (auto from purchase), GIFT (from giveaway).
ecommerce_get-giveaway-links
ChatGPTList giveaway links with pagination. Filter by packageId to see links from a specific batch. Statuses: AVAILABLE (unclaimed, has shareable URL), REDEEMED (claimed), CANCELLED (revoked). Each link has a uri (the shareable URL) and belongs to a packageId.
ecommerce_get-giveaway-links
ChatGPTList giveaway links with pagination. Filter by packageId to see links from a specific batch. Statuses: AVAILABLE (unclaimed, has shareable URL), REDEEMED (claimed), CANCELLED (revoked). Each link has a uri (the shareable URL) and belongs to a packageId.
ecommerce_get-membership-active-members-report
ChatGPTGet the Membership Active Members analytics report for the shop within a date range: active membership tracking over time. This report shows active member counts over time with the following columns per row: - date: The time period - active: Number of active members (latest snapshot) - newly_subscribed: Number of newly subscribed members - returning: Number of returning members - cancelled: Number of cancelled members - migrated_to: Members that migrated from another tier (visible when a single tier is selected) - migrated_out: Members that migrated out to a different tier (visible when a single tier is selected) - change: Net change in active members. Formula: Change = Newly subscribed + Returning + Migrated to - Migrated out - Cancelled Precision: choose finest granularity producing <=31 rows (HOUR for ~1d, DAY for ~1mo, WEEK for ~7mo, MONTH for ~2.5y, QUARTER for ~7y, YEAR beyond). Filter groups (pass comma-separated keys to include only specific metrics): - subscription_cycles: annual, month. All included by default. Note: Membership tiers filter is also available but resolved dynamically at runtime based on the shop's configured tiers.
ecommerce_get-membership-active-members-report
ChatGPTGet the Membership Active Members analytics report for the shop within a date range: active membership tracking over time. This report shows active member counts over time with the following columns per row: - date: The time period - active: Number of active members (latest snapshot) - newly_subscribed: Number of newly subscribed members - returning: Number of returning members - cancelled: Number of cancelled members - migrated_to: Members that migrated from another tier (visible when a single tier is selected) - migrated_out: Members that migrated out to a different tier (visible when a single tier is selected) - change: Net change in active members. Formula: Change = Newly subscribed + Returning + Migrated to - Migrated out - Cancelled Precision: choose finest granularity producing <=31 rows (HOUR for ~1d, DAY for ~1mo, WEEK for ~7mo, MONTH for ~2.5y, QUARTER for ~7y, YEAR beyond). Filter groups (pass comma-separated keys to include only specific metrics): - subscription_cycles: annual, month. All included by default. Note: Membership tiers filter is also available but resolved dynamically at runtime based on the shop's configured tiers.
ecommerce_get-membership-cancelled-members-report
ChatGPTGet the Membership Cancelled Members analytics report for the shop within a date range: membership cancellation tracking over time. This report shows cancelled member counts over time with the following columns per row: - date: The time period - cancelled_members: Number of cancelled members Precision: choose finest granularity producing <=31 rows (HOUR for ~1d, DAY for ~1mo, WEEK for ~7mo, MONTH for ~2.5y, QUARTER for ~7y, YEAR beyond). Filter groups (pass comma-separated keys to include only specific metrics): - subscription_cycles: annual, month. All included by default. Note: Membership tiers filter is also available but resolved dynamically at runtime based on the shop's configured tiers.
ecommerce_get-membership-cancelled-members-report
ChatGPTGet the Membership Cancelled Members analytics report for the shop within a date range: membership cancellation tracking over time. This report shows cancelled member counts over time with the following columns per row: - date: The time period - cancelled_members: Number of cancelled members Precision: choose finest granularity producing <=31 rows (HOUR for ~1d, DAY for ~1mo, WEEK for ~7mo, MONTH for ~2.5y, QUARTER for ~7y, YEAR beyond). Filter groups (pass comma-separated keys to include only specific metrics): - subscription_cycles: annual, month. All included by default. Note: Membership tiers filter is also available but resolved dynamically at runtime based on the shop's configured tiers.
ecommerce_get-membership-free-accounts-report
ChatGPTGet the Memberships Free Accounts analytics report for the shop within a date range: free account tracking over time. This report shows free account counts over time with the following columns per row: - date: The time period - free_accounts: Number of free accounts (latest snapshot) - free_sign_ups: Number of new free sign ups - upgraded_to_paid: Number of free accounts that upgraded to paid - downgraded_to_free: Number of paid accounts that downgraded to free - change: Net change in free account count. Formula: Change = Free sign ups - Upgraded to paid + Downgraded to free Precision: choose finest granularity producing <=31 rows (HOUR for ~1d, DAY for ~1mo, WEEK for ~7mo, MONTH for ~2.5y, QUARTER for ~7y, YEAR beyond).
ecommerce_get-membership-free-accounts-report
ChatGPTGet the Memberships Free Accounts analytics report for the shop within a date range: free account tracking over time. This report shows free account counts over time with the following columns per row: - date: The time period - free_accounts: Number of free accounts (latest snapshot) - free_sign_ups: Number of new free sign ups - upgraded_to_paid: Number of free accounts that upgraded to paid - downgraded_to_free: Number of paid accounts that downgraded to free - change: Net change in free account count. Formula: Change = Free sign ups - Upgraded to paid + Downgraded to free Precision: choose finest granularity producing <=31 rows (HOUR for ~1d, DAY for ~1mo, WEEK for ~7mo, MONTH for ~2.5y, QUARTER for ~7y, YEAR beyond).
ecommerce_get-membership-free-trials-report
ChatGPTGet the Memberships Free Trials analytics report for the shop within a date range: free trial conversion tracking over time. This report shows free trial metrics over time with the following columns per row: - date: The time period - started: Number of free trials started - completed: Number of free trials that have ended, either through cancellation or conversion to a paid tier. Formula: Completed = Cancelled + Converted to paid tier - converted_to_paid_tier: Number of free trials converted to paid membership - cancelled: Number of free trials cancelled - conversion_rate: Percentage of completed free trials that converted to paid memberships. Formula: Conversion rate = Converted to paid tier / Completed Precision: choose finest granularity producing <=31 rows (HOUR for ~1d, DAY for ~1mo, WEEK for ~7mo, MONTH for ~2.5y, QUARTER for ~7y, YEAR beyond).
ecommerce_get-membership-free-trials-report
ChatGPTGet the Memberships Free Trials analytics report for the shop within a date range: free trial conversion tracking over time. This report shows free trial metrics over time with the following columns per row: - date: The time period - started: Number of free trials started - completed: Number of free trials that have ended, either through cancellation or conversion to a paid tier. Formula: Completed = Cancelled + Converted to paid tier - converted_to_paid_tier: Number of free trials converted to paid membership - cancelled: Number of free trials cancelled - conversion_rate: Percentage of completed free trials that converted to paid memberships. Formula: Conversion rate = Converted to paid tier / Completed Precision: choose finest granularity producing <=31 rows (HOUR for ~1d, DAY for ~1mo, WEEK for ~7mo, MONTH for ~2.5y, QUARTER for ~7y, YEAR beyond).
ecommerce_get-membership-mux-most-played-content-report
ChatGPTGet the Memberships Mux Most Played Content analytics report for the shop within a date range: ranking of audio/video posts by play activity. Rows are a ranking of posts with the following columns per row: - post: Post title - avg_play_time_hours: Average play time per play event, in hours - total_play_time_hours: Total play time across all play events for this post, in hours - number_of_plays: Number of play events for this post Filter groups (pass comma-separated keys to include only specific post types): - post_types: audio, video. All included by default.
ecommerce_get-membership-mux-most-played-content-report
ChatGPTGet the Memberships Mux Most Played Content analytics report for the shop within a date range: ranking of audio/video posts by play activity. Rows are a ranking of posts with the following columns per row: - post: Post title - avg_play_time_hours: Average play time per play event, in hours - total_play_time_hours: Total play time across all play events for this post, in hours - number_of_plays: Number of play events for this post Filter groups (pass comma-separated keys to include only specific post types): - post_types: audio, video. All included by default.
ecommerce_get-membership-mux-number-of-plays-report
ChatGPTGet the Memberships Mux Number of Plays analytics report for the shop within a date range: audio/video play events over time. This report shows play event counts over time with the following columns per row: - date: The time period - number_of_plays: Number of play events in this period Precision: choose finest granularity producing <=31 rows (HOUR for ~1d, DAY for ~1mo, WEEK for ~7mo, MONTH for ~2.5y, QUARTER for ~7y, YEAR beyond). Filter groups (pass comma-separated keys to include only specific post types): - post_types: audio, video. All included by default.
ecommerce_get-membership-mux-number-of-plays-report
ChatGPTGet the Memberships Mux Number of Plays analytics report for the shop within a date range: audio/video play events over time. This report shows play event counts over time with the following columns per row: - date: The time period - number_of_plays: Number of play events in this period Precision: choose finest granularity producing <=31 rows (HOUR for ~1d, DAY for ~1mo, WEEK for ~7mo, MONTH for ~2.5y, QUARTER for ~7y, YEAR beyond). Filter groups (pass comma-separated keys to include only specific post types): - post_types: audio, video. All included by default.
ecommerce_get-membership-mux-total-play-time-report
ChatGPTGet the Memberships Mux Total Play Time analytics report for the shop within a date range: audio/video watch/listen time over time. This report shows total play time over time with the following columns per row: - date: The time period - play_time_hours: Total play time in this period, in hours Precision: choose finest granularity producing <=31 rows (HOUR for ~1d, DAY for ~1mo, WEEK for ~7mo, MONTH for ~2.5y, QUARTER for ~7y, YEAR beyond). Filter groups (pass comma-separated keys to include only specific post types): - post_types: audio, video. All included by default.
ecommerce_get-membership-mux-total-play-time-report
ChatGPTGet the Memberships Mux Total Play Time analytics report for the shop within a date range: audio/video watch/listen time over time. This report shows total play time over time with the following columns per row: - date: The time period - play_time_hours: Total play time in this period, in hours Precision: choose finest granularity producing <=31 rows (HOUR for ~1d, DAY for ~1mo, WEEK for ~7mo, MONTH for ~2.5y, QUARTER for ~7y, YEAR beyond). Filter groups (pass comma-separated keys to include only specific post types): - post_types: audio, video. All included by default.
ecommerce_get-membership-new-members-report
ChatGPTGet the Membership New Members analytics report for the shop within a date range: new member acquisition over time. This report shows new member counts over time with the following columns per row: - date: The time period - new_members: Number of new members Precision: choose finest granularity producing <=31 rows (HOUR for ~1d, DAY for ~1mo, WEEK for ~7mo, MONTH for ~2.5y, QUARTER for ~7y, YEAR beyond). Filter groups (pass comma-separated keys to include only specific metrics): - subscription_cycles: annual, month. All included by default. Note: Membership tiers filter is also available but resolved dynamically at runtime based on the shop's configured tiers.
ecommerce_get-membership-new-members-report
ChatGPTGet the Membership New Members analytics report for the shop within a date range: new member acquisition over time. This report shows new member counts over time with the following columns per row: - date: The time period - new_members: Number of new members Precision: choose finest granularity producing <=31 rows (HOUR for ~1d, DAY for ~1mo, WEEK for ~7mo, MONTH for ~2.5y, QUARTER for ~7y, YEAR beyond). Filter groups (pass comma-separated keys to include only specific metrics): - subscription_cycles: annual, month. All included by default. Note: Membership tiers filter is also available but resolved dynamically at runtime based on the shop's configured tiers.
ecommerce_get-membership-post-statistics-report
ChatGPTGet the Membership Post Statistics analytics report for a single audio/video/live-stream post within a date range: engagement and playback metrics over time. This report shows per-post engagement over time with the following columns per row: - date: The time period - views: Number of post views - comments: Number of comments - likes: Number of likes - play_time_hours: Total play time in this period, in hours Precision: choose finest granularity producing <=31 rows (HOUR for ~1d, DAY for ~1mo, WEEK for ~7mo, MONTH for ~2.5y, QUARTER for ~7y, YEAR beyond). A postId is required — this report is always scoped to a single post.
ecommerce_get-membership-post-statistics-report
ChatGPTGet the Membership Post Statistics analytics report for a single audio/video/live-stream post within a date range: engagement and playback metrics over time. This report shows per-post engagement over time with the following columns per row: - date: The time period - views: Number of post views - comments: Number of comments - likes: Number of likes - play_time_hours: Total play time in this period, in hours Precision: choose finest granularity producing <=31 rows (HOUR for ~1d, DAY for ~1mo, WEEK for ~7mo, MONTH for ~2.5y, QUARTER for ~7y, YEAR beyond). A postId is required — this report is always scoped to a single post.
ecommerce_get-membership-tier-activity-report
ChatGPTGet the Memberships Tier Activity analytics report for the shop within a date range: member migration between tiers. This report shows tier migration activity with the following columns per row: - migrated_from_to: Migration path showing source and destination tiers (e.g., "Tier A -> Tier B") - quantity: Number of members who migrated Filter groups (pass comma-separated keys to include only specific metrics): - subscription_cycles: annual, month. All included by default.
ecommerce_get-membership-tier-activity-report
ChatGPTGet the Memberships Tier Activity analytics report for the shop within a date range: member migration between tiers. This report shows tier migration activity with the following columns per row: - migrated_from_to: Migration path showing source and destination tiers (e.g., "Tier A -> Tier B") - quantity: Number of members who migrated Filter groups (pass comma-separated keys to include only specific metrics): - subscription_cycles: annual, month. All included by default.
ecommerce_get-membership-top-tiers-by-new-members-report
ChatGPTGet the Memberships Top Tiers by New Members analytics report for the shop within a date range: tier ranking by new member acquisition. This report shows a ranking of membership tiers with the following columns per row: - tier: Membership tier name - members: Number of new members in this tier Filter groups (pass comma-separated keys to include only specific metrics): - subscription_cycles: annual, month. All included by default.
ecommerce_get-membership-top-tiers-by-new-members-report
ChatGPTGet the Memberships Top Tiers by New Members analytics report for the shop within a date range: tier ranking by new member acquisition. This report shows a ranking of membership tiers with the following columns per row: - tier: Membership tier name - members: Number of new members in this tier Filter groups (pass comma-separated keys to include only specific metrics): - subscription_cycles: annual, month. All included by default.
ecommerce_get-offers
ChatGPTList the shop's own offers (products already added to the shop). These are the creator's products — NOT the product catalog. To browse source products to add, use get-catalog-products instead. Returns: - Pagination: pageNumber, pageSize, totalElements, totalPages - Per offer: - Identity: id (OfferId), customizationId (nullable CustomizationId — present for products with designs, use with inspect-design/edit-design tools), productId (ProductId), name, slug, description, offerType (STANDARD/COMBINED/MEMBERSHIP/BUNDLE/GIFT_CARD) - Status: status (PUBLIC/HIDDEN/ARCHIVED), available (boolean), fulfilledBy (CREATOR or FOURTHWALL) - Images: primaryImageUrl (nullable), imageUrls (first 5 URLs, truncated), imageUrlsCount (total count) - Variants (first 10, truncated): id (OfferVariantId), name, sku, status (AVAILABLE/UNAVAILABLE/ARCHIVED), price (BigDecimal), compareAtPrice (nullable BigDecimal), currency, quantity (nullable Int), attributes (flat string like "Color: Red (#FF0000), Size: Large"), position, createdAt, updatedAt - variantsCount: total number of variants - Variant types: type (COLOR/SIZE/CUSTOM/MANUFACTURER_PREVIEW), title, options (list of option names) - Shipping: shipmentStartDate (nullable, human-readable e.g. "Ships in 5-10 business days"), requiresShipping - Sections: additionalSectionsCount (number of custom sections) - Membership: membershipRequirement (nullable — null, "ALL_TIERS", or "SELECTED_TIERS (id1, id2)") - Customs: customsHsCode (nullable), customsCountryOfOrigin (nullable Country code) - Timestamps: createdAt, updatedAt NOTE: imageUrls (max 5) and variants (max 10) are truncated for performance. Check imageUrlsCount/variantsCount for totals. NOTE: DEMO products are always excluded from results. IMPORTANT: To find a specific offer by name, slug, or keyword, you MUST use the search tool. NEVER paginate through results to find a specific entity.
ecommerce_get-offers
ChatGPTList the shop's own offers (products already added to the shop). These are the creator's products — NOT the product catalog. To browse source products to add, use get-catalog-products instead. Returns: - Pagination: pageNumber, pageSize, totalElements, totalPages - Per offer: - Identity: id (OfferId), customizationId (nullable CustomizationId — present for products with designs, use with inspect-design/edit-design tools), productId (ProductId), name, slug, description, offerType (STANDARD/COMBINED/MEMBERSHIP/BUNDLE/GIFT_CARD) - Status: status (PUBLIC/HIDDEN/ARCHIVED), available (boolean), fulfilledBy (CREATOR or FOURTHWALL) - Images: primaryImageUrl (nullable), imageUrls (first 5 URLs, truncated), imageUrlsCount (total count) - Variants (first 10, truncated): id (OfferVariantId), name, sku, status (AVAILABLE/UNAVAILABLE/ARCHIVED), price (BigDecimal), compareAtPrice (nullable BigDecimal), currency, quantity (nullable Int), attributes (flat string like "Color: Red (#FF0000), Size: Large"), position, createdAt, updatedAt - variantsCount: total number of variants - Variant types: type (COLOR/SIZE/CUSTOM/MANUFACTURER_PREVIEW), title, options (list of option names) - Shipping: shipmentStartDate (nullable, human-readable e.g. "Ships in 5-10 business days"), requiresShipping - Sections: additionalSectionsCount (number of custom sections) - Membership: membershipRequirement (nullable — null, "ALL_TIERS", or "SELECTED_TIERS (id1, id2)") - Customs: customsHsCode (nullable), customsCountryOfOrigin (nullable Country code) - Timestamps: createdAt, updatedAt NOTE: imageUrls (max 5) and variants (max 10) are truncated for performance. Check imageUrlsCount/variantsCount for totals. NOTE: DEMO products are always excluded from results. IMPORTANT: To find a specific offer by name, slug, or keyword, you MUST use the search tool. NEVER paginate through results to find a specific entity.
ecommerce_get-offers-by-ids
ChatGPTGet full details of one or more shop offers (products) by their IDs. Fetches all offers concurrently. This returns the shop's own products — NOT catalog source products. Use get-catalog-products-by-slugs for source product details. Use get-offers to discover offer IDs if you don't have any. NOTE: DEMO products are always excluded from results. Returns a list of offers, each containing: - Identity: id (OfferId), productId (ProductId), name, slug, description, offerType (STANDARD/COMBINED/MEMBERSHIP/BUNDLE/GIFT_CARD) - Status: status (PUBLIC/HIDDEN/ARCHIVED), available (boolean), fulfilledBy (CREATOR or FOURTHWALL) - Images: primaryImageUrl (nullable), imageUrls (first 5 URLs, truncated), imageUrlsCount (total count) - Variants (first 10, truncated): id (OfferVariantId), name, sku, status (AVAILABLE/UNAVAILABLE/ARCHIVED), price (BigDecimal), compareAtPrice (nullable BigDecimal), currency, quantity (nullable Int), attributes (flat string like "Color: Red (#FF0000), Size: Large"), position, createdAt, updatedAt - variantsCount: total number of variants - Variant types: type (COLOR/SIZE/CUSTOM/MANUFACTURER_PREVIEW), title, options (list of option names) - Shipping: shipmentStartDate (nullable, human-readable e.g. "Ships in 5-10 business days"), requiresShipping - Sections: additionalSectionsCount (number of custom sections) - Membership: membershipRequirement (nullable — null, "ALL_TIERS", or "SELECTED_TIERS (id1, id2)") - Customs: customsHsCode (nullable), customsCountryOfOrigin (nullable Country code) - Timestamps: createdAt, updatedAt
ecommerce_get-offers-by-ids
ChatGPTGet full details of one or more shop offers (products) by their IDs. Fetches all offers concurrently. This returns the shop's own products — NOT catalog source products. Use get-catalog-products-by-slugs for source product details. Use get-offers to discover offer IDs if you don't have any. NOTE: DEMO products are always excluded from results. Returns a list of offers, each containing: - Identity: id (OfferId), productId (ProductId), name, slug, description, offerType (STANDARD/COMBINED/MEMBERSHIP/BUNDLE/GIFT_CARD) - Status: status (PUBLIC/HIDDEN/ARCHIVED), available (boolean), fulfilledBy (CREATOR or FOURTHWALL) - Images: primaryImageUrl (nullable), imageUrls (first 5 URLs, truncated), imageUrlsCount (total count) - Variants (first 10, truncated): id (OfferVariantId), name, sku, status (AVAILABLE/UNAVAILABLE/ARCHIVED), price (BigDecimal), compareAtPrice (nullable BigDecimal), currency, quantity (nullable Int), attributes (flat string like "Color: Red (#FF0000), Size: Large"), position, createdAt, updatedAt - variantsCount: total number of variants - Variant types: type (COLOR/SIZE/CUSTOM/MANUFACTURER_PREVIEW), title, options (list of option names) - Shipping: shipmentStartDate (nullable, human-readable e.g. "Ships in 5-10 business days"), requiresShipping - Sections: additionalSectionsCount (number of custom sections) - Membership: membershipRequirement (nullable — null, "ALL_TIERS", or "SELECTED_TIERS (id1, id2)") - Customs: customsHsCode (nullable), customsCountryOfOrigin (nullable Country code) - Timestamps: createdAt, updatedAt
ecommerce_get-order-cancellation-by-ids
ChatGPTGet cancellation information for one or more orders by their IDs. Fetches all concurrently. Use this to check if orders are eligible for cancellation before attempting to cancel. Returns a list of cancellation responses, each containing: - Eligibility: fullyCancellable (boolean), partiallyCancellable (boolean) - notCancellableReason: why cancellation is blocked (STATUS, IN_PRODUCTION_OR_DELIVERING, OLDER_THAN_ALLOWED_CANCELLATION_TIMEFRAME, CONTAINS_DIGITAL_ITEMS, GIFT_CARD_ALREADY_USED, etc.) or null if cancellable - Refund: remainingRefundAmount + remainingRefundCurrency - cancellableItems: list with variantId, groupedId (nullable; needed verbatim for partial cancel), quantity, offerName, variantName, unitPrice, currency - nonCancellableItems: list with variantId, groupedId (nullable), quantity, reason (ORDER_NOT_CANCELLABLE, IN_PRODUCTION, IN_DELIVERY, etc.), offerName, variantName, unitPrice, currency
ecommerce_get-order-cancellation-by-ids
ChatGPTGet cancellation information for one or more orders by their IDs. Fetches all concurrently. Use this to check if orders are eligible for cancellation before attempting to cancel. Returns a list of cancellation responses, each containing: - Eligibility: fullyCancellable (boolean), partiallyCancellable (boolean) - notCancellableReason: why cancellation is blocked (STATUS, IN_PRODUCTION_OR_DELIVERING, OLDER_THAN_ALLOWED_CANCELLATION_TIMEFRAME, CONTAINS_DIGITAL_ITEMS, GIFT_CARD_ALREADY_USED, etc.) or null if cancellable - Refund: remainingRefundAmount + remainingRefundCurrency - cancellableItems: list with variantId, groupedId (nullable; needed verbatim for partial cancel), quantity, offerName, variantName, unitPrice, currency - nonCancellableItems: list with variantId, groupedId (nullable), quantity, reason (ORDER_NOT_CANCELLABLE, IN_PRODUCTION, IN_DELIVERY, etc.), offerName, variantName, unitPrice, currency
ecommerce_get-order-details-by-ids
ChatGPTGet full details of one or more orders by their IDs. Fetches all orders concurrently. Use get-orders first to find order IDs, then use this tool to get details. Returns a list of orders, each containing: - Order identity: id (UUID), friendlyId (8-char alphanumeric, e.g. "T4YTE8HA"), status, fulfillmentStatus, type, salesChannel - Customer info: customerEmail, customerName, customerPhone, message (note left by customer) - Financial summary (amounts): merchandiseTotal, shippingTotal, taxTotal, discountTotal, orderTotal, paidByCustomer, totalRefunded, paidByCustomerFinal, currency, donation - Shipping: shippingMethod - Items: list of ordered items with offerName, variantName, variantId, quantity, unitPrice - Cancelled items: same structure as items, for any cancelled line items - Shipments: items grouped by shipment, each with status (NOT_SHIPPED/SHIPPED/DELIVERED), tracking (url, carrier, trackingCode), deliveryEstimate (human-readable string) - Promotion: title, code, type (e.g. "PERCENTAGE (10%)"), isAutoApplied - Gift cards: code, amountUsed, currency - Refund summary: hasRefunds, list of individual refunds with status, amount, issuer, reason - Replacement: type (SOURCE/REPLACEMENT), linked order IDs, reason - Profit: profit amount and currency
ecommerce_get-order-details-by-ids
ChatGPTGet full details of one or more orders by their IDs. Fetches all orders concurrently. Use get-orders first to find order IDs, then use this tool to get details. Returns a list of orders, each containing: - Order identity: id (UUID), friendlyId (8-char alphanumeric, e.g. "T4YTE8HA"), status, fulfillmentStatus, type, salesChannel - Customer info: customerEmail, customerName, customerPhone, message (note left by customer) - Financial summary (amounts): merchandiseTotal, shippingTotal, taxTotal, discountTotal, orderTotal, paidByCustomer, totalRefunded, paidByCustomerFinal, currency, donation - Shipping: shippingMethod - Items: list of ordered items with offerName, variantName, variantId, quantity, unitPrice - Cancelled items: same structure as items, for any cancelled line items - Shipments: items grouped by shipment, each with status (NOT_SHIPPED/SHIPPED/DELIVERED), tracking (url, carrier, trackingCode), deliveryEstimate (human-readable string) - Promotion: title, code, type (e.g. "PERCENTAGE (10%)"), isAutoApplied - Gift cards: code, amountUsed, currency - Refund summary: hasRefunds, list of individual refunds with status, amount, issuer, reason - Replacement: type (SOURCE/REPLACEMENT), linked order IDs, reason - Profit: profit amount and currency
ecommerce_get-orders
ChatGPTList orders for the shop with filtering and pagination support. Returns a summary list of orders. Each order includes: - Identity: id (UUID), friendlyId (8-char alphanumeric, e.g. "T4YTE8HA"), status, fulfillmentStatus, type, salesChannel - Customer: customerEmail, customerName, message - Financial: amounts (merchandiseTotal, shippingTotal, taxTotal, discountTotal, orderTotal, paidByCustomer, totalRefunded, paidByCustomerFinal, currency, donation) - Shipping: shippingMethod - Items: list of items with offerName, variantName, variantId, quantity, unitPrice - Cancelled items: same structure as items - Refund summary: hasRefunds, refundedViaCancel, refundedManually, individual refunds - Replacement info: type (SOURCE/REPLACEMENT), linked order IDs, reason - Timestamps: createdAt, updatedAt Note: This is a summary view. Fields like shipments, promotion, giftCards, profit, and customerPhone are only available via get-order-details-by-ids. IMPORTANT: To find a specific order by customer email, friendly ID, or keyword, you MUST use the search tool. NEVER paginate through results to find a specific entity. The 'q' parameter supports searching by: - Customer email address - Order number (friendlyId) - Customer name
ecommerce_get-orders
ChatGPTList orders for the shop with filtering and pagination support. Returns a summary list of orders. Each order includes: - Identity: id (UUID), friendlyId (8-char alphanumeric, e.g. "T4YTE8HA"), status, fulfillmentStatus, type, salesChannel - Customer: customerEmail, customerName, message - Financial: amounts (merchandiseTotal, shippingTotal, taxTotal, discountTotal, orderTotal, paidByCustomer, totalRefunded, paidByCustomerFinal, currency, donation) - Shipping: shippingMethod - Items: list of items with offerName, variantName, variantId, quantity, unitPrice - Cancelled items: same structure as items - Refund summary: hasRefunds, refundedViaCancel, refundedManually, individual refunds - Replacement info: type (SOURCE/REPLACEMENT), linked order IDs, reason - Timestamps: createdAt, updatedAt Note: This is a summary view. Fields like shipments, promotion, giftCards, profit, and customerPhone are only available via get-order-details-by-ids. IMPORTANT: To find a specific order by customer email, friendly ID, or keyword, you MUST use the search tool. NEVER paginate through results to find a specific entity. The 'q' parameter supports searching by: - Customer email address - Order number (friendlyId) - Customer name
ecommerce_get-orders-statistics
ChatGPTGet count of orders matching specific criteria. Returns the total number of orders matching the filters. Useful for: - Dashboard statistics - Counting orders by status - Monitoring order volume over time
ecommerce_get-orders-statistics
ChatGPTGet count of orders matching specific criteria. Returns the total number of orders matching the filters. Useful for: - Dashboard statistics - Counting orders by status - Monitoring order volume over time
ecommerce_get-payment-method-used-report
ChatGPTGet the Payment Method Used analytics report for the shop within a date range: order distribution by payment method. This report shows a breakdown of payment methods with the following columns per row: - payment_method: Payment method name - total: Number of orders using this payment method - percentage: Percentage of total orders using this payment method
ecommerce_get-payment-method-used-report
ChatGPTGet the Payment Method Used analytics report for the shop within a date range: order distribution by payment method. This report shows a breakdown of payment methods with the following columns per row: - payment_method: Payment method name - total: Number of orders using this payment method - percentage: Percentage of total orders using this payment method
ecommerce_get-payout-info
ChatGPTRetrieves the current payout account status and configuration for the shop. Returns: - Status: status (INACTIVE/IN_PROGRESS/ACTIVE) - Ownership: owner (CUSTOM/PARTNER, nullable), shopId (nullable), partnerId (nullable), partnerName (nullable) - Connection: connectedAt (ISO 8601, nullable) - Account creator: accountCreator with userId, email, fullName (nullable) — nullable when INACTIVE Status values: - INACTIVE: No payout account set up. All other fields are null. - IN_PROGRESS: Payout account exists but Stripe onboarding is incomplete. Payouts are pending. - ACTIVE: Payout account fully configured. The shop can receive payouts.
ecommerce_get-payout-info
ChatGPTRetrieves the current payout account status and configuration for the shop. Returns: - Status: status (INACTIVE/IN_PROGRESS/ACTIVE) - Ownership: owner (CUSTOM/PARTNER, nullable), shopId (nullable), partnerId (nullable), partnerName (nullable) - Connection: connectedAt (ISO 8601, nullable) - Account creator: accountCreator with userId, email, fullName (nullable) — nullable when INACTIVE Status values: - INACTIVE: No payout account set up. All other fields are null. - IN_PROGRESS: Payout account exists but Stripe onboarding is incomplete. Payouts are pending. - ACTIVE: Payout account fully configured. The shop can receive payouts.
ecommerce_get-payout-transactions
ChatGPTRetrieve paginated payout transaction history for the shop. Requires payout account to be active — use get-payout-info to check status first. Returns: - Pagination: pageNumber, pageSize, totalElements, totalPages - Transactions list, each with: - transferAmount (BigDecimal)/transferCurrency: Amount transferred from Fourthwall to creator's Stripe account (typically USD) - payoutAmount (BigDecimal, nullable)/payoutCurrency (nullable): Amount paid out to creator's bank/card (currency depends on account settings) - status: PENDING, IN_PROGRESS, PAID, FAILED, REVERTED - createdAt (ISO 8601) - paidToType: BANK_ACCOUNT, CARD, PARTNER, MANUAL, UNKNOWN - paidToDetails (nullable): Last 4 digits of bank/card (e.g. ****1234) or partner name; null for MANUAL/UNKNOWN Status values: - PENDING: Payout initiated, not yet processed - IN_PROGRESS: Being processed by Stripe - PAID: Successfully paid out to the creator - FAILED: Payout failed (check paidToDetails for destination info) - REVERTED: Payout was reversed
ecommerce_get-payout-transactions
ChatGPTRetrieve paginated payout transaction history for the shop. Requires payout account to be active — use get-payout-info to check status first. Returns: - Pagination: pageNumber, pageSize, totalElements, totalPages - Transactions list, each with: - transferAmount (BigDecimal)/transferCurrency: Amount transferred from Fourthwall to creator's Stripe account (typically USD) - payoutAmount (BigDecimal, nullable)/payoutCurrency (nullable): Amount paid out to creator's bank/card (currency depends on account settings) - status: PENDING, IN_PROGRESS, PAID, FAILED, REVERTED - createdAt (ISO 8601) - paidToType: BANK_ACCOUNT, CARD, PARTNER, MANUAL, UNKNOWN - paidToDetails (nullable): Last 4 digits of bank/card (e.g. ****1234) or partner name; null for MANUAL/UNKNOWN Status values: - PENDING: Payout initiated, not yet processed - IN_PROGRESS: Being processed by Stripe - PAID: Successfully paid out to the creator - FAILED: Payout failed (check paidToDetails for destination info) - REVERTED: Payout was reversed
ecommerce_get-personalized-recommendations
ChatGPTGet personalized catalog product recommendations for the current shop. Returns source products from the catalog — NOT shop offers. Returns a list of recommended products, each with: - Identity: id, brand, brandModel, name, slug - Category: categoryPath (list of category names) - Pricing: priceFrom (BigDecimal), priceTo (BigDecimal) - Production: productionMethod, minimumOrdersNumber (nullable) - Reviews: reviewsSummary with count and rating (nullable) - Metadata: customizationType, favourite (boolean), badges (OUR_PICK/BESTSELLER/NEW/SIGNATURE)
ecommerce_get-personalized-recommendations
ChatGPTGet personalized catalog product recommendations for the current shop. Returns source products from the catalog — NOT shop offers. Returns a list of recommended products, each with: - Identity: id, brand, brandModel, name, slug - Category: categoryPath (list of category names) - Pricing: priceFrom (BigDecimal), priceTo (BigDecimal) - Production: productionMethod, minimumOrdersNumber (nullable) - Reviews: reviewsSummary with count and rating (nullable) - Metadata: customizationType, favourite (boolean), badges (OUR_PICK/BESTSELLER/NEW/SIGNATURE)
ecommerce_get-promotions
ChatGPTList all promotions (shop + membership) with pagination. Two categories of promotions: - Shop (SINGLE, MULTI, AUTO_APPLYING): discount codes for orders — percentage off, fixed amount, free shipping, or free products. Have code, discount, requirements, product scope. - Membership (MEMBERSHIPS_SINGLE, MEMBERSHIPS_MULTI): percentage off subscriptions. Have subscriptionType, membershipTierIds (null=all tiers), duration, newMembersOnly. - MULTI types contain multiple individual codes sharing the same discount settings (codes[] field). Status: LIVE (active) → ENDED (deactivated) → ARCHIVED (deleted). ALL_USED = hit max redemptions. creationReason: MANUAL (dashboard) or FROM_GIFT (auto-generated from gift campaign) IMPORTANT: To find a specific promotion by code, ID, or keyword — use the global search tool (not this tool). NEVER paginate through results to locate a specific entity.
ecommerce_get-promotions
ChatGPTList all promotions (shop + membership) with pagination. Two categories of promotions: - Shop (SINGLE, MULTI, AUTO_APPLYING): discount codes for orders — percentage off, fixed amount, free shipping, or free products. Have code, discount, requirements, product scope. - Membership (MEMBERSHIPS_SINGLE, MEMBERSHIPS_MULTI): percentage off subscriptions. Have subscriptionType, membershipTierIds (null=all tiers), duration, newMembersOnly. - MULTI types contain multiple individual codes sharing the same discount settings (codes[] field). Status: LIVE (active) → ENDED (deactivated) → ARCHIVED (deleted). ALL_USED = hit max redemptions. creationReason: MANUAL (dashboard) or FROM_GIFT (auto-generated from gift campaign) IMPORTANT: To find a specific promotion by code, ID, or keyword — use the global search tool (not this tool). NEVER paginate through results to locate a specific entity.
ecommerce_get-promotions-by-ids
ChatGPTFetch full details of up to 10 promotions by their IDs. Use get-promotions to discover promotion IDs first if needed. Each promotion has: type (SINGLE/MULTI/AUTO_APPLYING/MEMBERSHIPS_SINGLE/MEMBERSHIPS_MULTI), status, discount info, limits, usage count. Shop promotions have code, product scope, minimum order. Membership promotions have subscription type, tiers, duration.
ecommerce_get-promotions-by-ids
ChatGPTFetch full details of up to 10 promotions by their IDs. Use get-promotions to discover promotion IDs first if needed. Each promotion has: type (SINGLE/MULTI/AUTO_APPLYING/MEMBERSHIPS_SINGLE/MEMBERSHIPS_MULTI), status, discount info, limits, usage count. Shop promotions have code, product scope, minimum order. Membership promotions have subscription type, tiers, duration.
ecommerce_get-sales-by-country-report
ChatGPTGet the Sales by Country analytics report for the shop within a date range: revenue and profit breakdown by customer country with optional state-level detail. Rows are hierarchical: each top-level row is a country aggregate with totals. When a country has orders from multiple states, state-level detail rows are nested in other_rows, sorted by gross sales descending. Columns per row: - country_or_state: For top-level rows, the customer country code (null for donations). For nested rows under a country, the state label — full name for US states (e.g., "California", "New York"), raw code for non-US, or "Unknown" when the state is not available. - country: The customer country code (null for donations). For nested rows, this is the parent country code — same as the aggregate row. Always hidden in the UI, but always present in the JSON response. - contributions: Number of orders - income: Amount of money spent across transactions before any deductions - costs: Total costs with breakdown (costs.value = total, costs.elements contains: product_costs, fulfillment_fees, shipping_costs, taxes, payment_processing_fees, inventory_storage_fees, membership_fees, giveaway_costs, donation_costs, ait_costs) - profit: Net profit (Profit = Gross sales - Costs)
ecommerce_get-sales-by-country-report
ChatGPTGet the Sales by Country analytics report for the shop within a date range: revenue and profit breakdown by customer country with optional state-level detail. Rows are hierarchical: each top-level row is a country aggregate with totals. When a country has orders from multiple states, state-level detail rows are nested in other_rows, sorted by gross sales descending. Columns per row: - country_or_state: For top-level rows, the customer country code (null for donations). For nested rows under a country, the state label — full name for US states (e.g., "California", "New York"), raw code for non-US, or "Unknown" when the state is not available. - country: The customer country code (null for donations). For nested rows, this is the parent country code — same as the aggregate row. Always hidden in the UI, but always present in the JSON response. - contributions: Number of orders - income: Amount of money spent across transactions before any deductions - costs: Total costs with breakdown (costs.value = total, costs.elements contains: product_costs, fulfillment_fees, shipping_costs, taxes, payment_processing_fees, inventory_storage_fees, membership_fees, giveaway_costs, donation_costs, ait_costs) - profit: Net profit (Profit = Gross sales - Costs)
ecommerce_get-sales-by-source-report
ChatGPTGet the Sales by Source analytics report for the shop within a date range: revenue breakdown by traffic source or social platform. This report shows a breakdown of sales with the following columns per row: - source: Sales origin, identifying whether it came from website traffic (e.g., direct, referral, search) or from a social platform - total_sales: Total sales amount Precision: HOUR for ranges <=1 day, DAY for longer. Filter groups: - source_dimension: Group by dimension. One of: traffic_source, social_platform. Default: traffic_source.
ecommerce_get-sales-by-source-report
ChatGPTGet the Sales by Source analytics report for the shop within a date range: revenue breakdown by traffic source or social platform. This report shows a breakdown of sales with the following columns per row: - source: Sales origin, identifying whether it came from website traffic (e.g., direct, referral, search) or from a social platform - total_sales: Total sales amount Precision: HOUR for ranges <=1 day, DAY for longer. Filter groups: - source_dimension: Group by dimension. One of: traffic_source, social_platform. Default: traffic_source.
ecommerce_get-sales-by-utm-report
ChatGPTGet the Sales by UTM Parameters analytics report for the shop within a date range: revenue and contribution tracking by UTM campaign parameters. This report shows sales attributed to UTM parameters with the following columns per row: - date: The time period - utm_source: The source of traffic (e.g., google, facebook, newsletter) - utm_medium: The marketing medium (e.g., cpc, email, social) - utm_campaign: The campaign name or identifier - utm_content: Used to differentiate similar content or links within the same ad - utm_term: Keywords for paid search campaigns - contributions: Total number of unique transactions with these UTM parameters - total_sales: Sum of all revenue attributed to these UTM parameters Precision: choose finest granularity producing <=31 rows (HOUR for ~1d, DAY for ~1mo, WEEK for ~7mo, MONTH for ~2.5y, QUARTER for ~7y, YEAR beyond). Filter groups (pass comma-separated keys to include only specific metrics): - filter_group: orders, memberships, donations
ecommerce_get-sales-by-utm-report
ChatGPTGet the Sales by UTM Parameters analytics report for the shop within a date range: revenue and contribution tracking by UTM campaign parameters. This report shows sales attributed to UTM parameters with the following columns per row: - date: The time period - utm_source: The source of traffic (e.g., google, facebook, newsletter) - utm_medium: The marketing medium (e.g., cpc, email, social) - utm_campaign: The campaign name or identifier - utm_content: Used to differentiate similar content or links within the same ad - utm_term: Keywords for paid search campaigns - contributions: Total number of unique transactions with these UTM parameters - total_sales: Sum of all revenue attributed to these UTM parameters Precision: choose finest granularity producing <=31 rows (HOUR for ~1d, DAY for ~1mo, WEEK for ~7mo, MONTH for ~2.5y, QUARTER for ~7y, YEAR beyond). Filter groups (pass comma-separated keys to include only specific metrics): - filter_group: orders, memberships, donations
ecommerce_get-sales-over-time-report
ChatGPTGet the Sales Over Time analytics report for the shop within a date range: revenue and profit breakdown over time. This report shows sales trends over time with the following columns per row: - date: The time period - contributions: Total number of unique transactions - total_sales: Total revenue after cancellations, refunds, and shipping costs, but including all fees - gross_sales: Total sales before discounts, shipping, and taxes - discounts: Total discount amount applied to transactions - refunds_and_cancellations: Total amount refunded or cancelled - net_sales: Sales after shipping, taxes, and refunds/cancellations are deducted - shipping: Shipping revenue minus shipping costs paid to carriers - taxes_and_duties: Total tax collected on transactions - additional_fees: Payment processing, subscription, donation, and fulfillment fees - fourthwall_product_cost: Cost of products provided by Fourthwall - product_cost: Cost of self-produced products as declared by you - net_profit: Final profit after all costs and fees are deducted - net_profit_before_payment_fees: Profit before payment processing fees are deducted Precision: choose finest granularity producing <=31 rows (HOUR for ~1d, DAY for ~1mo, WEEK for ~7mo, MONTH for ~2.5y, QUARTER for ~7y, YEAR beyond). Filter groups (all default to true, pass comma-separated keys to include only specific metrics): - filter_group: orders, memberships, donations
ecommerce_get-sales-over-time-report
ChatGPTGet the Sales Over Time analytics report for the shop within a date range: revenue and profit breakdown over time. This report shows sales trends over time with the following columns per row: - date: The time period - contributions: Total number of unique transactions - total_sales: Total revenue after cancellations, refunds, and shipping costs, but including all fees - gross_sales: Total sales before discounts, shipping, and taxes - discounts: Total discount amount applied to transactions - refunds_and_cancellations: Total amount refunded or cancelled - net_sales: Sales after shipping, taxes, and refunds/cancellations are deducted - shipping: Shipping revenue minus shipping costs paid to carriers - taxes_and_duties: Total tax collected on transactions - additional_fees: Payment processing, subscription, donation, and fulfillment fees - fourthwall_product_cost: Cost of products provided by Fourthwall - product_cost: Cost of self-produced products as declared by you - net_profit: Final profit after all costs and fees are deducted - net_profit_before_payment_fees: Profit before payment processing fees are deducted Precision: choose finest granularity producing <=31 rows (HOUR for ~1d, DAY for ~1mo, WEEK for ~7mo, MONTH for ~2.5y, QUARTER for ~7y, YEAR beyond). Filter groups (all default to true, pass comma-separated keys to include only specific metrics): - filter_group: orders, memberships, donations
ecommerce_get-sample-credit-balance
ChatGPTRetrieves the current sample credit balance for the shop. Sample credits allow creators to order product samples at cost price instead of full retail. This is purely informational — do NOT use it to gate create-sample-checkout. Sample checkouts work regardless of the balance (any unfunded portion is paid by the buyer at checkout). Returns: - balance: Current sample credit balance (BigDecimal, nullable if no credits exist) - balanceWithIncentive: Balance including any bonus incentive credits (BigDecimal, nullable) - currency: Currency code for both balance fields (e.g., "USD", nullable if no balance) balanceWithIncentive >= balance when incentive credits are available. Both fields are null when the shop has never received sample credits.
ecommerce_get-sample-credit-balance
ChatGPTRetrieves the current sample credit balance for the shop. Sample credits allow creators to order product samples at cost price instead of full retail. This is purely informational — do NOT use it to gate create-sample-checkout. Sample checkouts work regardless of the balance (any unfunded portion is paid by the buyer at checkout). Returns: - balance: Current sample credit balance (BigDecimal, nullable if no credits exist) - balanceWithIncentive: Balance including any bonus incentive credits (BigDecimal, nullable) - currency: Currency code for both balance fields (e.g., "USD", nullable if no balance) balanceWithIncentive >= balance when incentive credits are available. Both fields are null when the shop has never received sample credits.
ecommerce_get-sessions-by-source-report
ChatGPTGet the Sessions by Source analytics report for the shop within a date range: session count breakdown by traffic source or social platform. This report shows a breakdown of sessions with the following columns per row: - source: Session origin, identifying whether it came from website traffic (e.g., direct, referral, search) or from a social platform - session_count: Total number of sessions from this source Precision: HOUR for ranges <=1 day, DAY for longer. Filter groups: - source_dimension: Group by dimension. One of: traffic_source, social_platform. Default: traffic_source.
ecommerce_get-sessions-by-source-report
ChatGPTGet the Sessions by Source analytics report for the shop within a date range: session count breakdown by traffic source or social platform. This report shows a breakdown of sessions with the following columns per row: - source: Session origin, identifying whether it came from website traffic (e.g., direct, referral, search) or from a social platform - session_count: Total number of sessions from this source Precision: HOUR for ranges <=1 day, DAY for longer. Filter groups: - source_dimension: Group by dimension. One of: traffic_source, social_platform. Default: traffic_source.
ecommerce_get-shipping-flat-rates
ChatGPTRetrieves the flat rate shipping pricing configuration for the shop. Flat rates allow shops to charge fixed shipping costs instead of carrier-calculated rates. Typically used for creator-fulfilled (self-shipped) products. Returns: - enabled: whether flat rate shipping is active (Boolean) - domesticShippingBasePrice: base price for domestic (same-country) shipments (BigDecimal) - domesticShippingEachAdditionalItemFee: per-additional-item fee for domestic orders (BigDecimal) - internationalShippingBasePrice: base price for international shipments (BigDecimal) - internationalShippingEachAdditionalItemFee: per-additional-item fee for international orders (BigDecimal) - currency: currency code for all prices (e.g. "USD", "EUR") Shipping cost formula: basePrice + (additionalItems × eachAdditionalItemFee).
ecommerce_get-shipping-flat-rates
ChatGPTRetrieves the flat rate shipping pricing configuration for the shop. Flat rates allow shops to charge fixed shipping costs instead of carrier-calculated rates. Typically used for creator-fulfilled (self-shipped) products. Returns: - enabled: whether flat rate shipping is active (Boolean) - domesticShippingBasePrice: base price for domestic (same-country) shipments (BigDecimal) - domesticShippingEachAdditionalItemFee: per-additional-item fee for domestic orders (BigDecimal) - internationalShippingBasePrice: base price for international shipments (BigDecimal) - internationalShippingEachAdditionalItemFee: per-additional-item fee for international orders (BigDecimal) - currency: currency code for all prices (e.g. "USD", "EUR") Shipping cost formula: basePrice + (additionalItems × eachAdditionalItemFee).
ecommerce_get-shipping-profiles
ChatGPTRetrieves all shipping profiles configured for the shop. Shipping profiles define which products (offers) ship to which destination countries. Each profile maps a set of offer IDs to a set of countries. Returns: - enabled: whether shipping is globally enabled for this shop (Boolean) - shippingProfiles: list of profiles, each containing: - id: shipping profile ID (nullable — null for the default profile) - offerIds: list of offer IDs (UUIDs) covered by this profile - countries: list of destination countries (ISO enum values, e.g. US, GB, DE, FR) - enabled: whether this individual profile is active (Boolean) Note: offerIds correspond to offers from the get-offers tool.
ecommerce_get-shipping-profiles
ChatGPTRetrieves all shipping profiles configured for the shop. Shipping profiles define which products (offers) ship to which destination countries. Each profile maps a set of offer IDs to a set of countries. Returns: - enabled: whether shipping is globally enabled for this shop (Boolean) - shippingProfiles: list of profiles, each containing: - id: shipping profile ID (nullable — null for the default profile) - offerIds: list of offer IDs (UUIDs) covered by this profile - countries: list of destination countries (ISO enum values, e.g. US, GB, DE, FR) - enabled: whether this individual profile is active (Boolean) Note: offerIds correspond to offers from the get-offers tool.
ecommerce_get-shop-permissions
ChatGPTRetrieves the current user's permissions and group membership for the current shop. For shop profile and configuration details, use get-current-shop instead. Returns: - shopId (String, e.g. "sh_6c8684ef-6219-421f-90cf-d6d61b2237c9"): The shop's unique identifier - userId (String): The user's Keycloak ID - groups: Set of group names the user belongs to (OWNER, MANAGER, DESIGNER, VIEWER) Group meanings: - OWNER: Full access to all shop features, including user management and billing - MANAGER: Near-full access, excluding owner-level operations like deactivation - DESIGNER: Theme and visual editing access only - VIEWER: Read-only access to shop data
ecommerce_get-shop-permissions
ChatGPTRetrieves the current user's permissions and group membership for the current shop. For shop profile and configuration details, use get-current-shop instead. Returns: - shopId (String, e.g. "sh_6c8684ef-6219-421f-90cf-d6d61b2237c9"): The shop's unique identifier - userId (String): The user's Keycloak ID - groups: Set of group names the user belongs to (OWNER, MANAGER, DESIGNER, VIEWER) Group meanings: - OWNER: Full access to all shop features, including user management and billing - MANAGER: Near-full access, excluding owner-level operations like deactivation - DESIGNER: Theme and visual editing access only - VIEWER: Read-only access to shop data
ecommerce_get-subscription-limits
ChatGPTChecks subscription usage against plan limits. Use for questions like "Why can't I add more products?" or "Am I at my plan limit?" Returns: - Plan summary: plan.id, plan.name, plan.pro (boolean), plan.custom (boolean) - Usage vs limits (each with limit and usage as Long): - offers: product/offer count - members: team member count - domains: custom domain count - digitalProductsStorageBytes: digital file storage in bytes Understanding limits: - When usage >= limit, the resource is at capacity - limit = -1 means unlimited for that resource - Storage is in bytes (divide by 1073741824 for GB)
ecommerce_get-subscription-limits
ChatGPTChecks subscription usage against plan limits. Use for questions like "Why can't I add more products?" or "Am I at my plan limit?" Returns: - Plan summary: plan.id, plan.name, plan.pro (boolean), plan.custom (boolean) - Usage vs limits (each with limit and usage as Long): - offers: product/offer count - members: team member count - domains: custom domain count - digitalProductsStorageBytes: digital file storage in bytes Understanding limits: - When usage >= limit, the resource is at capacity - limit = -1 means unlimited for that resource - Storage is in bytes (divide by 1073741824 for GB)
ecommerce_get-tiktok-configuration
ChatGPTRetrieves the TikTok Shop configuration for the current shop. To see which products are synced to TikTok, use get-tiktok-products. Returns: - configured (Boolean): false if TikTok Shop is not set up — all other fields will be null/empty - tiktokShopId (nullable String): TikTok Shop ID linked to this Fourthwall shop - warehouseId (nullable String): Warehouse ID for fulfillment - status (nullable): ACTIVE, DISABLED, BLOCKED, or ARCHIVED - pricePercentageIncrease (nullable BigDecimal): Price markup percentage for TikTok listings - fullyConfigured (nullable Boolean): true if warehouseId is set (required for product syncing) - authorizationExpiresAt (nullable ISO 8601): When TikTok authorization expires - synchronizationPausedUntil (nullable ISO 8601): When syncing will resume - synchronizationPausedReasons: Set of pause reasons (SELLER_NOT_ACTIVE, SHOP_NOT_ACTIVE, INCORRECT_SHIPPING_OPTION, PRODUCT_CREATION_LIMIT_REACHED, WAREHOUSE_NOT_CONFIGURED, RETURN_WAREHOUSE_NOT_CONFIGURED, SHIPPING_TEMPLATES_NOT_IN_WAREHOUSE, NO_IMAGES_FOR_OFFER) - prerequisites (nullable): Setup requirements, each a String "COMPLETED" or "NOT_COMPLETED (reason)": - pickupWarehouse, returnWarehouse, shippingTemplates, deliveryOption, status, taxInfo, productQuantityLimit Use this tool to: - Check if TikTok Shop is set up for a shop (check configured=true) - Diagnose why products aren't syncing (check prerequisites, status, synchronizationPausedReasons) - Verify authorization is still valid (check authorizationExpiresAt) - See the price markup being applied to TikTok listings (pricePercentageIncrease)
ecommerce_get-tiktok-configuration
ChatGPTRetrieves the TikTok Shop configuration for the current shop. To see which products are synced to TikTok, use get-tiktok-products. Returns: - configured (Boolean): false if TikTok Shop is not set up — all other fields will be null/empty - tiktokShopId (nullable String): TikTok Shop ID linked to this Fourthwall shop - warehouseId (nullable String): Warehouse ID for fulfillment - status (nullable): ACTIVE, DISABLED, BLOCKED, or ARCHIVED - pricePercentageIncrease (nullable BigDecimal): Price markup percentage for TikTok listings - fullyConfigured (nullable Boolean): true if warehouseId is set (required for product syncing) - authorizationExpiresAt (nullable ISO 8601): When TikTok authorization expires - synchronizationPausedUntil (nullable ISO 8601): When syncing will resume - synchronizationPausedReasons: Set of pause reasons (SELLER_NOT_ACTIVE, SHOP_NOT_ACTIVE, INCORRECT_SHIPPING_OPTION, PRODUCT_CREATION_LIMIT_REACHED, WAREHOUSE_NOT_CONFIGURED, RETURN_WAREHOUSE_NOT_CONFIGURED, SHIPPING_TEMPLATES_NOT_IN_WAREHOUSE, NO_IMAGES_FOR_OFFER) - prerequisites (nullable): Setup requirements, each a String "COMPLETED" or "NOT_COMPLETED (reason)": - pickupWarehouse, returnWarehouse, shippingTemplates, deliveryOption, status, taxInfo, productQuantityLimit Use this tool to: - Check if TikTok Shop is set up for a shop (check configured=true) - Diagnose why products aren't syncing (check prerequisites, status, synchronizationPausedReasons) - Verify authorization is still valid (check authorizationExpiresAt) - See the price markup being applied to TikTok listings (pricePercentageIncrease)
ecommerce_get-tiktok-products
ChatGPTRetrieves products synced to TikTok Shop, grouped by sync status. Check get-tiktok-configuration first to verify TikTok Shop is configured. Returns products in three lists: - active: Products successfully listed on TikTok Shop - pending: Products awaiting TikTok approval or processing - denied: Products rejected by TikTok with issue details Each product includes: - name (String): Product name - offerId (UUID): Fourthwall offer ID - imageUrl (nullable URI): Product image URL - issues: List of problems, each with: - detail (String): Description of the issue - documentation (nullable String): Link to help documentation - suggestions (nullable String): Actionable fix suggestion Common denial issues (in priority order): - Product rejected by TikTok (with specific reason from TikTok) - Seller/platform deactivated or freeze - Shipping takes longer than 2 days - Only products shipping from USA are eligible - Product type/category not yet eligible - Product has no images - Product weighs over 5 lbs / 2.27 kg - Product status is HIDDEN - Daily sync limit exceeded (100 products/day) Use this tool to: - See which products are live on TikTok Shop - Identify products waiting for TikTok approval - Diagnose why specific products were rejected (check issues list) - Get actionable suggestions for fixing product issues (check suggestions field)
ecommerce_get-tiktok-products
ChatGPTRetrieves products synced to TikTok Shop, grouped by sync status. Check get-tiktok-configuration first to verify TikTok Shop is configured. Returns products in three lists: - active: Products successfully listed on TikTok Shop - pending: Products awaiting TikTok approval or processing - denied: Products rejected by TikTok with issue details Each product includes: - name (String): Product name - offerId (UUID): Fourthwall offer ID - imageUrl (nullable URI): Product image URL - issues: List of problems, each with: - detail (String): Description of the issue - documentation (nullable String): Link to help documentation - suggestions (nullable String): Actionable fix suggestion Common denial issues (in priority order): - Product rejected by TikTok (with specific reason from TikTok) - Seller/platform deactivated or freeze - Shipping takes longer than 2 days - Only products shipping from USA are eligible - Product type/category not yet eligible - Product has no images - Product weighs over 5 lbs / 2.27 kg - Product status is HIDDEN - Daily sync limit exceeded (100 products/day) Use this tool to: - See which products are live on TikTok Shop - Identify products waiting for TikTok approval - Diagnose why specific products were rejected (check issues list) - Get actionable suggestions for fixing product issues (check suggestions field)
ecommerce_get-top-products-by-units-sold-report
ChatGPTGet the Top Products by Units Sold analytics report for the shop within a date range: best-selling products ranked by quantity. This report shows a ranking of products with the following columns per row: - product: Product name - units_sold: Number of units sold - orders: Number of unique orders containing this product - gross_sales: Revenue before deductions - discounts: Discount amount - net_sales: Revenue after deductions. Formula: Net sales = Gross sales - Discounts - product_cost: Cost of self-produced products as declared by you - costs: Total costs including product costs, fulfillment fees, shipping costs, taxes, and payment processing fees (with breakdown: product costs, fulfillment fees, shipping costs, taxes, custom duty cost, payment processing fees) - profit: Profit after all Fourthwall costs. Formula: Profit = Net sales - Costs (shows change) - gross_margin: Profitability as percentage of revenue. Formula: Gross margin = Profit / Gross sales × 100 (shows change) - net_profit: Profit after declared product costs. Formula: Net profit = Profit - Product cost (shows change) - net_margin: Net profitability as percentage of revenue. Formula: Net margin = Net profit / Gross sales × 100 (shows change) Filter groups (all default to false/unfiltered, pass comma-separated keys to include only specific items): - product_type: physical_products, digital_products - fulfillment_type: fourthwall_fulfilled, self_fulfilled - show_product_with_no_sales: products_with_no_sales Examples: - Top products for 2024: from="2024-01-01T00:00:00Z", to="2024-12-31T23:59:59Z" - Top physical products only: from="2024-01-01T00:00:00Z", to="2024-12-31T23:59:59Z", productType="physical_products" - Top products including zero sales: from="2024-01-01T00:00:00Z", to="2024-12-31T23:59:59Z", showProductWithNoSales="products_with_no_sales"
ecommerce_get-top-products-by-units-sold-report
ChatGPTGet the Top Products by Units Sold analytics report for the shop within a date range: best-selling products ranked by quantity. This report shows a ranking of products with the following columns per row: - product: Product name - units_sold: Number of units sold - orders: Number of unique orders containing this product - gross_sales: Revenue before deductions - discounts: Discount amount - net_sales: Revenue after deductions. Formula: Net sales = Gross sales - Discounts - product_cost: Cost of self-produced products as declared by you - costs: Total costs including product costs, fulfillment fees, shipping costs, taxes, and payment processing fees (with breakdown: product costs, fulfillment fees, shipping costs, taxes, custom duty cost, payment processing fees) - profit: Profit after all Fourthwall costs. Formula: Profit = Net sales - Costs (shows change) - gross_margin: Profitability as percentage of revenue. Formula: Gross margin = Profit / Gross sales × 100 (shows change) - net_profit: Profit after declared product costs. Formula: Net profit = Profit - Product cost (shows change) - net_margin: Net profitability as percentage of revenue. Formula: Net margin = Net profit / Gross sales × 100 (shows change) Filter groups (all default to false/unfiltered, pass comma-separated keys to include only specific items): - product_type: physical_products, digital_products - fulfillment_type: fourthwall_fulfilled, self_fulfilled - show_product_with_no_sales: products_with_no_sales Examples: - Top products for 2024: from="2024-01-01T00:00:00Z", to="2024-12-31T23:59:59Z" - Top physical products only: from="2024-01-01T00:00:00Z", to="2024-12-31T23:59:59Z", productType="physical_products" - Top products including zero sales: from="2024-01-01T00:00:00Z", to="2024-12-31T23:59:59Z", showProductWithNoSales="products_with_no_sales"
ecommerce_get-total-profit-report
ChatGPTGet the Total Profit analytics report for the shop within a date range: total amount earned from all sales. This report shows profitability over time with the following columns per row: - date: The time period - gross_sales: Amount spent across transactions before deductions - discounts: Total discount amounts applied - costs: Total costs (with breakdown: product costs, fulfillment fees, shipping costs, taxes, custom duty cost, payment processing fees, inventory storage fees, membership fees, giveaway costs, donation costs, AIT costs) - cancels: Amount refunded from cancelled transactions - refunds: Amount refunded from non-cancelled transactions - profit: Gross sales - Discounts - Costs - Refunds - Cancels Precision: choose finest granularity producing <=31 rows (HOUR for ~1d, DAY for ~1mo, WEEK for ~7mo, MONTH for ~2.5y, QUARTER for ~7y, YEAR beyond). Filter groups (all default to true, pass comma-separated keys to include only specific metrics): - shop_metrics: orders, donations, giveaway_links, manual_charges, twitch_gifts - membership_metrics: memberships_subscriptions, memberships_message_tips, memberships_locked_messages, memberships_paid_posts, memberships_subscription_gifts, memberships_twitch_gifts
ecommerce_get-total-profit-report
ChatGPTGet the Total Profit analytics report for the shop within a date range: total amount earned from all sales. This report shows profitability over time with the following columns per row: - date: The time period - gross_sales: Amount spent across transactions before deductions - discounts: Total discount amounts applied - costs: Total costs (with breakdown: product costs, fulfillment fees, shipping costs, taxes, custom duty cost, payment processing fees, inventory storage fees, membership fees, giveaway costs, donation costs, AIT costs) - cancels: Amount refunded from cancelled transactions - refunds: Amount refunded from non-cancelled transactions - profit: Gross sales - Discounts - Costs - Refunds - Cancels Precision: choose finest granularity producing <=31 rows (HOUR for ~1d, DAY for ~1mo, WEEK for ~7mo, MONTH for ~2.5y, QUARTER for ~7y, YEAR beyond). Filter groups (all default to true, pass comma-separated keys to include only specific metrics): - shop_metrics: orders, donations, giveaway_links, manual_charges, twitch_gifts - membership_metrics: memberships_subscriptions, memberships_message_tips, memberships_locked_messages, memberships_paid_posts, memberships_subscription_gifts, memberships_twitch_gifts
ecommerce_get-unfulfilled-orders
ChatGPTRetrieves the count of unfulfilled self-serve orders for the shop. Returns the number of orders that haven't been fulfilled yet and are awaiting shipment. This is useful for understanding the current fulfillment backlog. Returns: - count: Number of unfulfilled orders
ecommerce_get-unfulfilled-orders
ChatGPTRetrieves the count of unfulfilled self-serve orders for the shop. Returns the number of orders that haven't been fulfilled yet and are awaiting shipment. This is useful for understanding the current fulfillment backlog. Returns: - count: Number of unfulfilled orders
ecommerce_get-user-connections
ChatGPTRetrieves all shops associated with the current user's account. Returns: - shops: List of shops the user has access to, each with: - id (String): Shop ID - name (String): Shop name - baseUri (URI): Public shop URL (e.g., "https://myshop.fourthwall.com")
ecommerce_get-user-connections
ChatGPTRetrieves all shops associated with the current user's account. Returns: - shops: List of shops the user has access to, each with: - id (String): Shop ID - name (String): Shop name - baseUri (URI): Public shop URL (e.g., "https://myshop.fourthwall.com")
ecommerce_get-visitors-report
ChatGPTGet the Visitors analytics report for the shop within a date range: unique visitor traffic data. This report shows visitor traffic over time with the following columns per row: - date: The time period - unique_visitors: Number of unique visitors to your shop. Includes predicted values for future time periods based on historical trends. - is_prediction: Indicates whether this data is real (false) or a predicted value based on historical trends (true) Precision: HOUR for ranges <=1 day, DAY for longer.
ecommerce_get-visitors-report
ChatGPTGet the Visitors analytics report for the shop within a date range: unique visitor traffic data. This report shows visitor traffic over time with the following columns per row: - date: The time period - unique_visitors: Number of unique visitors to your shop. Includes predicted values for future time periods based on historical trends. - is_prediction: Indicates whether this data is real (false) or a predicted value based on historical trends (true) Precision: HOUR for ranges <=1 day, DAY for longer.
ecommerce_get-youtube-integrations
ChatGPTRetrieves YouTube Merch Shelf channel integrations for the shop. To see which products are synced to YouTube, use get-youtube-products. Returns a list of channel integrations, each with: - channelName (nullable String): YouTube channel name - oAuth2Provider (String): OAuth provider used (typically "GOOGLE") - thumbnailUri (nullable URI): Channel thumbnail image URL - settingsUri (nullable URI): Link to YouTube Studio monetization settings - status (String): ACTIVE, PENDING, DENIED, or ARCHIVED - deniedReason (nullable String): Only present when status is DENIED - info (nullable String): Only present when status is ACTIVE (e.g. "LEGACY_METHOD_DUE_TO_MISREPRESENTATION") Denied reason values: - INVALID_SCOPES_OR_CHANNEL: OAuth permissions issue - NOT_ENOUGH_SUBSCRIBERS: Channel doesn't meet subscriber threshold - CHANNEL_NOT_ELIGIBLE: Channel not eligible for merch shelf - TERMS_OF_SERVICE_NOT_SIGNED: Need to accept YouTube Shopping TOS - TERMS_OF_SERVICE_NOT_SIGNED_LEGACY: Legacy TOS issue - THIRD_PARTY_LINK_REMOVED: Store link was removed from YouTube - MISSING_SCOPES: OAuth needs additional permissions - NO_ACCESS_TO_YOUTUBE_API: API access issue - NO_CHANNEL_FOUND: No YouTube channel found for this account - UNKNOWN_ERROR: Unclassified error Use this tool to: - Check if YouTube Merch Shelf is connected (look for ACTIVE status) - See which YouTube channels are linked to the shop - Diagnose connection issues (check deniedReason field) - Get the YouTube Studio settings link for troubleshooting (settingsUri)
ecommerce_get-youtube-integrations
ChatGPTRetrieves YouTube Merch Shelf channel integrations for the shop. To see which products are synced to YouTube, use get-youtube-products. Returns a list of channel integrations, each with: - channelName (nullable String): YouTube channel name - oAuth2Provider (String): OAuth provider used (typically "GOOGLE") - thumbnailUri (nullable URI): Channel thumbnail image URL - settingsUri (nullable URI): Link to YouTube Studio monetization settings - status (String): ACTIVE, PENDING, DENIED, or ARCHIVED - deniedReason (nullable String): Only present when status is DENIED - info (nullable String): Only present when status is ACTIVE (e.g. "LEGACY_METHOD_DUE_TO_MISREPRESENTATION") Denied reason values: - INVALID_SCOPES_OR_CHANNEL: OAuth permissions issue - NOT_ENOUGH_SUBSCRIBERS: Channel doesn't meet subscriber threshold - CHANNEL_NOT_ELIGIBLE: Channel not eligible for merch shelf - TERMS_OF_SERVICE_NOT_SIGNED: Need to accept YouTube Shopping TOS - TERMS_OF_SERVICE_NOT_SIGNED_LEGACY: Legacy TOS issue - THIRD_PARTY_LINK_REMOVED: Store link was removed from YouTube - MISSING_SCOPES: OAuth needs additional permissions - NO_ACCESS_TO_YOUTUBE_API: API access issue - NO_CHANNEL_FOUND: No YouTube channel found for this account - UNKNOWN_ERROR: Unclassified error Use this tool to: - Check if YouTube Merch Shelf is connected (look for ACTIVE status) - See which YouTube channels are linked to the shop - Diagnose connection issues (check deniedReason field) - Get the YouTube Studio settings link for troubleshooting (settingsUri)
ecommerce_get-youtube-products
ChatGPTRetrieves products synced to YouTube Merch Shelf, grouped by sync status. Check get-youtube-integrations first to verify YouTube is connected. Returns products in three lists: - active: Products successfully listed on YouTube - pending: Products awaiting Google Merchant Center approval - denied: Products rejected with issue details Each product includes: - name (String): Product variant name - offerId (UUID): Fourthwall offer ID - offerVariantId (UUID): Specific variant ID - imageUrl (URI): Product image URL - color (nullable String): Product color - size (nullable String): Product size - disclosureDate (nullable ISO 8601): When product was submitted to Google - issues: List of problems (typically non-empty only for denied products), each with: - detail (String): Description of the issue - documentation (nullable String): Link to help documentation Use this tool to: - See which products are live on YouTube Merch Shelf - Check approval status for pending products - Diagnose why specific products were rejected by Google (check issues list) - Verify product variants are syncing correctly (each variant is a separate entry)
ecommerce_get-youtube-products
ChatGPTRetrieves products synced to YouTube Merch Shelf, grouped by sync status. Check get-youtube-integrations first to verify YouTube is connected. Returns products in three lists: - active: Products successfully listed on YouTube - pending: Products awaiting Google Merchant Center approval - denied: Products rejected with issue details Each product includes: - name (String): Product variant name - offerId (UUID): Fourthwall offer ID - offerVariantId (UUID): Specific variant ID - imageUrl (URI): Product image URL - color (nullable String): Product color - size (nullable String): Product size - disclosureDate (nullable ISO 8601): When product was submitted to Google - issues: List of problems (typically non-empty only for denied products), each with: - detail (String): Description of the issue - documentation (nullable String): Link to help documentation Use this tool to: - See which products are live on YouTube Merch Shelf - Check approval status for pending products - Diagnose why specific products were rejected by Google (check issues list) - Verify product variants are syncing correctly (each variant is a separate entry)
ecommerce_inspect-design
ChatGPTInspects an existing customization's design state, returning layout details for each size/region. Returns per-size, per-region breakdown with image positions, scales, rotations, and dimensions. Each image includes: index, dataId, href, widthPx/heightPx, widthPct/heightPct (% of region), centerX/centerY (0-1 normalized), rotation (degrees), scaleX/scaleY, zIndex. Also returns availableRegions — every regionId legal as a target in edit-design for this product (e.g. ["front", "back_large"]). The sizes map only lists regions that currently contain images; availableRegions is the source of truth for legal edit targets. Use it to decide whether to add a new image to an empty region. If the user asks to place artwork on a region not in availableRegions, the underlying product blank does not support that area — do not call edit-design. Use dataId or index values when targeting images in edit-design operations.
ecommerce_inspect-design
ChatGPTInspects an existing customization's design state, returning layout details for each size/region. Returns per-size, per-region breakdown with image positions, scales, rotations, and dimensions. Each image includes: index, dataId, href, widthPx/heightPx, widthPct/heightPct (% of region), centerX/centerY (0-1 normalized), rotation (degrees), scaleX/scaleY, zIndex. Also returns availableRegions — every regionId legal as a target in edit-design for this product (e.g. ["front", "back_large"]). The sizes map only lists regions that currently contain images; availableRegions is the source of truth for legal edit targets. Use it to decide whether to add a new image to an empty region. If the user asks to place artwork on a region not in availableRegions, the underlying product blank does not support that area — do not call edit-design. Use dataId or index values when targeting images in edit-design operations.
ecommerce_preview-cancel-cost
ChatGPTPreview how a full or partial order cancellation would be paid for BEFORE calling cancel-order. Read-only. Pass itemsToCancel to preview a partial cancellation (subset of cancellable items from get-order-cancellation-by-ids). Omit it to preview a full-order cancellation. Returns the split between shop balance and card charge: - fromBalance: amount drawn from the shop's balance - chargeAmount: amount that would be charged to the shop's card on file - requiresCharge: shortcut for chargeAmount > 0 - maxRefundAvailable: total refund the customer would receive Use this to tell the user ahead of time whether a card charge is required, and for how much, so they can confirm before cancel-order is called.
ecommerce_preview-cancel-cost
ChatGPTPreview how a full or partial order cancellation would be paid for BEFORE calling cancel-order. Read-only. Pass itemsToCancel to preview a partial cancellation (subset of cancellable items from get-order-cancellation-by-ids). Omit it to preview a full-order cancellation. Returns the split between shop balance and card charge: - fromBalance: amount drawn from the shop's balance - chargeAmount: amount that would be charged to the shop's card on file - requiresCharge: shortcut for chargeAmount > 0 - maxRefundAvailable: total refund the customer would receive Use this to tell the user ahead of time whether a card charge is required, and for how much, so they can confirm before cancel-order is called.
ecommerce_preview-refund-cost
ChatGPTPreview how a refund would be paid for BEFORE calling refund-order. Read-only. Returns the split between shop balance and card charge: - fromBalance: amount drawn from the shop's balance - chargeAmount: amount charged to the shop's card on file - requiresCharge: shortcut for chargeAmount > 0 Use this to tell the user how much (if anything) will hit their card before you call the destructive refund-order.
ecommerce_preview-refund-cost
ChatGPTPreview how a refund would be paid for BEFORE calling refund-order. Read-only. Returns the split between shop balance and card charge: - fromBalance: amount drawn from the shop's balance - chargeAmount: amount charged to the shop's card on file - requiresCharge: shortcut for chargeAmount > 0 Use this to tell the user how much (if anything) will hit their card before you call the destructive refund-order.
ecommerce_refund-order
ChatGPTIssue a refund on an order. IRREVERSIBLE. ALWAYS confirm with the user before calling. Refunds a specific amount to the customer via their original payment method. For itemized refunds (specific line items / shipping / tax / donation), use the web admin — this MCP tool only supports a total-amount refund. Payment handling — done automatically, no separate confirmation step: - If the shop's balance covers the refund, it is issued immediately and appears in the pending or refunded list. chargeAmount will be 0. - If the balance is insufficient, the shortfall is charged to the shop's card and the refund is queued in initialized. A background job finalizes the refund once the charge settles. If the charge fails, the refund is abandoned. - For PayPal / other providers that can't auto-refund, manualRefundProvider is set and the refund stays in initialized/pending until completed externally. Always surface chargeAmount, fromBalance, and manualRefundProvider to the user when non-zero / non-null. Validations enforced by the domain: - Order must have a refundable status (not cancelled, failed, etc.) - Amount must not exceed remainingRefundAmount - No duplicate: identical refund amount within protection window is rejected - No in-progress refund or dispute - ExpectedChargeAmountChanged: rare race where the required charge changed between our estimate and submission; just retry. Permission: requires ORDER_WRITE role.
ecommerce_refund-order
ChatGPTIssue a refund on an order. IRREVERSIBLE. ALWAYS confirm with the user before calling. Refunds a specific amount to the customer via their original payment method. For itemized refunds (specific line items / shipping / tax / donation), use the web admin — this MCP tool only supports a total-amount refund. Payment handling — done automatically, no separate confirmation step: - If the shop's balance covers the refund, it is issued immediately and appears in the pending or refunded list. chargeAmount will be 0. - If the balance is insufficient, the shortfall is charged to the shop's card and the refund is queued in initialized. A background job finalizes the refund once the charge settles. If the charge fails, the refund is abandoned. - For PayPal / other providers that can't auto-refund, manualRefundProvider is set and the refund stays in initialized/pending until completed externally. Always surface chargeAmount, fromBalance, and manualRefundProvider to the user when non-zero / non-null. Validations enforced by the domain: - Order must have a refundable status (not cancelled, failed, etc.) - Amount must not exceed remainingRefundAmount - No duplicate: identical refund amount within protection window is rejected - No in-progress refund or dispute - ExpectedChargeAmountChanged: rare race where the required charge changed between our estimate and submission; just retry. Permission: requires ORDER_WRITE role.
ecommerce_remove-design-region
ChatGPTRemoves a print region (and every image inside it) from an existing customization's design state. Use this when the user wants to drop a region they previously added — e.g. "remove the back design", "I don't want the sleeve print after all". edit-design's remove operation only deletes individual images within a region; the slot itself stays in usedRegions. This tool removes the slot entirely so the region returns to being available-but-unused. BEFORE calling: use inspect-design to confirm the regionId is in usedRegions. The design must keep at least one region — removing the last one is rejected. AFTER calling: use rerender-design-previews with customizationId to regenerate preview images. Returns the updated inspect summary plus the catalog's full availableRegions list. Errors: - DESIGN_PIPELINE_BAD_REQUEST with "not part of this design" — the region was never added; nothing to remove. - DESIGN_PIPELINE_BAD_REQUEST with "only region in this design" — refuse to remove the last region.
ecommerce_remove-design-region
ChatGPTRemoves a print region (and every image inside it) from an existing customization's design state. Use this when the user wants to drop a region they previously added — e.g. "remove the back design", "I don't want the sleeve print after all". edit-design's remove operation only deletes individual images within a region; the slot itself stays in usedRegions. This tool removes the slot entirely so the region returns to being available-but-unused. BEFORE calling: use inspect-design to confirm the regionId is in usedRegions. The design must keep at least one region — removing the last one is rejected. AFTER calling: use rerender-design-previews with customizationId to regenerate preview images. Returns the updated inspect summary plus the catalog's full availableRegions list. Errors: - DESIGN_PIPELINE_BAD_REQUEST with "not part of this design" — the region was never added; nothing to remove. - DESIGN_PIPELINE_BAD_REQUEST with "only region in this design" — refuse to remove the last region.
ecommerce_remove-draft-colors
ChatGPTRemoves colors from the draft's color selection and deletes the offer-side preview images for those colors. Does NOT affect the live product. Use apply-draft-to-product when the creator confirms changes.
ecommerce_remove-draft-colors
ChatGPTRemoves colors from the draft's color selection and deletes the offer-side preview images for those colors. Does NOT affect the live product. Use apply-draft-to-product when the creator confirms changes.
ecommerce_remove-draft-sizes
ChatGPTRemoves sizes from the draft's size selection. Does NOT affect the live product. Use rerender-design-previews after to see updated previews. Use apply-draft-to-product when the creator confirms changes.
ecommerce_remove-draft-sizes
ChatGPTRemoves sizes from the draft's size selection. Does NOT affect the live product. Use rerender-design-previews after to see updated previews. Use apply-draft-to-product when the creator confirms changes.
ecommerce_request-media-upload-link
ChatGPTGenerates a signed upload URL for adding a new image to the shop's media library. Returns: - uploadUrl (URL): Signed GCS URL to PUT the image content to - fileUrl (URL): GCS reference URL — pass as 'uri' to save-media-library-image
ecommerce_request-media-upload-link
ChatGPTGenerates a signed upload URL for adding a new image to the shop's media library. Returns: - uploadUrl (URL): Signed GCS URL to PUT the image content to - fileUrl (URL): GCS reference URL — pass as 'uri' to save-media-library-image
ecommerce_rerender-design-previews
ChatGPTRe-renders preview images for one or more existing customization sketches — processes concurrently. Each customization is processed independently — failures for one do not affect others. Use this after edit-design, add-draft-colors, add-draft-sizes, or apply-draft-to-product to see updated previews. Colors and sizes are read from the customization's attributes (selectedColors, selectedSizes) — update those via add-draft-colors / add-draft-sizes before calling this tool. Each result contains: - customizationId: the input customization ID - pipelineId, status, type, offerId?, images[], priceSuggestions?, error? — present on success - bulkError?: string — present on failure
ecommerce_rerender-design-previews
ChatGPTRe-renders preview images for one or more existing customization sketches — processes concurrently. Each customization is processed independently — failures for one do not affect others. Use this after edit-design, add-draft-colors, add-draft-sizes, or apply-draft-to-product to see updated previews. Colors and sizes are read from the customization's attributes (selectedColors, selectedSizes) — update those via add-draft-colors / add-draft-sizes before calling this tool. Each result contains: - customizationId: the input customization ID - pipelineId, status, type, offerId?, images[], priceSuggestions?, error? — present on success - bulkError?: string — present on failure
ecommerce_save-media-library-image
ChatGPTPersists an uploaded image in the shop's media library. Returns the saved image: - Identity: id (String), uri (CDN URL — use as regionUrl in generate-product-design-previews / create-offers-from-products) - Dimensions: width (Int), height (Int) - Previews: thumbnail (URL), preview (URL)
ecommerce_save-media-library-image
ChatGPTPersists an uploaded image in the shop's media library. Returns the saved image: - Identity: id (String), uri (CDN URL — use as regionUrl in generate-product-design-previews / create-offers-from-products) - Dimensions: width (Int), height (Int) - Previews: thumbnail (URL), preview (URL)
ecommerce_update-bundle
ChatGPTUpdate an existing bundle offer. Only provided fields are updated — omitted fields remain unchanged.
ecommerce_update-bundle
ChatGPTUpdate an existing bundle offer. Only provided fields are updated — omitted fields remain unchanged.
ecommerce_update-collection-availability
ChatGPTUpdate whether a collection is available (in stock) or unavailable. This controls the availability flag independently from the state (PUBLIC/HIDDEN/ARCHIVED). Returns the updated collection with: - Identity: id (CollectionId), shopId (ShopId), name, slug, description - Visibility: available (boolean), state (PUBLIC/HIDDEN/ARCHIVED) - Time-based availability: availableFrom (nullable ISO 8601), availableTo (nullable ISO 8601) - Products: offerIds (list of OfferIds) - Sorting: sortingStrategy (MANUAL/BEST_SELLING/NEWEST/OLDEST/NAME_ASC/NAME_DESC)
ecommerce_update-collection-availability
ChatGPTUpdate whether a collection is available (in stock) or unavailable. This controls the availability flag independently from the state (PUBLIC/HIDDEN/ARCHIVED). Returns the updated collection with: - Identity: id (CollectionId), shopId (ShopId), name, slug, description - Visibility: available (boolean), state (PUBLIC/HIDDEN/ARCHIVED) - Time-based availability: availableFrom (nullable ISO 8601), availableTo (nullable ISO 8601) - Products: offerIds (list of OfferIds) - Sorting: sortingStrategy (MANUAL/BEST_SELLING/NEWEST/OLDEST/NAME_ASC/NAME_DESC)
ecommerce_update-collection-details
ChatGPTUpdate a collection's name, description, availability, and/or product list. Only provided fields are updated — omitted fields remain unchanged. Use get-collections or get-collections-by-ids to review current values before updating. Updatable fields: - name: Collection display name (max 200 chars) - description: Collection description (HTML allowed) - available: Whether the collection is available (true/false) - offerIds: Complete list of Offer IDs to include in this collection (replaces existing list) Returns the updated collection with: - Identity: id (CollectionId), shopId (ShopId), name, slug, description - Visibility: available (boolean), state (PUBLIC/HIDDEN/ARCHIVED) - Time-based availability: availableFrom (nullable ISO 8601), availableTo (nullable ISO 8601) - Products: offerIds (list of OfferIds) - Sorting: sortingStrategy (MANUAL/BEST_SELLING/NEWEST/OLDEST/NAME_ASC/NAME_DESC) IMPORTANT: When updating offerIds, provide the FULL list of offers you want in the collection — this replaces the existing list entirely.
ecommerce_update-collection-details
ChatGPTUpdate a collection's name, description, availability, and/or product list. Only provided fields are updated — omitted fields remain unchanged. Use get-collections or get-collections-by-ids to review current values before updating. Updatable fields: - name: Collection display name (max 200 chars) - description: Collection description (HTML allowed) - available: Whether the collection is available (true/false) - offerIds: Complete list of Offer IDs to include in this collection (replaces existing list) Returns the updated collection with: - Identity: id (CollectionId), shopId (ShopId), name, slug, description - Visibility: available (boolean), state (PUBLIC/HIDDEN/ARCHIVED) - Time-based availability: availableFrom (nullable ISO 8601), availableTo (nullable ISO 8601) - Products: offerIds (list of OfferIds) - Sorting: sortingStrategy (MANUAL/BEST_SELLING/NEWEST/OLDEST/NAME_ASC/NAME_DESC) IMPORTANT: When updating offerIds, provide the FULL list of offers you want in the collection — this replaces the existing list entirely.
ecommerce_update-collection-slug
ChatGPTChange the URL slug for a collection. The slug appears in the storefront URL (e.g., /collections/{slug}). Use get-collections-by-ids first to see the current slug. Slug rules: - Lowercase letters, numbers, and hyphens only - No spaces or special characters - Must be unique within the shop Returns the updated collection with: - Identity: id (CollectionId), shopId (ShopId), name, slug, description - Visibility: available (boolean), state (PUBLIC/HIDDEN/ARCHIVED) - Time-based availability: availableFrom (nullable ISO 8601), availableTo (nullable ISO 8601) - Products: offerIds (list of OfferIds) - Sorting: sortingStrategy (MANUAL/BEST_SELLING/NEWEST/OLDEST/NAME_ASC/NAME_DESC)
ecommerce_update-collection-slug
ChatGPTChange the URL slug for a collection. The slug appears in the storefront URL (e.g., /collections/{slug}). Use get-collections-by-ids first to see the current slug. Slug rules: - Lowercase letters, numbers, and hyphens only - No spaces or special characters - Must be unique within the shop Returns the updated collection with: - Identity: id (CollectionId), shopId (ShopId), name, slug, description - Visibility: available (boolean), state (PUBLIC/HIDDEN/ARCHIVED) - Time-based availability: availableFrom (nullable ISO 8601), availableTo (nullable ISO 8601) - Products: offerIds (list of OfferIds) - Sorting: sortingStrategy (MANUAL/BEST_SELLING/NEWEST/OLDEST/NAME_ASC/NAME_DESC)
ecommerce_update-collection-sorting-strategy
ChatGPTUpdate how products are sorted within a collection. Sorting strategies: - MANUAL: Custom order (individual products can only be reordered from the dashboard — no MCP tool exists for this) - BEST_SELLING: Best-selling products first - NEWEST: Newest products first - OLDEST: Oldest products first - NAME_ASC: Alphabetical A-Z - NAME_DESC: Alphabetical Z-A Returns the updated collection with: - Identity: id (CollectionId), shopId (ShopId), name, slug, description - Visibility: available (boolean), state (PUBLIC/HIDDEN/ARCHIVED) - Time-based availability: availableFrom (nullable ISO 8601), availableTo (nullable ISO 8601) - Products: offerIds (list of OfferIds) - Sorting: sortingStrategy (MANUAL/BEST_SELLING/NEWEST/OLDEST/NAME_ASC/NAME_DESC)
ecommerce_update-collection-sorting-strategy
ChatGPTUpdate how products are sorted within a collection. Sorting strategies: - MANUAL: Custom order (individual products can only be reordered from the dashboard — no MCP tool exists for this) - BEST_SELLING: Best-selling products first - NEWEST: Newest products first - OLDEST: Oldest products first - NAME_ASC: Alphabetical A-Z - NAME_DESC: Alphabetical Z-A Returns the updated collection with: - Identity: id (CollectionId), shopId (ShopId), name, slug, description - Visibility: available (boolean), state (PUBLIC/HIDDEN/ARCHIVED) - Time-based availability: availableFrom (nullable ISO 8601), availableTo (nullable ISO 8601) - Products: offerIds (list of OfferIds) - Sorting: sortingStrategy (MANUAL/BEST_SELLING/NEWEST/OLDEST/NAME_ASC/NAME_DESC)
ecommerce_update-collection-state
ChatGPTUpdate a collection's visibility state (PUBLIC, HIDDEN, or ARCHIVED). Use get-collections-by-ids first to see the current state. States: - PUBLIC: Visible on storefront - HIDDEN: Not visible on storefront but still exists - ARCHIVED: Soft deleted — will not appear in normal queries Optionally update time-based availability (availableFrom/availableTo) to schedule when the collection becomes visible. When setting a time frame without explicitly specifying the state, the state is automatically determined: - PUBLIC if the current time is within the time frame - HIDDEN otherwise Returns the updated collection with: - Identity: id (CollectionId), shopId (ShopId), name, slug, description - Visibility: available (boolean), state (PUBLIC/HIDDEN/ARCHIVED) - Time-based availability: availableFrom (nullable ISO 8601), availableTo (nullable ISO 8601) - Products: offerIds (list of OfferIds) - Sorting: sortingStrategy (MANUAL/BEST_SELLING/NEWEST/OLDEST/NAME_ASC/NAME_DESC) WARNING: Setting state to ARCHIVED removes the collection from the storefront. Use with caution.
ecommerce_update-collection-state
ChatGPTUpdate a collection's visibility state (PUBLIC, HIDDEN, or ARCHIVED). Use get-collections-by-ids first to see the current state. States: - PUBLIC: Visible on storefront - HIDDEN: Not visible on storefront but still exists - ARCHIVED: Soft deleted — will not appear in normal queries Optionally update time-based availability (availableFrom/availableTo) to schedule when the collection becomes visible. When setting a time frame without explicitly specifying the state, the state is automatically determined: - PUBLIC if the current time is within the time frame - HIDDEN otherwise Returns the updated collection with: - Identity: id (CollectionId), shopId (ShopId), name, slug, description - Visibility: available (boolean), state (PUBLIC/HIDDEN/ARCHIVED) - Time-based availability: availableFrom (nullable ISO 8601), availableTo (nullable ISO 8601) - Products: offerIds (list of OfferIds) - Sorting: sortingStrategy (MANUAL/BEST_SELLING/NEWEST/OLDEST/NAME_ASC/NAME_DESC) WARNING: Setting state to ARCHIVED removes the collection from the storefront. Use with caution.
ecommerce_update-combined-listing
ChatGPTUpdate an existing combined listing. Only provided fields are updated — omitted fields remain unchanged. IMPORTANT: When updating offerIds, pass the FULL list — it replaces the entire set. All offers must share the same product library with unique colors.
ecommerce_update-combined-listing
ChatGPTUpdate an existing combined listing. Only provided fields are updated — omitted fields remain unchanged. IMPORTANT: When updating offerIds, pass the FULL list — it replaces the entire set. All offers must share the same product library with unique colors.
ecommerce_update-offer
ChatGPTUpdate an existing shop offer (product). Only provided fields are updated — omitted fields remain unchanged. IMPORTANT: Always fetch the current offer first with get-offers-by-ids to confirm the offer exists and review current values before updating.
ecommerce_update-offer
ChatGPTUpdate an existing shop offer (product). Only provided fields are updated — omitted fields remain unchanged. IMPORTANT: Always fetch the current offer first with get-offers-by-ids to confirm the offer exists and review current values before updating.
ecommerce_update-offer-slug
ChatGPTChange the URL slug for an offer (product). The slug appears in the storefront URL (e.g., /products/{slug}). Use get-offers-by-ids first to see the current slug. Slug rules: - Lowercase letters, numbers, and hyphens only - No spaces or special characters - Must be unique within the shop (non-archived offers)
ecommerce_update-offer-slug
ChatGPTChange the URL slug for an offer (product). The slug appears in the storefront URL (e.g., /products/{slug}). Use get-offers-by-ids first to see the current slug. Slug rules: - Lowercase letters, numbers, and hyphens only - No spaces or special characters - Must be unique within the shop (non-archived offers)
ecommerce_update-offer-status
ChatGPTChange an offer's visibility status and/or sold-out flag. At least one of status or available must be provided. Status options: - PUBLIC: Visible on storefront, purchasable (if available=true) - HIDDEN: Not visible on storefront but still exists, can be made public later - ARCHIVED: Soft delete — removes from storefront, no longer purchasable. Will fail if the offer is part of a bundle or combined offer. Sold-out toggle (available): - true: Mark as in stock (available for purchase) - false: Mark as sold out (not purchasable even if PUBLIC) - Not applicable when status=ARCHIVED (archived offers are always unavailable) IMPORTANT: Always fetch the current offer first with get-offers-by-ids to check current status and availability before changing.
ecommerce_update-offer-status
ChatGPTChange an offer's visibility status and/or sold-out flag. At least one of status or available must be provided. Status options: - PUBLIC: Visible on storefront, purchasable (if available=true) - HIDDEN: Not visible on storefront but still exists, can be made public later - ARCHIVED: Soft delete — removes from storefront, no longer purchasable. Will fail if the offer is part of a bundle or combined offer. Sold-out toggle (available): - true: Mark as in stock (available for purchase) - false: Mark as sold out (not purchasable even if PUBLIC) - Not applicable when status=ARCHIVED (archived offers are always unavailable) IMPORTANT: Always fetch the current offer first with get-offers-by-ids to check current status and availability before changing.
ecommerce_update-offer-variant
ChatGPTUpdate a specific offer variant's price, compare-at price, weight, or SKU. IMPORTANT: Always fetch the current offer first with get-offers-by-ids to review variant IDs and current values before updating.
ecommerce_update-offer-variant
ChatGPTUpdate a specific offer variant's price, compare-at price, weight, or SKU. IMPORTANT: Always fetch the current offer first with get-offers-by-ids to review variant IDs and current values before updating.
ecommerce_update-promotion
ChatGPTUpdate an existing promotion's settings. Set category to SHOP or MEMBERSHIP and provide only the fields to change — omitted fields remain unchanged. All monetary amounts are set in USD dollars (NOT cents) — shops price in USD; checkout handles per-customer currency conversion automatically. FOR SHOP (category=SHOP): • Limits: maxUses + onePerCustomer (updated as a group — provide both) • Requirements: minimumOrderAmount in USD dollars (set 0 to remove), allowedCountries (ISO codes or [] for all) • Scope: productIds (specific offers) or applyToEntireOrder=true • Cannot change discount type/amount — create a new promotion instead FOR MEMBERSHIP (category=MEMBERSHIP): • Discount: percentage (1-100) • Scope: subscriptionType + tierIds (empty list [] = all tiers, specific IDs = selected tiers) • Duration: durationCharges (0 = lifetime, 1-1000 = limited billing cycles) • Requirements: newMembersOnly • Limits: limitToSingleUse Always use get-promotions-by-ids first to check current values before updating.
ecommerce_update-promotion
ChatGPTUpdate an existing promotion's settings. Set category to SHOP or MEMBERSHIP and provide only the fields to change — omitted fields remain unchanged. All monetary amounts are set in USD dollars (NOT cents) — shops price in USD; checkout handles per-customer currency conversion automatically. FOR SHOP (category=SHOP): • Limits: maxUses + onePerCustomer (updated as a group — provide both) • Requirements: minimumOrderAmount in USD dollars (set 0 to remove), allowedCountries (ISO codes or [] for all) • Scope: productIds (specific offers) or applyToEntireOrder=true • Cannot change discount type/amount — create a new promotion instead FOR MEMBERSHIP (category=MEMBERSHIP): • Discount: percentage (1-100) • Scope: subscriptionType + tierIds (empty list [] = all tiers, specific IDs = selected tiers) • Duration: durationCharges (0 = lifetime, 1-1000 = limited billing cycles) • Requirements: newMembersOnly • Limits: limitToSingleUse Always use get-promotions-by-ids first to check current values before updating.
ecommerce_update-shop-post-onboarding
ChatGPTUpdates the current shop's creator name (also used as the site name) and/or internal domain slug. Shops created via MCP (App) onboarding get a randomly generated creator name and internal domain — use this tool right after such a shop is created to set the real values the creator wants. Ask the creator for their preferred names before calling, since these are user-visible and changing the internal domain changes the shop's URL. Both parameters are optional, but at least one must be provided. Fields not provided remain unchanged. Parameters: - creatorName: New creator name (max 100 chars). The site (shop) name is set to the same value. - internalDomainSlug: New subdomain slug. Lowercase letters, numbers, and "-" only. Unless it already ends with "-shop", the "-shop" suffix is appended automatically (e.g. slug "acme" results in internal domain "acme-shop.fourthwall.com"). Fails if the slug is already taken by another shop. Returns the updated shop with the same shape as get-current-shop.
ecommerce_update-shop-post-onboarding
ChatGPTUpdates the current shop's creator name (also used as the site name) and/or internal domain slug. Shops created via MCP (App) onboarding get a randomly generated creator name and internal domain — use this tool right after such a shop is created to set the real values the creator wants. Ask the creator for their preferred names before calling, since these are user-visible and changing the internal domain changes the shop's URL. Both parameters are optional, but at least one must be provided. Fields not provided remain unchanged. Parameters: - creatorName: New creator name (max 100 chars). The site (shop) name is set to the same value. - internalDomainSlug: New subdomain slug. Lowercase letters, numbers, and "-" only. Unless it already ends with "-shop", the "-shop" suffix is appended automatically (e.g. slug "acme" results in internal domain "acme-shop.fourthwall.com"). Fails if the slug is already taken by another shop. Returns the updated shop with the same shape as get-current-shop.
ecommerce_update-shop-site-status
ChatGPTChanges the current shop's site visibility: - LIVE: published, publicly accessible - COMING_SOON: unpublished, placeholder page shown to visitors - PASSWORD_PROTECTED: visitors must enter the provided password to view the site Use this when a creator asks to publish/unpublish their site, take it live, set it to private/coming soon, hide it from visitors, or gate access behind a password. Confirm with the creator before calling — this is a user-visible state change. For PASSWORD_PROTECTED the password parameter is required; otherwise it is ignored. Returns the updated shop with the same shape as get-current-shop.
ecommerce_update-shop-site-status
ChatGPTChanges the current shop's site visibility: - LIVE: published, publicly accessible - COMING_SOON: unpublished, placeholder page shown to visitors - PASSWORD_PROTECTED: visitors must enter the provided password to view the site Use this when a creator asks to publish/unpublish their site, take it live, set it to private/coming soon, hide it from visitors, or gate access behind a password. Confirm with the creator before calling — this is a user-visible state change. For PASSWORD_PROTECTED the password parameter is required; otherwise it is ignored. Returns the updated shop with the same shape as get-current-shop.
ecommerce_validate-combined-listing
ChatGPTCheck if offers can be combined into a combined listing before creating one. All offers must share the same product library and have unique color variants. Returns canCombine (boolean) and per-offer eligibility with issues: - DIFFERENT_LIBRARY: offer has a different product library - DUPLICATE_COLOR: color variant conflicts with another offer - MISSING_PRODUCT: offer has no product assigned - ALREADY_SELECTED: candidate is already in the selected list
ecommerce_validate-combined-listing
ChatGPTCheck if offers can be combined into a combined listing before creating one. All offers must share the same product library and have unique color variants. Returns canCombine (boolean) and per-offer eligibility with issues: - DIFFERENT_LIBRARY: offer has a different product library - DUPLICATE_COLOR: color variant conflicts with another offer - MISSING_PRODUCT: offer has no product assigned - ALREADY_SELECTED: candidate is already in the selected list
ecommerce_validate-dns-entries
ChatGPTTriggers a fresh DNS validation by checking all configured records against live DNS and updates their verification status. Unlike get-dns-entries (which returns cached status), this tool performs real-time DNS lookups. Returns the same structure as get-dns-entries: - Domain: domainId, domain (e.g. "myshop.com") - Status: status (CONNECTED, NOT_CONNECTED, PARTIALLY_CONNECTED, SYNCING_YOUR_DOMAIN, REMOVAL_IN_PROGRESS) - Flags: areAllEntriesComplete (boolean), isSslSynced (boolean), retryAllowed (boolean) - Provider: dnsProvider (nullable String), dnsProviderMode (MANUAL/AUTOMATIC, nullable) - Nameservers: nameservers (list of hostname strings) - Per record in records: - recordType (CNAME, TXT, MX, A) - host (nullable), value (nullable) - status (VALID, INVALID, UNKNOWN) — freshly validated - validationError (nullable String — e.g. "RECORD_NOT_FOUND", "INCORRECT_TYPE_OR_VALUE (found: ...)") - alias (record purpose, e.g. SHOP_IP_ADDRESS, SHOP_WWW_REDIRECT, DMARC) - priority (nullable Int, for MX records) Use this tool when: - User reports their domain is not working after configuring DNS records - Need to refresh validation status (e.g. status was NOT_CONNECTED, user says they fixed it) - Troubleshooting specific record failures — check validationError for details - After user makes changes at their domain registrar and wants to verify - retryAllowed from get-dns-entries is true (status is NOT_CONNECTED or PARTIALLY_CONNECTED)
ecommerce_validate-dns-entries
ChatGPTTriggers a fresh DNS validation by checking all configured records against live DNS and updates their verification status. Unlike get-dns-entries (which returns cached status), this tool performs real-time DNS lookups. Returns the same structure as get-dns-entries: - Domain: domainId, domain (e.g. "myshop.com") - Status: status (CONNECTED, NOT_CONNECTED, PARTIALLY_CONNECTED, SYNCING_YOUR_DOMAIN, REMOVAL_IN_PROGRESS) - Flags: areAllEntriesComplete (boolean), isSslSynced (boolean), retryAllowed (boolean) - Provider: dnsProvider (nullable String), dnsProviderMode (MANUAL/AUTOMATIC, nullable) - Nameservers: nameservers (list of hostname strings) - Per record in records: - recordType (CNAME, TXT, MX, A) - host (nullable), value (nullable) - status (VALID, INVALID, UNKNOWN) — freshly validated - validationError (nullable String — e.g. "RECORD_NOT_FOUND", "INCORRECT_TYPE_OR_VALUE (found: ...)") - alias (record purpose, e.g. SHOP_IP_ADDRESS, SHOP_WWW_REDIRECT, DMARC) - priority (nullable Int, for MX records) Use this tool when: - User reports their domain is not working after configuring DNS records - Need to refresh validation status (e.g. status was NOT_CONNECTED, user says they fixed it) - Troubleshooting specific record failures — check validationError for details - After user makes changes at their domain registrar and wants to verify - retryAllowed from get-dns-entries is true (status is NOT_CONNECTED or PARTIALLY_CONNECTED)
import-chatgpt-image
ChatGPTImport an image the user attached directly to ChatGPT into Fourthwall, then return its durable Fourthwall URL plus a vision analysis of it. Use this whenever the user says to use an attached/uploaded ChatGPT image for a Fourthwall workflow. The input must be the ChatGPT file reference supplied by the host. Do not invent file URLs or use local paths. After this tool returns, use url exactly like an uploaded image and analysis for its described contents. Parameters: - image: ChatGPT-provided file reference. ChatGPT fills this from the user's attached image because this tool declares it as a file param.
import-chatgpt-image
ChatGPTImport an image the user attached directly to ChatGPT into Fourthwall, then return its durable Fourthwall URL plus a vision analysis of it. Use this whenever the user says to use an attached/uploaded ChatGPT image for a Fourthwall workflow. The input must be the ChatGPT file reference supplied by the host. Do not invent file URLs or use local paths. After this tool returns, use url exactly like an uploaded image and analysis for its described contents. Parameters: - image: ChatGPT-provided file reference. ChatGPT fills this from the user's attached image because this tool declares it as a file param.
load-skills
ChatGPTDynamically load the Fourthwall skills most relevant to a user prompt — analogous to how Claude Code loads skills based on intent. Ranks the skill catalog by semantic similarity to the prompt and returns the vetted skills that clear a relevance threshold — so a prompt that is unrelated, or whose intent belongs to a part of Fourthwall no returned skill covers, yields an empty list rather than irrelevant skills. Call this at the start of a session (and again whenever the user's intent shifts) before invoking any other Fourthwall tool, so the matching skill's instructions are in context. Parameters: - prompt: The user's intent as a short phrase, in their own words or a concise imperative (e.g. "add a product to my shop", "where is my order", "change my theme colors"). Pass only the intent itself: do NOT wrap it as "user wants to ..." and do NOT append the platform name ("Fourthwall"). The match is semantic, so that filler dilutes the signal and skews results toward unrelated skills — e.g. "user wants to design ..." drifts toward the storefront designer.
load-skills
ChatGPTDynamically load the Fourthwall skills most relevant to a user prompt — analogous to how Claude Code loads skills based on intent. Ranks the skill catalog by semantic similarity to the prompt and returns the vetted skills that clear a relevance threshold — so a prompt that is unrelated, or whose intent belongs to a part of Fourthwall no returned skill covers, yields an empty list rather than irrelevant skills. Call this at the start of a session (and again whenever the user's intent shifts) before invoking any other Fourthwall tool, so the matching skill's instructions are in context. Parameters: - prompt: The user's intent as a short phrase, in their own words or a concise imperative (e.g. "add a product to my shop", "where is my order", "change my theme colors"). Pass only the intent itself: do NOT wrap it as "user wants to ..." and do NOT append the platform name ("Fourthwall"). The match is semantic, so that filler dilutes the signal and skews results toward unrelated skills — e.g. "user wants to design ..." drifts toward the storefront designer.
media-library
ChatGPTOpen the media library for the user to browse, upload, and select an image. Renders a selectable image carousel plus an upload tile; a newly uploaded image joins the carousel preselected. When the user confirms an image with "Use selected image", its hosted URL arrives in their next message as a markdown link ("Selected [image](url)") — act on that URL. Parameters: - prompt: Instruction text shown in the media library UI (e.g. "Select artwork for your product"). - title: Optional heading displayed above the library.
media-library
ChatGPTOpen the media library for the user to browse, upload, and select an image. Renders a selectable image carousel plus an upload tile; a newly uploaded image joins the carousel preselected. When the user confirms an image with "Use selected image", its hosted URL arrives in their next message as a markdown link ("Selected [image](url)") — act on that URL. Parameters: - prompt: Instruction text shown in the media library UI (e.g. "Select artwork for your product"). - title: Optional heading displayed above the library.
navigate
ChatGPTNavigate the user to a specific page in the Fourthwall admin dashboard. The url must be an exact path from omni_knowledge results (modules or help docs) - never construct or guess paths. Do not tell users you are "searching" or "looking up" the path. Parameters: - url: Exact admin dashboard path from omni_knowledge results (e.g. "/admin/dashboard/promotions/promotion-codes/create/"), optionally with query parameters for filtering (e.g. "/admin/products/all/?badges=BESTSELLER"). Or a full URL returned by an MCP tool (e.g. checkout link), or a Fourthwall help-docs URL returned by omni_knowledge. Never guess or construct paths. - description: Button label shown to the user, 2-4 words, under 40 characters (e.g. "Create Promotion", "View Orders").
navigate
ChatGPTNavigate the user to a specific page in the Fourthwall admin dashboard. The url must be an exact path from omni_knowledge results (modules or help docs) - never construct or guess paths. Do not tell users you are "searching" or "looking up" the path. Parameters: - url: Exact admin dashboard path from omni_knowledge results (e.g. "/admin/dashboard/promotions/promotion-codes/create/"), optionally with query parameters for filtering (e.g. "/admin/products/all/?badges=BESTSELLER"). Or a full URL returned by an MCP tool (e.g. checkout link), or a Fourthwall help-docs URL returned by omni_knowledge. Never guess or construct paths. - description: Button label shown to the user, 2-4 words, under 40 characters (e.g. "Create Promotion", "View Orders").
omni_escalate
ChatGPTTransfer the conversation to human support via Slack. Call this when the user explicitly asks to speak with a person, asks for human help, or requests escalation. Do not call proactively — offer escalation first and wait for the user to confirm. Parameters: - reason: Short description of what the user needs help with, in their own words when possible. - context: A concise summary of the conversation that led here, written by you (the assistant). Include the user's questions, relevant tool results, and what has already been tried. Returns: - A dict with action ("escalate_success" or "escalate_error") and customerEmail (the customer's email from the access token, or empty string if unavailable).
omni_escalate
ChatGPTTransfer the conversation to human support via Slack. Call this when the user explicitly asks to speak with a person, asks for human help, or requests escalation. Do not call proactively — offer escalation first and wait for the user to confirm. Parameters: - reason: Short description of what the user needs help with, in their own words when possible. - context: A concise summary of the conversation that led here, written by you (the assistant). Include the user's questions, relevant tool results, and what has already been tried. Returns: - A dict with action ("escalate_success" or "escalate_error") and customerEmail (the customer's email from the access token, or empty string if unavailable).
omni_knowledge
ChatGPTSearch Fourthwall's knowledge base for help documentation, how-to guides, and tips. Use this to answer questions about how the Fourthwall platform works. Parameters: - query: Search term — a question or topic about Fourthwall (1-256 characters). Returns: - Matching knowledge grouped by type: admin modules (dashboard pages with their exact navigation paths), snippets (tips and Q&A), and help docs (official documentation). Pass a module's path verbatim to the navigate tool — never construct paths. When to use this tool: - The user asks how to do something on Fourthwall (e.g. "how do I create a promotion?", "how does shipping work?") - The user needs guidance on platform features, product design, store setup, or best practices - You need context about Fourthwall concepts before using other tools When NOT to use this tool: - The user wants to search their own shop data (use the "omni_search" tool or a dedicated ecommerce_* tool instead) - The user wants to perform an action like creating or updating resources Examples: - query="how to create a promotion" - query="product designer walkthrough" - query="shipping flat rates setup"
omni_knowledge
ChatGPTSearch Fourthwall's knowledge base for help documentation, how-to guides, and tips. Use this to answer questions about how the Fourthwall platform works. Parameters: - query: Search term — a question or topic about Fourthwall (1-256 characters). Returns: - Matching knowledge grouped by type: admin modules (dashboard pages with their exact navigation paths), snippets (tips and Q&A), and help docs (official documentation). Pass a module's path verbatim to the navigate tool — never construct paths. When to use this tool: - The user asks how to do something on Fourthwall (e.g. "how do I create a promotion?", "how does shipping work?") - The user needs guidance on platform features, product design, store setup, or best practices - You need context about Fourthwall concepts before using other tools When NOT to use this tool: - The user wants to search their own shop data (use the "omni_search" tool or a dedicated ecommerce_* tool instead) - The user wants to perform an action like creating or updating resources Examples: - query="how to create a promotion" - query="product designer walkthrough" - query="shipping flat rates setup"
omni_search
ChatGPTSearch for entities across the shop when no dedicated MCP tool exists for the specific search you need. Returns matching entity IDs that you can then look up with the appropriate detail tool. Parameters: - query: Search term — can be a name, email, code, ID, or keyword (1-256 characters). - source: Optional entity type to narrow the search. One of: "orders", "offers", "promotions", "collections". Omit to search all sources at once. Returns: - Matching entity IDs grouped by source, e.g.: promotions: prm_abc123, prm_def456 orders: ord_xyz789 Follow-up: After getting IDs from this tool, find the dedicated ecommerce_ tool that can fetch full details by ID. When to use this tool: - Always prefer a dedicated ecommerce_ tool if one exists for the search you need (e.g. ecommerce_list-offers for offers by name). - Use THIS tool when no dedicated tool covers the search, for example: • Find a promotion by promo code (e.g. query="SUMMER20") • Find a collection by name • Find an order by customer email or friendly ID • Broad search across multiple entity types at once Examples: - Search promotion by code: query="SUMMER20", source="promotions" - Search collection by name: query="holiday", source="collections" - Search everything: query="holiday"
omni_search
ChatGPTSearch for entities across the shop when no dedicated MCP tool exists for the specific search you need. Returns matching entity IDs that you can then look up with the appropriate detail tool. Parameters: - query: Search term — can be a name, email, code, ID, or keyword (1-256 characters). - source: Optional entity type to narrow the search. One of: "orders", "offers", "promotions", "collections". Omit to search all sources at once. Returns: - Matching entity IDs grouped by source, e.g.: promotions: prm_abc123, prm_def456 orders: ord_xyz789 Follow-up: After getting IDs from this tool, find the dedicated ecommerce_ tool that can fetch full details by ID. When to use this tool: - Always prefer a dedicated ecommerce_ tool if one exists for the search you need (e.g. ecommerce_list-offers for offers by name). - Use THIS tool when no dedicated tool covers the search, for example: • Find a promotion by promo code (e.g. query="SUMMER20") • Find a collection by name • Find an order by customer email or friendly ID • Broad search across multiple entity types at once Examples: - Search promotion by code: query="SUMMER20", source="promotions" - Search collection by name: query="holiday", source="collections" - Search everything: query="holiday"
read-skills
ChatGPTLoad named Fourthwall skills and return their full instructions. Use this to follow cross-references between skills; to discover skills by intent, use load-skills instead. MUST be called when a skill loaded via load-skills names another skill to load, use, hand off to, or that it requires — in its description or content (e.g. product-designer requires product-catalog; shop-onboarding loads storefronts-designer then product-designer). Load every referenced skill before acting on its instructions. Parameters: - names: Exact skill names, e.g. ["product-catalog", "storefronts-designer"]. Unknown or unavailable names are ignored.
read-skills
ChatGPTLoad named Fourthwall skills and return their full instructions. Use this to follow cross-references between skills; to discover skills by intent, use load-skills instead. MUST be called when a skill loaded via load-skills names another skill to load, use, hand off to, or that it requires — in its description or content (e.g. product-designer requires product-catalog; shop-onboarding loads storefronts-designer then product-designer). Load every referenced skill before acting on its instructions. Parameters: - names: Exact skill names, e.g. ["product-catalog", "storefronts-designer"]. Unknown or unavailable names are ignored.
request-upload-url
ChatGPTInternal helper for the show-upload widget. Request a signed URL to upload an image straight to storage. Not a user-facing action — do not call it in response to a chat request. The widget PUTs the file bytes to the returned signedUrl, then calls confirm-image-upload. Parameters: - filename: Original file name including extension (e.g. "logo.png"). - contentType: The file's MIME type — JPEG, PNG, GIF, or WebP (e.g. "image/png").
request-upload-url
ChatGPTInternal helper for the show-upload widget. Request a signed URL to upload an image straight to storage. Not a user-facing action — do not call it in response to a chat request. The widget PUTs the file bytes to the returned signedUrl, then calls confirm-image-upload. Parameters: - filename: Original file name including extension (e.g. "logo.png"). - contentType: The file's MIME type — JPEG, PNG, GIF, or WebP (e.g. "image/png").
show-card
ChatGPTDisplay a single key-value detail card (payout summary, shop info, configuration). Pass entries as a list of {label, value} pairs. Use data from MCP tool results. For admin links use the separate navigate tool — this card is read-only and renders no link button. Parameters: - title: Heading shown at the top of the card. - entries: Key-value entries (e.g. [{label: "Status", value: "Active"}]). - icon: Icon for the card header.
show-card
ChatGPTDisplay a single key-value detail card (payout summary, shop info, configuration). Pass entries as a list of {label, value} pairs. Use data from MCP tool results. For admin links use the separate navigate tool — this card is read-only and renders no link button. Parameters: - title: Heading shown at the top of the card. - entries: Key-value entries (e.g. [{label: "Status", value: "Active"}]). - icon: Icon for the card header.
show-entity
ChatGPTDisplay shop entities (orders, offers/products, promotions, collections, memberships, supporters, catalog products, gift cards, giveaway packages) as an interactive card list in the conversation. Use this whenever the user asks to get, show, list, display, view, or find entities — rendering the cards IS the answer. Call it as your first action; do not reply with a plain-text list and do not wait to be asked to "show it in the UI." Pass source + ids — the server resolves full item data. Always use IDs from MCP tool results. Parameters: - title: Optional heading displayed above the cards. - source: Entity source: "orders", "offers", "promotions", "memberships_supporters", "membership_posts", "collections", "catalog_products", "gift_cards", "giveaway_packages", "blanks". - ids: Exact "id" field values copied from MCP tool results. Do NOT use slugs, names, or fabricated identifiers. - variant: Card style. Omit for compact cards. Other values are reserved for specific skill workflows — set it only when a skill tells you to. - buttonLabel: Button text, used only by certain skill workflows.
show-entity
ChatGPTDisplay shop entities (orders, offers/products, promotions, collections, memberships, supporters, catalog products, gift cards, giveaway packages) as an interactive card list in the conversation. Use this whenever the user asks to get, show, list, display, view, or find entities — rendering the cards IS the answer. Call it as your first action; do not reply with a plain-text list and do not wait to be asked to "show it in the UI." Pass source + ids — the server resolves full item data. Always use IDs from MCP tool results. Parameters: - title: Optional heading displayed above the cards. - source: Entity source: "orders", "offers", "promotions", "memberships_supporters", "membership_posts", "collections", "catalog_products", "gift_cards", "giveaway_packages", "blanks". - ids: Exact "id" field values copied from MCP tool results. Do NOT use slugs, names, or fabricated identifiers. - variant: Card style. Omit for compact cards. Other values are reserved for specific skill workflows — set it only when a skill tells you to. - buttonLabel: Button text, used only by certain skill workflows.
show-gallery
ChatGPTDisplay a read-only grid of images inline. Pass image URLs from MCP tool results — do not fabricate URLs. Clicking a thumbnail opens the full-size image. Parameters: - title: Optional heading displayed above the gallery. - images: Images to display in the grid.
show-gallery
ChatGPTDisplay a read-only grid of images inline. Pass image URLs from MCP tool results — do not fabricate URLs. Clicking a thumbnail opens the full-size image. Parameters: - title: Optional heading displayed above the gallery. - images: Images to display in the grid.
show-table
ChatGPTDisplay tabular data inline. Pass columns (key + label) and rows keyed by column keys. Use for analytics, reports, or any structured comparison data from MCP tool results. Parameters: - title: Optional heading displayed above the table. - columns: Column definitions as an array of {key, label} objects, e.g. [{"key":"stage","label":"Funnel Stage"},{"key":"count","label":"Count"}]. Pass the array directly — do not JSON.stringify. - rows: Row data as an array of objects keyed by the column keys, e.g. [{"stage":"Total Sessions","count":"3,539"},{"stage":"Carts Created","count":"285"}]. Pass the array directly — do not JSON.stringify.
show-table
ChatGPTDisplay tabular data inline. Pass columns (key + label) and rows keyed by column keys. Use for analytics, reports, or any structured comparison data from MCP tool results. Parameters: - title: Optional heading displayed above the table. - columns: Column definitions as an array of {key, label} objects, e.g. [{"key":"stage","label":"Funnel Stage"},{"key":"count","label":"Count"}]. Pass the array directly — do not JSON.stringify. - rows: Row data as an array of objects keyed by the column keys, e.g. [{"stage":"Total Sessions","count":"3,539"},{"stage":"Carts Created","count":"285"}]. Pass the array directly — do not JSON.stringify.
show-upload
ChatGPTDisplay a drag-and-drop image upload area inline. Use when the user needs to provide an image. The picked image is uploaded and analyzed, and a description of its contents arrives in the user's next message ("Uploaded an image: …") — act on that description directly. Parameters: - title: Optional heading displayed above the upload area. - prompt: Custom prompt text shown inside the drop zone. Default: "Drop image or browse".
show-upload
ChatGPTDisplay a drag-and-drop image upload area inline. Use when the user needs to provide an image. The picked image is uploaded and analyzed, and a description of its contents arrives in the user's next message ("Uploaded an image: …") — act on that description directly. Parameters: - title: Optional heading displayed above the upload area. - prompt: Custom prompt text shown inside the drop zone. Default: "Drop image or browse".
