Create Subscriptions via API

Create your Helio Subscriptions programatically

You can also create a Charge via the API for your subscription, where you can pass additional metadata for individual subscriptions using additionalJSON.

Pre-requisites

Follow the pre-requisite steps to setup our API and get your keys.

Create the Pay Link using your API keys

NOTE: When using the production environment (app.hel.io), set your API endpoint to api.hel.io/v1 and generate API keys there. For the development environment, use api.dev.hel.io/v1 and generate API keys from app.dev.hel.io.

• API Endpoint: https://api.hel.io/v1/paylink/create/api-key

• HTTP Method: POST

• Required Query Parameters: ?apiKey={{Your public key here}}

• Required Headers: Authorization: Bearer {{Your API Token here}}

Required request body:

{
  "template": "SUBSCRIPTION",
  "name": "Your paylink name here",
  "price": "1000000", /* price is int64 represented by the base units of each currency, e.g. "price": "1000000" = 1 USDC */
  "pricingCurrency": "6340313846e4f91b8abc519b", /* currency ID to price it in - can be a fiat currency */
  "features": {
    "isSubscription": true
  },
  "recipients": [
    {
      "walletId": "YOUR_WALLET_ID",
      "currencyId": "6340313846e4f91b8abc519b"
    }
  ],
  "subscriptionDetails": {
    "renewalReminders": 3, /* number of daily renewal reminders before subscription cancellation */
    "gracePeriod": 2, /* grace period (in days) after subscription expiry */
    "annualDiscountBps": 0, /* discount in basis points if the subscription is annual */
    "interval": "MONTH" /* set the subscription interval: MONTH or YEAR */
  }
}

For the full list of Pay Link customisation options, such as Discord gating, split payments, etc., please refer to our full documentation.

Example Query:

curl --location 'https://api.hel.io/v1/paylink/create/api-key?apiKey=YOUR_PUBLIC_API_KEY>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_SECRET_API_KEY' \
--data '{
    "template": "SUBSCRIPTION",
    "name": "Your paylink name here",
    "price": "1000000", 
    "pricingCurrency": "6340313846e4f91b8abc519b",
    "features": {
        "isSubscription": true
    },
    "recipients": [
        {
            "walletId": "YOUR_WALLET_ID",
            "currencyId": "6340313846e4f91b8abc519b"
        }
    ],
    "subscriptionDetails": {
        "renewalReminders": 3,
        "gracePeriod": 2,
        "annualDiscountBps": 0,
        "interval": "MONTH"
    }
}'

From the following example replace: YOUR_PUBLIC_API_KEY, YOUR_SECRET_API_KEY, YOUR_WALLET_ID (and the pricing/recipient currency IDs) with the values you collected in the previous step.

Response body example

{
    "id": "67aca16c445e22c559fc347d",
    "platform": "HELIO",
    "template": "OTHER",
    "disabled": false,
    "inactive": false,
    "notifySenderByEmail": false,
    "notifyReceiverByEmail": false,
    "addDiscordRole": false,
    "helioPlayProperties": null,
    "features": {
        "canChangeQuantity": false,
        "canChangePrice": false,
        "requireQuantityLimits": false,
        "requireCountry": false,
        "requireEmail": true,
        "requireDeliveryAddress": false,
        "requireDiscordUsername": false,
        "requireDiscordLogin": false,
        "requireFullName": false,
        "requirePhoneNumber": false,
        "requireTwitterUsername": false,
        "requireTelegramUsername": false,
        "requireProductDetails": false,
        "requireMaxTransactions": false,
        "requireNftGate": false,
        "requireDiscordAuth": false,
        "requireAccessCode": false,
        "requireXFollow": false,
        "requireRaffle": false,
        "splitRevenue": false,
        "splitEqually": false,
        "canSwapTokens": false,
        "isHelioPlay": false,
        "isTransparentWallet": false,
        "nftDropEnabled": false,
        "showDiscountCode": false,
        "isEscrowed": false,
        "requireAllowlist": false,
        "requireTradingViewUsername": false,
        "allowAffiliate": false,
        "requireAirdrop": false,
        "isEventEnabled": false,
        "enableCountdown": false,
        "requireCaptchaValidation": false,
        "shouldRedirectOnSuccess": false,
        "customThemeEnabled": false,
        "isSubscription": true
    },
    "name": "Your paylink name here",
    "discordAuthDetails": [],
    "dynamic": false,
    "affiliateDetails": null,
    "price": "1000000",
    "normalizedPrice": "1000000",
    "subscriptionDetails": {
        "renewalReminders": 3,
        "gracePeriod": 2,
        "annualDiscountBps": 0,
        "interval": "MONTH"
    },
    "content": {},
    "creator": {
        "id": "667c1f9352919e407156128a",
        "userType": "MERCHANT",
        "email": "[e-mail]",
        "name": "",
        "isDisabled": false,
        "kycVerified": false,
        "platformDetails": {
            "platform": "HELIO"
        }
    },
    "company": {
        "id": "667c1f9352919e407156128c",
        "name": "Helio",
        "email": "[e-mail]",
        "websiteUrl": "",
        "discordUsername": "",
        "address": "",
        "phoneNumber": "",
        "escrowFunds": false,
        "tradingViewDetails": "66ab698681063452ebd41ba0",
        "twitterConfirmed": false,
        "kycVerified": false,
        "kybVerified": false
    },
    "currency": {
        "id": "6340313846e4f91b8abc519b",
        "name": "USD Coin",
        "decimals": 6,
        "order": 1,
        "mintAddress": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
        "coinMarketCapId": 3408,
        "symbol": "USDC",
        "symbolPrefix": "$",
        "type": "DIGITAL",
        "iconUrl": "USDC.svg",
        "features": [
            "PAYMENT_PRICING",
            "PAYMENT_RECIPIENT",
            "SWAP"
        ],
        "blockchain": {
            "id": "6340313846e4f91b8abc515c",
            "name": "SOL",
            "symbol": "SOL",
            "engine": {
                "id": "63b6b1200cfb4b3f6131f2b4",
                "type": "SOL"
            }
        }
    },
    "wallet": {
        "id": "667c1f9352919e4071561294",
        "name": "",
        "publicKey": "7YancRyNQyp9s6G7YNwx9H93UqswoKWqF9GuNJPufyvW",
        "btcProperties": null
    },
    "recipients": [
        {
            "currency": {
                "id": "6340313846e4f91b8abc519b",
                "name": "USD Coin",
                "decimals": 6,
                "order": 1,
                "mintAddress": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
                "coinMarketCapId": 3408,
                "symbol": "USDC",
                "symbolPrefix": "$",
                "type": "DIGITAL",
                "iconUrl": "USDC.svg",
                "features": [
                    "PAYMENT_PRICING",
                    "PAYMENT_RECIPIENT",
                    "SWAP"
                ],
                "blockchain": {
                    "id": "6340313846e4f91b8abc515c",
                    "name": "SOL",
                    "symbol": "SOL",
                    "engine": {
                        "id": "63b6b1200cfb4b3f6131f2b4",
                        "type": "SOL"
                    }
                }
            },
            "wallet": {
                "id": "667c1f9352919e4071561294",
                "name": "",
                "publicKey": "7YancRyNQyp9s6G7YNwx9H93UqswoKWqF9GuNJPufyvW",
                "btcProperties": null,
                "blockchainEngine": {
                    "id": "63b6b1200cfb4b3f6131f2b4",
                    "type": "SOL"
                }
            }
        }
    ],
    "volume": 0,
    "sales": "0",
    "product": null,
    "additionalImages": [],
    "additionalImageUrls": [],
    "discountCodes": [],
    "discordRoleIds": [],
    "pricingCurrency": {
        "id": "6340313846e4f91b8abc519b",
        "name": "USD Coin",
        "decimals": 6,
        "order": 1,
        "mintAddress": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
        "coinMarketCapId": 3408,
        "symbol": "USDC",
        "symbolPrefix": "$",
        "type": "DIGITAL",
        "iconUrl": "USDC.svg",
        "features": [
            "PAYMENT_PRICING",
            "PAYMENT_RECIPIENT",
            "SWAP"
        ],
        "blockchain": {
            "id": "6340313846e4f91b8abc515c",
            "name": "SOL",
            "symbol": "SOL",
            "engine": {
                "id": "63b6b1200cfb4b3f6131f2b4",
                "type": "SOL"
            }
        }
    }
}