# 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](/developer/using-the-graphql-api/api.md#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](https://github.com/bunnyapp/docs-developer/blob/main/bunny-sdk/broken-reference/README.md) 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.

Bunny will send your **tenantCode** back with subscription change webhooks so that you know which of your tenants to update with any changes.
{% 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](/developer/api-reference/types/subscriptionattributes.md) 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bunny.com/developer/bunny-sdk/create-a-subscription.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.