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.

Prerequisites

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.

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 request

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.

Mutation

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

Attributes

{
  "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 parameters

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.

Handling errors

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.

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?

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.

PreviousInstall the SDK NextTrack usage for billing

Last updated 1 month ago

Was this helpful?

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

{ "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", });

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