Storefronts
Interact with the Gameshift Storefront API
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
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
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
});
Updated 17 days ago