Payment Setup

How to configure Polar.sh or Lemon Squeezy as your payment provider for paid plugins.

Overview

SkillStack supports two payment providers for paid plugins. Both handle license key generation and subscription management — you create a product, add a license key benefit, and SkillStack takes care of the rest.

Provider Website What You Need
Polar.sh polar.sh Organization ID (UUID) and Product ID
Lemon Squeezy lemonsqueezy.com Store ID (integer)

Choose Your License Model

Before setting up your provider, decide how you want to sell:

Model Product Type What Buyers Get
Subscription Recurring (monthly/yearly) Access while subscribed; blocked on lapse
Lifetime One-time payment All future updates included
One-Time One-time payment Locked to the version at purchase
Free N/A No payment provider needed

Polar.sh Setup

For Subscriptions

  1. Create a Product with recurring pricing (monthly, yearly, or both)
  2. Add a License Key benefit to the product
  3. Leave key expiry empty — Polar handles revocation automatically

When a customer subscribes, Polar generates a license key. If the subscription lapses, Polar automatically revokes the key. Re-subscribing restores access.

For One-Time / Lifetime Purchases

  1. Create a Product with one-time pricing
  2. Add a License Key benefit to the product
  3. Leave key expiry empty — the key should live forever

The license key stays active permanently (unless refunded or manually revoked).

Find Your Polar IDs

Organization ID (UUID format):

Go to polar.sh > Settings > General. The Organization ID is displayed on that page. Make sure to copy the UUID, not the org slug.

Product ID (UUID format):

Go to polar.sh > Products > click your product. The Product ID is in the URL: polar.sh/products/<product-id>.

Add to skillstack.json

Add a .claude-plugin/skillstack.json sidecar file with your licensing config. The plugin name must match an entry in your marketplace.json:

{
  "plugins": {
    "my-plugin": {
      "license_provider": "polar",
      "license_config": {
        "org_id": "<your-polar-org-uuid>",
        "product_id": "<your-polar-product-uuid>"
      },
      "license_model": "subscription"
    }
  }
}

Change license_model to "onetime" or "lifetime" as needed. Your marketplace.json plugin entry stays as a pure Claude Code marketplace entry (name, source, version, description only).

Lemon Squeezy Setup

For Subscriptions

  1. Create a Product with recurring pricing
  2. Enable License Keys for the product
  3. Leave key expiry empty

Lemon Squeezy automatically expires the key when a subscription lapses and restores it on re-subscription.

For One-Time / Lifetime Purchases

  1. Create a Product with one-time pricing
  2. Enable License Keys for the product
  3. Leave key expiry empty (permanent)

Find Your Store ID

Go to Lemon Squeezy > Settings > General. Your Store ID is displayed on that page (integer format, e.g., 306756).

Add to skillstack.json

Add a .claude-plugin/skillstack.json sidecar file with your licensing config:

{
  "plugins": {
    "my-plugin": {
      "license_provider": "lemonsqueezy",
      "license_config": {
        "store_id": "306756"
      },
      "license_model": "subscription"
    }
  }
}

Change license_model to "onetime" or "lifetime" as needed. Your marketplace.json plugin entry stays as a pure Claude Code marketplace entry (name, source, version, description only).

Multi-License Setup

To offer multiple license types (e.g., subscription + lifetime) on a single plugin, create a separate product with its own license key benefit for each type.

Polar Multi-License

  1. Create a product for each license type (e.g., "My Plugin - Monthly", "My Plugin - Lifetime")
  2. Add a License Key benefit to each product
  3. Use license_options in skillstack.json instead of license_model:
{
  "plugins": {
    "my-plugin": {
      "license_provider": "polar",
      "license_config": {
        "org_id": "your-polar-org-uuid"
      },
      "license_options": {
        "subscription": { "benefit_id": "benefit-uuid-for-subscription-product" },
        "lifetime": { "benefit_id": "benefit-uuid-for-lifetime-product" }
      }
    }
  }
}

Finding Benefit IDs: Go to Polar > Products > your product > Benefits. The benefit ID is in the URL when you click on the license key benefit.

Lemon Squeezy Multi-License

  1. Create a product for each license type
  2. Enable License Keys on each product
  3. Use license_options in skillstack.json with product_id for each:
{
  "plugins": {
    "my-plugin": {
      "license_provider": "lemonsqueezy",
      "license_config": {
        "store_id": "306756"
      },
      "license_options": {
        "subscription": { "product_id": "product-id-for-subscription" },
        "onetime": { "product_id": "product-id-for-onetime" }
      }
    }
  }
}

Important: Each license type needs its own product in your provider. A single product with one license key benefit cannot be used for multiple license types — SkillStack needs to distinguish which type the buyer purchased. All multi-license config goes in skillstack.json, not marketplace.json.

Free Plugins

No payment provider setup needed. Just add a standard marketplace.json entry — no skillstack.json entry required:

{
  "name": "my-plugin",
  "source": "./plugins/my-plugin",
  "description": "My free plugin",
  "version": "1.0.0"
}

Common Mistakes

Mistake What Happens
Using Polar org slug instead of UUID Activation fails with 404
Wrong Lemon Squeezy Store ID Activation fails
Setting key expiry on subscription products Unnecessary — providers handle revocation automatically
Omitting license_model in skillstack.json Falls back to generic paid behavior
Typo in license_model value Falls back to generic paid behavior — must be exactly "subscription", "onetime", or "lifetime"
Omitting version in marketplace.json Plugin is invisible to buyers
Putting licensing fields in marketplace.json Won't be read — licensing config must be in skillstack.json