---
title: With Pay.sh
description: Create subscriptions with Pay.sh.
---

You can set up subscriptions via Pay.sh by setting up a Pay client on your
device or by setting up a Pay server. Install Pay with:

```bash
brew install pay
```

or

```bash
npm install -g @solana/pay
```

Verify the installation with:

```bash
pay --version
```

The toolchain will set up your address for you. Run the following to setup and
topup your wallet:

```bash
pay setup
```

## Subscriptions as a client

Users subscribe to subscription-gated API endpoints by invoking pay like normal.
It is on the API to send the subscription details in the initial `402 Status`
Response. Pay handles the subscription automatically, including instruction
invocation on the Solana SPL Subscriptions Program.

Users can manage their subscriptions using the following commands:

```bash
pay subscriptions                       # default: list + show available subcommands
pay subscriptions list                  # same, scriptable
pay subscriptions list --network mainnet
pay subscriptions list --json
```

You can learn more about managing your subscriptions as a user in the
[Pay.sh > Using Pay > Manage Subscriptions docs](https://pay.sh/docs/using-pay/subscriptions).

## Managing subscriptions as a provider (demo)

Pay servers allow for configuring subscribers and their subscriptions for each
endpoint. The following is an endpoint example that uses pay you can try with
your project:

```yaml
# monthly.yml
name: Subscriptions Example
subdomain: subscriptions-example
title: "Subscription Example"
description: "Demo Subscriptions"
category: ai_ml
version: v1
routing:
  type: respond
operator:
  currencies:
    usd: ["USDC", "USDT", "CASH"]
  network: "localnet"
  fee_payer: true
  challenge_binding_secret: d858d9104afd728f58a1f73d806dd75d8f32ebd37c9707145816b490e8631d41
  # insert your own challenge_binding_secret here. use `openssl rand -hex 32`

endpoints:
  - method: GET
    path: "api/v1/pro/feed"
    resource: "pro-feed"
    description: "Pro feed — monthly subscription, 30-day billing period."
    subscription:
      period: "30d"
      price_usd: 9.99
      currency: USDC
      plan_id_numeric: 1
```

Pay handles subscriptions using the `subscription:` attribute in its `endpoints`
YAML specification. This is opposed to the `metering:` attribute for pay-per-use
endpoints.

Starting the server in the above example creates an endpoint called
`api/v1/pro/feed` that requires a user to make recurring payments of 9.99 USDC
to it every 30 days.

You can try it by running the following command:

```bash
pay server start monthly.yml
```

Running this command will prompt you to create a plan. This creates a plan and
updates the yml file. If you're going to use it again, remember the plan address
and use that in your config as you're making changes.

You can test that the subscriptions work by running the following commands as a
client on another terminal:

```bash
# First call — activates the subscription, $9.99 USDC charge settles.
pay --sandbox curl http://127.0.0.1:1402/api/v1/pro/feed

# Same call within 30 days — no payment prompt, just the response.
pay --sandbox curl http://127.0.0.1:1402/api/v1/pro/feed
```

You should see an OK status as a response like this:

```json
{ "status": "ok" }
```

You can learn more about managing subscriptions on a Pay server via the
[Pay.sh > Building with Pay > Subscriptions > YAML Specification docs](https://pay.sh/docs/building-with-pay/subscriptions/yaml-specification).