Manage the organization profile

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

The following sections introduce the organization profile and describe how you can manage it using the UI and API.

About the organization profile

As part of the initial setup of monetization, the Apigee Edge configuration team sets up your organization profile.

You need to edit the organization profile to add or update information about your organization, as appropriate. For example, you may need to update the billing type, currency settings, or tax model.

Configure basic information about your organization, including:

  • Organization name, address, and country of operation
  • Billing type (prepaid, postpaid, or both), as described in Understand billing type
  • Billing cycle (pro-rated or calendar month)
  • Base currency
  • Tax model used by your organization

You can manage your organization profile using the UI and API, as described in the following sections.

Explore the Organization Profile page

Access the Organization Profile page, as described below.

Edge

To access the Organization Profile page using the Edge UI:

  1. Sign in to apigee.com/edge.
  2. Select Publish > Monetization > Organization Profile in the left navigation bar.

The Organization Profile page is displayed.

As highlighted in the figure, the Organization Profile page enables you to:

  • View the current organization profile settings
  • Edit the organization profile settings, including:

Classic Edge (Private Cloud)

To access the Organization Profile page using the Classic Edge UI:

  1. Sign in to http://ms-ip:9000, where ms-ip is the IP address or DNS name of the Management Server node.
  2. Select Admin > Organization Profile in the top navigation bar.

The Organization Profile page is displayed.

The Organization Profile page enables you to:

  • View the current organization profile settings
  • Edit the organization profile settings, including:

Edit the organization profile using the UI

To edit the organization profile using the UI:

  1. Access the Organization Profile page.
  2. Click Edit.
  3. Under Name and information, edit the organization name and country of operation.
  4. Under Taxes and currency, edit the following fields:
    Field Description
    Tax Model

    Note: Applies only if you set up revenue sharing rate plans and you want to generate billing documents.

    Tax model for revenue sharing rate plans that identifies the type of billing documents required.

    Valid values include:

    • Disclosed: 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: 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: 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

    Currencies that your organization supports. For revenue sharing, rate card, and fee only plans, the default currency is used for your rate plan. When you create a rate card or fee only plan, you can change which currency to use by selecting from a list of supported currencies. Optionally, you can set the minimum top-up amount that app developers can add to their prepaid account balance for each currency.

    To add a currency:

    1. Click Add currency.
    2. Select a currency from the drop-down menu in the Currency field.
    3. Optionally, set the minimum amount that app developers can add to their prepaid account balance in the specified currency in the Minimum top-up field.
    4. Click Add.
    5. Set as the default currency, if desired, by clicking the associated radio button.
    6. Repeat steps to add additional currencies.

    To delete a currency, position your cursor over the currency you want to delete and click .
  5. Manage terms and conditions, as described in Managing terms and conditions using the UI.
  6. Click Save.

Manage the organization profile using the API

Manage the organization profile using the API, as described in the following sections.

View the organization profile using the API

View your organization profile by issuing a GET request to /mint/organizations/{org_name}. For example:

curl -X GET "https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}" \
  -H "Accept: application/json" \
  -u email:password

The following provides an example of the response. For more information about the options shown, see Organization profile configuration properties for the API.

{
    "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",
    "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"
}

Edit the organization profile using the API

Edit the organization profile by issuing a PUT request to /mint/organizations/{org_name}. When editing the organization profile, you need to specify all the organization profile properties, not only the properties you are editing.

To edit the default currency for the organization, set the currency value to the ISO 4217 currency code of the supported currency that you want to set as the default.

For example, the following API call updates the currency to USD and the tax model setting to HYBRID (the updated fields are highlighted in the example). For more information about the options shown, see Organization profile configuration properties for the API.

curl -X PUT "https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}" \
  -H "Content-Type: application/json" \
  -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", 
  "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" 
}' \

-u email:password

Configure prepaid and postpaid billing types using the API

Developer accounts can be configured to use the following billing types: prepaid, postpaid, or both.

With prepaid accounts, developers pay in advance for the use of your APIs. Funds are deducted from the developer's prepaid balance that is maintained through an integrated payment provider. The developer must maintain a prepaid balance sufficient to purchase the APIs.

With postpaid accounts, developers are billed monthly (through an invoice) at the end of the month. The developer pays for the use of API products based on the payment terms set by the plan(s) included on the invoice.

To configure prepaid and postpaid billing types for your organization, set the supportedBillingType property to one of the following values to indicate which billing types are valid: PREPAID, POSTPAID, or BOTH. If you set the value to BOTH, the default will be PREPAID when you add an app developer or company. In this case, you can explicitly set the billing type for a company or an app developer using the API, as described in Managing companies and app developers.

For example:

curl -X PUT "https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}" \
  -H "Content-Type: application/json" \
  -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",
  "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"
  }' \
  -u email:password

Configure the billing cycle using the API

To configure the billing cycle for your organization, set the billingCycle property to one of the following values:

  • 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.

For example:

curl -X PUT "https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}" \
  -H "Content-Type: application/json" \
  -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",
    "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"
  }' \
  -u email:password

Organization profile configuration properties for the API

The organization profile enables you to set the following configuration properties using the API.

Name Description Default Required?
address

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
approveTrusted

This flag is not used.

 N/A No
approveUntrusted

This flag is not used.

 N/A No
billingCycle

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.

See Configuring the billing cycle using the API.

N/A Yes
country

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

 N/A Yes
currency

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

For revenue sharing plans: The specified currency is used for your plan.

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
description

Brief description of the organization.

 N/A No
hasBillingAdjustment

Flag that specifies 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
hasBroker

Flag that specifies whether the revenue is based on net. The value can be either of the following:

  • true: Revenue is based on net.
  • false: Revenue is not based on net.
 N/A No
hasSelfBilling

Flag that directs monetization to generate 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 app developer. It acts as an invoice to the API Provider on behalf of the app developer. The value can be either of the following:

  • true: Generates self-billing invoices instead of revenue share statements.
  • false: Disables self-billing invoices.
 N/A No
hasSeparateInvoiceForProduct

Flag that specifies whether a separate invoice is generated for each API product. The value can be either of the following:

  • true: Separate invoice is generated for each API product.
  • false: Separate invoice is not generated for each API product.
 N/A No
id

ID of the organization.

 N/A No
issueNettingStmt

Flag that specifies whether a netting statement is generated when creating billing documents. The value can be either of the following:

  • true: Netting statement is generated when creating billing documents.
  • false: Netting statement is not generated when creating billing documents.
 N/A No
logoUrl

URL of the organization's logo.

 N/A No
name

Name of the organization.

 N/A Yes
netPaymentAdviceNote

Net payment advice note.

 N/A No
nettingStmtPerCurrency

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

  • true: Separate netting statement is generated for each currency used.
  • false: Separate netting statement is not generated for each currency used.
 N/A No
regNo

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

 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
selfBillingForAllDev

If self-billing invoices are enabled, indicates whether it is enabled for all app developers. By default, self-billing invoices are generated only for app developers who have signed an agreement with the API provider. The value can be either of the following:

  • true: Self-billing invoices are enabled for all app developers.
  • false: Self-billing invoices are not enabled for all app developers.
 false No
separateInvoiceForFees

Flag that specifies whether a separate invoice is published for fees. The value can be either of the following:

  • true: Separate invoice is published for fees.
  • false: Separate invoice is not published for fees.
 false Yes
status

Status of the organization. Valid values include:

  • ACTIVE: Organization account is registered in monetization and is available for use.
  • INACTIVE: Organization account is registered in monetization, but is not available for use.
 N/A No
supportedBillingType

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

  • PREPAID: 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: 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: Supports either billing type. Defaults to PREPAID.

See Configuring prepaid and postpaid billing types using the API.

PREPAID Yes
taxModel

Note: Applies only if you set up revenue sharing rate plans and you want to generate billing documents.

Tax model for revenue sharing rate plans that identifies the type of billing documents required.

Valid values include:

  • Disclosed: 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: 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: 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.

 N/A No
taxRegNo

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
transactionRelayURL

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

 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 UTC, EST (Eastern Standard Time), or CET (Central European Time), are also supported.

 N/A Yes

Overriding the monetization profile settings for a company or an app developer

Override the monetization profile settings for a company or an app developer using the UI or API, as described in the following sections: