Introduction

Monetization automatically runs a monthly billing docs job that generates billing documents. This means that you do not have to generate billing documents manually (as described in this topic). Instead, you can take advantage of the pre-scheduled job. By default, the job runs on the 11th day of every month at 1 minute after midnight. You can change the schedule for the job or disable it. For details, see Schedule monetization jobs.

Using monetization you can create billing documents such as invoices and revenue share statements (which include applicable taxes) for the use of your APIs. You can review drafts of billing documents, and publish the billing documents when they are final.

You can also adjust billing documents. For example, you might need to increase or decrease the revenue share or fees specified in a billing document because of a discrepancy in your records. See Make billing adjustments for details.

Toolbox

You can create billing documents using the management UI or monetization API.

If you use the UI, you can create drafts and publish final billing documents on the Billing Document Configuration page.

If you use the API, you can generate drafts of billing documents by issuing a POST request to the /organizations/{org_name}/generate-draft-billing-documents resource. You can generate and publish final drafts by issuing a POST request to the /organizations/{org_name}/developers/{dev_id}/generate-draft-billing-documents resource.

Configuring billing documents using the UI

Before you generate billing documents, you need to provide some basic information such as the country in which you’re registered for tax purposes (this allows monetization to generate the applicable taxes on the documents), and the number of days to allow for payment after you issue an invoice. You provide this information in the billing document configuration.

To set up a billing document configuration:

  1. On the Monetization tab, select Billing Document Configuration.

    This opens the Billing Document Configuration page.

  2. Select a tab in the Billing Document Configuration page:
  3. Click Edit to edit the fields in the tab.
  4. Repeat steps 2 and 3 for each tab in the Billing Document Configuration page.
  5. Click Save to save the configuration (or revert to return to the previous version, if any).

Configuring tax and document settings

Use the Tax and Document Setting tab to specify tax-related information, such as the country in which you are registered for tax purposes, as well as other billing document settings, such as whether you want self-billing invoices generated instead of revenue share statements.

To configure tax and document settings:

  1. Select the Tax and Document Setting tab on the Billing Document Configuration page.
  2. Click Edit and enter the following information:

     

    Field Description
    Tax Settings
    Tax Nexus

    The country in which you are registered for tax purposes. Select a country from the drop-down menu.

    If your 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.

    Tax Registration Number

    Your tax registration number or Value Added Tax (VAT) registration number, if applicable. This field is optional because the tax registration number or VAT registration number does not apply in all countries. The number you enter in this field is displayed at the bottom of the tax invoice.

    Document Setting for All Tax Models. This section applies only to billing for plans that involve revenue share, and for which the API provider uses either the disclosed, undisclosed, or disclosed hybrid tax models.
    Netting Statements

    Directs monetization to produce netting statements that show the net balances between invoices and revenue share statements.

    Two checkboxes are displayed in this section:

    • Generate a Netting Statement when creating Billing Documents. Select this to produce a netting statement when you create a billing document. By default, monetization converts the various currencies into your base currency when it generates netting statements.
    • Create one Netting Statement per currency. This checkbox is enabled only if you select "Generate a Netting Statement when creating Billing Documents". Select "Create one Netting Statement per currency" to generate a separate netting statement for each currency used.
    Revenue Share and Rate Card Plans

    This applies to only to revenue share and rate card plans. It directs monetization to generate separate invoices for fees charged for these plans. These pertain to any fees charged in addition to the plan rates.

    Select "Generate separate invoices for Revenue Share Fees and/or rate card fees" to generate separate invoices for these fees. If you make this selection:

    • For undisclosed tax models, the fees are charged on a separate invoice. (If you don’t select "Generate separate invoices for Revenue Share Fees and/or rate card fees", these fees are charged in the revenue share statement.)
    • For both disclosed and hybrid tax models, the fees are charged on a separate invoice and are grouped with any other rate card plans the API provider sets up.
    Document Settings for Undisclosed Tax Models. This section applies only to billing for plans that involve revenue share, and for which the API provider uses the undisclosed tax model.
    Self-Billing Invoices

    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 developer. It acts as an invoice to the API Provider on behalf of the developer.

    Two checkboxes are displayed in this section:

    • Include Self-Billing Invoices. Select this to generate self-billing invoices instead of revenue share statements. By default, self-billing invoices are generated only for developers who have signed an agreement with the API provider. )
    • Include Self-Billing Invoices for all developers, subsidiaries, and partners. This checkbox is enabled only if you select “Include Self-Billing Invoices “. Select this checkbox to generate self-billing invoices for all developers, subsidiaries and partners.
  3. Click Save to save the configuration (or revert to return to the previous version, if any).

Configuring the logo and address

Use the Documents Logo and Address tab to add a company logo and address for display in billing documents.

To configure the logo and address:

  1. Select the Documents Logo and Address tab in the Billing Document Configuration page.
  2. Click Edit, and enter the following information.

     

    Field Description
    Company Logo
    Logo URL

    The URL of your company logo.

  3. Click Save to save the configuration (or revert to return to the previous version, if any).

Creating billing documents using the UI

  1. On the Monetization tab, select Billing Documents.

    This opens the Billing Documents page.

  2. Click Create Billing Documents.

    This opens the Billing Documents window.

  3. Enter the following information in the Billing Documents window:

     

    Field Description
    Open Billing Month

    The month for the billing documents. Select a month from the drop-down list. Only “open” months are listed. These are complete calendar months for which you have not yet published billing documents. After you publish billing documents for a month, that month is "closed". You cannot generate billing documents again for a closed month.

    Packages

    The API packages to include in the billing documents. Select one of the following:

    • All. This includes all API packages in the billing documents.
    • Selected. This displays a list from which you can select the packages to include in the billing documents. If you select no package, all packages are included in the billing documents.
    Products

    The API products in the package to include in the billing documents. Select one of the following:

    • All. This includes all API products in the billing documents.
    • Selected. This displays a list from which you can select the products to include in the billing documents. If you select no products, all products are included in the billing documents.
    Developers

    The developers to include in the billing documents. Select one of the following:

    • All. This includes all developers in the billing documents.
    • Selected. This displays a list from which you can select the developers to include in the billing documents. If you select no developers, all developers are included in the billing documents.
    Rate Plan

    The types of rate plans to include in the billing documents. Select one of the following:

    • All Rate Plans. This includes all types of rate plans in the billing documents.
    • Standard Rate Plans. This includes only standard rate plans in the billing documents.
    • Developer-Specific Rate Plans. This includes only developer-specific rate plans in the billing documents.

Viewing and printing drafts of billing documents using the UI

  1. Click View Draft (new window) at the bottom of the Billing Document window.

    The draft is displayed in a new window.

  2. Review the draft and update it as needed.
  3. Print the draft by clicking Print Draft.

Edge on-premises: Monetization displays billing documents to end users in HTML format. To provide billing documents as PDF files, you can integrate Monetization with a billing system that provides PDF generation or license a supported third-party PDF library.

Publishing billing documents using the UI

After you generate the draft billing documents (and finish checking them), you can publish the documents.

To publish billing documents, click "Publish Final Documents" in the window that displays the draft.

In response, you are prompted to confirm the publishing request. Select "Publish Final Documents" in the prompt to confirm, or Cancel to cancel the publishing request.

After you confirm, you will receive a notification that the batch of billing documents has been queued and a batch ID will be displayed.

If you decide not to publish the documents, close the window. You can then make updates, as needed, review the updated draft, and publish.

Check carefully before you confirm a publishing request. Once you click Confirm, you cannot change the published billing documents.

Viewing published billing documents using the UI

After billing documents have been published, you can view them.

To view a published billing document:

  1. Select a billing month from the drop-down menu in the Published Billing Documents section of the Billing Documents page.

    This displays a list of all published documents for the selected billing month.

    The columns in the list are as follows:

    • Developer. The developer to whom the billing document is addressed.
    • Document Type. The type of billing document (for example, invoice or revenue share statement).
    • Publish Date. The date the billing document was published.
    • Reference Number. The document number of the billing document.
  2. Select the reference number of the document you want to view. This opens the billing document.

Configuring billing documents in the API

Billing documents are configured based on various properties in the organization profile (see Organization profile configuration settings for details). For example, the logo and address included in a billing document is based on the logoURL and address property settings in the organization profile. The billing document-related properties in the organization profile include:

  • Tax properties: taxNexus, taxRegNo
  • Tax document properties: issueNettingStmt, nettingStmtPerCurrency, seperateInvoiceForFees, hasSelfBilling, selfBillingForAllDev, selfBillingAsExchOrg
  • Payment schedule properties: billingCycle, billingType
  • Document logo and address properties: logoURL, address

See the Updating the organization profile for details on how to update these properties.

In addition, you need to specify criteria that further configures the billing documents. For example, you need to specify a billing month and year for the documents, and optionally, the types of rate plans to include in the billing documents.

See Billing document configuration settings for a complete list of billing document criteria.

Retrieving billing months using the API

You can create billing documents only for "open" months. These are complete calendar months for which you have not yet published billing documents. After you publish billing documents for a month, that month is "closed". You cannot generate billing documents for a closed month.

You can get a list of billing months and their open or closed status by issuing a GET request to /organizations/{org_name}/billing-documents-months. For example:

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

The response should look something like this:

{
  "month" : 6,
  "monthEnum" : "JUNE",
  "status" : "OPEN",
  "year" : 2013
}, {
  "month" : 3,
  "monthEnum" : "MARCH",
  "status" : "OPEN",
  "year" : 2013
}, {
  "month" : 7,
  "monthEnum" : "JULY",
  "status" : "OPEN",
  "year" : 2013
}, {
  "month" : 5,
  "monthEnum" : "MAY",
  "status" : "OPEN",
  "year" : 2013
}, {
  "month" : 4,
  "monthEnum" : "APRIL",
  "status" : "CLOSED",
  "year" : 2013
} ]

You can also get the billing document status for a specific month by issuing a GET request to /organizations/{org_name}/billing-documents-status-for-month. When you make the request, you need to specify query parameters for the billing month and year. For example, the following requests the billing documents status for May, 2013:

$ curl -H "Accept:application/json" -X GET \
"https://api.enterprise.apigee.com /v1/mint/organizations/{org_name}/billing-documents-status-for-month?billingYear=2013&billingMonth=MAY" \
-u myname:mypass

The response should look something like this:

[ {
  "orgDescription" : "{org_name} Test",
  "orgId" : "{org_name}",
  "orgName" : "{org_name}",
  "status" : "OPEN"
} ]

Generating draft billing documents using the API

Before you publish billing documents, you can generate a draft. This allows you to review the billing documents and make adjustments if necessary. To generate draft billing documents, issue a POST request to /organizations/{org_name}/generate-draft-billing-documents. When you make the request, specify criteria that configure the documents. You need to specify criteria for the billing month and billing year. Other criteria that you can specify are:

  • The identification of the products to include in the billing documents.
  • The identification of the developers to include in the billing documents.
  • The type of rate plans to include in the billing documents, such as a standard rate plan, a developer rate plan, or both.

If the property for a criteria is not specified, the billing documents will be all inclusive for that property. For example, if no product identifications are specified in the criteria, all products will be included.

For example, the following generates draft billing documents for the month of July, 2013. The documents include transactions for a specific developer against the location, messaging, and payment products. Because the property for identifying the type of rate plan (ratePlanLevels) is not specified, the billing documents will include both standard and developer rate plans.

$ curl -H "Content-Type:application/json" -H "Accept: application/octet-stream" -X POST -d \
'{
   "billingMonth":"JULY",
   "billingYear":2013,
   "productIds":[
       "location",
       "messaging",
       "payment"],
   "devCriteria":[{
       "id":"K4jW2QLjZ1h8GFA8",
       "orgId":"{org_name}"}]
}' \
"https://api.enterprise.apigee.com/ v1/mint/organizations/{org_name}/generate-draft-billing-documents" \
-u myname:mypass

The response contains the HTML code for the draft billing documents (only part of the response is shown).

<!DOCTYPE html>
<html>
    <body>
...
            
            <tr>
                <td colspan=2 align="center">
                    <b>INVOICE</b>
                </td>
            </tr>
…            
            
        </table>
        <table align="center" width="95%" cellpadding="0" cellspacing="0">
            <tr>
                <td> For the attention of:    DEV FIVE</td>
…
        </table>
        <br/>
        <table align="center" width="95%" cellpadding="0" cellspacing="0" class="mintstripes">
            <!-- #### Main Content Table -->
            <tr>
                <th align="left">
                    <b>
                        <u>Usage</u>
                    </b>
                </th>
            </tr>
            <tr>
                <th align="left">Item Description</th>
                <th align="left">Operator Name</th>
                <th align="left">Description</th>
                <th align="left">Quantity</th>
                <th align="left">Unit Price<<th>
                <th align="left">Total</th>
            </tr>
            <tr>
                <td align="left">Location</td>
                <td align="left">Mycompany</td>
                <td align="left">Flat Rate</td>
                <td align="left">1.00</td>
                <td align="left">0.05</td>
                <td align="left">0.05</td>
            </tr>
            <tr>
                <td align="left">Messaging</td>
                <td align="left">Mycompany</td>
                <td align="left">Flat Rate</td>
                <td align="left">1.00</td>
                <td align="left">0.05</td>
                <td align="left">0.05</td>
            </tr>
            <!-- #### Main Content Table end -->
        </table>
… 

Retrieving information about unpublished billing documents using the API

You can retrieve a list of the developers, API products, and sub-organizations that are associated with unpublished billing documents. You request each type of object individually by issuing a GET request to the pertinent resource, as follows:

Resource Retrieves
/organizations/{org_name}/unpublished-billing-documents-developers

Developers with unpublished billing documents

/organizations/{org_name}/unpublished-billing-documents-products

API products with unpublished billing documents

/organizations/{org_name}/unpublished-billing-documents-suborgs

Sub-organizations with unpublished billing documents

When you make the request, you need to specify the billing month and billing year in the request body. You also need to specify one or more API products in the request body to retrieve the developers for unpublished billing documents. For example, the following request lists retrieves the developers with unpublished billing documents for the billing month and year July, 2013:

$ curl -H "Content-Type:application/json" -X POST -d \
'{
   "billingMonth":"JULY",
   "billingYear":2013,
   "productIds":[
          "location",
          "messaging",
          "payment"]
}' \
"https://api.enterprise.apigee.com/ v1/mint/organizations/{org_name}/unpublished-billing-documents-developers" \
-u myname:mypass

The response should look something like this:

"developer": [
{
"address": [
{
"address1": "6210 Stoneridge Drive",
"city": "Pleasanton",
"country": "US",
"id": "developer1-address",
"isPrimary": true,
"state": "CA",
"zip": "94588"
}
],
"billingType": "POSTPAID",
"broker": false,
"email": "developer@myorg.com",
"legalName": "Developer 1",
"name": "{org_name}",
"organization": {
"id": "{org_name}",
},
"registrationId": "developer1 ",
"status": "ACTIVE",
"type": "UNTRUSTED"
},
{
"address": [],
"billingType": "POSTPAID",
"broker": false,
"email": "developer@myorg.com",
"legalName": "Developer 2",
"name": "{org_name}",
"organization": {
"id": "{org_name}",
},
"registrationId": "developer2",
"status": "ACTIVE",
"type": "TRUSTED"
}
],
"totalRecords": 2
}

Generating and publishing final billing documents using the API

After you generate draft billing documents (and finish checking them), you can generate and publish a final version of the documents by issuing a POST request to /organizations/{org_name}/generate-final-billing-documents.

Check the draft billing documents carefully before you generate and publish the final versions. You cannot change the billing documents once they are published.

When you make the request, you specify criteria that configure the documents. As is the case for draft billing documents, you need to specify criteria for the billing month and billing year. Other criteria that you can specify are:

  • The identification of the products to include in the billing documents.
  • The identification of the developers to include in the billing documents.
  • The type of rate plans to include in the billing documents, such as a standard rate plan, a developer rate plan, or both.

If the property for a criteria is not specified, the billing documents will be all inclusive for that property. For example, if no product identifications are specified in the criteria, all products will be included.

The following example generates and publishes final billing documents for the month of July, 2013. The documents include transactions for a specific developer against the location, messaging, and payment products. Because the property for identifying the type of rate plan (ratePlanLevels) is not specified, the billing documents will include both standard and developer rate plans.

$ curl -H "Content-Type:application/json" -H "Accept: application/octet-stream" -X POST -d \
'{
   "billingMonth":"JULY",
   "billingYear":2013,
   "productIds":[
       "location",
       "messaging",
       "payment"],
   "devCriteria":[{
       "id":"K4jW2QLjZ1h8GFA8",
       "orgId":"{org_name}"}]
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/generate-final-billing-documents" \
-u myname:mypass

The response includes a batch ID and batch timestamp, indicating that a batch of billing documents has been queued.

{
    "batchId": "admin@apix.com-#-2013-08-30_16-32-00-925-UTC",
    "batchTimeStamp": "2013-08-30_16-32-00-925-UTC",
    "running": true,
    "submittedBy": "admin@apix.com"
}

You can get the status of a billing document batch by issuing a GET request to organizations/{org_name}/generate-billing-documents-batch-status. For example:

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

Retrieving published document months using the API

You can get a list of months in which you published billing documents (that is, "closed billing months"). You can get that list for an organization or for a specific developer.

To get a list of list of months in which you published billing documents for an organization, issue a GET request to /organizations/{org_name}/received-billing-documents-months. For example:

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

The response should look something like this:

[
  {
    "month": 8,
    "monthEnum": "AUGUST",    
    "year": 2013
  },
  {
    "month": 7,
    "monthEnum": "JULY",
    "year": 2013
  }
]

To get a list of months in which you published billing documents for a specific developer, issue a GET request to /organizations/{org_name}/{developer_id}/received-billing-documents-months, where {developer_id} is the identification of the developer. For example:

$ curl -H "Accept:application/json" -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}developers/5cTWgdUvdr6JW3xU/received-billing-documents-months" \
-u myname:mypass

Searching for published billing documents using the API

You can search for billing documents that you published by issuing a POST request to /organizations/{org_name}/search-billing-documents. When you make the request, you specify criteria for the search. As is the case for creating billing documents, you need to specify criteria for the billing month and billing year. Other criteria that you can specify are:

  • The identification of the products to include in the search.
  • The identification of the developers to include in the search.
  • The type of rate plans to include in the search, such as a standard rate plan, a developer rate plan, or both.

If the property for a criteria is not specified, the search will be all inclusive for that property. For example, if no product identifications are specified in the criteria, all products will be included in the search.

The following example searches for published billing documents for the billing month and year July, 2013, and for a specific developer. Because the properties for identifying products (productIds) and type of rate plan (ratePlanLevels) are not specified, the search will include transactions for that developer against all products and for both standard and developer rate plans.

$ curl -H "Content-Type:application/json" -X POST -d \
'{
   "billingMonth": "JULY",
   "billingYear": "2013",
   "devCriteria":[{
      "id":"K4jW2QLjZ1h8GFA8",
      "orgId":"{org_name}"}]
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/search-billing-documents" \
-u myname:mypass

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

{
    "billingDocument": [
        {
            "batchId": "admin@apix.com-#-2013-08-30_16-29-58-067-UTC",
            "billableDeveloper": {
                "address": [
                    {
                        "address1": "Dev One Address",
                        "city": "Pleasanton",
                        "country": "US",
                        "id": "ed78a161-be00-43ea-827f-1f6ae14cc199",
                        "isPrimary": true,
                        "state": "CA",
                        "zip": "94588"
                    }
                ],
                "approxTaxRate": 0,
                "billingType": "PREPAID",
                "broker": false,
                "developerRole": [],
                "email": "dev1@myorg.com",
                "hasSelfBilling": false,
                "id": "K4jW2QLjZ1h8GFA8",
                "legalName": "DEV ONE",
                "name": "Dev One",
                "organization": {
                    ...
                },
                "registrationId": "TestRegId",
                "status": "ACTIVE",
                "type": "TRUSTED"
            },
            "billingDocDate": "2013-08-30 16:30:05",
            "billingMonth": "JULY",
            "billingYear": 2013,
            "currency": "USD",
            "documentNumber": "myorg-NS000000000001",
            "dueDate": "2013-10-14 16:30:05",
            "endDate": "2013-07-31 21:59:59",
            "id": "849c5c34-051d-4f78-be79-cd32c36fb281",
            "organization": {
                ...
            },
            "product": [
                {
                    "customAtt1Name": "user",
                    "description": "Messaging",
                    "displayName": "Messaging",
                    "id": "messaging",
                    "name": "messaging",
                    "organization": {
                        ...
                    },
                    "status": "CREATED"
                },
                ...
            ],
            "startDate": "2013-06-30 22:00:00",
            "status": "FINAL",
            "type": "NETTING_STMT"
        }
    ],
    "totalRecords": 1
}

You can also search for received billing documents by setting the query parameter received in the request to true. For example:

$ curl -H "Content-Type:application/json" -X POST -d \
'{
   "billingMonth": "JULY",
   "billingYear": "2013",
   "devCriteria":[{
      "id":"K4jW2QLjZ1h8GFA8",
      "orgId":"{org_name}"}]
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/search-billing-documents?received=true" \
-u myname:mypass

Billing document configuration settings

The following billing document configuration options are exposed to the API:

Name Description Default Required?
productIds

The identification of one or more API products to include in the billing documents. If this property is not specified, all API products are included in the billing documents.

N/A No
devCriteria

Specifies the ID and organization for a specific developer to be included in the billing documents. If this property is not specified, all developers are included in the billing documents.

N/A No
billingMonth

The billing month for the billing documents, such as JULY.

N/A Yes
billingYear

The billing year for the billing documents, such as 2013.

N/A Yes
ratePlanLevels

The type of rate plan to be included in the billing documents. The value can be one or more of the following:

  • DEVELOPER. Developer-specific rate plan.
  • STANDARD. Standard rate plan.

 

If this property is not specified, both developer-specific and standard rate plans are included in the billing documents.

N/A No
documentNumber

This property is used only for querying billing documents. The billing document number.

N/A No
batchId

This property is used only for querying billing documents. The batch ID of the billing document.

N/A No

Get help

For help, see Apigee Customer Support.

Next steps

Monetization allows you to make adjustments to billing documents. For example, you might need to increase or decrease the revenue share or fees specified in a billing document because of a discrepancy in your records. See Make billing adjustments for details.

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