Carrier Service Mapping API

CarrierServiceMapping enables multi-vendor carrier integration by mapping vendor-agnostic ServiceTemplates to carrier-specific Product Plan Codes (PPCs).

Overview

Key Concepts:

Concept	Description	Example
ServiceTemplate	Vendor-agnostic service definition	SRV_OPTUS_VRP_1
Product Plan Code (PPC)	Carrier-specific provisioning identifier	Optus 010011
Carrier Code	Carrier identifier	optus, telstra, vodafone, vocus, one_nz
Pass Code	Optus hierarchy: 0=shared, 1=parent, 2=child	Speech = 1 (parent)

Why use it:

• Map a single ServiceTemplate to multiple carriers
• Support Optus-specific bundle hierarchy (parent/child PPCs)
• Store carrier-specific network configuration
• Enable multi-vendor provisioning without code changes

TypeScript Types

/**
 * CarrierServiceMapping entity
 */
export interface CarrierServiceMapping {
  /** Unique business identifier (e.g., MAP_OPTUS_VRP1_010011) */
  code: string;

  /** Human-readable description */
  description?: string;

  /** ServiceTemplate code this mapping applies to */
  serviceTemplateCode: string;

  /** Carrier code (optus, telstra, vodafone, vocus, one_nz) */
  carrierCode: string;

  /** Carrier-specific Product Plan Code */
  productPlanCode: string;

  /** Product type (Speech, GPRS, SMSMO, etc.) */
  productType?: string;

  /** CDR usage identifier for rating */
  usageId?: string;

  /** Optus hierarchy pass code: 0=shared, 1=parent, 2=child */
  passCode?: number;

  /** Whether this PPC is a parent in the hierarchy */
  isParentPpc?: boolean;

  /** Parent PPC code (for child PPCs) */
  parentPpcCode?: string;

  /** Carrier-specific network configuration */
  networkConfig?: Record<string, unknown>;

  /** Audit fields */
  created?: string;
  updated?: string;
}

/**
 * DTO for creating/updating mappings
 */
export interface CarrierServiceMappingDto {
  code: string;
  description?: string;
  serviceTemplateCode: string;
  carrierCode: string;
  productPlanCode: string;
  productType?: string;
  usageId?: string;
  passCode?: number;
  isParentPpc?: boolean;
  parentPpcCode?: string;
  networkConfig?: Record<string, unknown>;
}

/**
 * Query parameters for filtering
 */
export interface CarrierServiceMappingQueryParams {
  carrierCode?: string;
  serviceTemplateCode?: string;
  parentPpcsOnly?: boolean;
  passCode?: number;
}

API Endpoints

Create Mapping

POST /api/v1/catalog/carrier-service-mappings

curl -X POST "https://my.staqr.com/api/v1/catalog/carrier-service-mappings" \
  -H "Authorization: Bearer $JWT" \
  -H "x-seller-id: PRVIDR" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "MAP_OPTUS_VRP1_010011",
    "serviceTemplateCode": "SRV_OPTUS_VRP_1",
    "carrierCode": "optus",
    "productPlanCode": "010011",
    "productType": "Speech",
    "passCode": 1,
    "isParentPpc": true
  }'

Get Mapping by Code

GET /api/v1/catalog/carrier-service-mappings/:code

curl "https://my.staqr.com/api/v1/catalog/carrier-service-mappings/MAP_OPTUS_VRP1_010011" \
  -H "Authorization: Bearer $JWT" \
  -H "x-seller-id: PRVIDR"

List All Mappings

GET /api/v1/catalog/carrier-service-mappings

curl "https://my.staqr.com/api/v1/catalog/carrier-service-mappings" \
  -H "Authorization: Bearer $JWT" \
  -H "x-seller-id: PRVIDR"

List by Carrier

GET /api/v1/catalog/carrier-service-mappings/carrier/:carrierCode

curl "https://my.staqr.com/api/v1/catalog/carrier-service-mappings/carrier/optus" \
  -H "Authorization: Bearer $JWT" \
  -H "x-seller-id: PRVIDR"

List by ServiceTemplate

GET /api/v1/catalog/carrier-service-mappings/service/:serviceCode

curl "https://my.staqr.com/api/v1/catalog/carrier-service-mappings/service/SRV_OPTUS_VRP_1" \
  -H "Authorization: Bearer $JWT" \
  -H "x-seller-id: PRVIDR"

Get by Carrier + PPC

GET /api/v1/catalog/carrier-service-mappings/ppc/:carrierCode/:ppc

curl "https://my.staqr.com/api/v1/catalog/carrier-service-mappings/ppc/optus/010011" \
  -H "Authorization: Bearer $JWT" \
  -H "x-seller-id: PRVIDR"

List Parent PPCs

GET /api/v1/catalog/carrier-service-mappings/parents/:carrierCode

curl "https://my.staqr.com/api/v1/catalog/carrier-service-mappings/parents/optus" \
  -H "Authorization: Bearer $JWT" \
  -H "x-seller-id: PRVIDR"

Update Mapping

PUT /api/v1/catalog/carrier-service-mappings/:code

curl -X PUT "https://my.staqr.com/api/v1/catalog/carrier-service-mappings/MAP_OPTUS_VRP1_010011" \
  -H "Authorization: Bearer $JWT" \
  -H "x-seller-id: PRVIDR" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "MAP_OPTUS_VRP1_010011",
    "serviceTemplateCode": "SRV_OPTUS_VRP_1",
    "carrierCode": "optus",
    "productPlanCode": "010011",
    "productType": "Speech",
    "passCode": 1,
    "isParentPpc": true,
    "networkConfig": { "routingProfile": "PREMIUM" }
  }'

Delete Mapping

DELETE /api/v1/catalog/carrier-service-mappings/:code

curl -X DELETE "https://my.staqr.com/api/v1/catalog/carrier-service-mappings/MAP_OPTUS_VRP1_010011" \
  -H "Authorization: Bearer $JWT" \
  -H "x-seller-id: PRVIDR"

React Hooks

Import hooks from the catalog feature:

import {
  useCarrierServiceMappings,
  useCarrierServiceMapping,
  useCarrierServiceMappingsByCarrier,
  useCarrierServiceMappingsByService,
  useCarrierServiceMappingByPpc,
  useCarrierParentPpcs,
  useCreateCarrierServiceMapping,
  useUpdateCarrierServiceMapping,
  useDeleteCarrierServiceMapping,
} from '@/features/catalog/hooks/useCarrierServiceMappings';

Query Hooks

// Fetch all mappings
const { data: allMappings, isLoading } = useCarrierServiceMappings();

// Fetch single mapping by code
const { data: mapping } = useCarrierServiceMapping('MAP_OPTUS_VRP1_010011');

// Fetch mappings by carrier
const { data: optusMappings } = useCarrierServiceMappingsByCarrier('optus');

// Fetch mappings by service template
const { data: vrp1Mappings } = useCarrierServiceMappingsByService('SRV_OPTUS_VRP_1');

// Fetch mapping by carrier + PPC
const { data: speechMapping } = useCarrierServiceMappingByPpc('optus', '010011');

// Fetch parent PPCs for carrier
const { data: parentPpcs } = useCarrierParentPpcs('optus');

Mutation Hooks

// Create mutation
const createMapping = useCreateCarrierServiceMapping();

const handleCreate = () => {
  createMapping.mutate({
    code: 'MAP_NEW_OPTUS_SERVICE',
    serviceTemplateCode: 'SRV_NEW_SERVICE',
    carrierCode: 'optus',
    productPlanCode: '020001',
    productType: 'Voice',
    passCode: 0,
    isParentPpc: false,
  });
};

// Update mutation
const updateMapping = useUpdateCarrierServiceMapping();

const handleUpdate = (code: string) => {
  updateMapping.mutate({
    code,
    dto: {
      code,
      serviceTemplateCode: 'SRV_NEW_SERVICE',
      carrierCode: 'optus',
      productPlanCode: '020001',
      productType: 'Voice',
      networkConfig: { timeout: 30000 },
    },
  });
};

// Delete mutation
const deleteMapping = useDeleteCarrierServiceMapping();

const handleDelete = (code: string) => {
  deleteMapping.mutate(code);
};

Examples

Example 1: Create Optus VRP1 Bundle Mappings

Create a complete Optus VRP1 bundle with parent Speech PPC and child data/SMS PPCs:

import { useCreateCarrierServiceMapping } from '@/features/catalog/hooks/useCarrierServiceMappings';

function CreateVRP1BundleMappings() {
  const createMapping = useCreateCarrierServiceMapping();

  const createBundleMappings = async () => {
    // 1. Create parent Speech PPC (passCode=1, isParentPpc=true)
    await createMapping.mutateAsync({
      code: 'MAP_OPTUS_VRP1_SPEECH',
      serviceTemplateCode: 'SRV_OPTUS_VRP_1',
      carrierCode: 'optus',
      productPlanCode: '010011',
      productType: 'Speech',
      passCode: 1,
      isParentPpc: true,
    });

    // 2. Create child GPRS PPC (passCode=2, parentPpcCode='010011')
    await createMapping.mutateAsync({
      code: 'MAP_OPTUS_VRP1_GPRS',
      serviceTemplateCode: 'SRV_OPTUS_VRP_1_DATA',
      carrierCode: 'optus',
      productPlanCode: 'GPRS_MOSER_01',
      productType: 'GPRS',
      passCode: 2,
      isParentPpc: false,
      parentPpcCode: '010011',
    });

    // 3. Create child SMS PPC
    await createMapping.mutateAsync({
      code: 'MAP_OPTUS_VRP1_SMS',
      serviceTemplateCode: 'SRV_OPTUS_VRP_1_SMS',
      carrierCode: 'optus',
      productPlanCode: 'SMS_MO_01',
      productType: 'SMSMO',
      passCode: 2,
      isParentPpc: false,
      parentPpcCode: '010011',
    });
  };

  return (
    <button onClick={createBundleMappings}>
      Create VRP1 Bundle Mappings
    </button>
  );
}

Example 2: Query Mappings for Provisioning

Build an atomic PPC list for carrier provisioning:

import { useCarrierServiceMappingsByService } from '@/features/catalog/hooks/useCarrierServiceMappings';

function buildAtomicPpcList(
  mappings: CarrierServiceMapping[],
  carrierCode: string
): string[] {
  const carrierMappings = mappings.filter(m => m.carrierCode === carrierCode);

  // Sort: parent PPCs first, then children
  const sorted = carrierMappings.sort((a, b) => {
    if (a.isParentPpc && !b.isParentPpc) return -1;
    if (!a.isParentPpc && b.isParentPpc) return 1;
    return (a.passCode || 0) - (b.passCode || 0);
  });

  return sorted.map(m => m.productPlanCode);
}

function ProvisioningPpcList({ serviceCode }: { serviceCode: string }) {
  const { data: mappings = [] } = useCarrierServiceMappingsByService(serviceCode);

  const optusPpcs = buildAtomicPpcList(mappings, 'optus');

  return (
    <div>
      <h3>Optus Atomic PPC List</h3>
      <ul>
        {optusPpcs.map(ppc => (
          <li key={ppc}>{ppc}</li>
        ))}
      </ul>
    </div>
  );
}

Example 3: Multi-Carrier Service Mapping

Display mappings for a service across all carriers:

import {
  useCarrierServiceMappingsByService,
} from '@/features/catalog/hooks/useCarrierServiceMappings';

function MultiCarrierMappings({ serviceCode }: { serviceCode: string }) {
  const { data: mappings = [], isLoading } =
    useCarrierServiceMappingsByService(serviceCode);

  if (isLoading) return <div>Loading...</div>;

  // Group by carrier
  const byCarrier = mappings.reduce((acc, m) => {
    if (!acc[m.carrierCode]) acc[m.carrierCode] = [];
    acc[m.carrierCode].push(m);
    return acc;
  }, {} as Record<string, CarrierServiceMapping[]>);

  return (
    <div>
      <h3>Carrier Mappings for {serviceCode}</h3>
      {Object.entries(byCarrier).map(([carrier, carrierMappings]) => (
        <div key={carrier}>
          <h4>{carrier}</h4>
          <table>
            <thead>
              <tr>
                <th>PPC</th>
                <th>Type</th>
                <th>Hierarchy</th>
              </tr>
            </thead>
            <tbody>
              {carrierMappings.map(m => (
                <tr key={m.code}>
                  <td>{m.productPlanCode}</td>
                  <td>{m.productType || '-'}</td>
                  <td>
                    {m.isParentPpc ? 'Parent' :
                     m.parentPpcCode ? 'Child' : 'Shared'}
                  </td>
                </tr>
              ))}
            </tbody>
          </table>
        </div>
      ))}
    </div>
  );
}

Validation Rules

Field	Rule	Error
code	Required on create, unique	400 Bad Request
serviceTemplateCode	Required, must exist	404 Not Found
carrierCode	Required	400 Bad Request
productPlanCode	Required	400 Bad Request
carrierCode + productPlanCode	Unique combination	409 Conflict
passCode (Optus)	Must be 0, 1, or 2	400 Bad Request
parentPpcCode (Optus child)	Required when passCode=2	400 Bad Request

Related Documentation

• ServiceTemplate API - Vendor-agnostic service definitions (via Commerce API /catalog/serviceTemplates)
• Carrier Bundles - Carrier-specific bundles (/api/v1/catalog/carrier-bundles)
• Provisioning API - Use mappings for provisioning requests