Storefronts are a way to manage and sell inventory of different types of assets via SKUs (Stock Keeping Units). This allows developers to manage inventory of these assets and create and sell limited quantities as needed. A type of asset (one of OffChainAsset or NewMintUniqueAsset) needs to be created prior to creating a SKU. Once the SKU is created the asset can be purchased by an end user.

Storefront API

Types of Assets

OffChainAsset

The OffChainAsset is an asset type primarily managed by the developer, Gameshift Storefronts helps manage inventory of these types of assets and the payment related to their purchase. The delivery of this type of asset is the onus of the developer.

The off OffChainAsset can be created via the following endpoint, and it will take the following fields in the request body.

POST /nx/storefront/inventory/OffChainAsset

{
  name: string            // Required name (Will be displayed in checkout)
  imageUrl: string        // Required image URL
  maxQuantity?: number    // Optional maximum quantity
  vendorData?: Record<string, any>  // Optional vendor data
}

NewMintUniqueAsset

The NewMintUniqueAsset allows for a new asset to be minted to the buyer as a cNFT upon purchase. It can be created via a POST to the following endpoint and it takes in the fields specified below.

POST /nx/storefront/inventory/NewMintUniqueAsset

{
  name: string            // Required name 
  imageUrl: string        // Required image URL
  attributes?: {traitType: string, value: string}[]  // Optional on-chain attributes
  maxQuantity?: number    // Optional maximum quantity
  collectionId: string    // Required Gameshift collection UUID
  vendorData?: Record<string, any>  // Optional vendor data
}

SKUs

Once an asset type is created an associated SKU can be created for that asset. The SKU is a combination of an Asset along with it's price.

Note, the price is specified as a combination of currencyId and naturalAmount, where currencyId is the symbol of the currency, USDC for example, and the natural amount is the human readable amount of that currency.

A POST can be made to the SKU endpoint with the following fields in the request body:

POST /nx/storefront/skus

{
  name: string           // The name of the SKU
  price: {currencyId: string, naturalAmount: string}  // The currency and the price as a natural amount
  vendorData?: Record<string, any>  // Optional vendor data
  inventory: {          
    type: SkuType      // Type, one of NewMintUniqueAsset or OffChainAsset
    id: string         // Inventory identifier
  }
}

Storefront SDK

The JS Storefront SDK can be added to your project via script import or via npm. The script is available to import from https://api.gameshift.dev/nx/storefront/sdk

<script src="https://api.gameshift.dev/nx/storefront/sdk?v=1.0"></script>

Once the library has been added to the project it can be initialized in the following manner:

const storefront = new Storefront({
            apiKey: 'STOREFRONT_API_KEY',
            environment: "Development"
        });

Methods

listSkus

The listSkus method can take in a list of filtering parameters and return the list of available SKUs in your project. This list response can then be used to render your marketplace items.

// listSkus parameters
// page?: number;
// perPage?: number;
// priceLessThan?: string;
// priceGreaterThan?: string;
// nameContains?: string;
// type?: 'NewMintUniqueAsset' | 'OffChainAsset';
// collectionId?: string;

// Example usage
storefront.listSkus({ 
  priceLessThan: "5",
  nameContains: "MyAsset" 
}).then((results) => {
  console.log(results);
});

// Sample Response
{
  data: [{
  assetInventoryId: "713c0942-b43b-4686-96bb-1b31e515ed81",
  created: "2024-11-11T01:42:55.530Z",
  id: "57bf4030-5987-4fad-a0ee-61636eeaab09",
  inventory: {
    created: "2024-11-10T00:03:14.803Z",
    currentQuantity: 0,
    id: "713c0942-b43b-4686-96bb-1b31e515ed81",
    imageUrl: "https://example.com/image.jpg",
    maxQuantity: 1,
    name: "string",
    updated: "2024-11-13T00:03:14.803Z",
    vendorData: null
  },
  name: "MyAsset",
  price: {
    currencyId: "USDC",
    naturalAmount: "1.2"
  },
  type: "OffChainAsset",
  updated: "2024-11-13T01:42:55.530Z",
  vendorData: null
}],
    page: 1,
    perPage: 10,
    total: 1
  },
}

getSku

Gets details about a single SKU given its id.

// example
const sku = await storefront.getSku("sku-id");

// sample response
{
  data: {
    assetInventoryId: "713c0942-b43b-4686-96bb-1b31e515ed81",
    created: "2024-10-13T01:42:55.530Z",
    id: "57bf4030-5987-4fad-a0ee-61636eeaab09",
    name: "My SKU",
    price: { ... },
    type: "OffChainAsset",
    updated: "2024-10-13T01:42:55.530Z",
    vendorData: null
  },
  success: true
}

purchaseSkuImmediately

The purchaseSkuImmediately method can take details about a desired SKU, along with its quantity and userId for delivery in the case of a NewMintUniqueAsset.

// The following type is returned 

interface PurchaseResult {
  success: boolean;
  status?: 'completed' | 'cancelled' | 'failed';
  error?: string;
  data?: {
    transactionId?: string;
    orderId?: string;
    items?: Array<{
      id: string;
      quantity: number;
      price: number;
    }>;
    totalAmount?: number;
  };
}

// Sample usage
const result = 
      await storefront.purchaseSkuImmediately(
        {
          userReferenceId: "userRefId", 
          type:"NewMintUniqueAsset", // or OffChainAsset
          skuId: "sku-id",
          quantity: 1, // optional
        });