—Rate this article—
 

Add subsidiaries and sub-organizations

Introduction

If your organization structure is identified as a group organization (or a group operator) and you want monetization to differentiate subsidiaries or sub-organizations in rate plans and transactions records, you need to add the subsidiaries or sub-organizations to your organization profile.

Toolbox

You can add subsidiaries or sub-organizations using the management UI or monetization API. If you use the UI, you add the subsidiaries or sub-organizations in the Subsidiaries section of the Organization Profile page. In the UI, a subsidiary or sub-organization is referred to as a "local operator" or "subsidiary".

If you use the API, you add the subsidiaries or sub-organizations by issuing a POST request to the /organizations/{org_name} resource for the parent organization. This adds an /organizations/{org_name} resource for the subsidiary or sub-organization to the resource for the parent organization (that is, in the children property of the parent's resource).

You cannot add a subsidiary or sub-organization if your organization structure is an individual organization. This means you cannot add a subsidiary or sub-organization if:

  • UI: Your operator or organization structure is specified as "Individual Operator" or "Individual Organization". The Subsidiaries section is displayed in the Organization Profile page only for a Group Operator or Group Organization, respectively.
  • API: The value of the groupOrganization property in the /organizations/{org_name} resource is false.

After you add subsidiaries or sub-organizations, you can perform management operations on them such as update or delete.

Adding a subsidiary or sub-organization using the UI

  1. In the Subsidiaries section, click + Add Local Operator (or + Add Subsidiary). This opens a Local Operator or Subsidiary window.

  2. Enter the following information in the Local Operator or Subsidiary window:

    For telecommunications companies, the Organization Profile page uses "Operator" in the label of various fields (such as "Operator Structure"). For non-telecommunications companies, the label "Organization" is used (as in "Organization Structure").

    Field Description
    Operator/Organization Name

    The name of the local operator or subsidiary. This name is displayed to developers in the developer portal and in billing documentation. The name does not need to be the legal entity name of the local operator or subsidiary.

    Country

    The country of operation of the local operator or subsidiary.

    Tax Model

    This field applies only if you set up revenue sharing plans and you want monetization to generate billing documents. It refers to the tax model you want to use for those plans.

    The tax model dictates the type of billing documents that monetization produces for a local operator or local subsidiary. This applies if you set up a rate plan at a local level. In this case, the rate plan is split by local operator or subsidiary, and billing documents are generated based on the tax model of each local operator or subsidiary. For rate plans set up at a group level, the tax model specified in the Tax and Currency section of the company profile applies.

    Select one of the following:

    currency

    The currencies that the local operator or subsidiary supports.

    To add a currency, click Add Currency, and select a currency from the drop-down menu. Click Default if you want this currency to be the default currency. Click Add Currency and make a currency selection from the drop-down menu for each additional currency that you want to add (you can list multiple currencies).

    The currencies are used as follows:

    For revenue sharing plans: The default currency is used as the base currency of the local operator or subsidiary.

    For rate card (charging model) and fee only plans: The default currency is used as the base currency of the local operator or subsidiary.

    For rate card (charging model) and fee only plans: The same applies as for revenue sharing plans. However, when you create the plan, you can change which currency to use by selecting from a list of supported currencies.

  3. Click Save to save the record for the local operator or subsidiary (or Discard to cancel). This closes the Local Operator or Subsidiary window and returns you to the Organization Profile page.

     

    The local operator or subsidiary is added to the Local Operators or Subsidiaries section of the Organization Profile page.

  4. Click + Add Local Operator to add another local operator (or + Add Subsidiary to add another subsidiary), as needed. Repeat steps 2 and 3 for each local operator or subsidiary that you add.

Updating a subsidiary or sub-organization using the UI

  1. In the list of local operators or subsidiaries, select the name of the local operator or subsidiary that you want to edit. This opens the Local Operator or Subsidiary window.
  2. Click Edit. Make changes to the name, country, tax model, and currency fields, as needed.
  3. Click Save to save your edits and return to the Organization Profile page (or Revert to cancel).

Deleting a subsidiary or sub-organization using the UI

  1. In the list of local operators or subsidiaries, navigate to the local operator or subsidiary that you want to delete.
  2. Click Remove.

You cannot delete a local operator or subsidiary if you have products or rate plans associated with them.

Adding a subsidiary or sub-organization using the API

You add a subsidiary or sub-organization to an organization resource by issuing a POST request to /organizations/{org_name}, where {org_name} is the identification of the parent organization. You also need to specify the parent ID in the parent parameter of the request body. For example:

$ curl -H "Content-Type:application/json" -X POST -d \
'{
  "approveTrusted" : false,
  "approveUntrusted" : false,
  "billingCycle" : "CALENDAR_MONTH",
  "country" : "IN",
  "currency" : "INR",
  "description" : "Test sub-organization",
  "groupOrganization" : true,
  "hasBillingAdjustment" : false,
  "hasBroker" : false,
  "hasSelfBilling" : false,
  "hasSeparateInvoiceForProduct" : true,
  "issueNettingStmt": false, 
  "logoUrl" : "https://dl.dropboxusercontent.com/u/48279818/LOGOS/testorg.jpeg",
  "name" : "subin",
  "nettingStmtPerCurrency ": false,
  "regNo" : "RegNo-1234-myorg",
  "selfBillingAsExchOrg" : false,
  "selfBillingForAllDev" : false,
  "separateInvoiceForFees" : true,
  "status" : "ACTIVE",
  "supportedBillingType" : "PREPAID",
  "taxModel" : "HYBRID",
  "taxRegNo" : "TaxRegNo-1234-myorg",
  "timezone" : "UTC",
  "parent" : {
    "id" : "{org_name}"
  }
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}" \ 
-u myname:mypass 

The response should look like this (only part of the response is shown):

{
  "approveTrusted" : false,
  "approveUntrusted" : false,
  "billingCycle" : "CALENDAR_MONTH",
  "country" : "IN",
  "currency" : "INR",
  "description" : "Test sub-organization",
  "groupOrganization" : true,
  "hasBillingAdjustment" : false,
  "hasBroker" : false,
  "hasSelfBilling" : false,
  "hasSeparateInvoiceForProduct" : true,
  "id" : "subin",
  "issueNettingStmt" : false,
  "logoUrl" : " https://dl.dropboxusercontent.com/u/48279818/LOGOS/testorg.jpeg",
  "name" : "subin",
  "nettingStmtPerCurrency" : false,
  "parent" : {
    "address1" : "Test address”,
    "city" : "Test City",
    "country" : "US",
    "id" : "corp-address",
    "isPrimary" : true,
    "state" : "CA",
    "zip" : "54321"
    } ],
    …
    "approveTrusted" : false,
    "approveUntrusted" : false,
    "billingCycle" : "CALENDAR_MONTH",
    "country" : "US",
    "currency" : "USD",
    "description" : "Test sub-organization",
    "groupOrganization" : true,
    …
    
  },
  "regNo" : "RegNo-1234-mycorp",
  "selfBillingAsExchOrg" : false,
  "selfBillingForAllDev" : false,
  "separateInvoiceForFees" : true,
  "status" : "ACTIVE",
  "supportedBillingType" : "PREPAID",
  "taxModel" : "HYBRID",
  "taxRegNo" : "TaxRegNo-1234-myorg,
  "timezone" : "UTC"
}

Notice that the response includes information about the parent organization as well as the subsidiary or sub-organization.

Retrieving an organization and its subsidiaries or sub-organizations using the API

You can retrieve an organization and its subsidiaries or sub-organizations by issuing a GET request to /organizations/{org_name}/organization-family. For example:

$ curl -H "Accept: application/json" -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/organization-family" \
-u myname:mypass

Your response should look something like this (only part of the response is shown):


{
  "organization" : [ {
    "approveTrusted" : false,
    "approveUntrusted" : false,
    "billingCycle" : "CALENDAR_MONTH",
    "country" : "IN",
    "currency" : "INR",
    "description" : "Test sub-organization",
    "groupOrganization" : true,
    "hasBillingAdjustment" : false,
    "hasBroker" : false,
    "hasSelfBilling" : false,
    "hasSeparateInvoiceForProduct" : true,
    "id" : "subin",
    "issueNettingStmt" : false,
    "logoUrl" : " https://dl.dropboxusercontent.com/u/48279818/LOGOS/testorg.jpeg",
    "name" : "subin",
    "nettingStmtPerCurrency" : false,
    "parent" : {
      "address" : [ {
        "address1" : "Test address”,
        "city" : "Test City",
        "country" : "US",
        "id" : "corp-address",
        "isPrimary" : true,
        "state" : "CA",
        "zip" : "54321"
      } ],
      …
      } ],
    … 
    "regNo" : "RegNo-1234-myorg",
    "selfBillingAsExchOrg" : false,
    "selfBillingForAllDev" : false,
    "separateInvoiceForFees" : true,
    "status" : "ACTIVE",
    "supportedBillingType" : "PREPAID",
    "taxModel" : "DISCLOSED",
    "taxRegNo" : "TaxRegNo-1234-myorg",
    "timezone" : "UTC"
  } ],
  …
  "approveTrusted" : false,
    "approveUntrusted" : false,
    "billingCycle" : "CALENDAR_MONTH",
    "country" : "US",
    "currency" : "USD",
    "description" : "Group Test",
    …
  }]
}

Retrieving a subsidiary or sub-organization with transactions using the API

You can retrieve sub-organizations that have transactions in a given date range, that is, you can retrieve sub-organizations for which users have invoked apps that access the sub-organization's APIs within a specified start and end date.

To retrieve sub-organizations with transactions in a given date range, issue a GET request to /organizations/{org_name}/suborgs-with-transactions. When you issue the request, you need to specify as query parameters a start date and end date for the date range. For example, the following request retrieves sub-organizations with transactions during the month of August, 2013.

$ curl -H "Accept:application/json" -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/suborgs-with-transactions?START_DATE=2013-08-01&END_DATE=2013-08-31" \
-u myname:mypass

Updating a subsidiary or sub-organization using the API

You can update a subsidiary or sub-organization by issuing a PUT request to /organizations/{suborg_name}, where {suborg_name} is the identification of the subsidiary or sub-organization. When you make the update, you need to specify all the settings for the subsidiary or sub-organization, not only the setting you update. For example, the following API call updates the supported billing type to POSTPAID, and the tax model to DISCLOSED (the updated properties are highlighted in the example):

$ curl -H "Content-Type: application/json" -X PUT -d \
'{
 "approveTrusted" : false,
 "approveUntrusted" : false,
 "billingCycle" : "CALENDAR_MONTH",
 "country" : "IN",
 "currency" : "INR",
 "description ": "Test sub-organization",
 "groupOrganization ": true,
 "hasBillingAdjustment" : false,
 "hasBroker" : false,
 "hasSelfBilling" false,
 "hasSeparateInvoiceForProduct" : true,
 "id" : "{org_name}",
 "issueNettingStmt" : false, 
 "logoUrl" : "https://dl.dropboxusercontent.com/u/48279818/LOGOS/testorg.jpeg",
 "name" : "{suborg_name}",
 "nettingStmtPerCurrency": false,
 "regNo" : "RegNo-1234-myorg",
 "selfBillingAsExchOrg" : false,
 "selfBillingForAllDev" : false,
 "separateInvoiceForFees" : true,
 "status" : "ACTIVE",
 "supportedBillingType" : "POSTPAID",
 "taxModel" : "DISCLOSED",
 "taxRegNo" : "TaxRegNo-1234-myorg",
 "timezone" : "UTC",
 "parent" : {
 "id" : "{org_name}"
 }
}' \
"https://api.enterprise.apigee.com/v1/mint/{org_name}/{suborg_name}" \
-u myname:mypass

Subsidiary and sub-organization configuration settings

The configuration options available for a subsidiary or sub-organization that are exposed to the API are the same as for the organization profile. See Edit the organization profile for details.

Get help

For help, see Apigee Customer Support.

Next steps

Learn how to set up terms and conditions (T&C's) in Specify terms and conditions. Developers must accept your T&C's before they can purchase your rate plans.

Help or comments?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)