v1.2.0

OpenAPI 3.1.0

API Documentation

Introduction

Programmatic access to your Sellfy store from your own software. Endpoints are meant to be called from your server or application, and new ones are added regularly.

Authentication

Every request is authenticated with an API token — a secret tied to your Sellfy account, so a request only ever sees your own data.

To get a token:

In the Sellfy dashboard, open Store → Integrations → API keys.
Create a token and copy it right away — the full value is shown only once, on creation.
Send it with every request in the Authorization header:

Authorization: Bearer <your token>

Requests without a valid token are answered with 401 and a code of token_missing or token_invalid. A token can be deleted in the dashboard at any time to cut an integration off.

Server

https://api.sellfy.com

Client Libraries

Shell Curl

Ping

Verify that your integration can reach the API.

Ping Operations

get/ping/

Ping the API

Answers pong when the request is well-formed and the API token is valid — a harmless call to verify an integration's setup before going live.

Responses

application/json
application/json

get/ping/

curl https://api.sellfy.com/ping/ \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

Show Schema

{
  "message": "pong"
}

The token is valid and the API is reachable.

Licenses

Validate, activate and revoke license keys sold with Sellfy products. A key is located by its product_id and license_key pair within your account.

Licenses Operations

get/v1/licenses/validate/
post/v1/licenses/activations/
delete/v1/licenses/activations/{activation_id}/
post/v1/licenses/revoke/

Validate a license key

Looks up the current state of a license key. Read-only — validating never changes the key.

Query Parameters

product_id
Type: string
required

ID of the Sellfy product the license key belongs to. To find it, open Products → All products in your dashboard and pick Copy product ID from the options menu (⋯) of the product row. Alternatively, open the product for editing and copy the ID from the address bar: it is the last part of the URL
license_key
Type: string
min length:
1
required

The license key string.

Responses

application/json
application/json
application/json
application/json
application/json

get/v1/licenses/validate/

curl 'https://api.sellfy.com/v1/licenses/validate/?product_id=&license_key=' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

Show Schema

{
  "valid": true,
  "status": "string",
  "activations": [
    {
      "id": "string",
      "activated_at": "string",
      "meta": {}
    }
  ]
}

Current state of the license key.

Activate a license key

Records an activation on the key and returns just that activation. Store its id — deactivating later is DELETE /v1/licenses/activations/{activation_id}/.

Body·LicenseActivateInput

required

license_key
Type: string
min length:
1
required

The license key string.
product_id
Type: string
required

ID of the Sellfy product the license key belongs to. To find it, open Products → All products in your dashboard and pick Copy product ID from the options menu (⋯) of the product row. Alternatively, open the product for editing and copy the ID from the address bar: it is the last part of the URL
meta
Type: Meta

Free-form data describing the activation (e.g. device id, site url). Stored as-is and returned with the activation.

Responses

application/json
application/json
application/json
application/json
application/json
application/json

post/v1/licenses/activations/

curl https://api.sellfy.com/v1/licenses/activations/ \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "product_id": "",
  "license_key": "",
  "meta": {}
}'

Show Schema

{
  "id": "string",
  "activated_at": "string",
  "meta": {}
}

A single activation recorded on the license key.

Deactivate a license key activation

Releases an activation recorded earlier, e.g. when the buyer moves the license to another device, and returns the key's remaining state. The activation id alone addresses it — activation ids are unique within your account.

Path Parameters

activation_id
Type: string
required

Id of the activation to release, as returned when activating.

Responses

application/json
application/json
application/json

delete/v1/licenses/activations/{activation_id}/

curl 'https://api.sellfy.com/v1/licenses/activations/{activation_id}/' \
  --request DELETE \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

Show Schema

{
  "valid": true,
  "status": "string",
  "activations": [
    {
      "id": "string",
      "activated_at": "string",
      "meta": {}
    }
  ]
}

Current state of the license key.

Revoke a license key

Marks the key as revoked so it can no longer be activated — the same action as revoking the key in the Sellfy dashboard, where it can also be reactivated. Idempotent — revoking an already-revoked key just returns its state.

Body·LicenseLookupInput

required

license_key
Type: string
min length:
1
required

The license key string.
product_id
Type: string
required

ID of the Sellfy product the license key belongs to. To find it, open Products → All products in your dashboard and pick Copy product ID from the options menu (⋯) of the product row. Alternatively, open the product for editing and copy the ID from the address bar: it is the last part of the URL

Responses

application/json
application/json
application/json
application/json
application/json

post/v1/licenses/revoke/

curl https://api.sellfy.com/v1/licenses/revoke/ \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "product_id": "",
  "license_key": ""
}'

Show Schema

{
  "valid": false,
  "status": "revoked",
  "activations": []
}

Current state of the license key.

MCP server

Sellfy runs an MCP (Model Context Protocol) server, so tools like Claude can manage your store in plain language. Point any MCP client that supports remote servers (Streamable HTTP) at:

https://api.sellfy.com/mcp

Let your agent set it up

Paste this into Claude Code, Codex, Cursor, VS Code or Gemini CLI:

Set up the Sellfy MCP server for me by following https://api.sellfy.com/agent-setup.md

Connect a client

Every client goes through the same three steps: add the server URL, sign in once (a browser window opens on Sellfy, where you approve the access), and re-authorize when Sellfy asks for it again. Clients register themselves, so there is nothing to set up in Sellfy first.

Claude (claude.ai or the desktop app)

Add: Settings → Connectors → Browse connectors, find Sellfy and click Connect. If it is not listed for your organization, choose Add custom connector and paste the URL above.
Sign in: click Connect on the Sellfy connector and approve in the browser.
Re-authorize: Settings → Connectors → Sellfy → Disconnect, then Connect again.

Claude Code

claude mcp add --transport http sellfy https://api.sellfy.com/mcp

Sign in: inside a session run /mcp, pick sellfy and choose Authenticate; the browser opens on Sellfy.
Re-authorize: /mcp → sellfy → Clear authentication, then Authenticate again. Or remove and re-add the server:

claude mcp remove sellfy
claude mcp add --transport http sellfy https://api.sellfy.com/mcp

Codex CLI

codex mcp add sellfy --url https://api.sellfy.com/mcp
codex mcp login sellfy

codex mcp login opens the browser on Sellfy; approve the access and return to the terminal. codex mcp get sellfy shows the connection.
Re-authorize:

codex mcp logout sellfy
codex mcp login sellfy

ChatGPT and Codex app

Add: open the plugin directory, find Sellfy and choose Connect. Without the directory entry, open chatgpt.com/plugins, click + → Add custom MCP server, paste the URL above with OAuth as the authentication, then Create as a plugin.
Sign in: ChatGPT opens Sellfy in the browser when you first use the connector.
Re-authorize: remove the connector and create it again.

Cursor — add to .cursor/mcp.json:

{"mcpServers": {"sellfy": {"url": "https://api.sellfy.com/mcp"}}}

Sign in: Cursor Settings → MCP shows sellfy with a Login button; click it and approve in the browser.
Re-authorize: the same MCP settings entry offers Logout, then Login again.

VS Code — add to .vscode/mcp.json:

{"servers": {"sellfy": {"type": "http", "url": "https://api.sellfy.com/mcp"}}}

Sign in: VS Code prompts to sign in when the server starts; the browser opens on Sellfy.
Re-authorize: Command Palette → MCP: List Servers → sellfy → Sign out, then start the server again.

Any other OAuth-capable MCP client connects the same way: give it the URL, then sign in when it asks.

Authentication

The MCP server does not use the API tokens described above. A client connects through OAuth: on the first connection you sign in to Sellfy in the browser and approve or refuse the access it requests — mcp:read covers the read tools, mcp:write the write tools.

A connection stays valid while the client keeps using it: the client renews its access silently, and a connection unused for 30 days, or older than 180 days, expires. To end a connection, disconnect the server in the client; changing or resetting your Sellfy password ends every connection at once. In each of those cases the client reports an authorization error on its next call; re-authorize it as described for your client above to continue.

What you can ask

The assistant works only inside a conversation you start; nothing runs in the background. Some prompts that work as written:

Products

"Create a digital product called Autumn Presets at 19.99, keep it unpublished for now."
"Attach this file to Autumn Presets and publish it."
"Set a compare-at price of 29.99 on every product in the presets category."

Sales and customers

"How did last week compare with the week before?"
"Which five products earned the most this month?"
"Show the orders from jane@example.com."

Marketing

"Create a 20 percent discount code NEWSLETTER valid until Friday."
"Draft an email campaign announcing Autumn Presets and send me a test."
"List the reviews from the last 30 days with fewer than four stars."

Storefront

"Start a new draft of my store, add a page for the course bundle, and give me a preview link."
"Publish the draft."

License keys

"Add these license keys to Autumn Presets."
"Revoke the key ending in 7F3A."

Tools

Store

Tool	What it does	Access
`get_store_info`	Store overview	read

Products

Tool	What it does	Access
`list_products`	List products	read
`get_product`	Get product	read
`create_product`	Create product	write
`get_product_contents`	Get product contents	read
`set_product_contents`	Replace product contents	write
`begin_product_upload`	Begin file upload	write
`finalize_product_upload`	Finalize file upload	write
`update_product`	Update product	write

Variants

Tool	What it does	Access
`list_product_variants`	List product variants	read
`set_product_variants`	Set product variants	write

Media

Tool	What it does	Access
`list_product_media`	List product media	read
`add_product_media_link`	Add product embed	write
`begin_product_image_upload`	Start product image upload	write
`finalize_product_image_upload`	Finish product image upload	write
`set_product_media`	Set product media	write

Shipping

Tool	What it does	Access
`get_product_shipping`	Get product shipping	read
`set_product_shipping`	Set product shipping	write
`list_shipping_profiles`	List shipping profiles	read
`get_shipping_profile`	Get shipping profile	read
`create_shipping_profile`	Create shipping profile	write
`update_shipping_profile`	Update shipping profile	write

Licensing

Tool	What it does	Access
`get_product_licensing`	Get product licensing	read
`set_product_licensing`	Set product licensing	write
`add_license_keys`	Add license keys	write
`list_license_keys`	List license keys	read
`revoke_license_key`	Revoke license key	write
`reactivate_license_key`	Reactivate license key	write
`delete_license_key`	Delete license key	write

Orders

Tool	What it does	Access
`list_orders`	Search orders	read
`get_order`	Get order	read

Analytics

Tool	What it does	Access
`get_sales_summary`	Sales summary	read
`get_sales_histogram`	Sales over time	read
`get_top_stats`	Top sellers, sources and countries	read

Discounts

Tool	What it does	Access
`create_discount`	Create discount	write
`list_discounts`	List discounts	read
`update_discount`	Update discount	write

Campaigns

Tool	What it does	Access
`list_email_campaigns`	List email campaigns	read
`create_email_campaign`	Create email campaign draft	write
`update_email_campaign`	Update email campaign	write
`send_test_email`	Send test email	write

Customers

Tool	What it does	Access
`list_customers`	List customers	read

Reviews

Tool	What it does	Access
`list_reviews`	List reviews	read

Store Pages

Tool	What it does	Access
`list_store_pages`	List store pages	read
`get_store_page`	Get store page	read
`create_store_page`	Create store page	write
`update_store_page`	Update store page	write

Store Modules

Tool	What it does	Access
`list_store_module_types`	List store block types	read
`set_store_module`	Set store block	write

Store Settings

Tool	What it does	Access
`get_store_settings`	Get store settings	read
`update_store_settings`	Update store settings	write

Store Versions

Tool	What it does	Access
`create_store_version`	Create store draft	write
`list_store_versions`	List store versions	read
`publish_store_version`	Publish store draft	write
`restore_store_version`	Restore store backup	write
`delete_store_version`	Delete store draft	write

What the server will and will not do

New products are created unpublished. Publishing is a separate, explicit step, and a digital product needs a file, text, link or license keys before it can be published.
Email campaigns are drafts only. The assistant can send a test to your own address; sending to your list happens in the Sellfy dashboard.
There are no tools to delete products or discounts, issue refunds, or move money.
Storefront edits carry a revision. If the store changed in the meantime (for example you edited it in the dashboard), the write is rejected and the assistant reads again and retries.
Prices you give are taken in your store currency, as set in the dashboard. Say "19.99" and the product is priced 19.99 in that currency; the assistant does not convert between currencies.
Plan limits apply exactly as in the dashboard. When a feature is not included in your plan, the tool says so; the plans are described at https://sellfy.com/pricing/.
Requests are limited to 120 per minute across all of your connected clients. Beyond that the server answers with a retry delay, and the assistant waits.

Privacy

Through these tools the assistant can read your products, orders, customers, reviews, campaigns and storefront content. Orders, customers and reviews include buyer names and email addresses. Everything a tool returns is sent to the AI provider whose client you connected (for example Anthropic or OpenAI) and handled under that provider's terms. Sellfy sends nothing to a provider outside a conversation you start. Sellfy's own handling of this data is described in the privacy policy at https://sellfy.com/privacy/.

Security

Write tools change the live store. Keep your client's confirmation prompt on for write tools, and avoid running the Sellfy server in the same agent session as untrusted MCP servers: a malicious tool result there can try to steer the agent into unwanted writes (prompt injection).

Troubleshooting

Authorization error after the client updated or after a password change: re-authorize as described for your client above.
The URL with my store domain does not work: the server is always at the URL at the top of this page, never at your store address or custom domain.
"Stale revision" on a storefront write: the store changed since the assistant last read it. Ask it to reload and try again.
A tool says the feature is not on my plan: the same limit applies in the dashboard; see the pricing page above.

Support

Email support@sellfy.com with the client you use and, if there is one, the error text the assistant showed.