Customer Hierarchy API

The customerHierarchyUpdate endpoint creates a complete account hierarchy in a single atomic transaction.

Endpoint

POST /api/rest/v2/account/accountHierarchy/customerHierarchyUpdate

Purpose

Create/update the full hierarchy in one call:

• Sellers
• Customers
• CustomerAccounts
• BillingAccounts
• UserAccounts
• Subscriptions
• Access points

DTO Structure

CustomerHierarchyDto
└── SellersDto
    └── List<SellerDto>
        ├── code (required)
        ├── countryCode, currencyCode, languageCode
        └── CustomersDto
            └── List<CustomerDto>
                ├── code (required)
                ├── firstName, lastName, email
                ├── customerCategory, customerBrand
                └── CustomerAccountsDto
                    └── List<CustomerAccountDto>
                        ├── code (required)
                        ├── currency, language
                        ├── paymentMethods
                        └── BillingAccountsDto
                            └── List<BillingAccountDto>
                                ├── code (required)
                                ├── billingCycle
                                ├── country, language
                                └── UserAccountsDto
                                    └── List<UserAccountDto>
                                        ├── code (required)
                                        └── SubscriptionsDto
                                            └── List<SubscriptionDto>
                                                ├── code (required)
                                                ├── offerTemplate
                                                └── AccessesDto

Example Request

{
  "sellers": {
    "seller": [{
      "code": "SELLER_FR",
      "countryCode": "FR",
      "currencyCode": "EUR",
      "languageCode": "FRA",
      "customers": {
        "customer": [{
          "code": "CUST_001",
          "firstName": "John",
          "lastName": "Doe",
          "email": "john.doe@example.com",
          "customerCategory": "STANDARD",
          "customerAccounts": {
            "customerAccount": [{
              "code": "CUST_001_CA",
              "currency": "EUR",
              "language": "FRA",
              "paymentMethod": {
                "paymentMethodType": "DIRECTDEBIT"
              },
              "billingAccounts": {
                "billingAccount": [{
                  "code": "CUST_001_BA",
                  "billingCycle": "MONTHLY",
                  "country": "FR",
                  "language": "FRA",
                  "email": "billing@example.com",
                  "electronicBilling": true,
                  "userAccounts": {
                    "userAccount": [{
                      "code": "CUST_001_UA",
                      "subscriptions": {
                        "subscription": [{
                          "code": "CUST_001_SUB",
                          "offerTemplate": "BASIC_OFFER",
                          "subscriptionDate": "2024-01-15",
                          "accesses": {
                            "access": [{
                              "accessUserId": "ACC_001",
                              "startDate": "2024-01-15"
                            }]
                          }
                        }]
                      }
                    }]
                  }
                }]
              }
            }]
          }
        }]
      }
    }]
  }
}

Validation Rules

Required Fields

Level	Required Fields
Seller	code
Customer	code
CustomerAccount	code, currency
BillingAccount	code, billingCycle
UserAccount	code
Subscription	code

Parent-Child Validation

Each child must reference the correct parent code:

Customer.seller = parent Seller.code
CustomerAccount.customer = parent Customer.code
BillingAccount.customerAccount = parent CustomerAccount.code
UserAccount.billingAccount = parent BillingAccount.code
Subscription.userAccount = parent UserAccount.code
Access.subscription = parent Subscription.code

V2 Company Validations

When isCompany = true:

• legalEntityType.code is required
• description is required
• registrationNumbers is required

Subscription Validations

When subscribedTillDate is set:

• renewalRule is required
• renewalRule.initialTermType is required
• renewalRule.endOfTermAction is required
• renewalRule.terminationReasonCode is required

Response

Success

{
  "status": "SUCCESS",
  "message": "Hierarchy created successfully"
}

Error

{
  "status": "FAIL",
  "errorCode": "MISSING_PARAMETER",
  "message": "customer.code is required"
}

Key Features

• Atomic Transaction: All or nothing - rollback on any error
• Automatic Flushes: Entity manager flushes after each entity
• Prefix Handling: Optional code prefixes (CUST_, CA_, BA_, UA_)
• Status Management: Activate/terminate subscriptions and services
• Discount Plans: Instantiate and terminate discount plans
• Custom Fields: Full CF support at any level
• Thresholds: Configure invoicing thresholds

Bash Script Example

#!/bin/bash
source ./setup-env.sh

CUSTOMER_CODE="CUST_$(date +%s)"
OFFER_CODE=${1:-"BASIC_OFFER"}

curl -s -X POST "${OPENCELL_BASE_URL}/api/rest/v2/account/accountHierarchy/customerHierarchyUpdate" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{
        "sellers": {
            "seller": [{
                "code": "MAIN_SELLER",
                "customers": {
                    "customer": [{
                        "code": "'${CUSTOMER_CODE}'",
                        "firstName": "John",
                        "lastName": "Doe",
                        "email": "john@example.com",
                        "customerCategory": "STANDARD",
                        "customerAccounts": {
                            "customerAccount": [{
                                "code": "'${CUSTOMER_CODE}'_CA",
                                "currency": "EUR",
                                "language": "FRA",
                                "billingAccounts": {
                                    "billingAccount": [{
                                        "code": "'${CUSTOMER_CODE}'_BA",
                                        "billingCycle": "MONTHLY",
                                        "country": "FR",
                                        "language": "FRA",
                                        "email": "billing@example.com",
                                        "userAccounts": {
                                            "userAccount": [{
                                                "code": "'${CUSTOMER_CODE}'_UA",
                                                "subscriptions": {
                                                    "subscription": [{
                                                        "code": "'${CUSTOMER_CODE}'_SUB",
                                                        "offerTemplate": "'${OFFER_CODE}'",
                                                        "subscriptionDate": "'$(date -I)'"
                                                    }]
                                                }
                                            }]
                                        }
                                    }]
                                }
                            }]
                        }
                    }]
                }
            }]
        }
    }' | jq

Related Endpoints

Endpoint	Description
POST /account/accountHierarchy/	Create single-level hierarchy
PUT /account/accountHierarchy/	Update single-level hierarchy
POST /account/accountHierarchy/createOrUpdate	Create or update by code
POST /account/accountHierarchy/createCRMAccountHierarchy	Create with CRM model