The Create Recurring Application Charge API is used to create a recurring charge for an application. This API is essential for developers implementing subscription-based billing workflows for their apps, allowing businesses to manage recurring charges with specific terms and limits.

This API is especially useful for:

Setting up recurring billing for application usage.
Defining usage-based billing terms and limits.
Managing application subscription charges with trial periods and specific conditions.

Request Parameters

Public Request Parameters

📘
Public Request Parameters

Body Parameters

Field	Type	Required	Example	Description
`recurring_application_charge. name`	string	Yes	`test`	The name of recurring application charge.
`recurring_application_charge. price`	string	Yes	`10.0`	The price of the recurring application charge. Must match the package price defined in the app.
`recurring_application_charge. return_url`	string	Yes	`https://shoplazza.com`	The URL to redirect the merchant to after completing the subscription.
`recurring_application_charge. trial_days`	int32	No	`7`	The number of trial days offered for the subscription.
`recurring_application_charge. capped_amount`	string	No	`100.0`	The limit a customer can be charged for usage-based billing. If this property is provided, the `terms` property must also be provided.
`recurring_application_charge. terms`	string	No	"Monthly usage cap of $100"	The terms and conditions of usage-based billing charges. Required if `capped_amount` is provided.
`recurring_application_charge. test`	boolean	No	`false`	Whether it is a test charge. Defaults to false.

Response Explanation

Public Response Parameters

📘
Public Response Parameters

Success Response

Field	Type	Example	Description
`id`	string	`372269663945671159`	The unique ID of the recurring application charge.
`application_id`	string	`s1deCNxrkHePw03HD2bZ.<br>xfwJAqe07nznt`	The unique ID of the application.
`name`	string	`test`	The name of the recurring application charge.
`price`	string	`10.0`	The price of the recurring application charge.
`capped_amount`	string	`100.0`	The limit a customer can be charged for usage based billing. If this property is provided, then you must also provide the terms property. See usage charges for more information.
`terms`	string	`terms`	The terms and conditions of usage based billing charges. Must be present in order to create usage charges, for example when the capped_amount property is provided. Presented to the merchant when they approve an app's usage charges.
`return_url`	string	`https://shoplazza.com`	The redirect URL after payment.
`confirm_url`	string	`https://test-shoplazza.stg.myshoplaza.com`	The URL to confirm the recurring application charge.
`status`	string	`pending`	The status of the recurring application charge (e.g., pending, active).
`test`	boolean	`false`	Whether this is a test charge.
`trial_days`	int32	`7`	The trial period in days.
`trial_ends_on`	string	`null`	The end date of the trial period.
`billing_on`	string	`null`	The billing start date.
`cancelled_on`	string	`null`	The date the charge was cancelled.
`cancel_sub_on`	string	`null`	The subscription cancellation date, if applicable.
`created_at`	string	`2024-04-23T06:26:45Z`	The creation timestamp of the recurring application charge.
`updated_at`	string	`2024-04-23T06:26:45Z`	The last updated timestamp of the recurring application charge.

Error Response

Error responses in the API can be represented using two different fields: errors and error. Both fields provide details about issues encountered during request processing. Below is an explanation of the fields with their respective examples and descriptions.

Field	Type	Example	Description
`errors`	Array	`[ "file number error"]`	A list of errors encountered during the request processing.

Field	Type	Example	Description
`error`	String	`"page not found"`	Indicates an error encountered during the process

Error Detail

Status Code	Message	Possible Reason	Example Response
400	Bad Request	Invalid input format or request structure (e.g., missing required fields or incorrect data types).	`Bad Request`
	Unauthorized	The request is missing valid authentication credentials or the credentials provided are invalid.	`Unauthorized`
422	Unprocessable Entity	The return_url field is missing in the API request body.	ReturnUrl is required
		The return_url field is present but contains an invalid or improperly formatted URL	ReturnUrl must be a valid URL
		There is a mismatch between the charge type specified in the application plan configuration and the charge type being created. T	“The chargetype configuration in the plan does not match with the listing, please check”

API Structure Overview