API reference

Metering

The Red Hat Marketplace Metering API provides an interface to submit usage for subscriptions.

  • URL parameters

    No url parameters.

    Body parameters

    data

    array

    required

    An array of usage events.

    • start

      number

      required

      The start time of the usage measurement window. This is submitted as milliseconds from Epoch.


      end

      number

      required

      The end time of the usage measurement window. This is submitted as milliseconds from Epoch.


      resourceType

      string

      required

      The type of resource and is typically SAAS

      • SAAS
        Operator

      subscriptionId

      string

      required

      The ID of the subscription for which usage was collected.


      eventId

      string

      required

      A unique id for this event, if another request is sent with the same value, it is considered the same event.


      additionalAttributes

      object

      optional

      Any optional additional attributes. Currently unused.


      measuredUsage

      array

      required

      An array of recorded usage.

      • chargeId

        string

        required

        The identifier for the metered charge


        value

        number

        required

        The recorded usage for this charge

    POST /metering/api/v1/metricsCURL
    curl --location --request POST 'https://sandbox.marketplace.redhat.com/metering/api/v1/metrics' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer ACCESS_TOKEN' \
    --header 'Cookie: JSESSIONID=C0A04FE8844873827929FBD9B8365B87; om-iam-pre=5ea0422044e8b0b69799d5c6; om-iam-pre.sig=n8KXUVJl3_7367oUZ0-4NI7njR4; commerceFeatures={}; commerceFeatures.sig=p_Y_zw10j-sUuKlSGP0PtW3_xc8' \
    --data-raw '{
    "data": [
    {
    "start": 1597691095125,
    "end": 1597691705125,
    "resourceType": "Operator",
    "resourceInstanceId": "xxxxxxxxxxxxxxxxxxx",
    "resourceTypeName": "custom-resource-type-or-product-id",
    "subscriptionId": "5f3acdeae27a6b538020d09a",
    "eventId": "5f33e41cae0b0c529d200001",
    "additionalAttributes": {},
    "measuredUsage": [
    {
    "chargeId": "cockroach.db.com:Cockroachdb:container_cpu_usage_core_avg",
    "value": 500
    }
    ]
    }
    ]
    }'
    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.


    status

    string

    required

    Indicates overall status of the request.

    • inprogress
      accepted
      failed

    message

    string

    required

    A descriptive message further explaining the status.


    data

    array

    required

    Array of objects with status details on each submitted event as well as the event itself.

    • status

      string

      required

      Processing status of this one event.


      batchId

      string

      required

      A unique id used to reference the same event with the get status API.


      payload

      required

      A copy of the submitted event.

      • start

        number

        required

        The start time of the usage measurement window. This is submitted as milliseconds from Epoch.


        end

        number

        required

        The end time of the usage measurement window. This is submitted as milliseconds from Epoch.


        resourceType

        string

        required

        The type of resource and is typically SAAS

        • SAAS
          Operator

        subscriptionId

        string

        required

        The ID of the subscription for which usage was collected.


        eventId

        string

        required

        A unique id for this event, if another request is sent with the same value, it is considered the same event.


        additionalAttributes

        object

        optional

        Any optional additional attributes. Currently unused.


        measuredUsage

        array

        required

        An array of recorded usage.

        • chargeId

          string

          required

          The identifier for the metered charge


          value

          number

          required

          The recorded usage for this charge

    Response example
    {
    "status": "accepted",
    "message": "",
    "data": [
    {
    "status": "",
    "batchId": "",
    "payload": [
    {
    "start": 1597237547916,
    "end": 1597239444813,
    "resourceType": "SAAS",
    "resourceInstanceId": "instance-12345",
    "resourceTypeName": "super-db",
    "subscriptionId": "5f33e41cae0b0c529d2433aa",
    "eventId": "5f33e41cae0b0c529d243305",
    "additionalAttributes": {},
    "measuredUsage": [
    {
    "chargeId": "cockroach.db.com:Cockroachdb:container_cpu_usage_core_avg",
    "value": 150
    }
    ]
    }
    ]
    }
    ]
    }
    Error response

    HTTP status default

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


    No error response parameters.

  • URL parameters

    batchId

    string

    required

    The Id of the batch of usage to retrieve

    Body parameters

    No parameters.

    GET /v1/metrics/${batchId}CURL
    curl --location --request GET 'https://sandbox.marketplace.redhat.com/v1/metrics/${batchId}' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer ACCESS_TOKEN' \
    --header 'Cookie: JSESSIONID=C0A04FE8844873827929FBD9B8365B87; om-iam-pre=5ea0422044e8b0b69799d5c6; om-iam-pre.sig=n8KXUVJl3_7367oUZ0-4NI7njR4; commerceFeatures={}; commerceFeatures.sig=p_Y_zw10j-sUuKlSGP0PtW3_xc8' \
    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.


    status

    string

    required

    Indicates overall status of the request.

    • inprogress
      accepted
      failed

    message

    string

    required

    A descriptive message further explaining the status.


    data

    array

    required

    Array of objects with status details on each submitted event as well as the event itself.

    • status

      string

      required

      Processing status of this one event.


      batchId

      string

      required

      A unique id used to reference the same event with the get status API.


      payload

      required

      A copy of the submitted event.

      • start

        number

        required

        The start time of the usage measurement window. This is submitted as milliseconds from Epoch.


        end

        number

        required

        The end time of the usage measurement window. This is submitted as milliseconds from Epoch.


        resourceType

        string

        required

        The type of resource and is typically SAAS

        • SAAS
          Operator

        subscriptionId

        string

        required

        The ID of the subscription for which usage was collected.


        eventId

        string

        required

        A unique id for this event, if another request is sent with the same value, it is considered the same event.


        additionalAttributes

        object

        optional

        Any optional additional attributes. Currently unused.


        measuredUsage

        array

        required

        An array of recorded usage.

        • chargeId

          string

          required

          The identifier for the metered charge


          value

          number

          required

          The recorded usage for this charge

    Response example
    {
    "status": "accepted",
    "message": "",
    "data": [
    {
    "status": "",
    "batchId": "",
    "payload": [
    {
    "start": 1597237547916,
    "end": 1597239444813,
    "resourceType": "SAAS",
    "resourceInstanceId": "instance-12345",
    "resourceTypeName": "super-db",
    "subscriptionId": "5f33e41cae0b0c529d2433aa",
    "eventId": "5f33e41cae0b0c529d243305",
    "additionalAttributes": {},
    "measuredUsage": [
    {
    "chargeId": "cockroach.db.com:Cockroachdb:container_cpu_usage_core_avg",
    "value": 150
    }
    ]
    }
    ]
    }
    ]
    }
    Error response

    HTTP status default


    No error response parameters.

Product Lifecycle API

The 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.

  • 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

      optional

      The action being performed on the subscription

      • subscribe
        update

      id

      string

      optional

      The ID of the subscription


      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

    EVENT /{endpoint-url-path1}CURL
    curl --location --request EVENT 'https://sandbox.marketplace.redhat.com/{endpoint-url-path1}' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer ACCESS_TOKEN' \
    --header 'Cookie: JSESSIONID=C0A04FE8844873827929FBD9B8365B87; om-iam-pre=5ea0422044e8b0b69799d5c6; om-iam-pre.sig=n8KXUVJl3_7367oUZ0-4NI7njR4; commerceFeatures={}; commerceFeatures.sig=p_Y_zw10j-sUuKlSGP0PtW3_xc8' \
    --data-raw '{
    "summary": "Create subscription",
    "value": {
    "apiVersion": "1",
    "eventType": "subscription",
    "eventId": "1a2b3c4d5e",
    "retryCount": 1,
    "data": {
    "action": "subscribe",
    "id": "12345",
    "productKey": "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
      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'

    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.

  • 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

    EVENT /{endpoint-url-path}CURL
    curl --location --request EVENT 'https://sandbox.marketplace.redhat.com/{endpoint-url-path}' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer ACCESS_TOKEN' \
    --header 'Cookie: JSESSIONID=C0A04FE8844873827929FBD9B8365B87; om-iam-pre=5ea0422044e8b0b69799d5c6; om-iam-pre.sig=n8KXUVJl3_7367oUZ0-4NI7njR4; commerceFeatures={}; commerceFeatures.sig=p_Y_zw10j-sUuKlSGP0PtW3_xc8' \
    --data-raw '{
    "summary": "Suspend subscription",
    "value": {
    "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
      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'

    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.