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)
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.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)
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.
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.
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)
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:
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.
- 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)
Via API (Advanced)
For programmatic template creation, you can use the Create Template API.
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 theNEXT_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
andNEXT_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. Usingrecipient
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”.
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.6. Checking Active Status and Expiration
A subscription NFT is active as long as theexpiresAt
date is in the future.
The rules are straightforward:
- expiration date in the future = active subscription
- expiration date in the past = inactive subscription
Crossmint's APIs (recommended)
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
(Alternative) Using the API Playground
(Alternative) Using the API Playground
- Navigate to the Get All NFTs API on the playground.
- Input your parameters:
- Authorization, X-API-KEY: input
YOUR_API_KEY
generated in Step 1. - Path, collection ID: input your
YOUR_COLLECTION_ID
from the console - Query, page: input
1
- Authorization, X-API-KEY: input
- Click “Send”
- View all the tokens purchased in your collection.
- See “expiresAt” in the response. This is your subscription’s expiration date, that will be extended every time a user is charged for their subscription which Crossmint handles automatically for you.
Block Explorer
Block Explorer
To check the expiration of a subscription NFT, you can use a block explorer like Base Sepolia Explorer. Follow these steps:
- Get the contract address for your collection in the Smart Contract tab in the Collection view.
- Explore the contract address in the explorer. You may need to view the proxy contract (For Basescan, this is under “Contracts” -> “Read as Proxy” -> “expiresAt”).
- Find the specific token ID of the NFT you want to check (“1” usually works).
- View the expiration timestamp in the “expiresAt” field in Unix (e.g. 1731699796).
- Convert the Unix timestamp to a human-readable date format at a site like Epoch Converter.
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.