Select Items

Every order describes what the buyer is purchasing through the lineItems property — an array of items with a locator and callData.

Supported Item Types

Crossmint supports purchasing various types of digital assets:

Digital Assets
- Non-Fungible Tokens (NFTs)
- Semi-Fungible Tokens (SFTs)
- Fungible Tokens (FTs) like memecoins

All items available for purchase must comply with Crossmint's terms of service and legal requirements. Non-Fungible Collections and Fungible tokens must be reviewed and approved by Crossmint before being available in production.

Item Locator Formats

You'll use one of these locator formats in your lineItems:

Digital Assets - New Tokens
Digital Assets - Existing Tokens

collectionLocator - For minting new tokens:

crossmint:<_YOUR_COLLECTION_ID_> - For collections created in Crossmint Console (e.g. crossmint:9c82ef99-617f-497d-9abb-fd355291681b)
crossmint:<_YOUR_COLLECTION_ID_>:<_TEMPLATE_ID_> - For collections created in Crossmint Console where a specific NFT template is desired (e.g. crossmint:9c82ef99-617f-497d-9abb-fd355291681b:silver-pass)
<blockchain>:<contract-address> - Using direct contract addresses for external collections registered in Crossmint Console (e.g. ethereum:0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D).

tokenLocator - For buying existing tokens (onramp, memecoins, NFT secondaries, etc.):

EVM fungible tokens: <blockchain>:<contractAddress> (e.g. base-sepolia:0x036CbD53842c5426634e7929541eC2318f3dCF7e)
EVM NFTs: <blockchain>:<contractAddress>:<tokenId> (e.g. ethereum:0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D:1234)
Solana: solana:<mintAddress> (e.g. solana:7EivYFyNfgGj8xbUymR7J4LuxUHLKRzpLaERHLvi7Dgu)

Using tokenLocator doesn't require registering the collection in Crossmint Console.

NFT secondary purchases work in production only. Staging cannot get listings from the NFT marketplaces. To test a tokenLocator order in staging, use a fungible token.

Embedded
Hosted
Headless

<CrossmintProvider apiKey="<your-client-api-key>">
    <CrossmintEmbeddedCheckout
        lineItems={{
            collectionLocator: "crossmint:_YOUR_COLLECTION_ID_", // Crossmint managed collection
            // collectionLocator: "crossmint:_YOUR_COLLECTION_ID_:_TEMPLATE_ID_", // With specific template
            callData: {
                totalPrice: "5.00",
                quantity: 1, // matches your contract's parameter name
            },
        }}
    />
</CrossmintProvider>

<CrossmintProvider apiKey="<your-client-api-key>">
    <CrossmintEmbeddedCheckout
        lineItems={{
            tokenLocator: "base-sepolia:0x036CbD53842c5426634e7929541eC2318f3dCF7e", // USDC on Base Sepolia: <blockchain>:<contractAddress>
            executionParameters: {
                mode: "exact-in",
                amount: "5", // USD amount the buyer spends
            },
        }}
    />
</CrossmintProvider>

<CrossmintProvider apiKey="<your-client-api-key>">
    <CrossmintEmbeddedCheckout
        lineItems={{
            tokenLocator: "solana:7EivYFyNfgGj8xbUymR7J4LuxUHLKRzpLaERHLvi7Dgu", // XMEME test token: solana:<mintAddress>
            executionParameters: {
                mode: "exact-in",
                amount: "5", // USD amount the buyer spends
            },
        }}
    />
</CrossmintProvider>

You can access the current order’s item data from React with the useCrossmintCheckout hook (order?.lineItems), available inside components wrapped by CrossmintProvider and CrossmintCheckoutProvider.

<CrossmintProvider apiKey="<your-client-api-key>">
    <CrossmintHostedCheckout
        lineItems={{
            collectionLocator: "crossmint:_YOUR_COLLECTION_ID_", // Crossmint managed collection
            callData: {
                totalPrice: "5.00",
                quantity: 1, // matches your contract's parameter name
            },
        }}
    />
</CrossmintProvider>

<CrossmintProvider apiKey="<your-client-api-key>">
    <CrossmintHostedCheckout
        lineItems={{
            tokenLocator: "base-sepolia:0x036CbD53842c5426634e7929541eC2318f3dCF7e", // USDC on Base Sepolia: <blockchain>:<contractAddress>
            executionParameters: {
                mode: "exact-in",
                amount: "5", // USD amount the buyer spends
            },
        }}
    />
</CrossmintProvider>

{
  "lineItems": [
    {
      "collectionLocator": "crossmint:_YOUR_COLLECTION_ID_", // Crossmint managed collection
      // "collectionLocator": "crossmint:_YOUR_COLLECTION_ID_:_TEMPLATE_ID_", // With specific template
      "callData": {
        "totalPrice": "5.00",
        "quantity": 1 // matches your contract's parameter name
      }
    }
  ]
}
// To use exact-in mode, add executionParameters: { maxSlippageBps: "500" } to the lineItem object. For custom contract params, add executionParameters: { customParam: "value" }.

{
  "lineItems": [
    {
      "collectionLocator": "ethereum:0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D", // External collection registered in Crossmint Console
      "callData": {
        "totalPrice": "5.00",
        "quantity": 1 // matches your contract's parameter name
        // For external contracts, you might need additional parameters such as:
        // "_amount": 1, // if your mint function uses _amount instead of quantity
        // "tokenId": "123", // if your contract requires a specific tokenId
        // "metadata": "ipfs://...", // if your contract accepts metadata
      }
    }
  ]
}

{
  "lineItems": [
    {
      "tokenLocator": "solana:7EivYFyNfgGj8xbUymR7J4LuxUHLKRzpLaERHLvi7Dgu", // XMEME test token: solana:<mintAddress>
      "executionParameters": {
        "mode": "exact-in",
        "amount": "5" // USD amount the buyer spends
      }
    }
  ]
}

For external EVM contracts registered in Crossmint Console, ensure the attribute name in callData matches the parameter name in your mint function. For example: If your mint function has the signature: mintTo(address _to, uint256 _amount) then use _amount instead of quantity. See our Register External Collection guide for details on registering your contract.

The buyerCreatorRoyaltyPercent parameter controls how much of the creator royalty percentage the buyer pays when purchasing Solana NFTs through marketplaces.Marketplace Requirements:

Magic Eden: Required parameter
Tensor: Optional (defaults to NFTs’ on-chain royalty percentage)
Hadeswap: Optional (defaults to 100%)

Parameter Details:

Range: Must be between 0 and 100 (inclusive)
Impact: Always affects final price calculation by applying royalty fees
Validation: Throws error if outside valid range

Automatic 100% Enforcement: The system automatically overrides this parameter to 100% when:

Compressed NFTs: Detected when getAssetProof() returns valid proof data
Royalty-enforced NFTs: Detected when NFT has MIP1 or Cardinal Token Manager protection

Multiple Item Orders

You can enable users to purchase multiple items in a single transaction by providing an array of line items:

lineItems={[
  {
    // First item - Managed collection
    collectionLocator: "crossmint:_YOUR_COLLECTION_ID_",
    callData: {
      totalPrice: "5.00",
      quantity: 1
    }
  },
  {
    // Second item - Managed collection with template
    collectionLocator: "crossmint:_YOUR_COLLECTION_ID_:_TEMPLATE_ID_",
    callData: {
      totalPrice: "10.00",
      quantity: 2
    }
  },
  {
    // Third item - External collection
    collectionLocator: "ethereum:0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D",
    callData: {
      totalPrice: "15.00",
      quantity: 1
    }
  }
]}

lineItems={[
  {
    // First item
    tokenLocator: "ethereum:0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D:1234",
    callData: {
      totalPrice: "25.00",
      quantity: 1
    }
  },
  {
    // Second item
    tokenLocator: "ethereum:0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D:5678",
    callData: {
      totalPrice: "50.00",
      quantity: 1
    }
  }
]}

Multiple Item Limitations:

Maximum limit of 15 items per order
collectionLocator: All items must be on the same blockchain, and collections registered on the same project
tokenLocator: All items must be on the same blockchain. NFT secondary purchases work in production only.
Fungible tokens (executionParameters.mode: "exact-in"): Only 1 line item per order

Multiple line items let a buyer purchase several items in a single transaction — for example, a marketplace cart or several tokens from an ERC-1155 contract. This is currently supported for NFTs only, with a maximum of 15 NFTs per order. For secondary (marketplace) sales, each line item references a shared secondary-sales collectionId provisioned by your Crossmint Customer Success Engineer, with the specific contractAddress and tokenId in callData. See Marketplaces & Launchpads.

"lineItems": [
  {
    "collectionLocator": "crossmint:_YOUR_SECONDARY_SALES_COLLECTION_ID_",
    "callData": {
      "contractAddress": "0x___CONTRACT_ADDRESS_OF_TOKEN",
      "tokenId": "234"
    }
  },
  {
    "collectionLocator": "crossmint:_YOUR_SECONDARY_SALES_COLLECTION_ID_",
    "callData": {
      "contractAddress": "0x___ANOTHER_TOKEN_CONTRACT",
      "tokenId": "567"
    }
  }
]

Delivery is tracked per line item: when the order completes, check each item’s delivery.status individually. See How Checkout Works.

Introduction

Quickstarts ⚡

Concepts

Guides

API Reference

Select Items

Supported Item Types

Item Locator Formats

Select Items

Multiple Item Orders

Next Steps

Specify Recipient

Track Orders

​Supported Item Types

​Item Locator Formats

​Select Items

​Multiple Item Orders

​Next Steps

Specify Recipient

Track Orders

Supported Item Types

Item Locator Formats

Select Items

Multiple Item Orders

Next Steps