Plans

Recurring plans store information that can be applied to future recurring charges. They are useful for tracking the subscription status of a user (look for users subscribed to plan X) and making simpler Recur requests by only including a plan_id in the recur node as opposed to specifying each detail of the subscription such as charge interval, notification URL, free trial, etc.

Object Data

Variable	Type	Required	Format/Example
id	automatic		123456789
type	string		Either "free" or "paid".
name	string	yes	e.g., "Gold Plan"
amount	money	yes	The amount to charge each charge interval (e.g, "10.95").
interval	int	yes	The number of days between charges (e.g, "30").
occurrences	int		The total number of occurrences for the subscription (e.g, "5" for 5 total charges). Default: Infinite.
free_trial	int		If set, each subscription begins with a free trial of this many days (e.g, "7").
notification_url	string		A URL to send HTTP POST notifications recurring-related events such as expirations, cancellations, payments, etc. (detailed here).

Method: NewPlan

Create a new recurring plan.

Required data:

• plan_type ("free" or "paid"), not required after v1.91
• amount
• interval
• name

Optional data:

• Any/all of the object data above, except id.

Response data:

• response_code of "500", upon success.
• plan_id - The ID of the new plan.

Method: UpdatePlan

Update an existing plan.

Required data:

• plan_id

Optional data:

• Any/all of the object data above, except id.

Response data:

• response_code of "501", upon success.

Method: DeletePlan

Delete an existing plan.

Required data:

• plan_id

Response data:

• response_code of "502", upon success.

Method: GetPlan

Gets a record for an individual plan.

Required data:

• plan_id - The ID of the plan.

Response data:

• plan
  • All available plan data.
  • num_customers - Number of active subscribers to this plan.
  • status - Either "active" or "deleted".

Method: GetPlans

Searches all plans. If a request is made without any filters, the first 100 plan records, ordered by "id", are returned.

Optional filters:

• Any of the variables listed under Object Data, except id.
• deleted - Set to "1" to retrieve only deleted customers. Default: 0 (only active).
• offset - Retrieval will begin after offset # of records. Useful for pagination. Default: 0.
• limit - The total number of records to retrieve, beginning at the offset. Maximum: 100. Default: 100.
• sort - The field on which to sort retrieved records. Default: "id". Available values:
  • id
  • amount
• sort_dir - The direction in which to sort retrieved records. Default: "asc". Can also be "desc".

Response data:

• results - Number of records in this response
• total_results - Total # of records to retrieve. Use offset to gather all records over multiple iterated requests.
• plans
  • A plan node for each returned plan.
    • All data available for the plan, in the format of GetPlan.