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

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

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

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

product

object

required

Product data

productName

string

required

Product name

name

string

required

Edition name

description

string

required

Edition description

termUnit

string

required

Subscription term units

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

allowedSubscriptionTerms

array

optional

Allowed subscription terms for edition

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

editionCharges

array

optional

Rules governing edition charges

rules

array

optional

Rules governing edition charges

slaPartNumber

string

optional

SLA part number for edition

vendorTrialId

string

optional

Vendor defined ID for trial edition

category

string

optional

Edition category

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

product

object

required

Product data

productName

string

required

Product name

name

string

required

Edition name

description

string

required

Edition description

termUnit

string

required

Subscription term units

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

allowedSubscriptionTerms

array

optional

Allowed subscription terms for edition

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

editionCharges

array

optional

Rules governing edition charges

rules

array

optional

Rules governing edition charges

slaPartNumber

string

optional

SLA part number for edition

vendorTrialId

string

optional

Vendor defined ID for trial edition

category

string

optional

Edition category

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.

payment

object

optional

An object with payment information.

subscriptions

array

required

An array of subscriptions to create.

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.

metadata

object

optional

An object with create order response metadata.

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.

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.

billingFrequency

string

optional

How often billing will be done.

category

string

optional

Subscription category.

type

string

optional

Indicateds the subscription type.

state

string

optional

renewalType

string

optional

currentOperation

string

optional

lineItems

array

optional

An array of line items that make up the subscription.

provisioningInput

object

optional

view

object

optional

An object of tags.

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.

metadata

object

optional

An object with create order response metadata.

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.

workflowVersion

string

required

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

category

string

required

Subscription category.

type

string

required

Indicateds the subscription type.

isSaas

boolean

optional

byol

boolean

required

Indicates BYOL subscription. False by default.

tags

array

optional

An array of tags.

externalReferences

object

optional

lineItems

array

optional

An array of line items that make up the subscription.

POST /subscriptions/api/vi/subscriptionsCURL
curl --location --request POST 'https://marketplace.redhat.com/subscriptions/api/vi/subscriptions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ACCESS_TOKEN' \
--data-raw '{
    "activationDate": 1,
    "expirationDate": 1,
    "cancellationDate": 1,
    "accountId": "1231d1dasc23d12s1",
    "productName": "Power DB",
    "productKey": "3242423423423",
    "editionId": "2322d322d2d23d2",
    "editionRevision": 1,
    "editionName": "Community edition",
    "requestor": {
        "firstName": "Arun",
        "lastName": "R",
        "email": "arun@email.com",
        "iamId": "IBMId-5342342"
    },
    "workflowVersion": "v1",
    "category": "USAGE_CONTAINER",
    "type": "PURCHASE",
    "isSaas": false,
    "byol": true,
    "tags": [
        "2312312",
        "35324234"
    ],
    "externalReferences": {},
    "lineItems": [
        {
            "chargeId": "23e2e2",
            "quantity": 10,
            "price": 50,
            "unitPrice": 5,
            "overagePrice": 0,
            "tax": 7.5,
            "externalReferences": {}
        }
    ]
}'
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.

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.

billingFrequency

string

optional

How often billing will be done.

category

string

optional

Subscription category.

type

string

optional

Indicateds the subscription type.

state

string

optional

renewalType

string

optional

currentOperation

string

optional

lineItems

array

optional

An array of line items that make up the subscription.

provisioningInput

object

optional

view

object

optional

An object of tags.

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

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

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.

status

string

optional

Enum representing the offers current status: 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.

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

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.

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.

status

string

optional

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

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.

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

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.

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.

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

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

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

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

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

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

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.