Multiple Line Items

How to handle orders with multiple NFTs at once

The Headless Checkout multiple line items feature is used to build more elaborate purchase experiences, which require multiple NFT purchases at once. Multiple line items is currently only supported for NFTs.

Currently, there is a maximum limit of 15 NFTs per order.

Example use cases include:

• A marketplace where a buyer can add multiple NFTs to a cart and make the purchase in a single transaction.
• Enabling the purchase of multiple distinct tokens from an ERC-1155 contract in a single transaction.

Marketplace Sales

The following example requires that you have a custom collectionId that supports secondary sales provisioned for you by your Crossmint Customer Success Engineer. For more information on marketplace and launchpad support, check this guide.

If you need to contact the team about getting set up with reservoir-powered secondary sales support contact the team.

Multiple lineItems for Secondary Sales

To enable a multi item purchase, you simply need to pass an array of lineItems instead of a single object when creating an order.

The below examples demonstrate how to create a multiple line item order for secondary sales:

cURL

curl --request POST \
  --url https://staging.crossmint.com/api/2022-06-09/orders \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: _YOUR_API_KEY_' \
  --data '{
    "recipient": {
      "email": "[e-mail]"
    },
    "locale": "en-US",
    "payment": {
      "receiptEmail": "[e-mail]",
      "method": "ethereum-sepolia",
      "currency": "eth"
    },
    "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"
        }
      }
    ]
  }'

After this step you will collect payment from the buyer as outlined in the Order Lifecycle section.

Primary Sales of Multiple Items

Headless checkout currently only supports a single collectionId per order. This means the most common scenario where it makes sense to create a multiple line item order for primary sales is an ERC-1155 semi-fungible contract. This type of NFT contract supports minting distinct tokens by specifying the tokenId, whereas in ERC-721 style contract every token is unique and thus you only need to pass a quantity parameter to mint multiple. Using multiple line items for a standard ERC-721 contract would result in multiple mint transactions against the contract when only one is required.

If you have a custom ERC-721 contract that supports the minter being able to specify which token they want to mint you could use the example(s) below to enable them to purchase multiple and specific tokens in the same transaction. This is an uncommon pattern for ERC-721 contracts though.

In the following example, the use case is purchasing two unique tokens from an ERC-1155 contract. You can see that the _id passed in the callData of each lineItem is unique (1 and 2).

cURL

curl --request POST \
  --url https://staging.crossmint.com/api/2022-06-09/orders \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: _YOUR_API_KEY_' \
  --data '{
  "recipient": {
    "email": "[e-mail]"
  },
  "locale": "en-US",
  "payment": {
    "receiptEmail": "[e-mail]",
    "method": "ethereum-sepolia",
    "currency": "eth"
  },
  "lineItems": [
    {
      "collectionLocator": "crossmint:_YOUR_COLLECTION_ID_",
      "callData": {
        "_id_": "1",
        "_quantity": "1"
      }
    },
    {
      "collectionLocator": "crossmint:_YOUR_COLLECTION_ID_",
      "callData": {
        "_id_": "2",
        "_quantity": "1"
      }
    },
  ]
}'

As in the secondary sales example above, you’ll need to handle the remaining steps of the order lifecycle in your UI - payment, delivery, etc.

Error Handling

As outlined in the Delivery Phase of the order lifecycle guides, it is important to keep track of the delivery for each item passed when you created the order and report back to the user on the status of the order.

Each line item is attempted and processed independently. If one line item fails, others will still go through and be fulfilled. If any items are undeliverable, the buyer will be automatically refunded for that specific portion of their order.