Quote Phase
Initial phase of the order lifecycle
The first phase of the headless checkout process is the quote phase. During this phase, you construct an order that consists of the items being purchased, payment method, locale, and recipient. This will ultimately yield a quote to purchase it.
You can initialize an order such that the quote phase is completed in a single API call. Alternatively, you can create a basic order and iteratively update it with locale, recipient, and payment method information. The only information you cannot edit on a quote is the lineItems array, which indicate the details of what is being purchased.
lineItems in an order you must create a new order.Quote Statuses
requires-recipientexpiredvalid
Creating the Order
You will create the order via API call. The headless checkout offers support for both client-side or server-side API keys to enable you to build in a way that makes sense for your application.
Orders can be created using a client-side API key, but any subsequent fetches or updates will require passing the
clientSecret returned in the create-order API response as an authorization header. This guide is written with
the expectation of using a server-side API key.
For more information on using Crossmint APIs refer to API keys documentation page.
To create a minimal order, make a POST request to the /api/2022-06-09/orders endpoint (view API reference). The required properties to create an order are: payment and lineItems.
The payment object indicates the method and currency you intend to make the payment with. For crypto payments, this can be the same chain of the NFT or another chain that the buyer has liquidity on.
For example, buying an NFT on BASE chain with BASE ETH, buying an NFT on Solana with SOL, or any cross-chain combination of a supported chain and currency.
The payment.method value for credit card checkouts is stripe-payment-element and the payment.currency can be any of the supported fiat currencies.
The lineItems object describes the NFTs being purchased.
For primary sales, each item must be available from the same collectionId. Currently, minting from multiple contracts in the same purchase is not supported.
Collection Locator
The collectionLocator within lineItems is how you specify the collection within Crossmint. For primary sales where the NFTs are being minted for the first time, the contract will need to be registered in the Crossmint console. You can find your collectionId within the Collections tab in the developer console.
Alternative: Token Locator
Alternatively, if this is a secondary sale, and your token is already minted and available on a supported marketplace, you instead use a tokenLocator, instead of a collectionLocator.
Using a token locator means you do not need to register the collection in the Crossmint console.
The tokenLocator for EVM Chains follows the format blockchain:contractAddress:tokenId and for Solana follows the format blockchain:tokenAddress.
More information on the tokenLocator can be found on the buy API integration guide.
Remember, you can view orders within the Developer Console to help get insight into the order process during testing and even after launch.
Updating the Order
All orders require a recipient to progress to the payment phase. You can also optionally add a specific locale, which is used to indicate the language for the email receipt sent to the buyer.
The primary reason you’ll update an existing order is when the buyer changes the payment method or currency they’d like to pay with in the UI that you build. To update the order, make a PATCH request to the /api/2022-06-09/orders/<orderId> endpoint to make these changes and receive a response with updated payment details. View API reference here.
You can update all of these fields at the same time or individually depending on what makes the most sense for your use case.
Update the Recipient
First, take a look at how to add the recipient to an existing order. The requires-recipient state occurs when you initialize a minimal order and do not include a recipient value. Valid options for the recipient property are email or walletAddress.
When you set an email recipient, the token will be minted to a Crossmint custodial wallet that can be accessed via www.crossmint.com (or staging.crossmint.com during testing).
You can update the recipient for an existing order as follows:
PATCH /api/2022-06-09/orders/<orderId>
OR
The wallet address must be compatible with the chain the NFT is on. For example, a Solana NFT requries a Solana wallet address and an NFT on an EVM chain requries a compatible EVM wallet address.
Update Chain and/or Currency
To change details about how the buyer will pay for the NFTs you use the same API route as above and pass a new payment object.
This will return a new response that can be used to prompt the buyer to complete the crypto payment.
Anytime you update the order you must ensure you use the newly returned payment.preparation.serializedTransaction
to construct the transaction.
Update the Locale
As mentioned above, the locale is used to set the language and currency for the email receipt sent to your buyer. The default is en-US.
Below is an example of the body you’d pass to update the locale setting:
The available locale values are:
en-US, de-DE, es-ES, fr-FR, it-IT, ja-JP, ko-KR, pt-PT, ru-RU th-TH tr-TR uk-UA vi-VN zh-CN zh-TW, Klingon
Quote Expiration
The time before expiration depends on the payment method chosen. Check the quote.expiresAt property to determine how long the quote is valid for. Additionally, the quote.status property will be set to expired if this timeframe is exceeded.
If your quote has expired you’ll need to create a new order.