DocumentationAPI Endpoints
Documentation
Tokeny.com

Agent: Configure Subscriptions

Suggest Edits

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, e.g. Agent, Owner, etc.
  • Sign into your Servicing portal to disable your 2FA.
  • 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:

ParameterTypeRequiredDescription
aliasstringThe alias or name for the subscription.
capsobjectContains subscription limits:

- min: Minimum allowed investment amount.
- max: Maximum allowed investment amount.
- minOrder: Minimum order size.
- maxOrder: Maximum order size.
distributorbooleanIndicates if the subscription is distributed by a distributor.
endDatestringThe end date of the subscription period in ISO 8601 format (e.g., 2024-12-31T10:28:34.060Z).
feesobjectDefines the fees for the subscription:

- type: Fee type (e.g., FLAT).
- value: The fee value (e.g., a specific amount or percentage).
paymentBeforeMintingbooleanWhether payment must be made before minting the token.
paymentInputTokenQuantitybooleanIf the input requires a specific quantity of tokens to be provided.
paymentInputAmountToPaybooleanIf the input requires the amount to pay for the subscription.
paymentInputNetInvestmentbooleanIf the input requires net investment to be provided.
baseCurrency stringYesThe base currency used for pricing the subscription.
startDate stringYesThe start date for the subscription period in ISO 8601 format.
supportingDocumentsRequiredbooleanWhether supporting documents are required to process the subscription.
supportedCurrenciesarray of stringA list of currencies supported for payments (e.g., USD, EUR, BTC, etc.).
tokenPricestringThe price of the token.
paymentMethodsobjectAvailable 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.
typestringYesNote:

- If it is CLOSE_ENDED, the tokenPrice value must be set.
- If it is OPEN_ENDED, the tokenPrice value must be null.
autoMintingbooleanWhether tokens will be automatically minted after the subscription is created.
autoPriceSetAfterValuationbooleanIndicates whether the token price should be set automatically after valuation.
docusignIntegratorKeystringThe integrator key for integrating with DocuSign.
docusignRsaPrivateKeystringRSA private key for DocuSign integration.
docusignUserIdstringUser ID for DocuSign authentication.
docusignTemplateIdsobjectMapping of language-specific DocuSign templates. For each language, there are two templates: one for individual subscriptions and one for institutional subscriptions.
warningTextstringWarning text defined by the issuer. It appears in the subscription order creation pop-up in the investor app
infoTextstringInfo text defined by the issuer. It appears in the subscription order creation pop-up in the investor app
calendarIdstringThe 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}}

⚠️

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:

ParameterTypeRequiredDescription
aliasstringThe alias or name for the Interval.
endDatestringThe end date of the subscription period in ISO 8601 format (e.g., 2024-12-31T10:28:34.060Z).
feesobjectDefines the fees for the subscription:

- type: Fee type (e.g., FLAT).
- value: The fee value (e.g., a specific amount or percentage).
startDatestringYesThe start date for the subscription period in ISO 8601 format.
tokenPricestringThe price of the token.
typestringYesNote:

- If it is CLOSE_ENDED, the tokenPrice value must be set.
- If it is OPEN_ENDED, the tokenPrice value must be null.
autoMintingbooleanWhether tokens will be automatically minted after the subscription is created.
autoPriceSetAfterValuationbooleanIndicates 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.

Run in Postman >


Related links

Updated 7 days ago