---
description: >-
  Learn how to track trials and create subscriptions for users of your SaaS
  application
---

# Create a subscription

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:

1. **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.
2. **Active** - this is a paid subscription. Invoices will be generated and payments will be collected.

{% hint style="warning" %}
You should make the request to create a new subscription in Bunny immediately after a new sign-up happens on your SaaS application.
{% endhint %}

### Prerequisites

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

1. 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.
2. [Create an API client & install a Bunny SDK](../../using-the-graphql-api/api#create-an-api-client)

{% hint style="warning" %}
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.
{% endhint %}

### 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](broken-reference) 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._

{% tabs %}
{% tab title="GraphQL" %}
#### Mutation

```graphql
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

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

{% tab title="Ruby" %}
```ruby
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"
  }
)
```
{% endtab %}

{% tab title="Node.js" %}
```javascript
const res = await bunny.subscriptionCreate("priceListCode", {
  trial: true,
  accountName: "accountName",
  firstName: "firstName",
  lastName: "lastName",
  email: "email@example.com",
  tenantCode: "remoteId",
});
```
{% endtab %}
{% endtabs %}

{% hint style="info" %}
We recommend submitting the **tenantCode** with your request so that Bunny is aware which tenant in your SaaS application the subscription belongs to.&#x20;

Bunny will send your **tenantCode** back with subscription change webhooks so that you know which of your tenants to update with any changes.&#x20;
{% endhint %}

#### 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.                                                                         |

{% hint style="warning" %}
For more detail on all of the parameters that can be set when creating a trial see the [subscriptionAttributes](../api-reference/types/subscriptionattributes) object.
{% endhint %}

### 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._

```json
{
    "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.&#x20;
