Product API

Product API

The Product API is the implementation-layer service that exposes TPx product data from Salesforce (CPQ / Steelbrick) through a single, consistent HTTP endpoint. It retrieves a Salesforce Product2 record and returns it at a selectable depth, always including the four-level product hierarchy.

This service is intended to be composed into larger product-integration processes (bulk migration, catalog sync, ServiceNow/TMF alignment). Today it exposes the product-lookup endpoint plus a runtime diagnostics endpoint.

Base URL

All endpoints are relative to the following base URL:

https://product.tpxapps.com

The service runs on CloudHub 2.0. Requests and responses use application/json.

Authentication

This is an internal implementation-layer API. It is reached through the TPx integration platform rather than directly by external clients, and does not require a per-request bearer token at this layer. Network access is restricted to trusted callers.

Detail levels

The detail query parameter selects how much of the product graph is returned. Each level is a superset of the previous one. An omitted or invalid value falls back to basic.

Response format

The format query parameter selects the response shape. An omitted or invalid value falls back to default.

Product hierarchy

Every response includes a hierarchy object carrying Levels 1–4 — Company, Category, Group, Family. Each level has a numeric level, a label (the Salesforce picklist text), and an id.

Only Family resolves to a registry id (Assigned_Family__c → Product_Hierarchy__c); Company/Category/Group carry "id": null because no such link exists in the data.

Get Product by ID

Retrieves a single Salesforce Product2 at the requested detail level, including the four-level product hierarchy.

curl "https://product.tpxapps.com/product/01tO100000Ghdg5IAB?detail=basic"

{
  "id": "01tO100000Ghdg5IAB",
  "name": "Managed Microsoft 365 - Commercial",
  "productCode": "SSN1-TECH-O365-COM",
  "description": "Managed Microsoft 365 subscription with TPx onboarding and support.",
  "isActive": true,
  "hierarchy": {
    "company":  { "level": 1, "label": "TPx",            "id": null },
    "category": { "level": 2, "label": "Collaboration",  "id": null },
    "group":    { "level": 3, "label": "Cloud Services", "id": null },
    "family":   { "level": 4, "label": "Microsoft 365",  "id": "a2NO1000001s6W5MAI" }
  }
}

{
  "id": "01tO100000Ghdg5IAB",
  "name": "Managed Microsoft 365 - Commercial",
  "productCode": "SSN1-TECH-O365-COM",
  "description": "Managed Microsoft 365 subscription with TPx onboarding and support.",
  "isActive": true,
  "hierarchy": { /* … as above … */ },
  "features": [
    {
      "id": "a1AO100000ABcd1EAF",
      "name": "Base License",
      "number": 1,
      "minOptionCount": 1,
      "maxOptionCount": 1
    }
  ],
  "options": [
    {
      "id": "a1BO100000XYz01EAF",
      "name": "Microsoft 365 Business Standard",
      "number": 1,
      "required": true,
      "quantity": 1,
      "type": "Component",
      "featureId": "a1AO100000ABcd1EAF",
      "product": {
        "id": "01tO100000Haaa1IAB",
        "name": "Microsoft 365 Business Standard"
      }
    }
  ]
}

"product": {
  "id": "01tO100000Haaa1IAB",
  "name": "Microsoft 365 Business Standard",
  "productCode": "M365-BUS-STD",
  "description": "Microsoft 365 Business Standard seat.",
  "isActive": true,
  "family": "Microsoft 365"
}

JVM Diagnostics

Runtime diagnostic that reports the container JVM identity and the count of live com.tpxapps.* instances on the heap — used to verify the runtime does not retain the old application graph across a redeploy.

curl "https://product.tpxapps.com/utils/jvm"

{
  "jvm": {
    "pid": "12@productapi-v3jj0c",
    "startTime": "2026-07-08T21:09:44.512Z",
    "uptimeMillis": 384210,
    "classLoaderId": 1834501723,
    "classLoader": "MuleArtifactClassLoader[productapi]"
  },
  "com.tpxapps.instances": {
    "com.tpxapps.api.Api": 1,
    "com.tpxapps.api.salesforce.SalesforceConnectorPool": 1
  }
}

Response models

Product

idstring

Salesforce Product2 ID (18-char).

namestring

Product name.

productCodestring

SKU / product code.

descriptionstring · nullable

Long description.

isActiveboolean

Whether the product is active.

hierarchyobject

Levels 1–4 (see below). Always present.

featuresarray

full · extended Related feature groupings.

optionsarray

full · extended Bundle options, each with a nested product.

Hierarchy level

levelnumber

1 = Company, 2 = Category, 3 = Group, 4 = Family.

labelstring · nullable

Picklist text for the level.

idstring · nullable

Registry ID — populated for Family only; null otherwise.

Feature

idstring

SBQQ__ProductFeature__c ID.

namestring

Feature name.

numbernumber · nullable

Display order.

minOptionCountnumber · nullable

Minimum options selectable.

maxOptionCountnumber · nullable

Maximum options selectable.

Option

idstring

SBQQ__ProductOption__c ID.

namestring

Option name.

numbernumber · nullable

Display order.

requiredboolean · nullable

Whether the option is required.

quantitynumber · nullable

Default quantity.

typestring · nullable

Option type (e.g. Component).

featureIdstring · nullable

Owning feature ID.

productobject

The option's Product2 — id + name; enriched with productCode/description/isActive/family under extended.

Error codes

The API uses standard HTTP status codes to indicate success or failure.

Error responses carry no body — the status code is the signal.