Metered usage API

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

Credit Card Payment Gateway

To add a payment gateway on the SAP App Center:

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

 

  1. Click on Payment Gateway on the navigational ribbon
  2. Choose one of the options for Payment Gateways and follow these instructions to configure the payment gateway providers website: https://docs.spreedly.com/reference/supported-gateways/
  3. For the other options see below
    1. No Credit Card
      1. No fields appear, and credit card payments are not supported.
    2. Test Gateway
      1. Allows for developers to perform test transactions against a test payment processor instance. Transactions will always show as successful, but no money is exchanged. The merchant account is also unable to be accessed to see transactions.
    3. Existing Gateway Integration
      1. Current payment gateway configuration.