Quickstart ⚡

This quickstart walks you through creating and selling your first on-chain subscription collection on Crossmint, in under 5 minutes.

Video walkthrough is here.

Prerequisites

A Crossmint account
An IDE and (optional) an API client of your choice
A wallet that supports the base-sepolia testnet (e.g. Metamask or Phantom)

This quickstart is written for a technical audience, and primarily uses APIs in combination with the Crossmint console. It is opinionated and uses the base-sepolia chain and JavaScript/Node.js for the examples, but you can use any language and supported chain you like.

Production Access gated The Crossmint team must enable Subscriptions in your project before you can use them in

production. To get access, reach out using this form and specify your Project ID.

You can find the Project ID near the top right of the console overview page.

With onchain subscriptions, a subscription is recorded as an NFT owned by a user. To check if a user has a valid subscription, you check if they hold a subscription NFT and if it’s expired (encoded on-chain in the NFT’s metadata).

To create a new subscription at Crossmint, the first step is to create a collection, which is just a container for metadata, the price, payout address and other configurations for a collection of NFTs.

1. Create your Subscription Collection

A subscription collection is a special extension of a Crossmint collection, which only holds subscription NFTs. Each subscription collection maps to an NFT smart contract (ERC-5643 in EVM chains). Certain features like NFT transferability are not available in subscription collections.

Create your API keys

First, you’ll need to obtain the appropriate API keys.

Log in to your Crossmint Staging Console.
Navigate to the “Integrate” -> “API Keys” section in the console.
Create a new server-side API key with the following scopes:
- wallets.read
- wallets:nfts.read
- wallets.create
- All scopes in Payments
- All scopes in Minting, EXCEPT burn NFTs (nfts.delete)

You control these scopes by default in the staging environment.

When working with subscriptions in a production environment, make sure your account and collection are properly verified. Refer to the production launch guide for more information on the verification process.

With your API key ready, you can now proceed to create and manage subscription collections.

Create Collection via APIs

You will create your collection via curl requests (recommended), an API client, or whatever code language you wish.

If you are using an API client like Bruno or Postman, make sure you configure your header parameters properly:

Parameter	Value
`BASE URL`	`https://staging.crossmint.com`
`API-VERSION`	`2022-06-09`
`X-API-KEY`	`YOUR_API_KEY`

When you copy/paste code examples, make sure you replace the text marked “YOUR_API_KEY”, “YOUR_COLLECTION_ID”, “YOUR_PROJECT_ID”, and “YOUR_WALLET_ADDRESS” with your actual API key, collectionId, projectId, and wallet address.

curl --request POST \
  --url https://staging.crossmint.com/api/2022-06-09/collections \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "chain": "base-sepolia",
  "metadata": {
    "name": "My First Subscription Collection",
    "imageUrl": "https://cdn-icons-png.flaticon.com/512/5234/5234307.png",
    "description": "A collection of subscription-based NFTs on Base Sepolia"
  },
  "payments": {
    "recipientAddress": "YOUR_WALLET_ADDRESS",
    "currency": "usdc",
    "price": "1"
  },
  "transferable": false,
  "subscription": {
    "enabled": true
  }
}'

Notice the isSubscription: true field in the Response (last tab of code group).

Save the id from the response for later. We will refer to it as collectionId later (e.g. fdfd902c-e80a-4828-b884-1554bdaeb54d in the response above)

Check your collection

In the Crossmint console

Log into the Crossmint Staging Console and navigate to the Token collections tab. You should see your new collection in your list of collections.

Check collection through API (Advanced)

You can use the Get Collection Info API to check if your collection is ready.

You can use the API playground. Alternatively, use the code example below:

curl --request GET \
  --url https://staging.crossmint.com/api/2022-06-09/collections/{YOUR_COLLECTION_ID} \
  --header 'X-API-KEY: "YOUR_API_KEY"'

2. Configure subscription metadata

When a subscription is issued, your users will receive an NFT that represents it.

This NFT can contain a name, an image, a description, and other fields. You define these values by creating an NFT template that is copied each time a subscription is issued.

Let’s create a template now:

Navigate to the “Token collections” tab and select the collection you created earlier.
In the collection details page, click on the “NFTs” tab.
Click the “Manual Upload” button to create a new template.
Fill in the template details:
- Name: Enter a name for your NFT template.
- Description: Provide a brief description of the NFT.
- Image: Upload an image for your NFT. Recommended formats are JPEG, PNG, WEBP, or GIF. Keep file sizes below 10 MB for optimal performance.
- Attributes (optional): Add any additional attributes that describe your NFT. These can be used to add more details or properties to your NFT.
Once you’ve filled in all the necessary information, click the “Create NFT” button to add the template to your collection.

Once the template is uploaded, you can select its template ID when issuing a subscription to ensure the correct metadata is set.

Note:

Prices are defined at the collection level. For multiple subscription tiers, create multiple collections rather than different templates within a collection.
You may create multiple templates to add variety to the metadata users see.
For large-scale unique metadata (e.g., giving each user their own design), use the bulk uploading tool.
Typically, subscription collections only need one template, as the same NFT design is usually used for all subscribers.

Via API (Advanced)

For programmatic template creation, you can use the Create Template API.

curl --request POST \
  --url https://staging.crossmint.com/api/2022-06-09/collections/{YOUR_COLLECTION_ID}/templates \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
  "metadata": {
    "name": "<string>",
    "image": "<string>",
    "description": "<string>",
    "symbol": "<string>"
  },
  "onChain": {
    "tokenId": "1"
  },
  "supply": {
    "limit": 10
  },
  "reuploadLinkedFiles": true
}'

3. Set up a checkout on your website to sell subscriptions

Now it’s time to implement a page where your customers can pay for a subscription.

You can use two of Crossmint’s Checkout modalities for this: embedded checkout and headless. For simplicity, this guide recommends the use of “embedded” which has pre-built UI components.

Clone the Example Repo

Clone the embedded checkout example repo here and follow the instructions in the README.md file. This should get you a working embedded checkout that you can use to test your subscription collection in under 1 minute.

Subscriptions work with embedded and headless checkouts.

Configure Environment Variables

Make sure you change the NEXT_PUBLIC_PROJECT_ID and NEXT_PUBLIC_COLLECTION_ID in the demo’s .env.local file to your subscription collection’s projectId and collectionId.

Troubleshooting is covered in the embedded quickstart guide.

If your embedded checkout is configured properly, you should see your subscription NFT loaded, with a “Subscribe” button on the bottom.

Common errors

“collectionId or clientId not found!”: Ensure you have set the NEXT_PUBLIC_PROJECT_ID and NEXT_PUBLIC_COLLECTION_ID in the .env.local file to your subscription collection’s projectId and collectionId.
“Missing X-API-KEY”: Make sure you have set the X-API-KEY in the .env.local file to your server-side API key.
“There are no templates in this collection”: Ensure you have uploaded an NFT template to your collection in step 2.
“Embedded checkout is not enabled on this collection”: If you are in production, you may not have the necessary scopes for embedded checkout. Contact Crossmint sales to enable.
“Recipient Props” - Subscriptions only work with embedded checkout using the emailInputOptions={{show: true,}} prop. Using recipient props will not work.

4. Buy Your First Subscription NFT

With your newly created embedded checkout, you can now buy your first subscription NFT:

Input an email address where you can receive emails.
Enter a test credit card number (4242 4242 4242 4242, use random information for all other fields).
Click “Subscribe”.

You should see the subscription NFT being minted to your wallet.

5. Receive your subscription NFT

In embedded checkout

After the minting is complete, you will see buttons to view on Opensea, Basescan, and Crossmint. Explore these to see your subscription NFT and its information live on the blockchain.

Email

You will also receive a confirmation email with the details of your subscription. Crossmint automatically creates a wallet for any inputted email address. If you already have Crossmint wallet, it will be sent to your existing wallet.

Once the subscription NFT is successfully minted and delivered, you should receive an email with your transaction details.

Open your Crossmint wallet at https://staging.crossmint.com/user/ for staging, or https://www.crossmint.com/user/ for production, and see your new subscription NFT.

6. Checking Active Status and Expiration

A subscription NFT is active as long as the expiresAt date is in the future.

The rules are straightforward:

expiration date in the future = active subscription
expiration date in the past = inactive subscription

You can check the expiration of your subscription NFT in 2 ways:

Crossmint's APIs (recommended)

Any Crossmint API that returns NFT metadata will include the expiresAt field.

For this quickstart, Crossmint recommends you use the Get All NFTs API, as it gives an overall view of all NFTs in your subscription collection, including their expiration dates.

Using Code

curl --request GET \
  --url 'https://staging.crossmint.com/api/2022-06-09/collections/YOUR_COLLECTION_ID/nfts?page=1' \
  --header 'X-API-KEY: YOUR_API_KEY'

(Alternative) Using the API Playground

Block Explorer

Next Steps

Congratulations on successfully setting up and testing your subscription collection! Here’s what you can do next:

Go Live: Ready for production? Contact Crossmint sales to enable subscriptions for your account.
Learn More: Explore our full documentation for in-depth information on all Crossmint Checkout products.

Happy building!

Solution Guides

AI Agents

StoryKit

Prerequisites

Production Access gated The Crossmint team must enable Subscriptions in your project before you can use them in

1. Create your Subscription Collection

Create your API keys

Create Collection via APIs

Check your collection

2. Configure subscription metadata

3. Set up a checkout on your website to sell subscriptions

4. Buy Your First Subscription NFT

5. Receive your subscription NFT

In embedded checkout

Email

6. Checking Active Status and Expiration

Using Code

Next Steps

Solution Guides

AI Agents

StoryKit

​Prerequisites

​Production Access gated The Crossmint team must enable Subscriptions in your project before you can use them in

​1. Create your Subscription Collection

​Create your API keys

​Create Collection via APIs

​Check your collection

​2. Configure subscription metadata

​3. Set up a checkout on your website to sell subscriptions

​4. Buy Your First Subscription NFT

​5. Receive your subscription NFT

​In embedded checkout

​Email

​6. Checking Active Status and Expiration

​Next Steps

Prerequisites

Production Access gated The Crossmint team must enable Subscriptions in your project before you can use them in

1. Create your Subscription Collection

Create your API keys

Create Collection via APIs

Check your collection

2. Configure subscription metadata

3. Set up a checkout on your website to sell subscriptions

4. Buy Your First Subscription NFT

5. Receive your subscription NFT

In embedded checkout

Email

6. Checking Active Status and Expiration

Next Steps