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 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"
        }
      }
    ]
  }'

const options = {
  method: 'POST',
  headers: {'x-api-key': '_YOUR_API_KEY_', 'Content-Type': 'application/json'},
  body: '{
    "recipient": {
      "email": "[e-mail]"
    },
    "locale": "en-US",
    "payment": {
      "receiptEmail": "[e-mail]",
      "method": "ethereum-sepolia",
      "currency": "eth",
      "payerAddress": "0x1234_payer_address"
    },
    "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"
        }
      }
    ]
  }'
};

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

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

Primary Sales of Multiple Items

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"
      }
    },
  ]
}'

const options = {
  method: 'POST',
  headers: {'x-api-key': '_YOUR_API_KEY_', 'Content-Type': 'application/json'},
  body: '{
      "recipient":
      {
          "email": "[e-mail]"
      },
      "locale": "en-US",
      "payment":
      {
          "receiptEmail": "[e-mail]",
          "method": "ethereum-sepolia",
          "currency": "eth",
          "payerAddress": "0x1234_payer_address"
      },
      "lineItems": [
        {
          "collectionLocator": "crossmint:_YOUR_COLLECTION_ID_",
          "callData": {
            "_id_": "1",
            "quantity": "1"
          }
        },
        {
          "collectionLocator": "crossmint:_YOUR_COLLECTION_ID_",
          "callData": {
            "_id_": "2",
            "quantity": "1"
          }
        },
      ]
    }'
  };

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

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. For definitions of delivery and line item statuses, see the Status Codes page.