API reference

Account

The Red Hat Marketplace Account API provides an interface to manage account profiles.

Open specifications

Fetch accounts

get

/account/api/v1/accounts

Get a list of accounts by specifying at least one query parameter

URL parameters
_id

string

optional

identifier of account to fetch

billingAccountId

string

optional

billingAccount identifier of account(s) to fetch, use comma delimited for multiple (eg. billingAccountId=123,321)

skip

number

optional

number of records to skip in results

limit

number

optional

number of records to show in results (max 100)

name

string

optional

company name of account to fetch

includeNestedLevel

number

optional

level of user details to fetch (eg. includeNestedLevel=1 for user role, includeNestedLevel=2 for detailed user data)

Body parameters

No parameters.

GET /account/api/v1/accountsCURL
curl --location --request GET '/account/api/v1/accounts?5ee98dd2790490b6281a2402 \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ACCESS_TOKEN' \
Success responses

HTTP status 202

The message was understood and all events were accepted. The result of the processing is determined by the returned content.

totalResults

number

optional

Total accounts returned

OMAccounts

array

optional

An array of matching accounts

  • _id

    string

    optional

    ID of the account record

    name

    string

    optional

    Company name of the account

    isCompany

    boolean

    optional

    True if a company account

    billingAccountId

    string

    optional

    Billing account ID of the account

    billingAddress

    object

    optional

    Billing address of the account

    • companyName

      string

      optional

      Name of the company

      firstName

      string

      optional

      First name of the billing address

      lastName

      string

      optional

      Last name of the billing address

      address1

      string

      optional

      Address line 1 of the billing address

      address2

      string

      optional

      Address line 2 of the billing address

      city

      string

      optional

      City of the billing address

      stateProvince

      string

      optional

      State/Province of the billing address

      postalCode

      string

      optional

      Postal/Zip code of the billing address

      phoneNumber

      string

      optional

      Phone number of the billing address

      countryCode

      string

      optional

      Country code of the billing address

    vatNumber

    string

    optional

    VAT number of the account

    taxCode

    string

    optional

    Tax code of the account

    status

    string

    optional

    Status of the account

    • PENDING
      ACTIVE
      SUSPENDED
    vendorStatus

    string

    optional

    Status of the vendor account

    • PENDING
      ACTIVE
      SUSPENDED
    billingAccountRefs

    object

    optional

    Billing references of the account

    • zuoraAccountId

      string

      optional

      Reference to zuora account ID

      sapSiteNumber

      string

      optional

      Reference to SAP site number

      ibmCustomerNumber

      string

      optional

      Reference to IBM customer number (ICN)

      mppNumber

      string

      optional

      Reference to MPP number

    isCustomer

    boolean

    optional

    True if account is type customer

    isVendor

    boolean

    optional

    True if account is type vendor

    partnerConnectId

    string

    optional

    Partner connect ID of the account

    accountRHIdLink

    string

    optional

    Red Hat ID linked to the account

    loginRHIdLink

    string

    optional

    Red Hat login linked to the account

    companyRef

    string

    optional

    Reference to the ID record of the corresponding company for the account

    vendorAccount

    object

    optional

    Vendor details if a vendor account

    • addressVerified

      boolean

      optional

      True if address is verified

      vendorLegalAddress

      object

      optional

      The legal address for the vendor account

      • companyName

        string

        optional

        Name of the company

        firstName

        string

        optional

        First name of the vendor legal address

        lastName

        string

        optional

        Last name of the vendor legal address

        address1

        string

        optional

        Address line 1 of the vendor legal address

        address2

        string

        optional

        Address line 2 of the vendor legal address

        city

        string

        optional

        City of the vendor legal address

        stateProvince

        string

        optional

        State/Province of the vendor legal address

        postalCode

        string

        optional

        Postal/Zip code of the vendor legal address

        phoneNumber

        string

        optional

        Phone number of the vendor legal address

        countryCode

        string

        optional

        Country code of the vendor legal address

      vatNumber

      string

      optional

      VAT number for the vendor account

      taxCode

      string

      optional

      Tax code for the vendor account

      vendorType

      string

      optional

      Type of the vendor, can be IBM or ISV

      • IBM
        ISV
    bssAccountId

    string

    optional

    BSS account ID of the account

    createdAt

    string

    optional

    Created at timestamp of the account

    paymentInfo

    array

    optional

    An array of payment information objects.

    • _id

      string

      optional

      ID of the payment record

      type

      string

      optional

      Type of payment - can be Invoice or Credit Card

      isDefault

      boolean

      optional

      True if this is the default payment method

      cardType

      string

      optional

      Type of credit card

      scrambledNumber

      string

      optional

      Masked credit card number showing last 4 digits only

      expiryDate

      string

      optional

      Expiry date MMYY of credit card

      customerNumber

      string

      optional

      Customer number for Invoice payment method

      poNumber

      string

      optional

      PO number for Invoice payment method

      verified

      boolean

      optional

      True if payment method has been verified

      walletId

      string

      optional

      Wallet ID corresponding to the payment method

      accountId

      string

      optional

      Account ID corresponding to the payment method

    accountCreationStatus

    object

    optional

    Creation status of the account

    • _id

      string

      optional

      ID of the account create record

      accountId

      string

      optional

      The account ID for the account

      updatedOn

      string

      optional

      Last update timestamp of the account

      lastProcessingAttempt

      string

      optional

      Last processing attempt of the account

      stuckAlert

      boolean

      optional

      Flag for stuck account

      zuora

      boolean

      optional

      Flag for zuora account

      customerCreate

      boolean

      optional

      Flag for customer create account

      icn

      boolean

      optional

      Flag for ICN

      orderContainer

      boolean

      optional

      Flag for order container

    OMRoles

    array

    optional

    Roles of the users of the account

    • userId

      string

      optional

      The ID of the user record, only shown when includeNestedLevel=1

      roleName

      string

      optional

      The role of the user

      • AccountOwner
        AccountMember
        AccountAdmin
        ClusterAdmin
        Purchaser
        VendorProductAdmin
        VendorSalesAdmin
        VendorLegalAdmin
        Partner
      OMUser

      object

      optional

      Details of the user, only shown when includeNestedLevel=2

      • _id

        string

        optional

        The ID of the user record

        iamId

        string

        optional

        Cloud IAM ID of the user

        emailAddress

        string

        optional

        Email address of the user

        firstName

        string

        optional

        First name of the user

        lastName

        string

        optional

        Last name of the user

        preferredLanguage

        string

        optional

        Preferred language of the user

    enterpriseMarketplace

    object

    optional

    Details of the enterprise marketplace account

    • name

      string

      optional

      Display name of the EM enabled account

      theme

      object

      optional

      Theme details of the EM enabled account

      • primary

        string

        optional

        Primary background color (in hex) for the EM enabled account

        secondary

        string

        optional

        Generated gradient background color (in hex) for the EM enabled account

        fontColor

        string

        optional

        Generated font color (in hex) for the EM enabled account

      enabled

      boolean

      optional

      True if EM account is enabled

    isTaxExempt

    boolean

    optional

    True if account is tax exempt

Response example
{
    "totalResults": 1,
    "OMAccounts": [
        {
            "_id": "5ee98dd2790490b6281a2402",
            "name": "ABC Account",
            "isCompany": true,
            "billingAccountId": "ACCT000004261",
            "billingAddress": {
                "companyName": "ABC Test Company",
                "firstName": "John",
                "lastName": "Doe",
                "address1": "123 Test Street",
                "address2": "Suite 456",
                "city": "New York",
                "stateProvince": "New York",
                "postalCode": "10001",
                "phoneNumber": "(123)4567890",
                "countryCode": "US"
            },
            "vatNumber": "12345",
            "taxCode": "123",
            "status": "PENDING",
            "vendorStatus": "PENDING",
            "billingAccountRefs": {
                "zuoraAccountId": "2c92c0fb72e0de460172f21985ae6d5a",
                "sapSiteNumber": "0004134380",
                "ibmCustomerNumber": "1990789",
                "mppNumber": "0198098765"
            },
            "isCustomer": true,
            "isVendor": true,
            "partnerConnectId": "12345",
            "accountRHIdLink": "13337759",
            "loginRHIdLink": "redHatuserLogin",
            "companyRef": "5ee39b052ea9a08821470e4a",
            "vendorAccount": {
                "addressVerified": true,
                "vendorLegalAddress": {
                    "companyName": "ABC Vendor Company",
                    "firstName": "Jane",
                    "lastName": "Doe",
                    "address1": "123 Test Street",
                    "address2": "Suite 456",
                    "city": "New York",
                    "stateProvince": "New York",
                    "postalCode": "10001",
                    "phoneNumber": "(123)4567890",
                    "countryCode": "US"
                },
                "vatNumber": "12345",
                "taxCode": "123",
                "vendorType": "IBM"
            },
            "bssAccountId": "OMP-2f88191ae209449aae23884437c8c36b",
            "createdAt": "2020-06-17T03:28:18.050Z",
            "paymentInfo": [
                {
                    "_id": "5f982c6b7fb6b5e2d31214ee",
                    "type": "CREDIT_CARD",
                    "isDefault": true,
                    "cardType": "VISA",
                    "scrambledNumber": "****1234",
                    "expiryDate": "1123",
                    "verified": true,
                    "walletId": "61ef13f0185f11eb8d4b35c4e7bebf44",
                    "accountId": "5f982b957fb6b5e2d31214eb"
                },
                {
                    "_id": "5f99f2aa7fb6b5e2d31214f6",
                    "type": "CREDIT_CARD",
                    "isDefault": false,
                    "cardType": "MASTERCARD",
                    "scrambledNumber": "****1111",
                    "expiryDate": "0123",
                    "walletId": "61ef13f0185f11eb8d4b35c4e7bebf44",
                    "accountId": "5f982b957fb6b5e2d31214eb"
                }
            ],
            "accountCreationStatus": {
                "_id": "2c92c0fb72e0de460172f21985ae6d5a",
                "accountId": "5ee98dd2790490b6281a2402",
                "updatedOn": "2020-06-17T03:28:18.050Z",
                "lastProcessingAttempt": "2020-06-17T03:28:18.050Z",
                "stuckAlert": false,
                "zuora": true,
                "customerCreate": true,
                "icn": true,
                "orderContainer": true
            },
            "OMRoles": [
                {
                    "roleName": "AccountOwner",
                    "OMUser": {
                        "_id": "5f7dcdce501cf8bcadc40c54",
                        "iamId": "IBMid-55000950RA",
                        "emailAddress": "test@mail.test.ibm.com",
                        "firstName": "Userfirstname",
                        "lastName": "Userlastname",
                        "preferredLanguage": "en-us"
                    }
                },
                {
                    "roleName": "AccountMember",
                    "OMUser": {
                        "_id": "5f7de18b501cf8bcadc40c56",
                        "iamId": "IBMid-55000951R4",
                        "emailAddress": "test1@mail.test.ibm.com",
                        "firstName": "Userfirstname1",
                        "lastName": "Userlastname1",
                        "preferredLanguage": "en-us"
                    }
                }
            ],
            "enterpriseMarketplace": {
                "name": "ABC Test Company",
                "theme": {
                    "primary": "#ABC123",
                    "secondary": "#321DEF",
                    "fontColor": "#000000"
                },
                "enabled": true
            },
            "isTaxExempt": false
        }
    ]
}
Error response

HTTP status default

Any unrecoverable failure, the platform will give up sending the event

No error response parameters.

Commerce

The Red Hat Marketplace Commerce API provides an interface to access product edition data and units of measure.

Open specifications

Fetch all units of measure

get

/commerce/api/v2/uoms

Get all units of measure

URL parameters
locale

string

optional

Locale code to return translation for (default en-us)

Body parameters

No parameters.

GET /commerce/api/v2/uomsCURL
curl --location --request GET '/commerce/api/v2/uoms' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ACCESS_TOKEN' \
Success responses

HTTP status 200

List of units of measure

identifier

string

required

Unique identifier

multiplier

number

required

Unit multiplier

supportUsageChargeType

boolean

required

True if this UOM supports usage charges

translations

object

optional

Locale specific text values for UOM

  • de

    object

    optional

    Translations

    • singularName

      string

      required

      Singular name

      pluralName

      string

      required

      Plural name

      suffix

      string

      required

      Suffix

      inputLabel

      string

      required

      Input label

      summaryLabel

      string

      required

      Summary label

    en

    object

    optional

    Translations

    • singularName

      string

      required

      Singular name

      pluralName

      string

      required

      Plural name

      suffix

      string

      required

      Suffix

      inputLabel

      string

      required

      Input label

      summaryLabel

      string

      required

      Summary label

    es

    object

    optional

    Translations

    • singularName

      string

      required

      Singular name

      pluralName

      string

      required

      Plural name

      suffix

      string

      required

      Suffix

      inputLabel

      string

      required

      Input label

      summaryLabel

      string

      required

      Summary label

    fr

    object

    optional

    Translations

    • singularName

      string

      required

      Singular name

      pluralName

      string

      required

      Plural name

      suffix

      string

      required

      Suffix

      inputLabel

      string

      required

      Input label

      summaryLabel

      string

      required

      Summary label

    it

    object

    optional

    Translations

    • singularName

      string

      required

      Singular name

      pluralName

      string

      required

      Plural name

      suffix

      string

      required

      Suffix

      inputLabel

      string

      required

      Input label

      summaryLabel

      string

      required

      Summary label

created

number

required

Unix timestamp of creation

updated

number

required

Unix timestamp of last update

Response example
[
    {
        "identifier": "ActiveUser",
        "multiplier": 1,
        "created": 1583808165047,
        "updated": 1583808165047,
        "supportUsageChargeType": false,
        "singularName": "Active User",
        "pluralName": "Active Users",
        "suffix": "per active user",
        "inputLabel": "Enter number of active users",
        "summaryLabel": "Number of active users"
    },
    {
        "identifier": "Agent",
        "multiplier": 1,
        "created": 1593701055699,
        "updated": 1593701055699,
        "supportUsageChargeType": false,
        "singularName": "Agent",
        "pluralName": "Agents",
        "suffix": "per agent",
        "inputLabel": "Enter number of agents",
        "summaryLabel": "Number of agents"
    },
    {
        "identifier": "ApplicationInstance",
        "multiplier": 1,
        "created": 1583808165879,
        "updated": 1583808165879,
        "supportUsageChargeType": false,
        "singularName": "Application Instance",
        "pluralName": "Application Instances",
        "suffix": "per application instance",
        "inputLabel": "Enter number of application instances",
        "summaryLabel": "Number of application instances"
    }
]
Error response

HTTP status default

No error response parameters.

Fetch unit of measure

get

/commerce/api/v2/uoms/{identifier}

Get unit of measure

URL parameters
identifier

string

required

UOM identifier of entity to return

locale

string

optional

Locale code to return translation for (default en-us)

Body parameters

No parameters.

GET /commerce/api/v2/uoms/{identifier}CURL
curl --location --request GET '/commerce/api/v2/uoms/Asset' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ACCESS_TOKEN' \
Success responses

HTTP status 200

Unit of Measure

identifier

string

required

Unique identifier

multiplier

number

required

Unit multiplier

supportUsageChargeType

boolean

required

True if this UOM supports usage charges

translations

object

optional

Locale specific text values for UOM

  • de

    object

    optional

    Translations

    • singularName

      string

      required

      Singular name

      pluralName

      string

      required

      Plural name

      suffix

      string

      required

      Suffix

      inputLabel

      string

      required

      Input label

      summaryLabel

      string

      required

      Summary label

    en

    object

    optional

    Translations

    • singularName

      string

      required

      Singular name

      pluralName

      string

      required

      Plural name

      suffix

      string

      required

      Suffix

      inputLabel

      string

      required

      Input label

      summaryLabel

      string

      required

      Summary label

    es

    object

    optional

    Translations

    • singularName

      string

      required

      Singular name

      pluralName

      string

      required

      Plural name

      suffix

      string

      required

      Suffix

      inputLabel

      string

      required

      Input label

      summaryLabel

      string

      required

      Summary label

    fr

    object

    optional

    Translations

    • singularName

      string

      required

      Singular name

      pluralName

      string

      required

      Plural name

      suffix

      string

      required

      Suffix

      inputLabel

      string

      required

      Input label

      summaryLabel

      string

      required

      Summary label

    it

    object

    optional

    Translations

    • singularName

      string

      required

      Singular name

      pluralName

      string

      required

      Plural name

      suffix

      string

      required

      Suffix

      inputLabel

      string

      required

      Input label

      summaryLabel

      string

      required

      Summary label

created

number

required

Unix timestamp of creation

updated

number

required

Unix timestamp of last update

Response example
{
    "identifier": "Asset",
    "multiplier": 1,
    "created": 1583808166311,
    "updated": 1583808166311,
    "supportUsageChargeType": false,
    "singularName": "Asset",
    "pluralName": "Assets",
    "suffix": "per asset",
    "inputLabel": "Enter number of assets",
    "summaryLabel": "Number of assets"
}
Error response

HTTP status default

No error response parameters.

Fetch lastest edition version

get

/commerce/api/v3/edition/{id}

Get latest edition version

URL parameters
id

string

required

Id of edition to return

locale

string

optional

Locale code to return translation for (default en-us)

includeMetadata

boolean

optional

Set to true to include edition metadata (default false)

showDraftVersion

boolean

optional

Set to true to allow draft edition to be returned if latest (default false)

Body parameters

No parameters.

GET /commerce/api/v3/edition/{id}CURL
curl --location --request GET '/commerce/api/v3/edition/EIDHJLN9' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ACCESS_TOKEN' \
Success responses

HTTP status 200

Edition

_id

string

optional

Edition ID

id

string

required

Edition ID

type

string

required

Edition type

  • PURCHASE
    TRIAL
    FREE
product

object

required

Product data

  • id

    string

    required

    Product ID

productName

string

required

Product name

name

string

required

Edition name

description

string

required

Edition description

termUnit

string

required

Subscription term units

  • MONTHS
    DAYS
version

number

required

Edition version

created

number

required

Unix timestamp of creation

updated

number

required

Unix timestamp of last update

allowedBillingFrequencies

array

optional

Allowed billing frequencies for edition

  • MONTHLY
    QUARTERLY
    ANNUAL
    UPFRONT
allowedSubscriptionTerms

array

optional

Allowed subscription terms for edition

  • 1
    3
    6
    12
    24
    36
    48
    60
cooldownPeriod

number

optional

Minimum number of days allowed between subscriptions to this edition

trialTerm

number

optional

Length of the trial subscription to this edition

trialGracePeriod

number

optional

Number of days product will remain active after trial expiration

trialPart

string

optional

Trial edition part number

logoUrl

string

optional

URL of edition logo

billingSystem

string

optional

Billing system which processes edition subscriptions

  • ZUORA
    DSW
editionCharges

array

optional

Rules governing edition charges

  • id

    string

    required

    Charge ID

    sequence

    string

    required

    Charge display sequence

    type

    string

    required

    Charge type

    • Recurring
      Usage
      OneTime
    priceModel

    string

    required

    Price model

    • Standard
      VolumePricing
      TierPricing
    required

    boolean

    required

    Charge required

    minimumQuantity

    number

    required

    Minimum charge quantity

    maximumQuantity

    number

    required

    Maximum charge quantity

    defaultQuantity

    number

    required

    Default charge quantity

    increment

    number

    optional

    Charge quantity increment

    useInStartingPriceCalculation

    boolean

    required

    Include charge in edition starting price

    created

    number

    required

    Unix timestamp of creation

    updated

    number

    required

    Unix timestamp of last update

    tiers

    array

    required

    Charge pricing tiers

    • startingUnit

      number

      required

      Tier starting unit

      endingUnit

      number

      optional

      Tier ending unit

      pricing

      array

      required

      Charge tier pricing

      • currency

        string

        required

        Price currency

        price

        number

        required

        Price amount

        overagePrice

        number

        optional

        Overage price

    usageReportingType

    string

    optional

    Type of usage reporting

    • Cumulative
      HighWaterMark
    vendorChargeId

    string

    optional

    Vendor defined ID for charge

    ibmPartNumber

    string

    optional

    IBM part number for charge

    ibmOveragePartNumber

    string

    optional

    IBM part number for charge overage

    priceFrequency

    string

    optional

    Charge frequency

    • ANNUAL
      MONTHLY
    usageReportingId

    string

    optional

    Usage reporting ID

    uom

    object

    required

    • identifier

      string

      required

      Unique identifier

      multiplier

      number

      required

      Unit multiplier

      supportUsageChargeType

      boolean

      required

      True if this UOM supports usage charges

      translations

      object

      optional

      Translations

      • singularName

        string

        required

        Singular name

        pluralName

        string

        required

        Plural name

        suffix

        string

        required

        Suffix

        inputLabel

        string

        required

        Input label

        summaryLabel

        string

        required

        Summary label

      created

      number

      required

      Unix timestamp of creation

      updated

      number

      required

      Unix timestamp of last update

      singularName

      string

      required

      Singular name

      pluralName

      string

      required

      Plural name

      suffix

      string

      required

      Suffix

      inputLabel

      string

      required

      Input label

      summaryLabel

      string

      required

      Summary label

    metadata

    object

    optional

    • chargeSyncRequired

      boolean

      optional

      Charge sync required

      ibmPartNumber

      string

      optional

      IBM part number for charge

      ibmOveragePartNumber

      string

      optional

      IBM part number for overage

      zuoraRatePlanId

      string

      optional

      Zuora rate plan ID

      zuoraRatePlanChargeId

      string

      optional

      Zuora rate plan charge ID

      zuoraRatePlanOverages

      array

      optional

      Zuora rate plan overage metadata

      • startingUnit

        number

        required

        Tier starting unit

        zuoraRatePlanOverageChargeId

        string

        required

        Zuora rate plan overage charge ID

rules

array

optional

Rules governing edition charges

  • id

    string

    required

    Edition rule ID

    type

    string

    required

    Edition rule type

    • QuantitySyncRule
      MaxQuantityDependencyRule
      AddonQuantityLimiterRule
      QuantityDetermineAddonsRequiredRule
      EnableChargeIfSourceSelectedRule
      DisableChargeIfSourceSelectedRule
    sourceChargeIds

    array

    required

    Source charge IDs

    targetChargeIds

    array

    optional

    Target charge IDs

    quantityThreshold

    number

    optional

    Quantity threshold for rule

slaPartNumber

string

optional

SLA part number for edition

vendorTrialId

string

optional

Vendor defined ID for trial edition

category

string

optional

Edition category

  • PRODUCT
    PLATFORM
Response example
{
    "_id": "5e94eecd4509e00013c7f171",
    "id": "EIDHJLN9",
    "type": "Purchase",
    "productId": "7fa13fdf607424ec566e38b8cd29a11e",
    "productName": "Cortex Certifai",
    "name": "Cortex Certifai Platinum Edition",
    "description": "Cortex Certifai empowers enterprises to identify and mitigate risk and vulnerabilities within AI and deploy trusted AI systems into production.",
    "created": 1586816464726,
    "updated": 1586817236565,
    "metadata": {
        "status": "Published",
        "billingSystem": "ZUORA",
        "approverComment": "",
        "publishAttemptCount": 0
    },
    "version": 1,
    "termUnit": "Month",
    "allowedBillingFrequencies": [
        "Monthly"
    ],
    "allowedSubscriptionTerms": [
        1
    ],
    "trialTerm": null,
    "editionCharges": [
        {
            "sequence": 0,
            "type": "Recurring",
            "priceModel": "Standard",
            "required": true,
            "minimumQuantity": 1,
            "maximumQuantity": 1,
            "defaultQuantity": 1,
            "useInStartingPriceCalculation": true,
            "vendorChargeId": "cortexplatinum",
            "tiers": [
                {
                    "startingUnit": 1,
                    "pricing": [
                        {
                            "currency": "USD",
                            "price": 52000
                        }
                    ],
                    "id": "2ec04ba9-3097-4628-a7ec-248cdb0b512f"
                }
            ],
            "id": "5e94e8ca4509e00013c7f16f",
            "created": 1586817226391,
            "updated": 1586817226391,
            "usageReportingType": "Cumulative",
            "metadata": {
                "chargeSyncRequired": false,
                "ibmPartNumber": "D02FCZX",
                "zuoraRatePlanChargeId": "2c92c0f8715cd199017175ad7dfb71de",
                "zuoraRatePlanId": "2c92c0f9715ce772017175ad7be134e4"
            },
            "name": "Cortex certifai platinum edition",
            "uom": {
                "identifier": "Instance",
                "multiplier": 1,
                "created": 1583808172371,
                "updated": 1583808172371,
                "supportUsageChargeType": false,
                "singularName": "Instance",
                "pluralName": "Instances",
                "suffix": "per instance",
                "inputLabel": "Enter number of instances",
                "summaryLabel": "Number of instances"
            }
        }
    ],
    "logoUrl": "https://mp.s81c.com/pwb-production/7fa13fdf607424ec566e38b8cd29a11e/productLogoImg_da446f1b-6605-45ec-990f-a6ad1e756970_aa0b6f7c-f647-40d4-b27a-94053b0cb51d.png"
}
Error response

HTTP status default

No error response parameters.

Fetch edition version

get

/commerce/api/v3/edition/{id}/{version}

Get edition version

URL parameters
id

string

required

Id of edition to return

version

number

required

version number of edition to return

locale

string

optional

Locale code to return translation for (default en-us)

includeMetadata

boolean

optional

Set to true to include edition metadata (default false)

quoteId

string

optional

If provided, retrieves edition pricing for the specified quote

Body parameters

No parameters.

GET /commerce/api/v3/edition/{id}/{version}CURL
curl --location --request GET '/commerce/api/v3/edition/EIDHJLN9/1' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ACCESS_TOKEN' \
Success responses

HTTP status 200

Edition

_id

string

optional

Edition ID

id

string

required

Edition ID

type

string

required

Edition type

  • PURCHASE
    TRIAL
    FREE
product

object

required

Product data

  • id

    string

    required

    Product ID

productName

string

required

Product name

name

string

required

Edition name

description

string

required

Edition description

termUnit

string

required

Subscription term units

  • MONTHS
    DAYS
version

number

required

Edition version

created

number

required

Unix timestamp of creation

updated

number

required

Unix timestamp of last update

allowedBillingFrequencies

array

optional

Allowed billing frequencies for edition

  • MONTHLY
    QUARTERLY
    ANNUAL
    UPFRONT
allowedSubscriptionTerms

array

optional

Allowed subscription terms for edition

  • 1
    3
    6
    12
    24
    36
    48
    60
cooldownPeriod

number

optional

Minimum number of days allowed between subscriptions to this edition

trialTerm

number

optional

Length of the trial subscription to this edition

trialGracePeriod

number

optional

Number of days product will remain active after trial expiration

trialPart

string

optional

Trial edition part number

logoUrl

string

optional

URL of edition logo

billingSystem

string

optional

Billing system which processes edition subscriptions

  • ZUORA
    DSW
editionCharges

array

optional

Rules governing edition charges

  • id

    string

    required

    Charge ID

    sequence

    string

    required

    Charge display sequence

    type

    string

    required

    Charge type

    • Recurring
      Usage
      OneTime
    priceModel

    string

    required

    Price model

    • Standard
      VolumePricing
      TierPricing
    required

    boolean

    required

    Charge required

    minimumQuantity

    number

    required

    Minimum charge quantity

    maximumQuantity

    number

    required

    Maximum charge quantity

    defaultQuantity

    number

    required

    Default charge quantity

    increment

    number

    optional

    Charge quantity increment

    useInStartingPriceCalculation

    boolean

    required

    Include charge in edition starting price

    created

    number

    required

    Unix timestamp of creation

    updated

    number

    required

    Unix timestamp of last update

    tiers

    array

    required

    Charge pricing tiers

    • startingUnit

      number

      required

      Tier starting unit

      endingUnit

      number

      optional

      Tier ending unit

      pricing

      array

      required

      Charge tier pricing

      • currency

        string

        required

        Price currency

        price

        number

        required

        Price amount

        overagePrice

        number

        optional

        Overage price

    usageReportingType

    string

    optional

    Type of usage reporting

    • Cumulative
      HighWaterMark
    vendorChargeId

    string

    optional

    Vendor defined ID for charge

    ibmPartNumber

    string

    optional

    IBM part number for charge

    ibmOveragePartNumber

    string

    optional

    IBM part number for charge overage

    priceFrequency

    string

    optional

    Charge frequency

    • ANNUAL
      MONTHLY
    usageReportingId

    string

    optional

    Usage reporting ID

    uom

    object

    required

    • identifier

      string

      required

      Unique identifier

      multiplier

      number

      required

      Unit multiplier

      supportUsageChargeType

      boolean

      required

      True if this UOM supports usage charges

      translations

      object

      optional

      Translations

      • singularName

        string

        required

        Singular name

        pluralName

        string

        required

        Plural name

        suffix

        string

        required

        Suffix

        inputLabel

        string

        required

        Input label

        summaryLabel

        string

        required

        Summary label

      created

      number

      required

      Unix timestamp of creation

      updated

      number

      required

      Unix timestamp of last update

      singularName

      string

      required

      Singular name

      pluralName

      string

      required

      Plural name

      suffix

      string

      required

      Suffix

      inputLabel

      string

      required

      Input label

      summaryLabel

      string

      required

      Summary label

    metadata

    object

    optional

    • chargeSyncRequired

      boolean

      optional

      Charge sync required

      ibmPartNumber

      string

      optional

      IBM part number for charge

      ibmOveragePartNumber

      string

      optional

      IBM part number for overage

      zuoraRatePlanId

      string

      optional

      Zuora rate plan ID

      zuoraRatePlanChargeId

      string

      optional

      Zuora rate plan charge ID

      zuoraRatePlanOverages

      array

      optional

      Zuora rate plan overage metadata

      • startingUnit

        number

        required

        Tier starting unit

        zuoraRatePlanOverageChargeId

        string

        required

        Zuora rate plan overage charge ID

rules

array

optional

Rules governing edition charges

  • id

    string

    required

    Edition rule ID

    type

    string

    required

    Edition rule type

    • QuantitySyncRule
      MaxQuantityDependencyRule
      AddonQuantityLimiterRule
      QuantityDetermineAddonsRequiredRule
      EnableChargeIfSourceSelectedRule
      DisableChargeIfSourceSelectedRule
    sourceChargeIds

    array

    required

    Source charge IDs

    targetChargeIds

    array

    optional

    Target charge IDs

    quantityThreshold

    number

    optional

    Quantity threshold for rule

slaPartNumber

string

optional

SLA part number for edition

vendorTrialId

string

optional

Vendor defined ID for trial edition

category

string

optional

Edition category

  • PRODUCT
    PLATFORM
Response example
{
    "_id": "5e94eecd4509e00013c7f171",
    "id": "EIDHJLN9",
    "type": "Purchase",
    "productId": "7fa13fdf607424ec566e38b8cd29a11e",
    "productName": "Cortex Certifai",
    "name": "Cortex Certifai Platinum Edition",
    "description": "Cortex Certifai empowers enterprises to identify and mitigate risk and vulnerabilities within AI and deploy trusted AI systems into production.",
    "created": 1586816464726,
    "updated": 1586817236565,
    "metadata": {
        "status": "Published",
        "billingSystem": "ZUORA",
        "approverComment": "",
        "publishAttemptCount": 0
    },
    "version": 1,
    "termUnit": "Month",
    "allowedBillingFrequencies": [
        "Monthly"
    ],
    "allowedSubscriptionTerms": [
        1
    ],
    "trialTerm": null,
    "editionCharges": [
        {
            "sequence": 0,
            "type": "Recurring",
            "priceModel": "Standard",
            "required": true,
            "minimumQuantity": 1,
            "maximumQuantity": 1,
            "defaultQuantity": 1,
            "useInStartingPriceCalculation": true,
            "vendorChargeId": "cortexplatinum",
            "tiers": [
                {
                    "startingUnit": 1,
                    "pricing": [
                        {
                            "currency": "USD",
                            "price": 52000
                        }
                    ],
                    "id": "2ec04ba9-3097-4628-a7ec-248cdb0b512f"
                }
            ],
            "id": "5e94e8ca4509e00013c7f16f",
            "created": 1586817226391,
            "updated": 1586817226391,
            "usageReportingType": "Cumulative",
            "metadata": {
                "chargeSyncRequired": false,
                "ibmPartNumber": "D02FCZX",
                "zuoraRatePlanChargeId": "2c92c0f8715cd199017175ad7dfb71de",
                "zuoraRatePlanId": "2c92c0f9715ce772017175ad7be134e4"
            },
            "name": "Cortex certifai platinum edition",
            "uom": {
                "identifier": "Instance",
                "multiplier": 1,
                "created": 1583808172371,
                "updated": 1583808172371,
                "supportUsageChargeType": false,
                "singularName": "Instance",
                "pluralName": "Instances",
                "suffix": "per instance",
                "inputLabel": "Enter number of instances",
                "summaryLabel": "Number of instances"
            }
        }
    ],
    "logoUrl": "https://mp.s81c.com/pwb-production/7fa13fdf607424ec566e38b8cd29a11e/productLogoImg_da446f1b-6605-45ec-990f-a6ad1e756970_aa0b6f7c-f647-40d4-b27a-94053b0cb51d.png"
}
Error response

HTTP status default

No error response parameters.

Orders

Red Hat Marketplace Orders API provides an interface to create orders for approved products.

Open specifications

Check order

post

/subscriptions/api/v1/orders/check

Verifies the user can place an order for a specific product edition, like trials and approved software.

URL parameters

No url parameters.

Body parameters
accountId

string

required

The Red Hat Marketplace Account Id

editionId

required

The edition being requested

POST /subscriptions/api/v1/orders/checkCURL
curl -X 'POST' 'https://marketplace.redhat.com/subscriptions/api/v1/orders/check' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
--data-raw '{
    "accountId": "5dea935af2ecbc0012b6bca9",
    "editionId": "EID1ZRAI"
}'
Success responses

HTTP status 204

Order is allowed.

No success response parameters.

Error response

HTTP status 400

The request could not be processed.

No error response parameters.

Create order

post

/subscriptions/api/vi/orders

Places an order for a specific product edition.

URL parameters

No url parameters.

Body parameters
requestId

string

optional

A unique identifier for the request.

accountId

string

required

The Red Hat Marketplace Account Id.

requestor

object

optional

An object with user data.

  • iamId

    string

    optional

    The user's IAM Id. Available after login or auth token generation.

    email

    string

    optional

    The user's email address. Available using the iamId.

payment

object

optional

An object with payment information.

  • purchaseOrderNumber

    string

    optional

    The purchase order number to bill against.

    paymentAuthRef

    string

    optional

    The authorization reference for the credit card.

subscriptions

array

required

An array of subscriptions to create.

  • id

    string

    optional

    For when a subscription already exists. For example, an order for a subscription renewal would include an id.

    type

    string

    optional

    Indicateds the subscription type.

    • TRIAL
      PURCHASE
      FREE
    editionId

    string

    required

    The ID of the subscription's edition from the catalog.

    editionRevision

    number

    required

    The edition version number.

    term

    string

    required

    The length of the subscription term for purchases.

    termUnit

    string

    required

    The unit for term.

    • MONTHS
      YEARS
    billingFrequency

    string

    required

    How often billing will be done.

    • MONTHLY
      QUARTERLY
      ANNUAL
    currency

    string

    optional

    The currency for this purchase order.

    lineItems

    array

    required

    An array of line items that make up the subscription.

    • chargeId

      string

      required

      The Charge ID of this line item from Commerce Configuration.

      quantity

      number

      required

      The quantity to take of this line item.

      price

      number

      optional

      The price per billing frequency for this line item.

      unitPrice

      number

      optional

      The unit price per billing frequency for this line item.

      overagePrice

      number

      optional

      The overage price for this line item.

      tax

      number

      optional

      The tax percentage for this line item.

    startDate

    number

    optional

    The start date of the subscription.

    autoRenewal

    boolean

    optional

    Automatically renews subscription at the end of term. True by default.

    byolMessage

    string

    optional

    Customer message to the ISV for the BYOL subscription.

    byol

    boolean

    optional

    Indicates BYOL subscription. False by default.

    draftContent

    boolean

    optional

    Indicates that draft content should be used for this subscription. False by default.

quoteId

string

optional

Used to override any matching tiers in the Red Hat Marketplace Commerce API.

POST /subscriptions/api/vi/ordersCURL
curl -X 'POST' 'https://marketplace.redhat.com/subscriptions/api/vi/orders' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
--data-raw '{
    "requestId": "cb14422c-3b8c-4648-be17-4dac61785ce0",
    "accountId": "5dea935af2ecbc0012b6bca9",
    "quoteId": "1234567",
    "requestor": {
        "iamId": "ibmid-9934114LQD"
    },
    "payment": {
        "purchaseOrderNumber": "8923DJ302"
    },
    "subscriptions": [
        {
            "id": "5e3d48aa4cb19936a82a42d4",
            "type": "PURCHASE",
            "editionId": "EID1ZRAI",
            "editionRevision": 2,
            "term": 12,
            "termUnit": "MONTHS",
            "billingFrequency": "MONTHLY",
            "currency": "USD",
            "lineItems": [
                {
                    "chargeId": "D029DZX",
                    "quantity": 1,
                    "price": 0,
                    "unitPrice": 0,
                    "overagePrice": 0,
                    "tax": 0
                }
            ]
        }
    ]
}'
Success responses

HTTP status 202

Order placed successfully.

data

array

optional

An array of subscription objects.

  • accountId

    number

    optional

    Tier starting unit

    editionId

    string

    optional

    Zuora rate plan overage charge ID

    editionRevision

    number

    optional

    Zuora rate plan overage charge ID

    productKey

    string

    optional

    Zuora rate plan overage charge ID

    term

    number

    optional

    Zuora rate plan overage charge ID

    termUnit

    string

    optional

    The unit for term.

    • MONTHS
      YEARS
    billingFrequency

    string

    optional

    How often billing will be done.

    • MONTHLY
      QUARTERLY
      ANNUAL
    category

    string

    optional

    • PRODUCT
    type

    string

    optional

    Indicateds the subscription type.

    • TRIAL
      PURCHASE
      FREE
    state

    string

    optional

    • INPROGRESS
    renewalType

    string

    optional

    • RENEW_CURRENT_TERM
    currentOperation

    string

    optional

    • CREATING
    lineItems

    array

    optional

    An array of line items that make up the subscription.

    • chargeId

      string

      required

      The Charge ID of this line item from Commerce Configuration.

      quantity

      number

      required

      The quantity to take of this line item.

      price

      number

      optional

      The price per billing frequency for this line item.

      unitPrice

      number

      optional

      The unit price per billing frequency for this line item.

      overagePrice

      number

      optional

      The overage price for this line item.

      tax

      number

      optional

      The tax percentage for this line item.

    provisioningInput

    object

    optional

    id

    string

    optional

metadata

object

optional

An object with create order response metadata.

  • count

    number

    optional

Response example
{
    "data": [
        {
            "accountId": "5dea935af2ecbc0012b6bca9",
            "editionId": "EID1ZRAI",
            "editionRevision": 2,
            "productKey": "7fa13fdf607424ec566e38b8cd29a11e",
            "term": 12,
            "termUnit": "MONTHS",
            "billingFrequency": "MONTHLY",
            "category": "PRODUCT",
            "type": "PURCHASE",
            "state": "IN_PROGRESS",
            "renewalType": "RENEW_CURRENT_TERM",
            "currentOperation": "CREATING",
            "lineItems": [
                {
                    "chargeId": "D029DZX",
                    "quantity": 1,
                    "price": 0,
                    "tax": 0
                }
            ],
            "provisioningInput": {},
            "id": "5e64d18fda3f692c7da08ab5"
        }
    ],
    "metadata": {
        "count": 1
    }
}
Error response

HTTP status 400

The request could not be processed.

No error response parameters.

Subscriptions

Red Hat Marketplace Subscriptions API provides an interface to get and create subscriptions for approved products.

Open specifications

Get subscription by ID

get

/subscriptions/api/v1/subscriptions/{id}

Gets subscription associated to the subscription ID.

URL parameters
id

string

required

Subscription ID.

Body parameters

No parameters.

GET /subscriptions/api/v1/subscriptions/{id}CURL
curl --location --request GET 'https://marketplace.redhat.com/subscriptions/api/v1/subscriptions/5e4bdabc21a8e05a2753bd2f' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ACCESS_TOKEN' \
Success responses

HTTP status 202

Success.

id

string

optional

Subscription ID.

accountId

string

required

The Red Hat Marketplace Account Id

editionId

string

required

The ID of the subscription's edition from the catalog.

editionRevision

number

optional

quoteId

string

optional

Used to override any matching tiers in the Red Hat Marketplace Commerce API.

requestor

object

optional

An object with user data.

  • iamId

    string

    optional

    The user's IAM Id. Available after login or auth token generation.

    email

    string

    required

    The user's email address. Available using the iamId.

workflowVersion

string

optional

Return only subscriptions that match given workflow version Can be V1 or V2.

productKey

string

optional

term

number

optional

termUnit

string

optional

The unit for term.

  • MONTHS
    YEARS
billingFrequency

string

optional

How often billing will be done.

  • MONTHLY
    QUARTERLY
    ANNUAL
category

string

optional

Subscription category.

  • PRODUCT
    PLATFORM
    USAGE_CONTAINER
type

string

optional

Indicateds the subscription type.

  • TRIAL
    PURCHASE
    FREE
state

string

optional

  • INPROGRESS
renewalType

string

optional

  • RENEW_CURRENT_TERM
currentOperation

string

optional

  • CREATING
lineItems

array

optional

An array of line items that make up the subscription.

  • chargeId

    string

    required

    The Charge ID of this line item from Commerce Configuration.

    quantity

    number

    required

    The quantity to take of this line item.

    price

    number

    optional

    The price per billing frequency for this line item.

    unitPrice

    number

    optional

    The unit price per billing frequency for this line item.

    overagePrice

    number

    optional

    The overage price for this line item.

    tax

    number

    optional

    The tax percentage for this line item.

    externalReference

    object

    optional

provisioningInput

object

optional

view

object

optional

An object of tags.

  • tags

    array

    optional

    An array of tag objects.

    • accountId

      string

      optional

      name

      string

      optional

      value

      string

      optional

      description

      string

      optional

      createdDate