Send Docs Feedback

Create billing documents

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

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. For complete details, see Configure billing documents.

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.

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

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

    • All. This includes all companies in the billing documents.
    • Selected. This displays a list from which you can select the companies to include in the billing documents. If you select no companies, all companies 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 for Private Cloud: 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.

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 email:password

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 email:password

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.

For more information about the document configuration criteria, see Billing document configuration settings for the API.

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 email:password

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 and API products 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

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 email:password

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.

For more information about the document configuration criteria, see Billing document configuration settings for the API.

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 email:password

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 email:password

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 email:password

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 email:password

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.

For more information about the document search criteria, see Billing document configuration settings for the API.

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 email:password

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 email:password

Billing document configuration settings for the API

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

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?