Item Selection

Specify which items to purchase with Hosted Checkout

The Hosted Checkout (Pay Button) allows you to specify which items your users can purchase using the lineItems property. This guide explains how to configure item selection for different asset types.

Supported Item Types

Crossmint supports purchasing various types of digital and physical assets:

• Digital Assets

  • Non-Fungible Tokens (NFTs)
  • Semi-Fungible Tokens (SFTs)
  • Fungible Tokens (FTs) including USDC (onramp) and memecoins

• Physical Products

  • Amazon products
  • Shopify products
  • Flights: Closed alpha. Contact us if you are interested to try it out
  • Coming Soon: Hotels, food delivery, and more

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

collectionLocator - For minting new tokens:

1. crossmint:<_YOUR_COLLECTION_ID_> - For collections created in Crossmint Console (e.g. crossmint:9c82ef99-617f-497d-9abb-fd355291681b)
2. 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)
3. <blockchain>:<contract-address> - Using direct contract addresses for external collections registered in Crossmint Console (e.g. ethereum:0x71c7656ec7ab88b098defb751b7401b5f6d897).

Item Selection Examples

collectionLocator

<CrossmintProvider apiKey="_YOUR_CLIENT_API_KEY_">
    <CrossmintHostedCheckout
        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>

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 NFT's 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:

collectionLocator

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:0x71c7656ec7ab88b098defb751b7401b5f6d897",
    callData: {
      totalPrice: "15.00",
      quantity: 1
    }
  }
]}

Multiple Item Limitations:

1. Maximum limit of 15 items per order
2. collectionLocator & tokenLocator: All items must be on the same blockchain
3. productLocator: Multiple items only supported in Headless Checkout (not Hosted or Embedded Checkout)
4. productLocator: All items must be from the same ecommerce platform (e.g., all Amazon or all Shopify, but not mixed)

Order Status Tracking

The Pay Button cannot use webhooks for order status tracking because it operates in a separate window. Therefore, you’ll need to implement polling to check order status through alternative methods. See the Order Status Guide for more information on tracking order completion in pay button.