The Headless Checkout API 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:

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).

​
JSON Item Selection Examples

{
  "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" }.

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

​
Complete API Request Examples

For those who want a full copy/pastable code example, extended versions of the JSON guides are provided below.

const options = {
    method: "POST",
    headers: { "X-API-KEY": "_YOUR_API_KEY_", "Content-Type": "application/json" },
    body: JSON.stringify({
        recipient: {
            email: "buyer@example.com",
        },
        payment: {
            method: "ethereum-sepolia",
            currency: "eth",
        },
        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
            },
        },
    }),
};

fetch("https://staging.crossmint.com/api/2022-06-09/orders", options)
    .then((response) => response.json())
    .then((response) => console.log(response))
    .catch((err) => console.error(err));

For more details on physical product purchases, see our guides for Amazon Integration and Shopify Integration.

​
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: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)