# Products & checkout (/docs/mcp/tool-reference/products-and-checkout)

13 tools. Generated from the Swop MCP server’s own `tools/list` (server version 0.2.2), so names, inputs and limits match what your client sees.

## `swop_create_product` [#swop_create_product]

**Create a product** · Sign-in: `commerce.write` · `/mcp` and `/mcp/commerce`

Start selling something in one call: creates a product that people can buy on the linked account's Swop SmartSite and AI agents can buy in USDC over x402, with no store setup, payment processor, or verification needed. To change an existing product use swop_update_product instead. name, description and image are all REQUIRED by the backend. Confirm name and price with the user before creating. Then call swop_feature_product to show it on the SmartSite and swop_get_product_link to share it.

| Input | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Product name (min length 1; max length 120) |
| `description` | `string` | Yes | Product description (required) (min length 1; max length 2000) |
| `priceUsd` | `number` | Yes | Price in USD (settles in USDC) (&gt; 0) |
| `image` | `string` | Yes | Primary product image URL (required) (format `uri`) |
| `extraImages` | array of `string` | No | Additional image URLs, shown after the primary one (max items 9) |
| `productType` | `"physical"` \| `"digital"` \| `"in_person_checkout"` | No | physical (ships), digital (default), or in_person_checkout |
| `nftType` | `"phygital"` \| `"menu"` \| `"collectible"` \| `"subscription"` \| `"membership"` \| `"coupon"` | No | Fine-grained type; overrides productType. phygital/menu are physical, the rest digital |
| `mintLimit` | `integer` | No | Inventory available, default 1 (&gt; 0) |
| `keywords` | array of `string` | No | Search keywords (max items 20) |
| `variants` | array of object (`name`, `options`) | No | Buyer-selectable options. Replaces the existing set when given. |
| `requiresShipping` | `boolean` | No | Physical goods: collect a shipping address |
| `shippingCost` | `number` | No | Flat shipping cost in USD (min 0) |
| `digitalDeliveryNote` | `string` | No | Digital goods: what the buyer receives after purchase (max length 500) |
| `royaltyPercentage` | `number` | No | Resale royalty percent (min 0; max 100) |
| `royaltyRecipient` | `string` | No | Wallet receiving royalties |

## `swop_update_product` [#swop_update_product]

**Update or unlist a product** · Sign-in: `commerce.write` · `/mcp` and `/mcp/commerce` · Changes or moves things

Edit one of the linked account's products, or unlist it. Pass its productId (from swop_list_my_products) plus ONLY the fields to change — anything omitted keeps its current value. To unlist it, set status to 'archived'. Confirm price and name changes with the user first.

| Input | Type | Required | Description |
|---|---|---|---|
| `productId` | `string` | Yes | The product id from swop_list_my_products |
| `name` | `string` | No | New product name (max length 120) |
| `description` | `string` | No | New description (max length 2000) |
| `priceUsd` | `number` | No | New price in USD (settles in USDC) (&gt; 0) |
| `image` | `string` | No | New primary image URL (format `uri`) |
| `extraImages` | array of `string` | No | Replaces the additional images. Requires image, since the full list is rewritten (max items 9) |
| `mintLimit` | `integer` | No | New inventory available (&gt; 0) |
| `keywords` | array of `string` | No | Replaces the keywords (max items 20) |
| `variants` | array of object (`name`, `options`) | No | Buyer-selectable options. Replaces the existing set when given. |
| `requiresShipping` | `boolean` | No | Collect a shipping address |
| `shippingCost` | `number` | No | Flat shipping cost in USD (min 0) |
| `digitalDeliveryNote` | `string` | No | What a buyer receives (max length 500) |
| `royaltyPercentage` | `number` | No | Resale royalty percent (min 0; max 100) |
| `royaltyRecipient` | `string` | No | Wallet receiving royalties |
| `status` | `"active"` \| `"archived"` | No | Set 'archived' to unlist |

## `swop_list_my_products` [#swop_list_my_products]

**List my products** · Sign-in: `commerce.write` · `/mcp` and `/mcp/commerce` · Read-only

List the linked account's OWN products (each with its id, name, price, inventory, and status); to browse another seller's products use swop_get_store. Use the id with swop_update_product (to edit or unlist) or swop_feature_product (to show it on the SmartSite).

_No inputs._

## `swop_feature_product` [#swop_feature_product]

**Feature a product on my SmartSite** · Sign-in: `commerce.write` · `/mcp` and `/mcp/commerce`

Show an existing product on the linked account's SmartSite as a tile visitors can buy from. Pass the templateId returned by swop_create_product (or the id from swop_list_my_products). Each call ADDS a new tile and never replaces existing ones, so check swop_get_my_smartsite first to avoid duplicates; remove a tile with swop_remove_link. The product must belong to the linked account.

| Input | Type | Required | Description |
|---|---|---|---|
| `templateId` | `string` | Yes | The product/template id from swop_create_product |
| `carouselTitle` | `string` | No | Optional heading for the product section (max length 80) |
| `smartsiteId` | `string` | No | Specific SmartSite id (default: primary) |

## `swop_create_checkout` [#swop_create_checkout]

**Create a checkout for a cart** · Sign-in: `commerce.write` · `/mcp` and `/mcp/commerce`

Take payment on the seller's own website: creates a checkout for a cart of the linked account's OWN products, so a buyer pays there instead of being sent to Swop. For a single shareable link use swop_get_product_link instead. Prices come from the seller's catalogue and must NOT be sent — a price in the request is rejected. Shipping is charged automatically for physical products, and for those the buyer's name, email and delivery address are REQUIRED (the call is refused otherwise, naming what is missing). Rails: USDC on Solana always; set offerCard when the seller is card-enabled and every item is a physical good — then the response has cardOffered: true and paymentRequest is null until the buyer picks a rail on the seller's page via the public URLs POST /api/v5/checkout-intents/\{intentId\}/card-payment-intents (Stripe client secret for a Payment Element) or POST .../select-crypto (publishes the Solana Pay request). Otherwise paymentRequest is returned at once (a solana: URL the buyer's wallet opens, also fine as a QR code). Settlement is automatic once the payment lands — nothing to confirm; poll swop_get_checkout for status. Show the buyer the products, quantities and total before creating.

| Input | Type | Required | Description |
|---|---|---|---|
| `items` | array of object (`productId`, `quantity`, `selectedOptions`) | Yes | The cart. Ids only — prices come from the catalogue (min items 1; max items 50) |
| `buyerName` | `string` | No | Buyer's name (required for physical items) (max length 120) |
| `buyerEmail` | `string` | No | Buyer's email, for the receipt (required for physical items) (format `email`) |
| `buyerPhone` | `string` | No | Buyer's phone, for the courier (max length 60) |
| `shippingAddress` | object (`line1`, `line2`, `city`, `state`, `postalCode`, `country`) | No | Delivery address. Required when any item is a physical product |
| `offerCard` | `boolean` | No | Offer card as well as USDC. Only takes effect when the seller is card-enabled and every item is physical; otherwise the checkout is USDC-only |
| `description` | `string` | No | What this checkout is for (max length 200) |

## `swop_get_checkout` [#swop_get_checkout]

**Check a checkout** · Sign-in: `commerce.write` · `/mcp` and `/mcp/commerce` · Read-only

Read back a checkout created with swop_create_checkout: its status (active, pending_payment, paid, settled, expired, cancelled), the payment request if one is published, and the line items. Poll this after the buyer has been shown the payment to learn when it lands — paid means the buyer's money arrived; settled means the seller has been paid out. Only the linked account's own checkouts are visible.

| Input | Type | Required | Description |
|---|---|---|---|
| `intentId` | `string` | Yes | The intentId returned by swop_create_checkout (pattern `^co_[A-Za-z0-9_-]\{4,40\}$`) |

## `swop_list_webhooks` [#swop_list_webhooks]

**List my webhooks** · Sign-in: `commerce.write` · `/mcp` and `/mcp/commerce` · Read-only

Show the webhook endpoints Swop notifies when the linked account gets paid, and the events available. Two events: checkout.paid (the buyer's money arrived and an order exists) and payout.released (Swop released the seller's money — for a card sale that can be days later). Use before adding or removing one.

_No inputs._

## `swop_register_webhook` [#swop_register_webhook]

**Add a webhook** · Sign-in: `commerce.write` · `/mcp` and `/mcp/commerce`

Get notified the moment the user gets paid. Register an https URL that Swop will POST a signed JSON event to when the linked account gets paid (checkout.paid) and paid out (payout.released). Returns a signing secret ONCE — tell the user to store it now; it cannot be retrieved again. Deliveries carry a Swop-Signature header: t=&lt;unix seconds&gt;,v1=&lt;hex HMAC-SHA256 of "&lt;t&gt;.&lt;raw body&gt;" with the secret&gt;; failed deliveries retry for about 15 hours. Confirm the exact URL with the user first.

| Input | Type | Required | Description |
|---|---|---|---|
| `url` | `string` | Yes | https URL to POST events to (http allowed for localhost only) (max length 2000; format `uri`) |
| `events` | array of `"checkout.paid"` \| `"payout.released"` | No | Which events to send. Default: both (min items 1) |
| `label` | `string` | No | A name for this endpoint (max length 80) |

## `swop_test_webhook` [#swop_test_webhook]

**Send a test event to a webhook** · Sign-in: `commerce.write` · `/mcp` and `/mcp/commerce`

POST a signed 'ping' event to one of the linked account's webhooks right now and report the HTTP status the endpoint returned. Use to confirm an integration before relying on it.

| Input | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | Webhook id from swop_list_webhooks |

## `swop_remove_webhook` [#swop_remove_webhook]

**Remove a webhook** · Sign-in: `commerce.write` · `/mcp` and `/mcp/commerce` · Changes or moves things

Stop sending events to one of the linked account's webhook URLs. Pending deliveries to it are dropped. Confirm with the user first.

| Input | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | Webhook id from swop_list_webhooks |

## `swop_list_embed_origins` [#swop_list_embed_origins]

**List sites allowed to frame my checkout** · Sign-in: `commerce.write` · `/mcp` and `/mcp/commerce` · Read-only

Show which websites may currently display the linked account's Swop checkout in a frame. Use before adding or removing one so the user can see what is already allowed.

_No inputs._

## `swop_register_embed_origin` [#swop_register_embed_origin]

**Allow a site to frame my checkout** · Sign-in: `commerce.write` · `/mcp` and `/mcp/commerce`

Allow ONE website to display the linked account's Swop checkout inside a frame. This is a security setting: only registered origins can ever frame the checkout, so a leaked API key still cannot put it on someone else's site. Give a bare origin — scheme and host only, https (http allowed for localhost), no wildcards, no path. Confirm the exact origin with the user first.

| Input | Type | Required | Description |
|---|---|---|---|
| `origin` | `string` | Yes | Bare origin, e.g. https://acme.com (min length 1) |
| `label` | `string` | No | A note to recognise it later (max length 80) |

## `swop_remove_embed_origin` [#swop_remove_embed_origin]

**Stop a site framing my checkout** · Sign-in: `commerce.write` · `/mcp` and `/mcp/commerce` · Changes or moves things

Remove a website from the list allowed to frame the linked account's checkout. Takes an id from swop_list_embed_origins. Afterwards that site can no longer display the checkout.

| Input | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | Yes | Origin id from swop_list_embed_origins (min length 1) |
