English

简体中文

English

简体中文

Appearance

About RecurringApplicationCharge ​

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

EVENT appSubscriptions/update: application subscription update

Recurring application charge Object ​

The recurring application charge object.

Properties ​

recurringApplicationChargeobject
Subscription entity class.
- Hide child properties
idnumber
The ID of the recurring application charge.
namestring
The name of the recurring application charge.
pricestring
The price of the recurring application charge.
billingTimestring
The date and time when the customer is billed.
statusstring
The status of the recurring charge. Enum value:
* pending;
* active;
* declined;
* expired;
* froze;
* cancelled.
createTimestring
The date and time when the recurring application charge was created.
updateTimestring
The date and time when the recurring application charge was last updated.
activatedTimestring
The date and time when the customer activated the recurring application charge.
returnUrlstring
The URL where the merchant is redirected after accepting the charge.
testboolean
Whether the application charge is a test transaction
cancelledTimestring
The date and time when the merchant canceled their recurring application charge.
trialDaysnumber
The number of days that the customer is eligible for a free trial.
trialEndsTimestring
The date and time when the free trial ends.
confirmationUrlstring
The URL where the merchant accepts or declines the recurring application charge.
currencystring
The currency of the price of the recurring application charge.
bash
{
  "recurringApplicationCharge": {
    "trialEndsTime": "2025-04-01T15:46:46-04:00",
    "trialDays": "5",
    "test": "false",
    "confirmationUrl": "https://jsmith.blaze.com/admin/charges/755357713/1029266966/RecurringApplicationCharge/confirm_recurring_application_charge?signature=BAh7BzoHaWRpBBZeWT06EmF1dG9fYWN0aXZhdGVU--98ef575ea1fff24621e47eaa65e42758f13a3ae5",
    "billingTime": "2025-04-01T15:46:46-04:00",
    "updateTime": "2025-04-01T15:46:46-04:00",
    "createTime": "2025-04-01T15:46:46-04:00",
    "activatedTime": "2025-04-01T15:46:46-04:00",
    "price": "20.0",
    "cancelledTime": "2025-04-01T15:46:46-04:00",
    "name": "Super Duper Plan",
    "currency": "USD",
    "id": "1029266966",
    "returnUrl": "http://super-duper.blaze.com/",
    "status": "pending"
  }
}

EVENT application subscription update ​

Messages about changes in the subscribed application mainly include Pending, Active, Rejected, Expired, Frozen, and Cancelled

Access scope

Requires ANY of the following access scopes: write_billing read_billing

Topic

EVENT appSubscriptions/update 

Event Data

appSubscriptionobject
Subscription message body.
- Hide child properties
createTimestring
Creation time.
currencystring
Currency.
idstring
The ID of the recurring application charge.
namestring
The name of the recurring application charge.
shopIdstring
Shop unique identifier.
statusstring
Enum value:
* pending - pending status;
* active - active status;
* declined - declined status;
* expired - expired status
* froze - froze status;
* cancelled - cancelled status.
updateTimestring
Update time.
cappedAmountstring
The upper limit of the fees that can be charged to customers when billing is based on usage.
pricestring
The price of periodic application fees.
intervalstring
Subscription cycle.
json
{
  "appSubscription": {
    "cappedAmount": "20.0",
    "createTime": "2025-04-22T11:08:24.284+0800",
    "price": "10.0",
    "name": "Free install",
    "currency": "USD",
    "updateTime": "2025-04-22T11:08:25.412+0800",
    "interval": "MONTH",
    "id": "15300",
    "shopId": "4022082659398",
    "status": "cancelled"
  }
}