English

简体中文

English

简体中文

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 ​

recurringApplicationChargeobjectrequired
Subscription entity class.
- Hide child properties
idnumberrequired
The ID of the recurring application charge.
namestringrequired
The name of the recurring application charge.
pricestringrequired
The price of the recurring application charge.
billingTimestringrequired
The date and time when the customer is billed.
statusstringrequired
The status of the recurring charge. Enum value:
* pending;
* active;
* declined;
* expired;
* froze;
* cancelled.
createTimestringrequired
The date and time when the recurring application charge was created.
updateTimestringrequired
The date and time when the recurring application charge was last updated.
activatedTimestringrequired
The date and time when the customer activated the recurring application charge.
returnUrlstringrequired
The URL where the merchant is redirected after accepting the charge.
testbooleanrequired
Whether the application charge is a test transaction
cancelledTimestringrequired
The date and time when the merchant canceled their recurring application charge.
trialDaysnumberrequired
The number of days that the customer is eligible for a free trial.
trialEndsTimestringrequired
The date and time when the free trial ends.
confirmationUrlstringrequired
The URL where the merchant accepts or declines the recurring application charge.
currencystringrequired
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

appSubscriptionobjectrequired
Subscription message body.
- Hide child properties
createTimestringrequired
Creation time.
currencystringrequired
Currency.
idstringrequired
The ID of the recurring application charge.
namestringrequired
The name of the recurring application charge.
shopIdstringrequired
Shop unique identifier.
statusstringrequired
Enum value:
* pending - pending status;
* active - active status;
* declined - declined status;
* expired - expired status
* froze - froze status;
* cancelled - cancelled status.
updateTimestringrequired
Update time.
cappedAmountstringrequired
The upper limit of the fees that can be charged to customers when billing is based on usage.
pricestringrequired
The price of periodic application fees.
intervalstringrequired
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"
  }
}