Was this Helpful?

Introduction

One of the things that the Apigee Edge configuration team does when they set up monetization is create an organization profile. The profile contains basic information about your organization, such as:

  • Your organization's name, address, and country of operation.
  • Your organization's structure, that is, whether your organization is an individual organization, or is a group organization with sub-organizations or subsidiaries.

    If your organization is a group organization, and you want monetization to differentiate the subsidiaries or sub-organizations in rate plans and transaction records, you need to add the subsidiaries or sub-organizations to the organization profile (see Add subsidiaries and sub-organizations for details).

  • The tax model used by your organization — the tax model dictates the type of billing documents that monetization produces for your organization.
  • The "base" currency that your organization uses.
  • Settings used to configure billing documents that your organization generates.

After the profile is created, you need to edit it to add and update information about your organization, as appropriate. For example, you may need to update the tax model and currency settings.

Toolbox

You can use the management UI or the monetization API to edit the organization profile.

If you use the UI, you update information displayed in the Organization Profile page. If you use the API, you issue a PUT request to the /organizations/{org_name} resource.

Editing the organization profile using the UI

To edit the organization profile:

  1. Login to enterprise.apigee.com. This opens the Edge Management UI.
  2. On the Admin tab, select Organization Profile.

    This opens the Organization Profile page.

  3. Click Edit on the Organization Profile page, and enter the following information.

    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
    Operator/Organization Structure

    This field is pre-set by the configuration team when they set up monetization for your organization and cannot be changed. Indicates whether you are using monetization as a group operator or organization (with subsidiaries or sub-organizations) or as an individual operator or organization (without subsidiaries or sub-organizations). The field reflects your organization structure for monetization (not necessarily your actual registered organization structure). You only need a group structure if you want to differentiate your rate plans or transaction records by subsidiary or sub-organization.

    Name and Information
    Operator/Organization Name

    The name of your organization.

    Country

    The country of operation of your organization.

    Tax and Currency
    Tax Model

    This field only applies 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. This applies to an individual operator or organization. It also applies to a group operator or organization if you set up a rate plan at a group level. In this case, the rate plan applies to all local operators or local subsidiaries in the group, and the billing documents that are generated are based on the tax model of the group.

    If you set up your rate plan at a local level, the tax model specified in the Local Operator or Local Subsidiary section of the company profile applies (see Define subsidiaries and sub-organizations).

    Select one of the following:

    • Disclosed
    • Undisclosed
    • Hybrid

    Disclosed: In this tax model, the API provider acts as a disclosed agent of the developer. The gross revenue (including sales taxes) collected from the end user is passed to the developer. The API provider’s commission is collected from the developer in the form of a commission invoice. The API provider does not handle the sales tax collected from the end user, and it is the developer’s responsibility to report the sales tax.

    Undisclosed: In this tax model, the API provider acts as an undisclosed agent of the developer, and deducts the tax collected from the end users and pays it to the local tax authorities. The developer invoices the API provider for the net revenue share due to the developer (less sales taxes and the API provider’s commission).

    Hybrid: In this tax model, the API provider acts as a disclosed agent of the developer. However, the API provider pays the sales tax collected from their subscribers to the local tax authorities on the developer’s behalf. The API provider passes the remaining revenue to the developer, and then invoices for commission charges.

    Currency

    The currencies that your organization 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:

    • Individual organization: The default currency is used for your rate plan.
    • Group organization: The default currency is used for your rate plan if you set up your plan at a group level. If you set up your plan at a local level, the currency is used as the base currency of your local subsidiary or sub-organization (see Define subsidiaries and sub-organizations).

    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.

    To delete a currency, click Delete next to the currency.

    You cannot delete a supported currency that is used by a developer or rate plan.

Viewing the organization profile using the API

You can view your organization profile by issuing a GET request to /organizations/{org_name}. For example:

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

Here is a sample response:

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

Updating the organization profile using the API

Using an API, you can update any of the values in the organization profile with the exception of the organization structure.

To update the organization profile, issue a PUT request to /organizations/{org_name}. When you make the update, you need to specify all the organization profile settings, not only the settings you update. For example, the following API call updates the supported billing type setting to POSTPAID and the tax model setting to HYBRID (the updated fields are highlighted in the example):

$ curl  -H "Content-Type: application/json" -X PUT -d \
'{ 
  "address" : [ { 
    "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 organization", 
  "groupOrganization" : false, 
  "hasBillingAdjustment" : true, 
  "hasBroker" : false, 
  "hasSelfBilling" : false, 
  "hasSeparateInvoiceForProduct" : false,
  "id" : "myorg", 
  "issueNettingStmt" : false, 
  "logoUrl" : "https://dl.dropboxusercontent.com/u/48279818/LOGOS/testorg.jpeg", 
  "name" : "{org_name}", 
  "nettingStmtPerCurrency" : false, 
  "regNo" : "RegNo-1234-myorg", 
  "selfBillingAsExchOrg" : false, 
  "selfBillingForAllDev" : false, 
  "separateInvoiceForFees" : false, 
  "status" : "ACTIVE", 
  "supportedBillingType" : "POSTPAID",
  "taxModel" : "HYBRID", 
  "taxRegNo" : "TaxRegNo-1234-myorg", 
  "timezone" : "UTC" 
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}" \
-u {myID:mypass}

The value of the currency property sets the default supported currency for the organization. If you want to update the default, set the currency property to the name (that is, the ISO 4217 currency code) of the supported currency that you want to make the default.

Organization profile configuration settings

The organization profile exposes the following configuration options to the API:

Name Description Default Required?
name

The name of the organization.

N/A Yes
description

A brief description of the organization.

N/A No
status

The status of the organization. The value can be one of the following:

  • ACTIVE. The organization account is registered in monetization and is available for use.
  • INACTIVE. The organization account is registered in monetization, but is not available for use.
N/A No
billingCycle

The billing cycle period. The value can be one of the following:

  • PRORATED. Billing is based on the number of days that an API product is used in a calendar month.
  • CALENDAR_MONTH. Billing is done monthly.
N/A Yes
supportedBillingType

The developer payment model used for billing. The value can be one of the following:

  • PREPAID. The developer pays in advance for the use of an API product. Funds are deducted from the developer's balance when the API product is used. The developer must maintain a prepaid balance sufficient to purchase the API product.
  • POSTPAID. The developer is billed monthly (through an invoice) for the use of API products. The developer pays for the use of API products based on the payment terms set by the plan(s) included on the invoice.
  • BOTH. Defaults to PREPAID.
PREPAID Yes
taxModel

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

The tax model dictates the type of billing documents that monetization produces. This applies to an individual operator or organization. It also applies to a group operator or organization if you set up a rate plan at a group level. In this case, the rate plan applies to all local operators or local subsidiaries in the group, and the billing documents that are generated are based on the tax model of the group.

If you set up your rate plan at a local level, the tax model specified for the local operator or local subsidiary in the company profile applies (see Add subsidiaries and sub-organizations).

The value can be one of the following:

  • Disclosed: In this tax model, the API provider acts as a disclosed agent of the developer. The gross revenue (including sales taxes) collected from the end user is passed to the developer. The API provider’s commission is collected from the developer in the form of a commission invoice. The API provider does not handle the sales tax collected from the end user, and it is the developer’s responsibility to report the sales tax.
  • Undisclosed: In this tax model, the API provider acts as an undisclosed agent of the developer, and deducts the tax collected from the end users and pays it to the local tax authorities. The developer invoices the API provider for the net revenue share due to the developer (less sales taxes and the API provider’s commission).
  • Hybrid: In this tax model, the API provider acts as a disclosed agent of the developer. However, the API provider pays the sales tax collected from their subscribers to the local tax authorities on the developer’s behalf. The API provider passes the remaining revenue to the developer, and then invoices for commission charges.
N/A Yes
taxNexus

The country in which the organization is registered for tax purposes.

If the tax nexus is the United States, you need to provide additional information on all the states where you are registered for tax purposes. You provide this information as part of a configuration questionnaire when you first purchase monetization.

 

N/A No
currency

The ISO 4217 code for the "base" or accounting currency that the organization uses (such as USD for Unites States dollar).

For revenue sharing plans:

  • Individual organization: The specified currency is used for your plan. 
  • Group organization: The specified currency is used for your plan if you set up your plan at group level. If you set up your plan at local level, the currency used is the base currency of your local operator or local subsidiary (see Add subsidiaries and sub-organizations).
  • The currency selection is pre-set and cannot be changed.

For rate card (charging model) plans: The same applies as for revenue sharing plans. However, you can change the currency setting to any currency supported by the organization.

For fees only plans: You can change the currency setting to any currency supported by the organization.

N/A Yes
hasBroker

Whether the revenue is based on net. The value can be either of the following:

  • true. The revenue is based on net.
  • false. The revenue is not based on net.
N/A No
timezone

The time zone identifier for the organization’s operations, such as America/New_York. Or Europe/Paris. Time zone abbreviations, such as EST (Eastern Standard Time) or CET (Central European Time), are also supported

Use caution when updating the timezone setting in an organization profile. Changing the timezone setting can impact date and time-based events such as when a rate plan starts and ends and when notifications are sent.

N/A Yes
country

The ISO 3166-2 code for the country of operation for the organization, such as BR for Brazil.

N/A Yes
approveTrusted

Whether the developer is given approved status by the organization. The value can be either of the following:

  • true. The developer is given approved status by the organization.
  • false. The developer is not given approved status by the organization.
N/A No
approveUntrusted

Whether untrusted developers are given approved status by the organization. The value can be either of the following:

  • true. Untrusted developers are given approved status by the organization.
  • false. Untrusted developers are not given approved status by the organization.
N/A No
groupOrganization

Whether the organization is using monetization as a group organization (with subsidiaries or sub-organizations) or as an individual organization (without subsidiaries or sub-organizations). This property is pre-set by the configuration team when they set up monetization for your organization and cannot be changed. The property reflects the organization structure for monetization (not necessarily the actual registered organization structure). You only need a group structure if you want to differentiate your rate plans or transaction records by subsidiary or sub-organization.

N/A No
parent

This property only applies to a subsidiary or sub-organization. The property contains information about the parent organization.

N/A No
children

This property only applies to a group organization.  The property contains information about the subsidiaries or sub-organizations of the organization.

N/A No
separateInvoiceForFees

Whether a separate invoice is published for fees. The value can be either of the following:

  • true. A separate invoice is published for fees.
  • false. A separate invoice is not published for fees.
false Yes
issueNettingStmt

Whether a netting statement is generated when creating billing documents. The value can be either of the following:

  • true. A netting statement is generated when creating billing documents.
  • false. A netting statement is not generated when creating billing documents.
N/A No
nettingStmtPerCurrency

Whether a separate netting statement is generated for each currency used. The value can be either of the following:

  • true. A separate netting statement is generated for each currency used.
  • false. A separate netting statement is not generated for each currency used.
N/A No
hasSelfBilling

Whether self-billing invoices are enabled. If enabled, monetization generates a self-billing invoice instead of a revenue share statement. A self-billing invoice is a financial document that details the amount due to the developer. It acts as an invoice to the API Provider on behalf of the developer. The value can be either of the following:

  • true. Self-billing invoices are enabled.
  • false. Self-billing invoices are not enabled.
N/A No
selfBillingForAllDev

If self-billing invoices are enabled, indicates whether it is enabled for all developers. The value can be either of the following:

  • true. Self-billing invoices are enabled for all developers.
  • false. Self-billing invoices are not enabled for all developers.
N/A No
selfBillingAsExchOrg

If self-billing invoices are enabled, indicates whether it is enabled for exchange organizations. The value can be either of the following:

  • true. Self-billing invoices are enabled for exchange organizations.
  • false. Self-billing invoices are not enabled for exchange organizations.
N/A No
hasSeparateInvoiceForProduct

Whether a separate invoice is generated for each API product. The value can be either of the following:

  • true. A separate invoice is generated for each API product.
  • false. A separate invoice is not generated for each API product.
N/A No
netPaymentAdviceNote

Net payment advice note.

N/A No
hasBillingAdjustment

Whether adjustments are enabled. If enabled, you can make adjustments to the traffic details recorded by API Services for your API products The value can be either of the following:

  • true. Adjustments are enabled.
  • false. Adjustments are not enabled.
N/A No
logoUrl

The URL of the organization's logo.

N/A No
taxRegNo

The organization’s tax registration number or Value Added Tax (VAT) registration number, if applicable. This property is optional because the tax registration number or VAT registration number does not apply in all countries. The number you enter for this parameter is displayed at the bottom of billing documents.

N/A No
regNo

The organization's registration number. The number you enter for this property is displayed at the bottom of billing documents.

N/A No
transactionRelayURL

The URL of another system to which transactions can be relayed, such as a data warehouse.

N/A No
address

The organization’s address, which can include the street address, city, state, zip code, country, and an indication whether this is the primary address for the organization.

N/A No

Get help

For help, see Apigee Customer Support.

Next steps

Learn how to define subsidiaries and sub-organizations to monetization in Add subsidiaries and sub-organizations.