Mint to Specific Template

Specify which NFT template to mint from during checkout (for Managed collections only)

Overview

When minting NFTs from a collection with multiple templates, you can specify which template to mint to using your Crossmint integration. This feature must be explicitly enabled in the Crossmint Console.

This gives you control over exactly which template gets minted when processing a purchase, rather than relying on random template selection.

Supported Collection Types

Template minting is supported for Managed EVM collections only:

• Managed ERC-721 and ERC-1155 collections created in the Crossmint Console

Template minting is not available for:

• Solana collections
• Aptos collections

Enabling Template Minting

Follow these steps in the Crossmint Console to enable template-specific minting:

1. Go to your collection in the Crossmint Console
2. Navigate to the “Payments” section
3. Under “NFT Template Settings”, enable “Mint to specific NFT Template”

Using Template IDs

If template-specific minting is disabled for your collection and you pass a template ID in the collection locator, the request will fail with an error. Make sure to enable this feature in the Console before using template IDs.

To see all your available templates, navigate to the “NFTs” section in the Console for your managed collection.

You can also get all your available templates for a collection using the NFT Template API.

Once enabled, specify which template to mint by adding the template ID to your collection locator. The collection locator format without templateId is:

crossmint:<collectionId>

and with templateId is:

crossmint:<collectionId>:<templateId>

The templateId portion is optional with mint to specific template enabled. If omitted, the system will use your collection’s default minting behavior.

Here’s how to implement template minting in your integration:

Embedded Checkout v3

Add the template ID to your collection locator string:

<CrossmintProvider apiKey={clientApiKey}>
  <CrossmintEmbeddedCheckout
    lineItems={{
      // For a specific template:
      collectionLocator: `crossmint:${collectionId}:${templateId}`,
      // Or for random template selection:
      // collectionLocator: `crossmint:${collectionId}`,
      callData: {
        totalPrice: "0.001",
        quantity: 1,
      },
    }}
  />
</CrossmintProvider>

Add the template ID to your collection locator string:

<CrossmintProvider apiKey={clientApiKey}>
  <CrossmintEmbeddedCheckout
    lineItems={{
      // For a specific template:
      collectionLocator: `crossmint:${collectionId}:${templateId}`,
      // Or for random template selection:
      // collectionLocator: `crossmint:${collectionId}`,
      callData: {
        totalPrice: "0.001",
        quantity: 1,
      },
    }}
  />
</CrossmintProvider>

Add the template ID to your collection locator string when creating an order:

{
  "payment": {
    "method": "stripe-payment-element"  // or your preferred payment method
  },
  "lineItems": {
    // For a specific template:
    "collectionLocator": "crossmint:<collectionId>:<templateId>",
    // Or for random template selection:
    // "collectionLocator": "crossmint:<collectionId>",
    "callData": {
      "totalPrice": "0.001"
    }
  }
}

Error Handling

When implementing template minting, handle these potential error cases:

1. Template Minting Disabled

   • Error message: “Error - Mint to specific template must be enabled in Crossmint console”
   • Occurs when: Using a template ID while the feature is disabled in the console
   • Resolution: Enable template minting in the console settings

2. Invalid Template ID

   • Error message: Transaction fails with template validation error
   • Occurs when: The specified template ID doesn’t exist in the collection
   • Resolution: Verify the template ID exists in your collection

3. No Code Storefront

   • Mint to specific template is not currently supported on No Code Storefront. If you’d like this feature, please reach out to your CSE rep

Here’s how to handle these errors in your code:

Embedded Checkout v3

try {
  <CrossmintProvider apiKey={clientApiKey}>
    <CrossmintEmbeddedCheckout
      lineItems={{
        collectionLocator: `crossmint:${collectionId}:${templateId}`,
        callData: {
          totalPrice: "0.001",
          quantity: 1,
        },
      }}
      onError={(error) => {
        if (error.message.includes("must be enabled")) {
          // Template minting is disabled
          console.error("Please enable template minting in the console");
        } else if (error.message.includes("template")) {
          // Invalid template ID
          console.error("Invalid template ID provided");
        }
      }}
    />
  </CrossmintProvider>
} catch (error) {
  // Handle other errors
  console.error("Minting failed:", error);
}

try {
  <CrossmintProvider apiKey={clientApiKey}>
    <CrossmintEmbeddedCheckout
      lineItems={{
        collectionLocator: `crossmint:${collectionId}:${templateId}`,
        callData: {
          totalPrice: "0.001",
          quantity: 1,
        },
      }}
      onError={(error) => {
        if (error.message.includes("must be enabled")) {
          // Template minting is disabled
          console.error("Please enable template minting in the console");
        } else if (error.message.includes("template")) {
          // Invalid template ID
          console.error("Invalid template ID provided");
        }
      }}
    />
  </CrossmintProvider>
} catch (error) {
  // Handle other errors
  console.error("Minting failed:", error);
}

try {
  const response = await fetch("/api/create-order", {
    method: "POST",
    body: JSON.stringify({
      lineItems: {
        collectionLocator: `crossmint:${collectionId}:${templateId}`,
        callData: {
          totalPrice: "0.001"
        }
      }
    })
  });

  if (!response.ok) {
    const error = await response.json();
    if (error.message.includes("must be enabled")) {
      // Template minting is disabled
      throw new Error("Please enable template minting in the console");
    } else if (error.message.includes("template")) {
      // Invalid template ID
      throw new Error("Invalid template ID provided");
    }
    throw error;
  }
} catch (error) {
  // Handle the error appropriately
  console.error("Order creation failed:", error);
}