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

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

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.

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.

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.

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.

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:

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.

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):