Documentation - Red Hat Marketplace

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
number
optional
modifiedDate
string
optional

Response example

{
    "id": "5e4bdabc21a8e05a2753bd2f",
    "accountId": "5dea935af2ecbc0012b6bca9",
    "editionId": "EID0E8R3",
    "editionRevision": 1,
    "quoteId": "1234567",
    "requestor": {
        "iamId": "IBMid-550001882F",
        "firstName": "OM",
        "lastName": "Account",
        "email": "omprovtest@yopmail.com"
    },
    "workflowVersion": "V1",
    "productKey": "7fa13fdf607424ec566e38b8cd29a11e",
    "term": 24,
    "termUnit": "MONTHS",
    "billingFrequency": "MONTHLY",
    "category": "PRODUCT",
    "type": "TRIAL",
    "state": "ACTIVE",
    "renewalType": "RENEW_CURRENT_TERM",
    "currentOperation": "NONE",
    "lineItems": [
        {
            "chargeId": "OM_CC_dDsN2kN89DgKWp2rFHGBZa",
            "chargeNumber": "5e4bdabc21a8e05a2753bd2f-CN1",
            "quantity": 1,
            "price": 0,
            "tax": 0,
            "externalReferences": {
                "zuora_ratePlanChargeId": "2c92c0f9732e100e017349aa4aa803c5",
                "zuora_ratePlanOverageChargeIds": [
                    "2c92c0f9732e100e017349aa4aa803c4",
                    "2c92c0f9732e100e017349aa4aa803c6"
                ]
            }
        }
    ],
    "provisioningInput": {},
    "view": {
        "tags": [
            {
                "accountId": "5dea935af2ecbc0012b6bca9",
                "name": "tag name",
                "value": "tag value",
                "description": "tag description",
                "createdDate": 1598371219238,
                "modifiedDate": 1598371219238
            }
        ]
    }
}

Error response

HTTP status default

No error response parameters.

Get subscription

get

/subscriptions/api/v1/subscriptions

Gets subscription associated to the query parameter.

URL parameters

accountId

string

optional

Red Hat Marketplace Account ID.

editionId

string

optional

Edition ID.

type

string

optional

Subscription type.

productKey

string

optional

Subscription product key.

state

string

optional

Subscription state.

tag

string

optional

Subscription tag identifier.

category

string

optional

Subscription category.

operation

string

optional

Subscription current operation.

vendorAccountId

string

optional

Vendor Account Id of the subscription product.

byol

boolean

optional

Indicates BYOL subscription. Default to true if the vendorAccountId request parameter is procided.

startDate

number

optional

Start date in millis. Filters out subscriptions that were created before.

endDate

number

optional

End date in millis. Filters out subscriptions that were created after.

pageSize

integer

optional

Maximum number of entities per page. 50 by default.

page

integer

optional

Page number default.

draftContent

boolean

optional

Return only draftContent subscriptions when this flag is true. Default value is false.

isFuture

boolean

optional

Return only future date subscriptions when this flag is true. Default value is false.

workflowVersion

string

optional

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

Body parameters

No parameters.

GET /subscriptions/api/v1/subscriptionsCURL

curl --location --request GET 'https://marketplace.redhat.com/subscriptions/api/v1/subscriptions?editionId=EID0E8R3' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ACCESS_TOKEN' \

Success responses

HTTP status 202

Success.

data

array

optional

An array of subscription objects.

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
number
optional
modifiedDate
string
optional

metadata

object

optional

An object with create order response metadata.

count
number
optional
total
number
optional
page
number
optional
pageTotal
number
optional
pageSize
number
optional

Response example

{
    "data": [
        {
            "id": "5e4bdabc21a8e05a2753bd2f",
            "accountId": "5dea935af2ecbc0012b6bca9",
            "editionId": "EID0E8R3",
            "editionRevision": 1,
            "quoteId": "1234567",
            "requestor": {
                "iamId": "IBMid-550001882F",
                "firstName": "OM",
                "lastName": "Account",
                "email": "omprovtest@yopmail.com"
            },
            "workflowVersion": "V1",
            "productKey": "7fa13fdf607424ec566e38b8cd29a11e",
            "term": 24,
            "termUnit": "MONTHS",
            "billingFrequency": "MONTHLY",
            "category": "PRODUCT",
            "type": "TRIAL",
            "state": "ACTIVE",
            "renewalType": "RENEW_CURRENT_TERM",
            "currentOperation": "NONE",
            "lineItems": [
                {
                    "chargeId": "OM_CC_dDsN2kN89DgKWp2rFHGBZa",
                    "chargeNumber": "5e4bdabc21a8e05a2753bd2f-CN1",
                    "quantity": 1,
                    "price": 0,
                    "tax": 0,
                    "externalReferences": {
                        "zuora_ratePlanChargeId": "2c92c0f9732e100e017349aa4aa803c5",
                        "zuora_ratePlanOverageChargeIds": [
                            "2c92c0f9732e100e017349aa4aa803c4",
                            "2c92c0f9732e100e017349aa4aa803c6"
                        ]
                    }
                }
            ],
            "provisioningInput": {},
            "view": {
                "tags": [
                    {
                        "accountId": "5dea935af2ecbc0012b6bca9",
                        "name": "tag name 1",
                        "value": "tag value 1",
                        "description": "tag description 1",
                        "createdDate": 1598371219238,
                        "modifiedDate": 1598371219238
                    }
                ]
            }
        },
        {
            "id": "5e4bdabc21a8e05a2753bd2g",
            "accountId": "5dea935af2ecbc0012b6bca9",
            "editionId": "EID0E8R3",
            "editionRevision": 1,
            "quoteId": "1234567",
            "requestor": {
                "iamId": "IBMid-550001882F",
                "firstName": "OM",
                "lastName": "Account",
                "email": "omprovtest@yopmail.com"
            },
            "workflowVersion": "V1",
            "productKey": "7fa13fdf607424ec566e38b8cd29a11e",
            "term": 24,
            "termUnit": "MONTHS",
            "billingFrequency": "MONTHLY",
            "category": "PRODUCT",
            "type": "TRIAL",
            "state": "ACTIVE",
            "renewalType": "RENEW_CURRENT_TERM",
            "currentOperation": "NONE",
            "lineItems": [
                {
                    "chargeId": "OM_CC_dDsN2kN89DgKWp2rFHGBZa",
                    "chargeNumber": "5e4bdabc21a8e05a2753bd2f-CN1",
                    "quantity": 1,
                    "price": 0,
                    "tax": 0,
                    "externalReferences": {
                        "zuora_ratePlanChargeId": "2c92c0f9732e100e017349aa4aa803c5",
                        "zuora_ratePlanOverageChargeIds": [
                            "2c92c0f9732e100e017349aa4aa803c4",
                            "2c92c0f9732e100e017349aa4aa803c6"
                        ]
                    }
                }
            ],
            "provisioningInput": {},
            "view": {
                "tags": [
                    {
                        "accountId": "5dea935af2ecbc0012b6bca9",
                        "name": "tag name 2",
                        "value": "tag value 2",
                        "description": "tag description 2",
                        "createdDate": 1598371219238,
                        "modifiedDate": 1598371219238
                    }
                ]
            }
        }
    ],
    "metadata": {
        "count": 2,
        "total": 2,
        "page": 1,
        "pageTotal": 1,
        "pageSize": 50
    }
}

Error response

HTTP status default

No error response parameters.

Create subscription

post

/subscriptions/api/vi/subscriptions

Creates a subscription.

URL parameters

No url parameters.

Body parameters

activationDate

number

optional

expirationDate

number

optional

cancellationDate

number

optional

accountId

string

required

The Red Hat Marketplace Account Id

productName

string

required

The product name.

productKey

string

optional

editionId

string

optional

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

editionRevision

number

optional

editionName

number

required

requestor

object

required

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

required

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

category

string

required

Subscription category.

PRODUCT
PLATFORM
USAGE_CONTAINER

type

string

required

Indicateds the subscription type.

TRIAL
PURCHASE
FREE

isSaas

boolean

optional

byol

boolean

required

Indicates BYOL subscription. False by default.

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
number
optional
modifiedDate
string
optional

Response example

{
    "id": "5e4bdabc21a8e05a2753bd2f",
    "accountId": "5dea935af2ecbc0012b6bca9",
    "editionId": "EID0E8R3",
    "editionRevision": 1,
    "quoteId": "1234567",
    "requestor": {
        "iamId": "IBMid-550001882F",
        "firstName": "OM",
        "lastName": "Account",
        "email": "omprovtest@yopmail.com"
    },
    "workflowVersion": "V1",
    "productKey": "7fa13fdf607424ec566e38b8cd29a11e",
    "term": 24,
    "termUnit": "MONTHS",
    "billingFrequency": "MONTHLY",
    "category": "PRODUCT",
    "type": "TRIAL",
    "state": "ACTIVE",
    "renewalType": "RENEW_CURRENT_TERM",
    "currentOperation": "NONE",
    "lineItems": [
        {
            "chargeId": "OM_CC_dDsN2kN89DgKWp2rFHGBZa",
            "chargeNumber": "5e4bdabc21a8e05a2753bd2f-CN1",
            "quantity": 1,
            "price": 0,
            "tax": 0,
            "externalReferences": {
                "zuora_ratePlanChargeId": "2c92c0f9732e100e017349aa4aa803c5",
                "zuora_ratePlanOverageChargeIds": [
                    "2c92c0f9732e100e017349aa4aa803c4",
                    "2c92c0f9732e100e017349aa4aa803c6"
                ]
            }
        }
    ],
    "provisioningInput": {},
    "view": {
        "tags": [
            {
                "accountId": "5dea935af2ecbc0012b6bca9",
                "name": "tag name",
                "value": "tag value",
                "description": "tag description",
                "createdDate": 1598371219238,
                "modifiedDate": 1598371219238
            }
        ]
    }
}

Error response

HTTP status default

No error response parameters.

Private Offers

Private Offers API provides an interface to create and update offers.

Open specifications

Fetch private offer

get

/commerce/api/v2/offer/{id}

Fetches private offer, using the private offer ID.

URL parameters

id

string

required

An id that uniquely identifies a given private offer. Max length 500 chars.

Body parameters

No parameters.

GET /commerce/api/v2/offer/{id}CURL

curl -L -X GET '/commerce/api/v2/offer/4a37ded5-fa42-383e-8e25-d4a922ddea48' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ACCESS_TOKEN' \

Success responses

HTTP status 200

Private Offer details return.

offerDetails

object

optional

A JSON object containing the private offer

accountId
string
required
The marketplace account associated to the customer receiving the offer. Max length is 500 chars.
editionId
string
required
String id representing the edition for product. Max length is 50 chars.
billingFrequency
string
required
Enum of possible billing frequencies for a private offer.
ANNUAL
QUARTERLY
MONTHLY
externalRef
string
required
Consumer provided string representing a reference to this private offer, primarily to avoid duplicate offers.
offerTerms
array
required
Array of objects, each representing a list of charges for a given term duration. A single item denotes a single term for a private offer deal, multiple items denotes a set of ramps for a private offer deal.
term
number
required
Number of units defined by time unit of months.
charges
array
required
An array of charge objects (Max 50).
id
string
required
quantity
number
required
unitPrice
number
required
status
string
optional
Enum representing the offers current status only Draft & Pending are editable.
Draft
Pending
Quoted
CSMRejected
Rejected
Accepted
offerStartDate
number
optional
Date object indicating the future start date for the offer's underlying product subscription.
offerExpireDate
number
required
Date object representing the offer's expiration date.
updateKey
string
optional
Unique hash used to ensure no private offer can be simultaneously updated.
options
object
optional
An object with optional properties.
suppressCustomerRHMEmails
boolean
optional
Suppressess Red Hat Markeptlace branded email notifications.

message

string

optional

Shows an error message, when applicable.

Response example

{
    "accountId": "1234",
    "editionId": "halloween-edition-1",
    "billingFrequency": "MONTHLY",
    "offerTerms": [
        {
            "term": 12,
            "charges": [
                {
                    "id": "abc123",
                    "quantity": 10,
                    "unitPrice": 5000
                }
            ]
        }
    ],
    "status": "Pending",
    "offerStartDate": 1630497540000,
    "offerExpireDate": 1630997540000,
    "externalRef": "af854379-4320-3967-a272-549c15eb412f",
    "updateKey": "62bc21b5-1f41-3d5e-8523-6f0b3821e6d8"
}

Error response

HTTP status default

No error response parameters.

Update private offer

patch

/commerce/api/v2/offer/{id}

Update private offer details, using the private offer ID and updated private offer details object.

URL parameters

id

string

required

An id that uniquely identifies a given private offer. Max length 500 chars.

Body parameters

editionId

string

optional

The Editionid Schema

billingFrequency

string

optional

Enum that represents the offers possible billing frequencies

ANNUAL
QUARTERLY
MONTHLY

offerTerms

array

optional

Array of objects, each representing a list of charges for a given term duration. A single item denotes a single term for a private offer deal, multiple items denotes a set of ramps for a private offer deal.

term
number
required
Number of units defined by time unit of months.
charges
array
required
An array of charge objects (Max 50).
id
string
required
quantity
number
required
unitPrice
number
required

status

string

optional

Enum representing the offers current status: Draft, Pending, Quoted, CSMRejected, Rejected, Accepted

Draft
Pending
Quoted
CSMRejected
Rejected
Accepted

offerStartDate

integer

optional

Date object representing the offers start date

offerExpireDate

integer

optional

Date object representing the offers expiration date

updateKey

string

required

Unique hash used to ensure no private offer is updated simultaneously

options

object

optional

An object with optional properties.

suppressCustomerRHMEmails
boolean
optional
Suppressess Red Hat Markeptlace branded email notifications.

PATCH /commerce/api/v2/offer/{id}CURL

curl -L -X PATCH '/commerce/api/v2/offer/4a37ded5-fa42-383e-8e25-d4a922ddea48 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
--data-raw '{
    "editionId": "halloween-edition-1",
    "billingFrequency": "MONTHLY",
    "offerTerms": [
        {
            "term": 12,
            "charges": [
                {
                    "id": "abc123",
                    "quantity": 10,
                    "unitPrice": 5000
                }
            ]
        }
    ],
    "status": "Pending",
    "offerStartDate": 1630497540000,
    "offerExpireDate": 1630997540000,
    "updateKey": "8c397393-a077-3246-997e-update",
    "options": {
        "suppressCustomerRHMEmails": true
    }
}'

Success responses

HTTP status 200

Successful private offer update

status

string

optional

Enum representing the offers current status: Draft, Pending, Quoted, CSMRejected, Rejected, Accepted

Draft
Pending

message

string

optional

Shows an error message, when applicable.

Response example

{
    "ok": "true",
    "status": "Pending"
}

Error response

HTTP status 400

The request could not be processed.

No error response parameters.

Create private offer

post

/commerce/api/v2/offer

Create a new private offer, using the private offer details object.

URL parameters

No url parameters.

Body parameters

accountId

string

required

The marketplace account associated to the customer receiving the offer. Max length is 500 chars.

editionId

string

required

String id representing the edition for product. Max length is 50 chars.

billingFrequency

string

required

Enum of possible billing frequencies for a private offer.

ANNUAL
QUARTERLY
MONTHLY

externalRef

string

required

Consumer provided string representing a reference to this private offer, primarily to avoid duplicate offers.

offerTerms

array

required

Array of objects, each representing a list of charges for a given term duration. A single item denotes a single term for a private offer deal, multiple items denotes a set of ramps for a private offer deal.

term
number
required
Number of units defined by time unit of months.
charges
array
required
An array of charge objects (Max 50).
id
string
required
quantity
number
required
unitPrice
number
required

status

string

optional

Enum representing the offers current status only Draft & Pending are editable.

Draft
Pending
Quoted
CSMRejected
Rejected
Accepted

offerStartDate

number

optional

Date object indicating the future start date for the offer's underlying product subscription.

offerExpireDate

number

required

Date object representing the offer's expiration date.

updateKey

string

optional

Unique hash used to ensure no private offer can be simultaneously updated.

options

object

optional

An object with optional properties.

suppressCustomerRHMEmails
boolean
optional
Suppressess Red Hat Markeptlace branded email notifications.

POST /commerce/api/v2/offerCURL

curl -L -X POST '/commerce/api/v2/offer' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
--data-raw '{
    "accountId": "a86e518969cb2de1",
    "editionId": "halloween-edition-1",
    "billingFrequency": "MONTHLY",
    "offerTerms": [
        {
            "term": 12,
            "charges": [
                {
                    "id": "abc123",
                    "quantity": 20,
                    "unitPrice": 3500
                },
                {
                    "id": "def123",
                    "quantity": 5,
                    "unitPrice": 6000
                }
            ]
        },
        {
            "term": 12,
            "charges": [
                {
                    "id": "hij123",
                    "quantity": 15,
                    "unitPrice": 2500
                }
            ]
        }
    ],
    "status": "Pending",
    "offerStartDate": 1630497540000,
    "offerExpireDate": 1630997540000,
    "externalRef": "f37a1a42-141f-3122-a861-4e1bfab0bb06",
    "updateKey": "8c397393-a077-3246-997e-update",
    "options": {
        "suppressCustomerRHMEmails": true
    }
}'

Success responses

HTTP status 200

Offer created

status

string

optional

Enum representing the offers current status: Draft, Pending, Quoted, CSMRejected, Rejected, Accepted

Draft
Pending

id

string

optional

String id uniquely representing a given private offer

message

string

optional

Shows an error message, when applicable.

Response example

{
    "ok": "true",
    "status": "Pending",
    "offerId": "49028da9-4d8b-3357-8feb-dd62c6e7c8af",
    "message": "Private offer created successfully."
}

Error response

HTTP status 400

The request could not be processed.

No error response parameters.

Create attachment URL (upload)

post

/commerce/api/v2/offer/attachmenturls (upload)

Create URL that can be used to upload an attachment to cloud object storage. Only PDFs supported.

URL parameters

No url parameters.

Body parameters

action

string

required

Enum representing the action associated with the attachment URL.

upload
download

POST /commerce/api/v2/offer/attachmenturls (upload)CURL

curl -L -X POST '/commerce/api/v2/offer/attachmenturls' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
--data-raw '{
    "action": "upload"
}'

Success responses

HTTP status 200

Attachment URL returned.

ok

boolean

optional

Indicates whether the request was processed successfully. True indicates success, False indicates a processing error.

url

string

optional

URL that will be used to upload or download a file to cloud object storage.

id

string

optional

String id uniquely representing a given private offer attachment key with the format (account id / uuid). Returned when action is upload.

Response example

{
    "ok": true,
    "url": "https://rhm-commerce-cos-bucket-stage.s3.us.cloud-object-storage.appdomain.cloud/5e99d8da07f07c0013954599/9a36fbf2-a700-467f-9fc9-035b56045465?AWSAccessKeyId=d352ed6596bd4be9b3a6a7325f50c4b0&Content-Type=application%2Fpdf&Expires=1658156565&Signature=nbPQ7hwpQiCAslErAwKX%2BBlIP3s%3D",
    "id": "5e99d8da07f07c0013954599/9a36fbf2-a700-467f-9fc9-035b56045465"
}

Error response

HTTP status 400

Error creating presigned attachment url, user does not have VendorSalesAdmin role.

No error response parameters.

Create attachment URL (download)

post

/commerce/api/v2/offer/attachmenturls (download)

Create URL that can be used to download an attachment to cloud object storage.

URL parameters

No url parameters.

Body parameters

action

string

required

Enum representing the action associated with the attachment URL.

upload
download

key

string

required

The key associated with the file that will be downloaded from cloud object storage. Required for download action.

name

string

optional

The name associated with the file that will be downloaded from cloud object storage.

POST /commerce/api/v2/offer/attachmenturls (download)CURL

curl -L -X POST '/commerce/api/v2/offer/attachmenturls' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
--data-raw '{
    "action": "download",
    "key": "5e99d8da07f07c0013954599",
    "name": "testFile.pdf"
}'

Success responses

HTTP status 200

Attachment URL returned.

ok

boolean

optional

Indicates whether the request was processed successfully. True indicates success, False indicates a processing error.

url

string

optional

URL that will be used to upload or download a file to cloud object storage.

Response example

{
    "ok": true,
    "url": "https://rhm-commerce-cos-bucket-stage.s3.us.cloud-object-storage.appdomain.cloud/5e99d8da07f07c0013954599/9a36fbf2-a700-467f-9fc9-035b56045465?AWSAccessKeyId=d352ed6596bd4be9b3a6a7325f50c4b0&Expires=1658157031&Signature=UDNLNj4gCx0wGadlAsOjzljQTUY%3D&response-content-disposition=attachment%3B%20filename%20%3D%20%22testFile.pdf%22"
}

Error response

HTTP status 400

Error creating presigned attachment url, user does not have VendorSalesAdmin role.

No error response parameters.

Product Lifecycle API

Red Hat Marketplace Product Lifecycle API defines the API contract between the Red Hat Marketplace platform and the product to manage its lifecycle. These APIs are a set of simple webhook-based event notifications that can be consumed by product providers to orchestrate the provisioning, deprovisioning, update and any other operations that might have to be performed. For more information, refer to How Product Lifecycle API works.

Open specifications

New or updated subscription

put

/{endpoint-url-path1}

Partners selling on Red Hat Marketplace receive an event notification when a user creates or updates a subscription.

URL parameters

endpoint-url-path

string

required

The complete path of the endpoint URL which may contain multiple path segments

Body parameters

apiVersion

string

required

The version of the API

eventType

string

required

The type of event being sent

subscription

eventId

string

required

A unique identifier for this event which may be repeated if the same event is sent again

retryCount

integer

required

The number of attempts so far for this particular message

testEvent

boolean

optional

Indicates if this event is a test event or not

data

object

required

Data specific to the event's action

action
string
required
The action being performed on the subscription
subscribe
update
id
string
required
The ID of the subscription
productId
string
required
The ID of the product being subscribed to
productName
string
required
Readable name for the product
editionId
string
required
The identifier for the edition
editionName
string
required
Readable name of the edition
type
string
required
The type of subscription
TRIAL
FREE
PURCHASE
renewType
string
required
Indicates the operation performed when the term completes. Renewal, termination
ORIGINAL_TERM
TERMINATE
attributes
object
required
Attributes selected for the plan during purchase. This is an open object and varies by product and edition. It will typically contain the charges selected and the quantities for those charges as the name of the charge and intege value
context
object
required
The context of the requesting user
accountId
string
required
The ID of the account that owns the subscription
companyName
string
optional
The company name on the billing address of this subscription
address1
string
optional
Line 1 of the billing address of this subscription
address2
string
optional
Line 2 of the billing address of this subscription
city
string
optional
The city of the billing address of this subscription
postalCode
string
optional
The postal code of the billing address of this subscription
stateProvince
string
optional
The state/province of the billing address of this subscription
countryCode
string
required
The 2 character country code following the ISO alpha-2 standard
user
object
required
Details of the user that placed the order
firstName
string
optional
User's first name
lastName
string
optional
User's last name
email
string
optional
User's email address

PUT /{endpoint-url-path1}CURL

curl --location --request PUT '/{endpoint-url-path1}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ACCESS_TOKEN' \
--data-raw '{
    "apiVersion": "1",
    "eventType": "subscription",
    "eventId": "1a2b3c4d5e",
    "retryCount": 1,
    "data": {
        "action": "subscribe",
        "id": "12345",
        "productId": "PK_01",
        "productName": "Power DB",
        "editionId": "EIDJWBWL",
        "editionName": "Power DB Trial Edition",
        "type": "TRIAL",
        "term": 12,
        "renewType": "TERMINATE",
        "attributes": {
            "part1": 10,
            "sku1": 50,
            "part2": "PREMIUM",
            "sku2": 50
        },
        "provisioningInput": {
            "dataCenter": "US_DAL_EAST"
        },
        "context": {
            "accountId": "ad6218f0-e07a-11e9-a1c9-bd48ff9cc364",
            "companyName": "My Corp",
            "address1": "100 High Street",
            "address2": "Building 500",
            "city": "Raleigh",
            "postalCode": "27560",
            "stateProvince": "NC",
            "countryCode": "US",
            "user": {
                "firstName": "User",
                "lastName": "X",
                "email": "user@domain.com"
            }
        }
    }
}'

Success responses

HTTP status 200

The message was understood and processed. The result of the processing is determined by the returned content.

status

string

required

The current status of the event processing

inprogress
needs_user_input
complete
failed

message

string

optional

A readable message typically to indicate failure reasons and used for debugging purposes

retryAfter

integer

optional

A suggestion on when to retry the event and applicable only when the status is 'inprogress' or 'needs_user_input'

Response example

{
    "status": "complete",
    "message": "",
    "retryAfter": 2
}

Error response

HTTP status 404

The endpoint was unreachable or the resource was not found by the endpoint. The request will be retried till a give-up threshold

No error response parameters.

Suspended, resumed, or unsubscribed subscription

put

/{endpoint-url-path}

Partners selling on Red Hat Marketplace receive an event notification when the marketplace suspends or resumes a user's subscription, as well as when a user unsubscribes from an active subscription.

URL parameters

endpoint-url-path

string

required

The complete path of the endpoint URL which may contain multiple path segments

Body parameters

apiVersion

string

required

The version of the API

eventType

string

required

The type of event being sent

subscription

eventId

string

required

A unique identifier for this event which may be repeated if the same event is sent again

retryCount

integer

required

The number of attempts so far for this particular message

testEvent

boolean

optional

Indicates if this event is a test event or not

data

object

required

Data specific to the event's action

action
string
required
The action being performed on the subscription
suspend
resume
unsubscribe
id
string
required
The ID of the subscription

PUT /{endpoint-url-path}CURL

curl --location --request PUT '/{endpoint-url-path}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ACCESS_TOKEN' \
--data-raw '{
    "apiVersion": "1",
    "eventType": "subscription",
    "eventId": "1a2b3c4d5e",
    "retryCount": 1,
    "data": {
        "action": "suspend",
        "id": "12345"
    }
}'

Success responses

HTTP status 200

The message was understood and processed. The result of the processing is determined by the returned content.

status

string

required

The current status of the event processing

inprogress
needs_user_input
complete
failed

message

string

optional

A readable message typically to indicate failure reasons and used for debugging purposes

retryAfter

integer

optional

A suggestion on when to retry the event and applicable only when the status is 'inprogress' or 'needs_user_input'

Response example

{
    "status": "complete",
    "message": "",
    "retryAfter": 2
}

Error response

HTTP status 404

The endpoint was unreachable or the resource was not found by the endpoint. The request will be retried till a give-up threshold

No error response parameters.

API reference

Account

URL parameters

Body parameters

Success responses

Error response

Commerce

URL parameters

Body parameters

Success responses

Error response

URL parameters

Body parameters

Success responses

Error response

URL parameters

Body parameters

Success responses

Error response

URL parameters

Body parameters

Success responses

Error response

Orders

URL parameters

Body parameters

Success responses

Error response

URL parameters

Body parameters

Success responses

Error response

Subscriptions

URL parameters

Body parameters

Success responses

Error response

URL parameters

Body parameters

Success responses

Error response

URL parameters

Body parameters

Success responses

Error response

Private Offers

URL parameters

Body parameters

Success responses

Error response

URL parameters

Body parameters

Success responses

Error response

URL parameters

Body parameters

Success responses

Error response

URL parameters

Body parameters

Success responses

Error response

URL parameters

Body parameters

Success responses

Error response

Product Lifecycle API

URL parameters

Body parameters

Success responses

Error response

URL parameters

Body parameters

Success responses

Error response