Managing Collections

This guide shows how to create and manage Core Collections on Solana using the Metaplex Core SDK. Collections group related Assets together under a shared identity with collection-level metadata and plugins.

Summary

A Collection is a Core account that groups related Assets together. It stores collection metadata (name, image, description) and can hold plugins that apply to all Assets in the collection.

• Collections act as the "front cover" for a group of Assets
• Assets reference their Collection via the collection field
• Collection plugins (like Royalties) can apply to all member Assets
• Creating a Collection costs ~0.0015 SOL

Out of Scope

Token Metadata Collections (use mpl-token-metadata), compressed NFT collections (use Bubblegum), and migrating existing collections to Core.

Quick Start

Jump to: Create Collection · With Plugins · Fetch · Update

1. Install: npm install @metaplex-foundation/mpl-core @metaplex-foundation/umi
2. Upload collection metadata JSON to get a URI
3. Call createCollection(umi, { collection, name, uri })
4. Pass collection address when creating Assets

Prerequisites

• Umi configured with a signer and RPC connection
• SOL for transaction fees (~0.002 SOL per collection)
• Metadata JSON uploaded to Arweave/IPFS with collection image

What are Collections?

Collections are a group of Assets that belong together, part of the same series, or group. In order to group Assets together, we must first create a Collection Asset whose purpose is to store any metadata related to that collection such as collection name and collection image. The Collection Asset acts as a front cover to your collection and can also store collection wide plugins. The data that is stored and accessible from the Collection Asset is as follows;

Creating a Collection

To create a Core Collection you can use the CreateCollection instruction like this:

Creating a Simple Collection

The following snippet creates a simple collection without Plugins or anything special.

1import { createUmi } from '@metaplex-foundation/umi-bundle-defaults'
2import { createCollection } from '@metaplex-foundation/mpl-core'
3import { mplCore } from '@metaplex-foundation/mpl-core'
4import { generateSigner } from '@metaplex-foundation/umi'
5
6// Initialize UMI
7const umi = createUmi('https://api.devnet.solana.com')
8  .use(mplCore())
9
10// Generate a new keypair for the collection
11const collectionSigner = generateSigner(umi)
12
13// Create a new Collection
14await createCollection(umi, {
15  collection: collectionSigner,
16  name: 'My Collection',
17  uri: 'https://example.com/collection.json',
18}).sendAndConfirm(umi)
19
20console.log('Collection created:', collectionSigner.publicKey)

Creating a Collection with Plugins

The following snippet creates a collection with the Royalties Plugin attached. You can attach additional plugins as described here.

import { generateSigner, publicKey } from '@metaplex-foundation/umi'
import { createCollection, ruleSet } from '@metaplex-foundation/mpl-core'
const collectionSigner = generateSigner(umi)
const creator1 = publicKey('11111111111111111111111111111111')
const creator2 = publicKey('22222222222222222222222222222222')
await createCollection(umi, {
  collection: collectionSigner,
  name: 'My NFT',
  uri: 'https://example.com/my-nft.json',
  plugins: [
    {
      type: 'Royalties',
      basisPoints: 500,
      creators: [
        {
          address: creator1,
          percentage: 20,
        },
        {
          address: creator2,
          percentage: 80,
        },
      ],
      ruleSet: ruleSet('None'), // Compatibility rule set
    },
  ],
}).sendAndConfirm(umi)

Fetch a Collection

To fetch a collection the following function can be used:

import { fetchCollectionV1 } from '@metaplex-foundation/mpl-core'
import { publicKey } from '@metaplex-foundation/umi'
const collectionId = publicKey('11111111111111111111111111111111')
const collection = await fetchCollection(umi, collectionId)
console.log(collection)

Updating a Collection

To update the data of a Core Collection use the UpdateCollection instruction. For example, you use this instruction to change the name of a collection.

import { publicKey } from '@metaplex-foundation/umi'
import { updateCollection } from '@metaplex-foundation/mpl-core'
const collectionAddress = publicKey('1111111111111111111111111111111')
await updateCollection(umi, {
  collection: collectionAddress,
  name: 'my-nft',
  uri: 'https://exmaple.com/new-uri',
}).sendAndConfirm(umi)

Updating a Collection Plugin

If you want to change the behaviour of a plugin that is attached to a Core Collection you may want to use the updateCollectionPlugin instruction.

import { publicKey } from '@metaplex-foundation/umi'
import { updateCollectionPlugin, ruleSet } from '@metaplex-foundation/mpl-core'
const collectionAddress = publicKey('1111111111111111111111111111111')
const newCreator = publicKey('5555555555555555555555555555555')
await updateCollectionPlugin(umi, {
  collection: collectionAddress,
  plugin: {
    type: 'Royalties',
    basisPoints: 400,
    creators: [{ address: newCreator, percentage: 100 }],
    ruleSet: ruleSet('None'),
  },
}).sendAndConfirm(umi)

Common Errors

Collection account already exists

The collection keypair was already used. Generate a new signer:

const collectionSigner = generateSigner(umi) // Must be unique

Authority mismatch

You're not the update authority of the collection. Check the collection's updateAuthority field matches your signer.

Insufficient funds

Your payer wallet needs ~0.002 SOL. Fund it with:

solana airdrop 1 <WALLET_ADDRESS> --url devnet

Notes

• The collection parameter must be a new keypair when creating
• Collection plugins are inherited by Assets unless overridden at the Asset level
• Use fetchCollection to verify collection state after creation
• The numMinted counter tracks total Assets ever created (not current size)

Quick Reference

Program ID

Minimum Code

import { generateSigner } from '@metaplex-foundation/umi'
import { createCollection } from '@metaplex-foundation/mpl-core'
const collection = generateSigner(umi)
await createCollection(umi, { collection, name: 'My Collection', uri: 'https://...' }).sendAndConfirm(umi)

Cost Breakdown

FAQ

What's the difference between a Collection and an Asset?

A Collection is a container that groups Assets together. It has its own metadata (name, image) but cannot be owned or transferred like an Asset. Assets are the actual NFTs that users own.

Can I add an existing Asset to a Collection?

Yes, use the update instruction with the newCollection parameter. The Asset's update authority must have permission to add it to the target Collection.

Do I need a Collection for my NFTs?

No. Assets can exist standalone without a Collection. However, Collections enable collection-level royalties, easier discoverability, and batch operations.

Can I remove an Asset from a Collection?

Yes, use the update instruction to change the Asset's collection. You need the appropriate authority on both the Asset and Collection.

What happens if I delete a Collection?

Collections cannot be deleted while they contain Assets. Remove all Assets first, then the Collection account can be closed.

Glossary