Subscription Plans
To begin collecting subscription payments from your customers, you first need to setup Subscription Plans: These represent the products or services your customers will subscribe to, and are to be billed for. When setting up a subscription collection for a specific customer, you will then reference the Subscription Plans which should be collected from the customer.
Create a Subscription Plan
Subscription Plan creation requires a client token with the subscription:plan scope. Follow the steps described in the client token guide to obtain a client token.
The GraphQL API URL https://api.stitch.money/graphql can be used for all Subscription Plan requests (whether on test or live clients).
An example of the required GraphQL mutation is shown in the below Query, with sample inputs provided in the Variables tab. The reference information of the subscription plan and scheduling details of billing are specified as part on a plan creation request.
Subscription Plan Input Fields
The table below details various fields that may be included in the API request:
| Name | Required | Description | Type |
|---|---|---|---|
nonce | Yes | A unique reference generated by your system, for idempotency. | String |
planReference | Yes | Your unique reference for the subscription plan, which you may use to identify the subscription plan over its lifetime. | String |
planName | Yes | A user-friendly name or description for the Subscription plan which your customer may see on their bank statements, when collection funds are debited. | String |
amount | Yes | The quantity and currency to be collected for a typical collection associated to this Subscription Plan. | Object |
billingModel | Yes | The model of how the amount will be collected. This may be one of the following values: - onceOff if the amount is to be collected upfront, as a once-off payment - fixed if the amount is a fixed fee, to be collected at the specified frequency - usage if the amount is for a specific unit of a product/service provided. The usage per selected frequency should be specified, for Stitch to apply the amount applicable for the total units of usage. | String |
frequency | Conditional | The frequency at which the Subscription Plan should be collected and can be daily, weekly, monthly, or annually. For a billingModel of onceOff, this field is not required as the customer will be billed immediately when the Subscription is created. | String |
due | Conditional | The maximum period after collection date, that a collection should be done by, with relation to the frequency, specified with a due.period (time unit of days, weeks or months) and due.periodValue (the number of days, weeks or months after collection for a period). | Object |
trial | Optional | The details of a trial period, if this is to be offered within the Subscription Plan. The trial.type may be either of: - free if a free trial period is offered, the customer will not be billed for the specified period - discounted if a discount should be applied to the amount. For this value, the field trial.value should be populated to indicate the discount amount to apply/deduct. trial.period (time unit of days, weeks or months) and trial.periodValue (the number of days, weeks or months after collection for a period) should also be specified for any trial. | Object |
Subscription Plan Response
The response will indicate the status of the request and provide a unique ID in the subscriptionPlan.id field. This ID is to be used when creating Collections for customers. Additionally, this ID should be specified for any further actions on the Subscription Plan, such as amending or deactivating the plan.
A Subscription Plan status is indicated by the subscriptionPlan.active property:
true: The Subscription Plan is active and subscription collections may be created using the plan.false: The Subscription Plan was deactivated and can no longer be assigned to any customer subscriptions.
A sample response is included in the GraphQL request above, under the Example Response tab.
Amend a Subscription Plan
You may amend any of the details used after creating a Subscription Plan. Any of the input fields used on initial creation of a subscription plan may be specified, indicating that specified properties should be updated on the plan. The Subscription Plan id previously received on the plan creation should be used when creating the Subscription Plan.
An example of the amendment mutation is shown below with the Query, with sample inputs provided under the Variables. This example shows an update to the plan name and amount, of the sample plan created above.
In the case of plan changes that should only be effected from a specific future date, an additional effectiveDate field may be specified. Any subscription collections from the effective date forward will use the updated plan details.
When amending a Subscription Plan, you only need to pass in the fields of the properties you wish to amend. These will override the details currently stored on the Subscription Plan, and other properties not specified to be updated will remain the same.
Deactivate a Subscription Plan
Should a Subscription Plan no longer be required, it may be deactivated by simply specifying the Subscription Plan id, using the below mutation. Once a Subscription Plan is deactivated:
- The
activeproperty on the plan will becomefalse, - Existing collections against the given plan will stop being collected, and
- No new collections will be possible to be created against the given plan.
An optional effectiveDate may be also be specified if this is only to be deactivated from a future date. Any collections on this plan will then remain active until the effective date, after which collections will be stopped.