Products API

Complete API reference for managing products and product versions in the Billerang catalog.

Overview

A Product is a unified catalog entity (NEW model, v12+) that represents both services and physical products. Products use explicit versioning -- each version has its own validity dates, charges, and attributes.

Endpoints

List Products

GET /v1/catalog/products?range=0-24&product_line=SOFTWARE

Query Parameters:

Parameter	Type	Description
range	string	Pagination range (e.g., 0-24)
product_line	string	Filter by product line code
brand	string	Filter by brand code
status	string	Filter by current version status
sort	string	Sort field (prefix - for descending)
expand	string	Include: charges, versions, attributes

Response:

[
  {
    "code": "PROD_PLATFORM",
    "name": "Platform Access",
    "product_line": "SOFTWARE",
    "brand": "BILLERANG",
    "current_version": {
      "version": 2,
      "status": "published",
      "valid_from": "2024-06-01T00:00:00Z"
    },
    "charge_codes": ["RC_PLATFORM_MONTHLY", "OS_SETUP_FEE"]
  }
]

Get Product

GET /v1/catalog/products/{code}

Response:

{
  "code": "PROD_PLATFORM",
  "name": "Platform Access",
  "description": "Core billing platform with API access",
  "product_line": "SOFTWARE",
  "brand": "BILLERANG",
  "current_version": {
    "version": 2,
    "status": "published",
    "valid_from": "2024-06-01T00:00:00Z",
    "valid_to": null,
    "charge_codes": ["RC_PLATFORM_MONTHLY", "OS_SETUP_FEE"],
    "attributes": {
      "tier": { "type": "list", "default": "basic", "options": ["basic", "pro", "enterprise"] },
      "max_api_calls": { "type": "number", "default": 100000 }
    }
  },
  "versions": [
    { "version": 1, "status": "closed", "valid_from": "2024-01-01T00:00:00Z", "valid_to": "2024-05-31T00:00:00Z" },
    { "version": 2, "status": "published", "valid_from": "2024-06-01T00:00:00Z", "valid_to": null }
  ]
}

Create Product

POST /v1/catalog/products

{
  "code": "PROD_ANALYTICS",
  "name": "Analytics Add-on",
  "description": "Real-time analytics dashboard",
  "product_line": "SOFTWARE",
  "brand": "BILLERANG"
}

Response: 201 Created + Location: /v1/catalog/products/PROD_ANALYTICS

Upsert Product

POST /v1/catalog/products/{code}

Same UPSERT semantics as offers. Supports newCode for rename.

Update Product

PUT /v1/catalog/products/{code}

{
  "name": "Advanced Analytics",
  "description": "Updated analytics with ML insights"
}

Delete Product

DELETE /v1/catalog/products/{code}

Only allowed if no offers reference this product and no active subscriptions exist.

Clone Product

POST /v1/catalog/products/{code}/clone

{
  "new_code": "PROD_ANALYTICS_V2",
  "new_name": "Analytics V2"
}

Creates a deep copy including all charges and the current version (as DRAFT).

Manage Charges

Add charges to product:

POST /v1/catalog/products/{code}/charges

{
  "charge_codes": ["RC_ANALYTICS_MONTHLY", "UC_QUERY_USAGE"],
  "counter_codes": { "UC_QUERY_USAGE": "CTR_MONTHLY_QUERIES" }
}

Remove charge from product:

DELETE /v1/catalog/products/{code}/charges/{charge_code}

Product Versions

Create Version

POST /v1/catalog/product_versions

{
  "product_code": "PROD_PLATFORM",
  "valid_from": "2025-01-01T00:00:00Z",
  "charge_codes": ["RC_PLATFORM_MONTHLY_V2", "OS_SETUP_FEE"],
  "attributes": {
    "tier": { "type": "list", "default": "pro", "options": ["basic", "pro", "enterprise"] }
  }
}

Update Version

PUT /v1/catalog/product_versions/{id}

{
  "valid_from": "2025-02-01T00:00:00Z",
  "attributes": { "max_api_calls": { "type": "number", "default": 200000 } }
}

Publish Version

PUT /v1/catalog/product_versions/{id}
{ "status": "published" }

Version Lifecycle

Rules:

• Only one version can be PUBLISHED at a time
• Publishing a new version automatically closes the previous one
• CLOSED versions cannot be reopened
• Existing subscriptions continue using their subscribed version until renewal

Product vs ServiceTemplate

Feature	Product (NEW)	ServiceTemplate (OLD)
Versioning	Explicit (ProductVersion)	None
Charge linking	ProductChargeTemplateMapping	ServiceChargeTemplate*
Attributes	ProductVersionAttribute	Custom fields only
Physical products	Yes	No (services only)
Table	cpq_product	cat_service_template

Runtime bridge: ServiceInstance handles both. Check serviceInstance.productVersion != null for NEW model.

Error Codes

Error Code	HTTP	Description
PRODUCT_NOT_FOUND	404	Product code doesn't exist
PRODUCT_ALREADY_EXISTS	409	Duplicate product code
PRODUCT_HAS_ACTIVE_OFFERS	422	Cannot delete product referenced by offers
PRODUCT_VERSION_NOT_FOUND	404	Version ID doesn't exist
PRODUCT_VERSION_STATUS_INVALID	422	Invalid version status transition