Metered usage API

The SAP App Center supports metered usage billing, also known as usage-based billing, which is how Developers charge users for their variable use of a product during each billing period. Developers configure metered usage through the pricing settings, for each product edition and add-on product. Typically, you use the unit that you set within the pricing settings, to measure and charge for usage. For example, for each gigabyte, hour, or user license, that a user uses.

When you enable metered usage pricing, the SAP App Center exposes an API endpoint for you to report usage to the marketplace that owns the user account. For example, you can report the number of gigabytes of storage that users use, and the marketplace charges them for it based on the price per gigabyte that you define.

You may report usage as often as you like during a billing cycle. The marketplace sums all of the usage that you send during the current billing cycle for that edition or add-on product unit type, and invoices users for the total units. Users only receive one invoice for the billing cycle, with the total units and total price for each metered usage type.

You can configure metered usage with one of two settings, custom or pre-configured, and you can call the API call in either of those modes. Following are descriptions of the two settings.

Pre-configured metered usage

You pre-configure a unit type, price, and a description of the usage to appear on invoices, to apply to all usage of that unit type. You can configure an unlimited number of unit types for the same product edition or add-on product. For example, you could configure both of the following for the same product edition, or add-on product:

  • metered usage for unit type gigabyte, with a description of Gigabyptes of storage used, and price per unit of $0.15.
  • metered usage for unit type hours, with a description of Hours used, and price per unit of $2.00.

Custom metered usage

You select Allow custom usage to charge custom usage rates, instead of pre-configuring a unit, price and description that applies to all usage charges. This means that you can charge the user any price for usage, and describe the charge uniquely for each customer and billing period. With the API, you pass the price, description, and quantity, but not the unit for the usage.

When a user cancels a subscription during a billing cycle, you must report the usage before you cancel the subscription. The marketplace cannot invoice usage that you report after you cancel the subscription.

You must complete the following prerequisites before you can send a user’s metered usage to the SAP App Center.

Configure products for metered usage

  1. For pre-configured metered usage – enable metered usage under per unit pricing
  2. For custom metered usage – enable custom metered usage (located under usage options)
    • To separate the metered invoice from the standard invoice please enable separate pre-paid order (located under usage options)
      Locate the marketplace base URL

To report usage, you POST an OAuth-signed XML document to this endpoint URL: https://www.sapappcenter.com/api/integration/v1/billing/usage.

Send pre-configured metered usage

Description: Send usage data for pre-configured metered usage to the user account. For a description of pre-configured metered usage, see Metered usage API.
Endpoint URL: https://www.sapappcenter.com/api/integration/v1/billing/usage
Request operation: POST
Mandatory parameters in the request:

  • account—User account that incurred the usage.
  • accountIdentifier—User’s unique account identifier.
  • unit—Unit type that you pre-configured, for which you are sending metered usage.
  • quantity—Number of units of metered usage incurred by the user.

Following are example JSON and XML requests to send pre-configured metered usage to a marketplace. In this example scenario, you configured metered usage for unit type gigabyte, and unit type hour, and a price for each. Now, you POST the following JSON or XML to tell the marketplace to charge the user for usage of 34 gigabytes, and three hours.

JSON example

{
  "account": { "accountIdentifier": "MY_ACCOUNT" },
  "items": [
    {
      "unit": "GIGABYTE",
      "quantity": "34"
    },
    {
      "unit": "HOUR",
      "quantity": "3"
    }
  ]
}

XML example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<usage>
  <account>
    <accountIdentifier>MY_ACCOUNT</accountIdentifier>
  </account>
  <items>
    <item>
      <unit>GIGABYTE</unit>
      <quantity>34</quantity>
    </item>
    <item>
      <unit>HOUR</unit>
      <quantity>3</quantity>
    </item>
  </items>
</usage>

For HTTP status codes and example JSON and XML responses for metered usage, see HTTP status codes.

Send custom metered usage

Description—Send usage data for custom metered usage to the user account. For a description of custom metered usage, see Metered usage API.
Endpoint URL—https://www.sapappcenter.com/api/integration/v1/billing/usage
Request operation—POST
Mandatory parameters in the request

  • account—User account that incurred the usage.
  • accountIdentifier—User’s unique account identifier.
  • quantity—Number of units of metered usage incurred by the user.
  • price—Custom price per unit.
  • description—Custom description of this charge. It appears on invoices.

Following are example JSON and XML requests to send custom metered usage to a marketplace. In this example scenario, you configured custom metered usage for an edition or add-on product. Now, you POST the following JSON or XML to tell the marketplace to charge the user for using a quantity of 34, at a price of $0.15 each, with a custom description in which you typically name the unit applicable to the usage.

JSON example

{
  "account": { "accountIdentifier": "MY_ACCOUNT" },
  "items": {
    "quantity": 34,
    "price": "0.15",
    "description": "Aaron, this month you used 34 gigabytes."
  }
}

XML example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<usage>
  <account>
    <accountIdentifier>MY_ACCOUNT</accountIdentifier>
  </account>
  <item>
    <quantity>34</quantity>
    <price>0.15</price>
    <description>Aaron, this month you used 34 gigabytes.</description>
  </item>
</usage>

For HTTP status codes and example JSON and XML responses for metered usage, see HTTP status codes.

HTTP status codes

Refer to the following table for the HTTP status codes that are relevant to the metered usage API, a description of each, and JSON and XML response examples.

Positive responses

Code    Description Response body
200 OK
Returns the result  

JSON

{
  "success": "true",
  "message": "Account billed successfully"
}

XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<result>
  <success>true</success>
  <message>Account billed successfully</message>
</result>

Error responses

400 BAD REQUEST
Some required fields were not received. JSON & XML

Integration Report – Manual

After a listing is switched over to manual modethere are several steps that need to be taken care of before the product is ready to be bought, these steps are located on the Integration tabs of the product

To get started:

  1. Please Login to the App Center
  2. Click on the navigational dropdown in the upper right and choose Publish Apps

  1. Click on products on the navigational ribbon
  2. Click Edit Product for the product that is now enabled for transaction
  3. Find the Integration tabs on the left side of the screen

  1. On the Edit Integration tab please enter the email address that will be notified when a customer purchases the product and save

  1. Next on the Edit Authentication tab,
    1. There are several different methods that can be used on this tab, the mostly commonly used method is the Bookmark method.
    2. After selecting the Bookmark method, enter the landing page url for the solution and save.

 

  1. Next is Integration Report tab
    1. Please Mark Complete the three buttons at the bottom of the integration report tab.

  1. Now it is time to test the subscription of the product
    1. Run the test for test #1
    2. Choose the edition to use for the remaining tests
    3. Click create subscription
    4. Make sure the check box is selected under order information
    5. Click continue
    6. And then click return to overview

    1. Now it is time to complete the Open event that is tied to the subscription, a similar step will need to be taken care of every time a customer purchases the product
        1. Click on the Event tab under Integration
        2. Click the Complete Event button
        3. Now choose event succeeded, and click save

  1.                              
    1. Now it is time to run test 2 to 5, just remember to complete the event after doing the test.
      1. Note: if the subscription only allows 1 user, instead of starting with adding a user, start with removing a user, completing the event, and then adding the user.
    2. After the integration report is 100% complete the product is ready to be republished with the updated information.

     

Listing types

Types of listings on the SAP App Center

Referral Only Listing

A “referral” listing on the SAP App Center is a marking only listing. This type of listing allows for lead generation with a Call to Action button labeled “Contact Me”, or a link to a third party site through a Call to Action button labeled “Learn More”, or both of these options with both Call to Action buttons.

Manual Transact (Web App Manual Setup Full Integration)

The simplest type of transactable listing to create on the App Center is a manual transact listing. This type of listing is managed through manual events that must be completed by someone with the developer role on the SAP App Center who is part of your company.

The way this works is that after a customer purchases your product, you or someone who is part of your company must manually set up the account for the customer on your company’s server. After the account is created use the event that was created when the customer purchased the product to send out the login information to the customer. The customer will then be able to access the app through the SAP App Center as long as it is a cloud based app.

Automated Transact (Web App Full Integration)

An automated transact listing allows for the use of API calls to automatically communicate between the SAP App Center and your company’s server for a customer to access a purchase.

Note: An automated transact listing works best with apps that run on a cloud platform.

How-to create a listing

To create/modify an app on the SAP App Center:

  1. Please Login to the App Center
  2. Click on the navigational dropdown in the upper right and choose Publish Apps.

 

  1. Click on products on the navigational ribbon
  2. Click Create Product/Edit Product
    1. If creating a new listing, choose standalone product
  3. There are 4 required tabs to be filled out:
    1. Listing Info
    2. Profile
    3. Features
    4. Editions

After any changes are made please save and after all changes are done and saved please hit the publish button to allow for the App Center Team to approve the updated listing.