Best practices for setting up your product portfolio

A well-structured product portfolio helps ensure that purchases are mapped correctly, pricing rules can be applied consistently, and invoices remain correct. This article provides practical recommendations for setting up and maintaining product categories, products, references, and SKUs within your organisation and in CloudBilling.

Why product structure matters

Products are at the core of how CloudBilling processes purchases, applies pricing, and prepares invoice data. A clear and stable product structure helps you to:

map incoming purchases correctly
avoid unmapped usage
apply pricing rules consistently
maintain a clear invoice design
reduce operational effort when source systems or connectors change

A poorly maintained product structure can lead to purchases no longer matching the correct product, especially when identifiers are changed without considering existing integrations or historical usage.

1. Define a clear product category structure first

Before creating products, first determine how your product categories should be structured. In most cases, a tree structure with multiple levels gives the best results.

A common approach is:

Level 1: Service domain
Example: Public Cloud
Level 2: Product category
Example: Azure Plan
Level 3: Subcategories Example: Virtual Machines
Level 4: Individual products

Your structure can be based on:

the categorization provided by the cloud vendor
your own internal product catalogue
the intended invoice structure

Choose a structure that is stable and understandable for both operational users and billing stakeholders.

2. Use consistent naming conventions

Use clear and consistent naming for product categories, products, references, and SKUs.

Recommended practices:

use a naming structure that is understandable to both technical and business users
keep naming consistent across products in the same category
avoid unnecessary abbreviations unless they are widely understood
document naming conventions for internal teams

Consistency makes it easier to manage products over time and reduces the risk of mapping errors.

3. Keep Product Name and Product Reference aligned where possible

As a best practice, keep the Product Name and Product Reference the same where possible.

This is especially helpful when:

products are sent to or searched for through the CloudBilling API
external systems send the product label directly
a customer uses the product name as the source identifier

Keeping the Product Name and Product Reference aligned makes product mapping easier to understand and reduces the chance of mismatches between source data and configured products.

4. Treat references and SKUs as stable identifiers

References and SKUs should be treated as stable identifiers, not as labels that can be changed freely.

If an existing Reference or SKU is changed while incoming usage still contains the old identifier, CloudBilling may no longer recognise that usage. As a result, purchases can become unmapped.

This is particularly important for usage that has not yet been included on a finalised invoice.

Recommendation

do not change an existing Reference or SKU without checking whether it is still used in incoming or existing data
verify whether the identifier is used by APIs, connectors, imports, or external customer systems
consider the impact on historical and current usage before making changes

5. Preserve old identifiers when renaming or updating products

If you need to change the name, Reference, or SKU of an existing product, do not immediately remove the old identifier.

Instead, preserve the link to the same product by adding the old identifier as an additional SKU where appropriate.

This helps ensure that:

historical or in-flight usage can still be matched
source systems do not need to be updated at exactly the same time
purchases remain mapped during a transition period

Example

A product originally has:

Product Name: Microsoft Azure Compute
Reference: Microsoft Azure Compute

Later, the product is renamed to:

Product Name: Azure Virtual Machines
Reference: Azure Virtual Machines

If incoming usage still contains Microsoft Azure Compute, that usage may become unmapped unless the previous identifier remains linked to the same product.

In that case, add Microsoft Azure Compute as an additional SKU on the updated product.

6. Review unmapped purchases regularly

Unmapped purchases are a strong signal that one or more identifiers are missing or no longer match your configured products.

Review unmapped purchases regularly, especially:

after changing product names, references, or SKUs
after onboarding a new connector or integration
after changes in source systems
after introducing new products or offers

Timely review helps prevent missing invoice lines and reduces manual correction work.

Unmapped purchases can lead to missing usage on customer invoices. Always investigate unmapped purchases as soon as possible.

7. Support multiple identifiers where needed

A single product may be known by different identifiers in different systems.

For example:

one identifier may come from a CSP connector
another may be used in a customer ERP or ticketing system
another may come from a custom API integration

Where needed, link these identifiers to the same product by using additional SKUs. This allows CloudBilling to map usage from multiple sources to one product.

8. Document changes to product identifiers

Whenever you change product names, references, SKUs, or category placement, document the change internally.

Document at least:

what changed
why it changed
when it changed
which source systems or integrations are affected
whether old identifiers are still supported

This helps teams understand mapping decisions and reduces the risk of accidental clean-up of still-active identifiers.

9. Make changes with invoice timing in mind

Be especially careful when changing product identifiers during an active billing period.

If purchases have already been imported but not yet invoiced, changing identifiers too early can interrupt the mapping between usage and products.

Where possible:

make changes after checking current usage
align updates with billing cycle milestones
verify whether usage has already been finalised on invoices
test changes on a limited set before applying them broadly

Summary

A strong product portfolio setup in CloudBilling depends on stable identifiers, consistent naming, and careful change management.

Key recommendations:

define a clear product category structure
use consistent product naming
keep Product Name and Product Reference aligned where possible
treat References and SKUs as stable identifiers
preserve old identifiers as additional SKUs during transitions
review unmapped purchases regularly
document changes and plan them carefully

Following these practices helps keep purchases mapped correctly and supports accurate billing and invoicing over time.