English

简体中文

English

简体中文

Appearance

About UsageCharge ​

Access scope

Multiple access scopes needed — refer to each endpoint for access scope requirements.

The Billing API provides a set of RESTful endpoints for managing app billing information, including creating, canceling, retrieving bills, and reporting usage charges. This API is designed to support merchants on the Genstore platform in subscribing to and using apps.

Core Features:

  1. Create recurring app charges: Allows merchants to create recurring subscription fees for apps.
  2. Cancel recurring charges: Allows merchants to cancel their subscription fees for apps.
  3. Retrieve a single charge: Allows merchants to query charge details using the subscription charge ID.
  4. Create usage-based charges: Allows merchants to create charges based on actual usage.

Notes

When using the Billing API, please note the following:

  1. Data consistency: To avoid duplicate usage charges, ensure that the extUniqueId in each usage report request is unique.

Use Cases

Here are some common use cases to help developers better understand the practical value of the Billing API:

  • Create recurring application charges: Merchants can use the API to create recurring billing plans for apps, supporting time-based, usage-based, or hybrid billing models.
  • Cancel recurring charges: Merchants can cancel their current subscription fees through the API.
  • Retrieve a single charge: Merchants can retrieve details of an individual subscription to view its full billing information.
  • Create usage-based charges: Once a merchant subscribes to a usage-based plan, they can report usage via the API to generate corresponding usage charges.

Endpoints

POST /api/202412/recurring_application_charges/{chargeId}/usage_charges: Create usage charge

Usage charge Object ​

The Usage charge object.

Properties ​

usageChargeobject
Usage charge entity class.
- Hide child properties
idnumber
The ID of the usage charge.
descriptionstring
The description of the usage charge.
pricestring
The price of the usage charge.
createTimestring
The date and time when the usage charge was created.
currencystring
The currency of the price of the usage charge.
balanceUsedstring
Used balance.
balanceRemainingstring
Remaining balance.
riskLevelnumber
Risk level.
bash
{
  "usageCharge": {
    "balanceRemaining": "2",
    "riskLevel": "0",
    "createTime": "2013-06-27T08:48:27-04:00",
    "price": "10",
    "description": "Super Mega Plan 1000 emails",
    "currency": "USD",
    "id": "675931192",
    "balanceUsed": "11"
  }
}

POST Create usage charge ​

After a merchant subscribes to a usage-based billing app, this endpoint allows reporting the app usage to generate a corresponding usage charge.

Access scope

Requires ANY of the following access scopes: write_billing

Endpoint

POST /api/202412/recurring_application_charges/{chargeId}/usage_charges 

Request Params

usageChargeobject
Usage charge entity class.
+ Show child properties
extUniqueIdstring
A unique key used to identify each request.

Response Data

usageChargeobject
Usage charge entity class.
- Hide child properties
idnumber
The ID of the usage charge.
descriptionstring
The description of the usage charge.
pricestring
The price of the usage charge.
createTimestring
The date and time when the usage charge was created.
currencystring
The currency of the price of the usage charge.
balanceUsedstring
Used balance.
balanceRemainingstring
Remaining balance.
riskLevelnumber
Risk level.
bash
curl -X POST \ 
https://{shop}.genmystore.com/api/202412/recurring_application_charges/{chargeId}/usage_charges" \ 
-H "X-Genstore-Access-Token: {access_token}" \ 
-H "Content-Type: application/json" \ 
-d '{
	"usageCharge":{
		"price":"10",
		"description":"Super Mega Plan 1000 emails"
	},
	"extUniqueId":"2435331231"
}'
json
HTTP/1.1 200 OK
{
  "usageCharge": {
    "balanceRemaining": "2",
    "riskLevel": "0",
    "createTime": "2013-06-27T08:48:27-04:00",
    "price": "10",
    "description": "Super Mega Plan 1000 emails",
    "currency": "USD",
    "id": "675931192",
    "balanceUsed": "11"
  }
}