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:

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

Notes

When using the Billing API, please note the following:

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: Create recurring app charge

DELETE /api/202412/recurring_application_charges/{chargeId}: Cancel recurring app charge

GET /api/202412/recurring_application_charges/{chargeId}: Retrieve single app charge

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.

Recurring application charge Object

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"
  }
}

`POST` Create recurring app charge

Creates a recurring charge for an app subscription. Supports time-based, usage-based, and hybrid billing models.

Access scope

Requires ANY of the following access scopes: write_billing

Endpoint

POST /api/202412/recurring_application_charges

Request Params

recurringApplicationChargeobject

Subscription entity class.

- Hide child properties

cappedAmountstring

The limit a customer can be charged for usage based billing

termsstring

terms

pricestring

price

namestring

name

returnUrlstring

The URL where the merchant is redirected after accepting the charge.

trialDaysnumber

The number of days that the customer is eligible for a free trial.

Response Data

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.

POST /api/202412/recurring_application_charges

bash

curl -X POST \ 
https://{shop}.genmystore.com/api/202412/recurring_application_charges" \ 
-H "X-Genstore-Access-Token: {access_token}" \ 
-H "Content-Type: application/json" \ 
-d '{
	"recurringApplicationCharge":{
		"trialDays":"7",
		"cappedAmount":"100",
		"terms":"$1 for 1000 emails",
		"price":"100.00",
		"name":"Super Duper Expensive action",
		"returnUrl":"http://super-duper.blaze.com"
	}
}'

Response

json

HTTP/1.1 200 OK
{
  "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"
  }
}

`DELETE` Cancel recurring app charge

Cancels the current recurring charge for a shop.

Access scope

Requires ANY of the following access scopes: write_billing

Endpoint

DELETE /api/202412/recurring_application_charges/{chargeId}

Request Params

{}

Response Data

{}

DELETE /api/202412/recurring_application_charges/{chargeId}

bash

curl -X DELETE \ 
https://{shop}.genmystore.com/api/202412/recurring_application_charges/{chargeId}" \ 
-H "X-Genstore-Access-Token: {access_token}" \

Response

json

HTTP/1.1 200 OK
{}

`GET` Retrieve single app charge

Retrieve detailed information about a single charge based on the charge ID.

Access scope

Requires ANY of the following access scopes: write_billing read_billing

Endpoint

GET /api/202412/recurring_application_charges/{chargeId}

Request Params

{}

Response Data

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.

GET /api/202412/recurring_application_charges/{chargeId}

bash

curl -X GET \ 
https://{shop}.genmystore.com/api/202412/recurring_application_charges/{chargeId}" \ 
-H "X-Genstore-Access-Token: {access_token}" \

Response

json

HTTP/1.1 200 OK
{
  "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"
  }
}

About RecurringApplicationCharge

Access scope

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

Core Features:

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

Notes

When using the Billing API, please note the following:

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.

Recurring application charge Object

The recurring application charge object.

Properties

`POST` Create recurring app charge

Creates a recurring charge for an app subscription. Supports time-based, usage-based, and hybrid billing models.

Access scope

Requires ANY of the following access scopes: write_billing

Endpoint

POST /api/202412/recurring_application_charges

`DELETE` Cancel recurring app charge

Cancels the current recurring charge for a shop.

Access scope

Requires ANY of the following access scopes: write_billing

Endpoint

DELETE /api/202412/recurring_application_charges/{chargeId}

`GET` Retrieve single app charge

Retrieve detailed information about a single charge based on the charge ID.

Access scope

Requires ANY of the following access scopes: write_billing read_billing

Endpoint

GET /api/202412/recurring_application_charges/{chargeId}

Product

Product Variant

Collection

Inventory

Product Category

Gift Card

Product Vendor

Order

Fulfillment

Customer

Theme

Shop

Market

Translate

Metafield

Metafield Definition

Finance Account

Pay Transaction

Discount

webhook

RecurringApplicationCharge

UsageCharge

About RecurringApplicationCharge ​

Recurring application charge Object ​

Properties ​

POST Create recurring app charge ​

Request Params

Response Data

DELETE Cancel recurring app charge ​

Request Params

Response Data

GET Retrieve single app charge ​

Request Params

Response Data

About RecurringApplicationCharge ​

Recurring application charge Object ​

Properties ​

POST Create recurring app charge ​

DELETE Cancel recurring app charge ​

GET Retrieve single app charge ​

About RecurringApplicationCharge

Recurring application charge Object

Properties

`POST` Create recurring app charge

`DELETE` Cancel recurring app charge

`GET` Retrieve single app charge

About RecurringApplicationCharge

Recurring application charge Object

Properties

`POST` Create recurring app charge

`DELETE` Cancel recurring app charge

`GET` Retrieve single app charge