Create a subscription

Learn how to track trials and create subscriptions for users of your SaaS application

When a new tenant is created in your SaaS application it will be reflected in Bunny as a Subscription.

There are 2 main types of subscription:

Trial - where a product plan has been configured to allow trials this type of subscription will be flagged as a trial. At the end of the trial it will either cancel or activate to a paid subscription.
Active - this is a paid subscription. Invoices will be generated and payments will be collected.

You should make the request to create a new subscription in Bunny immediately after a new sign-up happens on your SaaS application.

PrerequisitesLink to Prerequisites section

Before you can start tracking your trial subscriptions you will need to complete these tasks:

Create a Plan and associated Price List in Bunny. Take note of the code that you set for the price list as you will need that in the next step.
Create an API client & install a Bunny SDK

When creating an API client you need to select the scopes that you want to allow. To create subscriptions in Bunny your API client needs the standard:read and standard:write scopes.

Make the requestLink to Make the request section

Assuming that you have completed both of the prerequisite steps you should have API credentials and a Bunny SDK installed as well as having a plan, price list and code setup.

You can either use the subscriptionCreate mutation or the create subscription method on our SDKs to setup a new subscription.

For example, create a new trial subscription and provide Bunny with the unique ID of the new tenant in your SaaS application.

MutationLink to Mutation section

mutation subscriptionCreate ($attributes: SubscriptionAttributes!) {
    subscriptionCreate (attributes: $attributes) {
        subscription {
            id          
            account {
                id
                name
                contacts {
                    id
                    firstName
                    lastName
                }                
            }
            trialStartDate
            trialEndDate
            startDate
            endDate
            state
            plan {
              code
              name
            }
            priceList {
                code
                name
            }
            tenant {
                id
                code
                name
            }
        }
        errors
    }
}

AttributesLink to Attributes section

{
  "attributes": {
    "account": {
        "billingContact": {
            "firstName": "John",
            "lastName": "Titor",
            "email": "john@example.com"
        },
        "name": "Superdesk Inc"
    },  
    "trial": true,
    "priceListCode": "free",
    "tenant":{
        "code": "superdesk"
    }
  }
}

response = BunnyApp::Subscription.create(
  price_list_code: 'starter',
  options: {
    account_name: "Superdesk",
    first_name: "Meg",
    last_name: "La Don",
    email: "meg@example.com",
    trial: true,
    tenant_code: "123456",
    tenant_name: "Superdesk"
  }
)

const res = await bunny.subscriptionCreate("priceListCode", {
  trial: true,
  accountName: "accountName",
  firstName: "firstName",
  lastName: "lastName",
  email: "email@example.com",
  tenantCode: "remoteId",
});

We recommend submitting the tenantCode with your request so that Bunny is aware which tenant in your SaaS application the subscription belongs to.

Bunny will send your tenantCode back with subscription change webhooks so that you know which of your tenants to update with any changes.

Optional parametersLink to Optional parameters section

Parameter
trial	Boolean	If the product plan supports a trial period then when this parameter is `true` the subscription will be created in a TRIAL state.
tenantCode	String	The unique identifier for the tenant on your SaaS platform.
evergreen	Boolean	Whether the subscription renews automatically at the end of each term. The Node SDK defaults this to `true` and the Ruby SDK to `false`, so set it explicitly.

For more detail on all of the parameters that can be set when creating a trial see the subscriptionAttributes object.

Handling errorsLink to Handling errors section

Providing that you have a valid access_token and well formed query then any errors are likely to be related to the data you are submitting.

The SDKs turn these errors into exceptions: the Node SDK throws an Error and the Ruby SDK raises BunnyApp::ResponseError, both with the error messages.

In the case of an error the response will contain an `errors` section that provides detail on what went wrong.

For example, In this case we provided an invalid product plan code.

{
    "data": {
        "subscriptionCreate": null
    },
    "errors": [
        {
            "message": "Product plan not found",
            "locations": [
                {
                    "line": 2,
                    "column": 5
                }
            ],
            "path": [
                "subscriptionCreate"
            ]
        }
    ]
}

What happens next?Link to What happens next? section

After a success request to create a subscription the following objects will be created in your Bunny account.

Account - The company or organization that has signed up for your SaaS application
- Contact
- Deal - A new deal representing the trial or new business opportunity.
  - Quote
- Subscription
  - Tenant - If provisoning is enabled on your platform.

If you created a trial subscription then get to work on making the customer experience awesome and converting that trial to a paid subscription.