Products

API: Internal/Beta

Products define the services exposed by a Provider.

Rationale

Providers expose services into UCloud. But, different Providers expose different services. UCloud uses Products to define the services of a Provider. As an example, a Provider might have the following services:

  • Storage: Two tiers of storage. Fast storage, for short-lived data. Slower storage, for long-term data storage.

  • Compute: Three tiers of compute. Slim nodes for ordinary computations. Fat nodes for memory-hungry applications. GPU powered nodes for artificial intelligence.

For many Providers, the story doesn’t stop here. You can often allocate your Jobs on a machine “slice”. This can increase overall utilization, as users aren’t forced to request full nodes. A Provider might advertise the following slices:

Name vCPU RAM (GB) GPU Price
example-slim-1 1 4 0 0,100 DKK/hr
example-slim-2 2 8 0 0,200 DKK/hr
example-slim-4 4 16 0 0,400 DKK/hr
example-slim-8 8 32 0 0,800 DKK/hr

Table: A single node-type split up into individual slices.

Concepts

UCloud represent these concepts in the following abstractions:

Below, we show an example of how a Provider can organize their services.

Figure: All Products in UCloud are of a specific type, such as: STORAGE and COMPUTE. Providers have zero or more categories of every type, e.g. example-slim. In a given category, the Provider has one or more slices.

Payment Model

UCloud uses a flexible payment model, which allows Providers to use a model which is familiar to them. In short, a Provider must first choose one of the following payment types:

  1. Differential models (ChargeType.DIFFERENTIAL_QUOTA)

    1. Quota (ProductPriceUnit.PER_UNIT)

  2. Absolute models (ChargeType.ABSOLUTE)

    1. One-time payment (ProductPriceUnit.PER_UNIT and ProductPriceUnit.CREDITS_PER_UNIT)

    2. Periodic payment (ProductPriceUnit.UNITS_PER_X and ProductPriceUnit.CREDITS_PER_X)


📝 NOTE: To select a model, you must specify a ChargeType and a ProductPriceUnit. We have shown all valid combinations above.


Quotas put a strict limit on the “number of units” in concurrent use. UCloud measures this number in a Product specific way. A unit is pre-defined and stable across the entirety of UCloud. A few quick examples:

  • Storage: Measured in GB (10⁹ bytes. 1 byte = 1 octet)

  • Compute: Measured in hyper-threaded cores (vCPU)

  • Public IPs: Measured in IP addresses

  • Public links: Measured in public links

If using an absolute model, then you must choose the unit of allocation:

  • You specify allocations in units (UNITS_PER_X). For example: 3000 IP addresses.

  • You specify allocations in money (CREDITS_PER_X). For example: 1000 DKK.


📝 NOTE: For precision purposes, UCloud specifies all money sums as integers. As a result, 1 UCloud credit is equal to one millionth of a Danish Crown (DKK).


When using periodic payments, you must also specify the length of a single period. Providers are not required to report usage once for every period. But the reporting itself must specify usage in number of periods. UCloud supports period lengths of a minute, one hour and one day.

Understanding the price

All Products have a pricePerUnit property:

The pricePerUnit specifies the cost of a single unit in a single period.

Products not paid with credits must have a pricePerUnit of 1. Quotas and one-time payments are always made for a single “period”.

This can lead to some surprising results when defining compute products. Let’s consider the example from the beginning:

Name vCPU RAM (GB) GPU Price
example-slim-1 1 4 0 0,100 DKK/hr
example-slim-2 2 8 0 0,200 DKK/hr
example-slim-4 4 16 0 0,400 DKK/hr
example-slim-8 8 32 0 0,800 DKK/hr

Table: Human-readable compute products.

When implementing this in UCloud, a Provider might naively set the following prices:

Name ChargeType ProductPriceUnit Price
example-slim-1 ABSOLUTE CREDITS_PER_HOUR 100_000
example-slim-2 ABSOLUTE CREDITS_PER_HOUR 200_000
example-slim-4 ABSOLUTE CREDITS_PER_HOUR 400_000
example-slim-8 ABSOLUTE CREDITS_PER_HOUR 800_000

Table: ️⚠️ Incorrect implementation of prices in UCloud ️⚠️

This is wrong. UCloud defines the price as the cost of using a single unit in a single period. The “unit of use” for a compute product is a single vCPU. Thus, a correct Provider implementation would over-report the usage by a factor equal to the number of vCPUs in the machine. Instead, the price must be based on a single vCPU:

Name ChargeType ProductPriceUnit Price
example-slim-1 ABSOLUTE CREDITS_PER_HOUR 100_000
example-slim-2 ABSOLUTE CREDITS_PER_HOUR 100_000
example-slim-4 ABSOLUTE CREDITS_PER_HOUR 100_000
example-slim-8 ABSOLUTE CREDITS_PER_HOUR 100_000

Table: ✅ Correct implementation of prices in UCloud ✅

Table of Contents

1. Examples
Description
Browse all available products
Browse products by type
Retrieve a single product
2. Remote Procedure Calls
Name Description
browse Browse a set of products
retrieve Retrieve a single product
create Creates a new [`Product`](/docs/reference/dk.sdu.cloud.accounting.api.Product.md) in UCloud
3. Data Models
Name Description
ChargeType No description
Product Products define the services exposed by a Provider.
Product.Compute A compute Product
Product.Ingress An ingress Product
Product.License A license Product
Product.NetworkIP An IP address Product
Product.Storage A storage Product
ProductCategoryId No description
ProductPriceUnit No description
ProductReference Contains a unique reference to a [Product](/backend/accounting-service/README.md)
ProductType A classifier for a [`Product`](/docs/reference/dk.sdu.cloud.accounting.api.Product.md)
ProductsBrowseRequest The base type for requesting paginated content.
ProductsRetrieveRequest No description

Example: Browse all available products

Frequency of useCommon
Actors
  • An authenticated user (user)
Communication Flow: Kotlin
Products.browse.call(
    ProductsBrowseRequest(
        consistency = null, 
        filterArea = null, 
        filterCategory = null, 
        filterName = null, 
        filterProvider = null, 
        filterVersion = null, 
        includeBalance = null, 
        itemsPerPage = 50, 
        itemsToSkip = null, 
        next = null, 
        showAllVersions = null, 
    ),
    user
).orThrow()

/*
PageV2(
    items = listOf(Product.Compute(
        category = ProductCategoryId(
            id = "example-compute", 
            name = "example-compute", 
            provider = "example", 
        ), 
        chargeType = ChargeType.ABSOLUTE, 
        cpu = 10, 
        description = "An example compute product", 
        freeToUse = false, 
        gpu = 0, 
        hiddenInGrantApplications = false, 
        memoryInGigs = 20, 
        name = "example-compute", 
        pricePerUnit = 1000000, 
        priority = 0, 
        productType = ProductType.COMPUTE, 
        unitOfPrice = ProductPriceUnit.CREDITS_PER_MINUTE, 
        version = 1, 
        balance = null, 
        id = "example-compute", 
    ), Product.Storage(
        category = ProductCategoryId(
            id = "example-storage", 
            name = "example-storage", 
            provider = "example", 
        ), 
        chargeType = ChargeType.DIFFERENTIAL_QUOTA, 
        description = "An example storage product (Quota)", 
        freeToUse = false, 
        hiddenInGrantApplications = false, 
        name = "example-storage", 
        pricePerUnit = 1, 
        priority = 0, 
        productType = ProductType.STORAGE, 
        unitOfPrice = ProductPriceUnit.PER_UNIT, 
        version = 1, 
        balance = null, 
        id = "example-storage", 
    )), 
    itemsPerPage = 50, 
    next = null, 
)
*/
Communication Flow: TypeScript
// Authenticated as user
await callAPI(ProductsApi.browse(
    {
        "itemsPerPage": 50,
        "next": null,
        "consistency": null,
        "itemsToSkip": null,
        "filterName": null,
        "filterProvider": null,
        "filterArea": null,
        "filterCategory": null,
        "filterVersion": null,
        "showAllVersions": null,
        "includeBalance": null
    }
);

/*
{
    "itemsPerPage": 50,
    "items": [
        {
            "type": "compute",
            "balance": null,
            "name": "example-compute",
            "pricePerUnit": 1000000,
            "category": {
                "name": "example-compute",
                "provider": "example"
            },
            "description": "An example compute product",
            "priority": 0,
            "cpu": 10,
            "memoryInGigs": 20,
            "gpu": 0,
            "version": 1,
            "freeToUse": false,
            "unitOfPrice": "CREDITS_PER_MINUTE",
            "chargeType": "ABSOLUTE",
            "hiddenInGrantApplications": false,
            "productType": "COMPUTE"
        },
        {
            "type": "storage",
            "balance": null,
            "name": "example-storage",
            "pricePerUnit": 1,
            "category": {
                "name": "example-storage",
                "provider": "example"
            },
            "description": "An example storage product (Quota)",
            "priority": 0,
            "version": 1,
            "freeToUse": false,
            "unitOfPrice": "PER_UNIT",
            "chargeType": "DIFFERENTIAL_QUOTA",
            "hiddenInGrantApplications": false,
            "productType": "STORAGE"
        }
    ],
    "next": null
}
*/
Communication Flow: Curl
# ------------------------------------------------------------------------------------------------------
# $host is the UCloud instance to contact. Example: 'http://localhost:8080' or 'https://cloud.sdu.dk'
# $accessToken is a valid access-token issued by UCloud
# ------------------------------------------------------------------------------------------------------

# Authenticated as user
curl -XGET -H "Authorization: Bearer $accessToken" "$host/api/products/browse?itemsPerPage=50" 

# {
#     "itemsPerPage": 50,
#     "items": [
#         {
#             "type": "compute",
#             "balance": null,
#             "name": "example-compute",
#             "pricePerUnit": 1000000,
#             "category": {
#                 "name": "example-compute",
#                 "provider": "example"
#             },
#             "description": "An example compute product",
#             "priority": 0,
#             "cpu": 10,
#             "memoryInGigs": 20,
#             "gpu": 0,
#             "version": 1,
#             "freeToUse": false,
#             "unitOfPrice": "CREDITS_PER_MINUTE",
#             "chargeType": "ABSOLUTE",
#             "hiddenInGrantApplications": false,
#             "productType": "COMPUTE"
#         },
#         {
#             "type": "storage",
#             "balance": null,
#             "name": "example-storage",
#             "pricePerUnit": 1,
#             "category": {
#                 "name": "example-storage",
#                 "provider": "example"
#             },
#             "description": "An example storage product (Quota)",
#             "priority": 0,
#             "version": 1,
#             "freeToUse": false,
#             "unitOfPrice": "PER_UNIT",
#             "chargeType": "DIFFERENTIAL_QUOTA",
#             "hiddenInGrantApplications": false,
#             "productType": "STORAGE"
#         }
#     ],
#     "next": null
# }
Communication Flow: Visual

Example: Browse products by type

Frequency of useCommon
Actors
  • An authenticated user (user)
Communication Flow: Kotlin
Products.browse.call(
    ProductsBrowseRequest(
        consistency = null, 
        filterArea = ProductType.COMPUTE, 
        filterCategory = null, 
        filterName = null, 
        filterProvider = null, 
        filterVersion = null, 
        includeBalance = null, 
        itemsPerPage = 50, 
        itemsToSkip = null, 
        next = null, 
        showAllVersions = null, 
    ),
    user
).orThrow()

/*
PageV2(
    items = listOf(Product.Compute(
        category = ProductCategoryId(
            id = "example-compute", 
            name = "example-compute", 
            provider = "example", 
        ), 
        chargeType = ChargeType.ABSOLUTE, 
        cpu = 10, 
        description = "An example compute product", 
        freeToUse = false, 
        gpu = 0, 
        hiddenInGrantApplications = false, 
        memoryInGigs = 20, 
        name = "example-compute", 
        pricePerUnit = 1000000, 
        priority = 0, 
        productType = ProductType.COMPUTE, 
        unitOfPrice = ProductPriceUnit.CREDITS_PER_MINUTE, 
        version = 1, 
        balance = null, 
        id = "example-compute", 
    )), 
    itemsPerPage = 50, 
    next = null, 
)
*/
Communication Flow: TypeScript
// Authenticated as user
await callAPI(ProductsApi.browse(
    {
        "itemsPerPage": 50,
        "next": null,
        "consistency": null,
        "itemsToSkip": null,
        "filterName": null,
        "filterProvider": null,
        "filterArea": "COMPUTE",
        "filterCategory": null,
        "filterVersion": null,
        "showAllVersions": null,
        "includeBalance": null
    }
);

/*
{
    "itemsPerPage": 50,
    "items": [
        {
            "type": "compute",
            "balance": null,
            "name": "example-compute",
            "pricePerUnit": 1000000,
            "category": {
                "name": "example-compute",
                "provider": "example"
            },
            "description": "An example compute product",
            "priority": 0,
            "cpu": 10,
            "memoryInGigs": 20,
            "gpu": 0,
            "version": 1,
            "freeToUse": false,
            "unitOfPrice": "CREDITS_PER_MINUTE",
            "chargeType": "ABSOLUTE",
            "hiddenInGrantApplications": false,
            "productType": "COMPUTE"
        }
    ],
    "next": null
}
*/
Communication Flow: Curl
# ------------------------------------------------------------------------------------------------------
# $host is the UCloud instance to contact. Example: 'http://localhost:8080' or 'https://cloud.sdu.dk'
# $accessToken is a valid access-token issued by UCloud
# ------------------------------------------------------------------------------------------------------

# Authenticated as user
curl -XGET -H "Authorization: Bearer $accessToken" "$host/api/products/browse?itemsPerPage=50&filterArea=COMPUTE" 

# {
#     "itemsPerPage": 50,
#     "items": [
#         {
#             "type": "compute",
#             "balance": null,
#             "name": "example-compute",
#             "pricePerUnit": 1000000,
#             "category": {
#                 "name": "example-compute",
#                 "provider": "example"
#             },
#             "description": "An example compute product",
#             "priority": 0,
#             "cpu": 10,
#             "memoryInGigs": 20,
#             "gpu": 0,
#             "version": 1,
#             "freeToUse": false,
#             "unitOfPrice": "CREDITS_PER_MINUTE",
#             "chargeType": "ABSOLUTE",
#             "hiddenInGrantApplications": false,
#             "productType": "COMPUTE"
#         }
#     ],
#     "next": null
# }
Communication Flow: Visual

Example: Retrieve a single product

Frequency of useCommon
Actors
  • An authenticated user (user)
Communication Flow: Kotlin
Products.retrieve.call(
    ProductsRetrieveRequest(
        filterArea = null, 
        filterCategory = "example-compute", 
        filterName = "example-compute", 
        filterProvider = "example", 
        filterVersion = null, 
        includeBalance = null, 
    ),
    user
).orThrow()

/*
Product.Compute(
    category = ProductCategoryId(
        id = "example-compute", 
        name = "example-compute", 
        provider = "example", 
    ), 
    chargeType = ChargeType.ABSOLUTE, 
    cpu = 10, 
    description = "An example compute product", 
    freeToUse = false, 
    gpu = 0, 
    hiddenInGrantApplications = false, 
    memoryInGigs = 20, 
    name = "example-compute", 
    pricePerUnit = 1000000, 
    priority = 0, 
    productType = ProductType.COMPUTE, 
    unitOfPrice = ProductPriceUnit.CREDITS_PER_MINUTE, 
    version = 1, 
    balance = null, 
    id = "example-compute", 
)
*/
Communication Flow: TypeScript
// Authenticated as user
await callAPI(ProductsApi.retrieve(
    {
        "filterName": "example-compute",
        "filterCategory": "example-compute",
        "filterProvider": "example",
        "filterArea": null,
        "filterVersion": null,
        "includeBalance": null
    }
);

/*
{
    "type": "compute",
    "balance": null,
    "name": "example-compute",
    "pricePerUnit": 1000000,
    "category": {
        "name": "example-compute",
        "provider": "example"
    },
    "description": "An example compute product",
    "priority": 0,
    "cpu": 10,
    "memoryInGigs": 20,
    "gpu": 0,
    "version": 1,
    "freeToUse": false,
    "unitOfPrice": "CREDITS_PER_MINUTE",
    "chargeType": "ABSOLUTE",
    "hiddenInGrantApplications": false,
    "productType": "COMPUTE"
}
*/
Communication Flow: Curl
# ------------------------------------------------------------------------------------------------------
# $host is the UCloud instance to contact. Example: 'http://localhost:8080' or 'https://cloud.sdu.dk'
# $accessToken is a valid access-token issued by UCloud
# ------------------------------------------------------------------------------------------------------

# Authenticated as user
curl -XGET -H "Authorization: Bearer $accessToken" "$host/api/products/retrieve?filterName=example-compute&filterCategory=example-compute&filterProvider=example" 

# {
#     "type": "compute",
#     "balance": null,
#     "name": "example-compute",
#     "pricePerUnit": 1000000,
#     "category": {
#         "name": "example-compute",
#         "provider": "example"
#     },
#     "description": "An example compute product",
#     "priority": 0,
#     "cpu": 10,
#     "memoryInGigs": 20,
#     "gpu": 0,
#     "version": 1,
#     "freeToUse": false,
#     "unitOfPrice": "CREDITS_PER_MINUTE",
#     "chargeType": "ABSOLUTE",
#     "hiddenInGrantApplications": false,
#     "productType": "COMPUTE"
# }
Communication Flow: Visual

Remote Procedure Calls

browse

API: Internal/Beta Auth: Public

Browse a set of products

Request Response Error
ProductsBrowseRequest PageV2<Product> CommonErrorMessage

This endpoint uses the normal pagination and filter mechanisms to return a list of Product.

Examples:

Example
Browse in the full product catalog
Browse for a specific type of product (e.g. compute)

retrieve

API: Internal/Beta Auth: Authenticated

Retrieve a single product

Request Response Error
ProductsRetrieveRequest Product CommonErrorMessage

Examples:

Example
Retrieving a single product by ID

create

API: Internal/Beta Auth: SERVICE, ADMIN, PROVIDER

Creates a new Product in UCloud

Request Response Error
BulkRequest<Product> Unit CommonErrorMessage

Only providers and UCloud administrators can create a Product. When this endpoint is invoked by a provider, then the provider field of the Product must match the invoking user.

The Product will become ready and visible in UCloud immediately after invoking this call. If no Product has been created in this category before, then this category will be created.


📝 NOTE: Most properties of a ProductCategory are immutable and must not be changed. As a result, you cannot create a new Product later with different category properties.


If the Product already exists, then a new version of it is created. Version numbers are always sequential and the incoming version number is always ignored by UCloud.

Data Models

ChargeType

API: Internal/Beta

enum class ChargeType {
    ABSOLUTE,
    DIFFERENTIAL_QUOTA,
}
Properties
ABSOLUTE
DIFFERENTIAL_QUOTA

Product

API: Internal/Beta

Products define the services exposed by a Provider.

sealed class Product {
    abstract val balance: Long?
    abstract val category: ProductCategoryId
    abstract val chargeType: ChargeType
    abstract val description: String
    abstract val freeToUse: Boolean
    abstract val hiddenInGrantApplications: Boolean
    abstract val id: String
    abstract val name: String
    abstract val pricePerUnit: Long
    abstract val priority: Int
    abstract val productType: ProductType
    abstract val unitOfPrice: ProductPriceUnit
    abstract val version: Int

    class Compute : Product()
    class Ingress : Product()
    class License : Product()
    class NetworkIP : Product()
    class Storage : Product()
}

For more information see this page.

Properties
balance: Long? Included only with certain endpoints which support `includeBalance`
category: ProductCategoryId The category groups similar products together, it also defines which provider owns the product
chargeType: ChargeType The category of payment model. Used in combination with unitOfPrice to create a complete payment model.
description: String A short (single-line) description of the Product
freeToUse: Boolean Indicates that a Wallet is not required to use this Product

Under normal circumstances, a Wallet is always required. This is required even if a Product has a pricePerUnit of 0. If freeToUse = true then the Wallet requirement is dropped.

hiddenInGrantApplications: Boolean Flag to indicate that this Product is not publicly available

⚠️ WARNING: This doesn’t make the Product secret. In only hides the Product from the grant system’s UI.

id: String

Deprecated: Yes

name: String A unique name associated with this Product
pricePerUnit: Long The price of a single unit in a single period

For more information go here.

priority: Int A integer used for changing the order in which products are displayed (ascending order)
productType: ProductType Classifier used to explain the type of Product
unitOfPrice: ProductPriceUnit The unit of price. Used in combination with chargeType to create a complete payment model.
version: Int A version number for this Product, managed by UCloud

Product.Compute

API: Internal/Beta

A compute Product

data class Compute(
    val name: String,
    val pricePerUnit: Long,
    val category: ProductCategoryId,
    val description: String?,
    val priority: Int?,
    val cpu: Int?,
    val memoryInGigs: Int?,
    val gpu: Int?,
    val version: Int?,
    val freeToUse: Boolean?,
    val unitOfPrice: ProductPriceUnit?,
    val chargeType: ChargeType?,
    val hiddenInGrantApplications: Boolean?,
    val productType: ProductType,
    val balance: Long?,
    val id: String,
    val type: String /* "compute" */,
)

Unit

API

Measured in hyper-threaded cores (vCPU)

Click here

Properties
name: String A unique name associated with this Product
pricePerUnit: Long The price of a single unit in a single period

For more information go here.

category: ProductCategoryId The category groups similar products together, it also defines which provider owns the product
description: String? A short (single-line) description of the Product
priority: Int? A integer used for changing the order in which products are displayed (ascending order)
cpu: Int?
memoryInGigs: Int?
gpu: Int?
version: Int? A version number for this Product, managed by UCloud
freeToUse: Boolean? Indicates that a Wallet is not required to use this Product

Under normal circumstances, a Wallet is always required. This is required even if a Product has a pricePerUnit of 0. If freeToUse = true then the Wallet requirement is dropped.

unitOfPrice: ProductPriceUnit? The unit of price. Used in combination with chargeType to create a complete payment model.
chargeType: ChargeType? The category of payment model. Used in combination with unitOfPrice to create a complete payment model.
hiddenInGrantApplications: Boolean? Flag to indicate that this Product is not publicly available

⚠️ WARNING: This doesn’t make the Product secret. In only hides the Product from the grant system’s UI.

productType: ProductType
balance: Long? Included only with certain endpoints which support `includeBalance`
id: String

Deprecated: Yes

type: String /* "compute" */ The type discriminator

API: Stable


Product.Ingress

API: Internal/Beta

An ingress Product

data class Ingress(
    val name: String,
    val pricePerUnit: Long,
    val category: ProductCategoryId,
    val description: String?,
    val priority: Int?,
    val version: Int?,
    val freeToUse: Boolean?,
    val unitOfPrice: ProductPriceUnit?,
    val chargeType: ChargeType?,
    val hiddenInGrantApplications: Boolean?,
    val productType: ProductType,
    val balance: Long?,
    val id: String,
    val type: String /* "ingress" */,
)

Unit

API

Measured in number of ingresses

Click here

Properties
name: String A unique name associated with this Product
pricePerUnit: Long The price of a single unit in a single period

For more information go here.

category: ProductCategoryId The category groups similar products together, it also defines which provider owns the product
description: String? A short (single-line) description of the Product
priority: Int? A integer used for changing the order in which products are displayed (ascending order)
version: Int? A version number for this Product, managed by UCloud
freeToUse: Boolean? Indicates that a Wallet is not required to use this Product

Under normal circumstances, a Wallet is always required. This is required even if a Product has a pricePerUnit of 0. If freeToUse = true then the Wallet requirement is dropped.

unitOfPrice: ProductPriceUnit? The unit of price. Used in combination with chargeType to create a complete payment model.
chargeType: ChargeType? The category of payment model. Used in combination with unitOfPrice to create a complete payment model.
hiddenInGrantApplications: Boolean? Flag to indicate that this Product is not publicly available

⚠️ WARNING: This doesn’t make the Product secret. In only hides the Product from the grant system’s UI.

productType: ProductType
balance: Long? Included only with certain endpoints which support `includeBalance`
id: String

Deprecated: Yes

type: String /* "ingress" */ The type discriminator

API: Stable


Product.License

API: Internal/Beta

A license Product

data class License(
    val name: String,
    val pricePerUnit: Long,
    val category: ProductCategoryId,
    val description: String?,
    val priority: Int?,
    val tags: List<String>?,
    val version: Int?,
    val freeToUse: Boolean?,
    val unitOfPrice: ProductPriceUnit?,
    val chargeType: ChargeType?,
    val hiddenInGrantApplications: Boolean?,
    val productType: ProductType,
    val balance: Long?,
    val id: String,
    val type: String /* "license" */,
)

Unit

API

Measured in number of licenses

Click here

Properties
name: String A unique name associated with this Product
pricePerUnit: Long The price of a single unit in a single period

For more information go here.

category: ProductCategoryId The category groups similar products together, it also defines which provider owns the product
description: String? A short (single-line) description of the Product
priority: Int? A integer used for changing the order in which products are displayed (ascending order)
tags: List<String>?
version: Int? A version number for this Product, managed by UCloud
freeToUse: Boolean? Indicates that a Wallet is not required to use this Product

Under normal circumstances, a Wallet is always required. This is required even if a Product has a pricePerUnit of 0. If freeToUse = true then the Wallet requirement is dropped.

unitOfPrice: ProductPriceUnit? The unit of price. Used in combination with chargeType to create a complete payment model.
chargeType: ChargeType? The category of payment model. Used in combination with unitOfPrice to create a complete payment model.
hiddenInGrantApplications: Boolean? Flag to indicate that this Product is not publicly available

⚠️ WARNING: This doesn’t make the Product secret. In only hides the Product from the grant system’s UI.

productType: ProductType
balance: Long? Included only with certain endpoints which support `includeBalance`
id: String

Deprecated: Yes

type: String /* "license" */ The type discriminator

API: Stable


Product.NetworkIP

API: Internal/Beta

An IP address Product

data class NetworkIP(
    val name: String,
    val pricePerUnit: Long,
    val category: ProductCategoryId,
    val description: String?,
    val priority: Int?,
    val version: Int?,
    val freeToUse: Boolean?,
    val unitOfPrice: ProductPriceUnit?,
    val chargeType: ChargeType?,
    val hiddenInGrantApplications: Boolean?,
    val productType: ProductType,
    val balance: Long?,
    val id: String,
    val type: String /* "network_ip" */,
)

Unit

API

Measured in number of IP addresses

Click here

Properties
name: String A unique name associated with this Product
pricePerUnit: Long The price of a single unit in a single period

For more information go here.

category: ProductCategoryId The category groups similar products together, it also defines which provider owns the product
description: String? A short (single-line) description of the Product
priority: Int? A integer used for changing the order in which products are displayed (ascending order)
version: Int? A version number for this Product, managed by UCloud
freeToUse: Boolean? Indicates that a Wallet is not required to use this Product

Under normal circumstances, a Wallet is always required. This is required even if a Product has a pricePerUnit of 0. If freeToUse = true then the Wallet requirement is dropped.

unitOfPrice: ProductPriceUnit? The unit of price. Used in combination with chargeType to create a complete payment model.
chargeType: ChargeType? The category of payment model. Used in combination with unitOfPrice to create a complete payment model.
hiddenInGrantApplications: Boolean? Flag to indicate that this Product is not publicly available

⚠️ WARNING: This doesn’t make the Product secret. In only hides the Product from the grant system’s UI.

productType: ProductType
balance: Long? Included only with certain endpoints which support `includeBalance`
id: String

Deprecated: Yes

type: String /* "network_ip" */ The type discriminator

API: Stable


Product.Storage

API: Internal/Beta

A storage Product

data class Storage(
    val name: String,
    val pricePerUnit: Long,
    val category: ProductCategoryId,
    val description: String?,
    val priority: Int?,
    val version: Int?,
    val freeToUse: Boolean?,
    val unitOfPrice: ProductPriceUnit?,
    val chargeType: ChargeType?,
    val hiddenInGrantApplications: Boolean?,
    val productType: ProductType,
    val balance: Long?,
    val id: String,
    val type: String /* "storage" */,
)

Unit

API

Measured in GB (10⁹ bytes. 1 byte = 1 octet)

Click here

Properties
name: String A unique name associated with this Product
pricePerUnit: Long The price of a single unit in a single period

For more information go here.

category: ProductCategoryId The category groups similar products together, it also defines which provider owns the product
description: String? A short (single-line) description of the Product
priority: Int? A integer used for changing the order in which products are displayed (ascending order)
version: Int? A version number for this Product, managed by UCloud
freeToUse: Boolean? Indicates that a Wallet is not required to use this Product

Under normal circumstances, a Wallet is always required. This is required even if a Product has a pricePerUnit of 0. If freeToUse = true then the Wallet requirement is dropped.

unitOfPrice: ProductPriceUnit? The unit of price. Used in combination with chargeType to create a complete payment model.
chargeType: ChargeType? The category of payment model. Used in combination with unitOfPrice to create a complete payment model.
hiddenInGrantApplications: Boolean? Flag to indicate that this Product is not publicly available

⚠️ WARNING: This doesn’t make the Product secret. In only hides the Product from the grant system’s UI.

productType: ProductType
balance: Long? Included only with certain endpoints which support `includeBalance`
id: String

Deprecated: Yes

type: String /* "storage" */ The type discriminator

API: Stable


ProductCategoryId

API: Internal/Beta

data class ProductCategoryId(
    val name: String,
    val provider: String,
    val id: String,
)
Properties
name: String
provider: String
id: String

Deprecated: Yes


ProductPriceUnit

API: Internal/Beta

enum class ProductPriceUnit {
    CREDITS_PER_UNIT,
    PER_UNIT,
    CREDITS_PER_MINUTE,
    CREDITS_PER_HOUR,
    CREDITS_PER_DAY,
    UNITS_PER_MINUTE,
    UNITS_PER_HOUR,
    UNITS_PER_DAY,
}
Properties
CREDITS_PER_UNIT
PER_UNIT
CREDITS_PER_MINUTE
CREDITS_PER_HOUR
CREDITS_PER_DAY
UNITS_PER_MINUTE
UNITS_PER_HOUR
UNITS_PER_DAY

ProductReference

API: Internal/Beta

Contains a unique reference to a Product

data class ProductReference(
    val id: String,
    val category: String,
    val provider: String,
)
Properties
id: String The `Product` ID
category: String The ID of the `Product`'s category
provider: String The provider of the `Product`

ProductType

API: Internal/Beta

A classifier for a Product

enum class ProductType {
    STORAGE,
    COMPUTE,
    INGRESS,
    LICENSE,
    NETWORK_IP,
}

For more information, see the individual Products:

Properties
STORAGE See Product.Storage
COMPUTE See Product.Compute
INGRESS See Product.Ingress
LICENSE See Product.License
NETWORK_IP See Product.NetworkIP

ProductsBrowseRequest

API: Internal/Beta

The base type for requesting paginated content.

data class ProductsBrowseRequest(
    val itemsPerPage: Int?,
    val next: String?,
    val consistency: PaginationRequestV2Consistency?,
    val itemsToSkip: Long?,
    val filterName: String?,
    val filterProvider: String?,
    val filterArea: ProductType?,
    val filterCategory: String?,
    val filterVersion: Int?,
    val showAllVersions: Boolean?,
    val includeBalance: Boolean?,
)

Paginated content can be requested with one of the following consistency guarantees, this greatly changes the semantics of the call:

Consistency Description
PREFER Consistency is preferred but not required. An inconsistent snapshot might be returned.
REQUIRE Consistency is required. A request will fail if consistency is no longer guaranteed.

The consistency refers to if collecting all the results via the pagination API are consistent. We consider the results to be consistent if it contains a complete view at some point in time. In practice this means that the results must contain all the items, in the correct order and without duplicates.

If you use the PREFER consistency then you may receive in-complete results that might appear out-of-order and can contain duplicate items. UCloud will still attempt to serve a snapshot which appears mostly consistent. This is helpful for user-interfaces which do not strictly depend on consistency but would still prefer something which is mostly consistent.

The results might become inconsistent if the client either takes too long, or a service instance goes down while fetching the results. UCloud attempts to keep each next token alive for at least one minute before invalidating it. This does not mean that a client must collect all results within a minute but rather that they must fetch the next page within a minute of the last page. If this is not feasible and consistency is not required then PREFER should be used.


📝 NOTE: Services are allowed to ignore extra criteria of the request if the next token is supplied. This is needed in order to provide a consistent view of the results. Clients should provide the same criterion as they paginate through the results.


Properties
itemsPerPage: Int? Requested number of items per page. Supported values: 10, 25, 50, 100, 250.
next: String? A token requesting the next page of items
consistency: PaginationRequestV2Consistency? Controls the consistency guarantees provided by the backend
itemsToSkip: Long? Items to skip ahead
filterName: String?
filterProvider: String?
filterArea: ProductType?
filterCategory: String?
filterVersion: Int?
showAllVersions: Boolean?
includeBalance: Boolean?

ProductsRetrieveRequest

API: Internal/Beta

data class ProductsRetrieveRequest(
    val filterName: String,
    val filterCategory: String,
    val filterProvider: String,
    val filterArea: ProductType?,
    val filterVersion: Int?,
    val includeBalance: Boolean?,
)
Properties
filterName: String
filterCategory: String
filterProvider: String
filterArea: ProductType?
filterVersion: Int?
includeBalance: Boolean?