Cancel orders

Once an order has been listed, it can be canceled if the player no longer wants to sell their NFT.

An order can only be cancelled before it has been filled by another player.

💡Who is this for?

Developers who want to build an in-game marketplace in Unity.

💡Alpha version

This module is experimental and may change in the future. We recommend using it for testing purposes only.

Overview

To cancel an order, the player needs to sign a cancel order transaction that includes the listing ID of the order they want to cancel and the player's wallet address.

Below is the full code example that demonstrate the essential parts of each of these steps. If you want to see the full implementation, you can take a look at CreateOrderUseCase.cs in our Unity sample game and the Build a game with Unity tutorial.

For more details on each step, refer to the Typescript Orderbook specification.

💡Inventory

To display a gamer's NFT inventory, you can use the Unity zkEVM API package. For an example, refer to this page.

Cancel order workflow

📋Prerequisites

Ensure you have completed the following prerequisites:

Passport package setup
Orderbook package setup
Login
Initialise provider and connect wallet
Link all game contracts to the Immutable Hub to enable pre-approved transactions. For detailed instructions, please refer to the guide here.

The process of cancelling an order is done by preparing the cancellation request and submitting it:

1. Submit the cancel order

Unlike creating or filling an order, it's assumed the player already has approved your collection to interact with the Immutable Orderbook to create their listing, so you don't need to sign and submit an approval transaction.

You only need to sign and submit the cancel order transaction by calling CancelOrdersOnChainAsync as shown below.

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: LOGGED_IN_WALLET, // Replace with player's wallet
                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.

Cancel orders

Overview​

Cancel order workflow​

1. Submit the cancel order​

After cancelling the order​

Overview

Cancel order workflow

1. Submit the cancel order

After cancelling the order