Cancelling orders in Unity

In this tutorial step, you will learn how to cancel orders in your game by using the Unity Orderbook package.

This allows players to remove NFTs from the marketplace that have been previously listed for sale.

💡Prerequisite step

Before continuing with this step, ensure you have completed the previous creating orders step of this tutorial series.

Overview

Now that players can create NFT order listings, allowing them to cancel orders when needed is equally important. Using the Unity Orderbook package, along with the Unity Passport package for authentication and wallet setup, players can easily cancel their active orders. In the sample game, we've changed the sell button to a cancel button on the Asset Details screen for NFTs with active listings, which allows the player to remove their NFT from the marketplace.

Cancel an order

There are two methods for cancelling an order:

1. Soft cancellation: A method that does not require gas to cancel.

2. Hard cancellation: Involves an on-chain transaction and requires gas.

For this tutorial, we will use the hard or on-chain cancellation method. The following code demonstrates how to cancel an order on-chain.

using System;
using System.Collections.Generic;
using Cysharp.Threading.Tasks;
using Immutable.Orderbook.Api;
using Immutable.Orderbook.Client;
using Immutable.Orderbook.Model;
using Immutable.Passport;
using Immutable.Passport.Model;
using Newtonsoft.Json;
using UnityEngine;

public class CancelListingUseCase
{
    private static readonly Lazy<CancelListingUseCase> s_Instance = new(() => new CancelListingUseCase());

    private readonly OrderbookApi m_OrderbookApi = new(new Configuration { BasePath = "https://api.immutable.com" });

    private CancelListingUseCase() { }

    public static CancelListingUseCase Instance => s_Instance.Value;

    /// <summary>
    /// Cancels the specified listing.
    /// </summary>
    /// <param name="listingId">The unique identifier of the listing to cancel.</param>
    public async UniTask CancelListing(string listingId)
    {
        try
        {
            var request = new CancelOrdersOnChainRequest(
                accountAddress: SaveManager.Instance.WalletAddress, orderIds: new List<string> { listingId });

            var response = await m_OrderbookApi.CancelOrdersOnChainAsync(request);
            var transactionAction = response?.CancellationAction.PopulatedTransactions;

            if (transactionAction?.To == null)
                throw new Exception("Failed to cancel listing.");

            var txResponse = await Passport.Instance.ZkEvmSendTransactionWithConfirmation(
                new TransactionRequest
                {
                    to = transactionAction.To,
                    data = transactionAction.Data,
                    value = "0"
                });

            if (txResponse.status != "1")
                throw new Exception("Failed to cancel listing.");
        }
        catch (ApiException e)
        {
            Debug.LogError($"API Error: {e.Message} (Status: {e.ErrorCode})");
            Debug.LogError(e.ErrorContent);
            Debug.LogError(e.StackTrace);
            throw;
        }
    }
}

After cancelling the order

The order cancellation transaction is now being processed. Upon validating the required the ownership of the listing being cancelled on‑chain, the order will asynchronously transition to the CANCELLED status.

We recommend taking an optimistic view and showing the order as CANCELLED as soon as it is submitted, then polling the order status to check for updates for the most seamless player experience.

💡Status polling

You can poll the Get Listing endpoint to check on status updates. In the near future we also plan on introducing push based (webhook) integration for order events.

You can see all the different order status types in the table in the order statuses documentation.

You can also view a full example in the Unity sample game.

Next steps

Great, now you can cancel an order, removing it from the marketplace. Next we will teach you how to fill an order to purchase an NFT that is for sale in the marketplace. Click next below to continue the tutorial.