Please find the Primary Market documentation for Subscriptions here.

📘
Prerequisites:
To complete this use case, you will need to authenticate your request(s). You can generate your token by following these steps:

Make sure to leverage an existing account from the correct role, e.g. Agent, Owner, Investor, etc.

If this use case requires you to leverage an Agent account, make sure your 2FA is disabled via the Servicing portal.

Navigate to the "Getting API access" page to generate the required JWT, thanks to your credentials.

Add the JWT to the header of your request.

Step 1: Get the token identifier

First, you will need to retrieve the token_id, you can do so here.

Step 2: Get existing Subscriptions

Before configuring a new Subscription, or updating one, we recommend retrieving all existing Subscriptions.

GET /subscriptions/tokens/:tokenId

Response example in the case of one existing Subscription:

{
  {
    "items": [
        {
            "id": "string",
            "alias": "string", // Subscription name
            "calendarId": null,
            "baseCurrency": "USD",
            "distributor": true,
            "paymentBeforeMinting": true,
            "supportedCurrencies": [
                "USD"
            ],
            "supportingDocumentsRequired": true,
            "templates": {},
            "tokenId": "3a3229172-cd233-4f64-8f229-d853447147f",
            "createdAt": "2000-01-13T15:34:29.878Z",
            "updatedAt": "2000-01-13T15:34:29.878Z",
            "paymentInputTokenQuantity": true,
            "paymentInputAmountToPay": true,
            "paymentInputNetInvestment": true,
            "paymentMethods": {
                "EUR": {
                    "type": "FIAT",
                    "name": "EUR",
                    "strategy": {
                        "bankTransfer": {
                            "BIC": "BICXXXX",
                            "IBAN": "IBAN134603820191483",
                            "bankName": "BANK NAME",
                            "accountOwner": "Account Owner"
                        }
                    },
                    "decimals": 2
                },
                "GBP": {
                    "type": "FIAT",
                    "name": "GBP",
                    "strategy": {
                        "bankTransfer": {
                            "BIC": "BICXXXX",
                            "IBAN": "IBAN134603820191483",
                            "bankName": "BANK NAME",
                            "accountOwner": "Account Owner"
                        }
                    },
                    "decimals": 2
                },
                "BTC": {
                    "type": "Crypto",
                    "name": "Bitcoin",
                    "strategy": {
                        "unique_pool": {
                            "reconciliate": true,
                            "scorechain_scanner": false
                        }
                    },
                    "decimals": 8
                }
            },
            "warningText": "warningText",
            "infoText": "infoText",
            "intervals": [
                {
                    "id": "417c5123-2385-47e9-a27e-Rfbsa981R734f",
                    "alias": "ADTalias", // Interval name
                    "startDate": "2024-12-14T11:14:26.442Z",
                    "endDate": "2030-12-13T11:14:26.442Z",
                    "caps": {
                        "min": "1",
                        "max": "10000000000",
                        "minOrder": "1",
                        "maxOrder": "10"
                    },
                    "totalInvestedAmount": "0",
                    "tokenPrice": "2",
                    "fees": {
                        "type": "FLAT",
                        "value": "1"
                    },
                    "subscriptionId": "344ba5cf-fd9a-124d-9b58-9c9zefskja7bef0d",
                    "type": "CLOSE_ENDED",
                    "autoMinting": false,
                    "autoPriceSetAfterValuation": false
                }
            ]
        }
    ],
    "totalItemsFound": 1
}
}

Step 3: Create a Subscription and it's Interval

This all-in-one endpoint allows you to create a new subscription, for a token, with a specified interval.

POST /subscriptions/tokens/{tokenId}

The request body must contain the following parameters:

Parameter	Type	Required	Description
alias	`string`		The alias or name for the subscription.
caps	`object`		Contains subscription limits: `min`: Minimum allowed investment amount. `max`: Maximum allowed investment amount. `minOrder`: Minimum order size. `maxOrder`: Maximum order size.
distributor	`boolean`		Indicates if the subscription is distributed by a distributor.
endDate	`string`		The end date of the subscription period in ISO 8601 format (e.g., `2024-12-31T10:28:34.060Z`).
fees	`object`		Defines the fees for the subscription: `type`: Fee type (e.g., `FLAT`). `value`: The fee value (e.g., a specific amount or percentage).
paymentBeforeMinting	`boolean`		Whether payment must be made before minting the token.
paymentInputTokenQuantity	`boolean`		If the input requires a specific quantity of tokens to be provided.
paymentInputAmountToPay	`boolean`		If the input requires the amount to pay for the subscription.
paymentInputNetInvestment	`boolean`		If the input requires net investment to be provided.
baseCurrency	`string`	Yes	The base currency used for pricing the subscription.
startDate	`string`	Yes	The start date for the subscription period in ISO 8601 format.
supportingDocumentsRequired	`boolean`		Whether supporting documents are required to process the subscription.
supportedCurrencies	`array of string`		A list of currencies supported for payments (e.g., `USD`, `EUR`, `BTC`, etc.).
tokenPrice	`string`		The price of the token.
paymentMethods	`object`		Available payment methods for each supported currency. For each currency (e.g., `EUR`, `GBP`, `BTC`), the method could be either `FIAT` (bank transfer, etc.) or `crypto` (e.g., Bitcoin). For `FIAT` methods, information like bank transfer details (`BIC`, `IBAN`, `bankName`, `accountOwner`) will be included. For `crypto` methods (e.g., Bitcoin), additional details like wallet reconciliation options may be provided.
type	`string`	Yes	Note: If it is `CLOSE_ENDED`, the tokenPrice value must be set. If it is `OPEN_ENDED`, the tokenPrice value must be null.
autoMinting	`boolean`		Whether tokens will be automatically minted after the subscription is created.
autoPriceSetAfterValuation	`boolean`		Indicates whether the token price should be set automatically after valuation.
docusignIntegratorKey	`string`		The integrator key for integrating with DocuSign.
docusignRsaPrivateKey	`string`		RSA private key for DocuSign integration.
docusignUserId	`string`		User ID for DocuSign authentication.
docusignTemplateIds	`object`		Mapping of language-specific DocuSign templates. For each language, there are two templates: one for individual subscriptions and one for institutional subscriptions.
warningText	`string`		Warning text defined by the issuer. It appears in the subscription order creation pop-up in the investor app
infoText	`string`		Info text defined by the issuer. It appears in the subscription order creation pop-up in the investor app
calendarId	`string`		The calendar identifier associated with the subscription's schedule

The response contains the details of the newly created token subscription, including interval information, subscription ID, payment methods, and other details.

Example:

{
  "id": "string",
  "intervals": [
    {
      "id": "string",
      "alias": "string",
      "endDate": "2024-12-31T10:28:34.082Z",
      "fees": {
        "type": "FLAT",
        "value": "string"
      },
      "startDate": "2024-12-31T10:28:34.082Z",
      "subscriptionId": "string",
      "tokenPrice": "string",
      "caps": {
        "min": "string",
        "max": "string",
        "minOrder": "string",
        "maxOrder": "string"
      },
      "totalInvestedAmount": "string",
      "type": "CLOSE_ENDED",
      "autoMinting": true,
      "autoPriceSetAfterValuation": true
    }
  ],
  "alias": "string",
  "createdAt": "2024-12-31T10:28:34.082Z",
  "distributor": true,
  "paymentBeforeMinting": true,
  "paymentInputTokenQuantity": true,
  "paymentInputAmountToPay": false,
  "paymentInputNetInvestment": false,
  "paymentMethods": { ... },
  "baseCurrency": "string",
  "supportedCurrencies": [ "string" ],
  "templates": { ... },
  "tokenId": "string",
  "updatedAt": "2024-12-31T10:28:34.082Z",
  "supportingDocumentsRequired": true,
  "calendarId": "string",
  "docusignIntegratorKey": "string",
  "docusignRsaPrivateKey": "string",
  "docusignUserId": "string",
  "docusignTemplateIds": { ... },
  "warningText": "string",
  "infoText": "string",
  "blockchainNetwork": "string"
}

Step 4: Updating existing Intervals

To update an Interval, use the following PUT endpoint. This endpoint requires all the previously obtained information, including the token_id, subscription_id, and Interval configuration data.

PUT /subscriptions/{{subscription_id}/tokens/{{token_id}}/interval/{{interval_id}}

⚠️
Warning:
Please note that updating any production Interval fields will have a significant impact on your Subscription.

cURL request

curl -XPUT 'https://api-testing.tokeny.com/servicing/api/subscriptions/:subscription_id/tokens/:token_id/interval/:interval_id' \
  -H 'authorization: Bearer <jwt>'
  -H 'content-type: application/json' \
  --data-binary '{
{
  "alias": "intervalName",
  "endDate": null,
  "fees": {
    "type": "FLAT",
    "value": "string"
  },
  "startDate": "2000-01-01T12:00:00.000Z",
  "tokenPrice": "string",
  "type": "CLOSE_ENDED",
  "autoMinting": false,
  "autoPriceSetAfterValuation": false
}
}'

Please keep in mind, we are dealing with type CLOSE_ENDED, in an open-ended scenario null would be expected in tokenPrice as the Price would be defined by the NAV.

The request body must contain the following parameters:

Parameter	Type	Required	Description
alias	`string`		The alias or name for the Interval.
endDate	`string`		The end date of the subscription period in ISO 8601 format (e.g., `2024-12-31T10:28:34.060Z`).
fees	`object`		Defines the fees for the subscription: `type`: Fee type (e.g., `FLAT`). `value`: The fee value (e.g., a specific amount or percentage).
startDate	`string`	Yes	The start date for the subscription period in ISO 8601 format.
tokenPrice	`string`		The price of the token.
type	`string`	Yes	Note: If it is `CLOSE_ENDED`, the tokenPrice value must be set. If it is `OPEN_ENDED`, the tokenPrice value must be null.
autoMinting	`boolean`		Whether tokens will be automatically minted after the subscription is created.
autoPriceSetAfterValuation	`boolean`		Indicates whether the token price should be set automatically after valuation.

Response

{
  {
    "id": "string",
    "alias": "intervalName",
    "startDate": "string",
    "endDate": null,
    "caps": {
        "minOrder": "string",
        "maxOrder": "string",
        "max": "string"
    },
    "totalInvestedAmount": "string",
    "tokenPrice": "string",
    "fees": {
        "type": "PERCENTAGE_INVESTMENT_AMOUNT",
        "value": "string"
    },
    "subscriptionId": "string",
    "type": "CLOSE_ENDED",
    "autoMinting": false,
    "autoPriceSetAfterValuation": false
	}
}

Step 5: Creating a new Interval

The Interval is what defines the token Price, fees, investments caps, etc, during a specific period of time of a close-ended subscription. You can therefore define multiple subsequent intervals for a single subscription, this update these fields, over time, on a single Subscription.

POST /subscriptions/{{subscription_id}/tokens/{{token_id}}/interval

cURL request

curl -XPOST 'https://api-testing.tokeny.com/servicing/api/subscriptions/:subscription_id/tokens/:token_id/interval' \
  -H 'authorization: Bearer <jwt>'
  -H 'content-type: application/json' \
  --data-binary '{
  "alias": "NewIntervalName",
  "endDate": "2026-01-22T10:26:14.638Z",
  "fees": {
    "type": "FLAT",
    "value": "string"
  },
  "startDate": "2000-01-13T10:26:14.638Z",
  "tokenPrice": "string",
  "caps": {
    "min": "string",
    "max": "string",
    "minOrder": "string",
    "maxOrder": "string"
  },
  "type": "CLOSE_ENDED",
  "autoMinting": false,
  "autoPriceSetAfterValuation": true
}'

Response

{
  {
    "id": "string",
    "alias": "intervalName",
    "startDate": "string",
    "endDate": null,
    "caps": {
        "minOrder": "string",
        "maxOrder": "string",
        "max": "string"
    },
    "totalInvestedAmount": "string",
    "tokenPrice": "string",
    "fees": {
        "type": "PERCENTAGE_INVESTMENT_AMOUNT",
        "value": "string"
    },
    "subscriptionId": "string",
    "type": "CLOSE_ENDED",
    "autoMinting": false,
    "autoPriceSetAfterValuation": false
	}
}

You can manage subscription in Postman, depending on the role and the type of subscription (OPEN_ENDED or CLOSE_ENDED).

OPEN_ENDED subscriptions allow investors to subscribe and unsubscribe at any time. The Subscription price, i.e. the price per token, is defined and fix in each Interval.
CLOSE_ENDED subscriptions have a fixed duration, and investors can only subscribe during the open period. The subscription price, i.e. the price per token, is defined with the NAV.

When using Postman, make sure you are using the right environment and that your role has the necessary permissions to access the endpoints. The type of subscription will dictate the actions you can perform.