Using the API

Get an access token and send GraphQL queries and mutations to Bunny's API, with JavaScript, Ruby and curl examples for subscriptions and accounts.

Bunny’s GraphQL API lets you create trial subscriptions, track feature usage, update accounts, contacts, quotes and almost all other objects that you can see in the web user interface.

To interact with the Bunny API you will need to follow these steps:

1. Get an access token
2. Send a GraphQL request to query or modify data

Get an access tokenLink to Get an access token section

All requests to Bunny require an Access Token to be sent in an Authorization header. To get started quickly you can generate an access token directly in the Bunny admin portal or alternatively you can obtain the client credentials for an API client and generate an access token using an SDK.

• In Bunny, go to Settings > Developers > API clients
• Select the Default API client
• Click the Generate Access Token button and copy the token

Send a GraphQL requestLink to Send a GraphQL request section

The Bunny SDKs offers convenience methods for some of the common GraphQL requests as well as a raw query method so that you can build your own queries. Learn how to use the Bunny API reference to build your own custom queries.

For example, if a new trial has signed up in your SaaS application then you will track this in Bunny using the convenient subscription creation methods.

const subscription = await bunny.subscriptionCreate('free', {
  trial: true,
  accountName: 'Acme Yachts',
  firstName: 'Jill',
  lastName: 'McGill',
  email: 'jill@example.com',
  tenantCode: '123456'
})

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

curl --location 'https://SUBDOMAIN.bunny.com/graphql' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ACCESS_TOKEN' \
--data-raw '{"query":"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 }}","variables":{"attributes":{"account":{"billingContact":{"firstName":"Bruce","lastName":"Wayne","email":"bruce@example.com"},"name":"Superdesk"},"trial":true,"priceListCode":"free","tenant":{"code":"tenant-123"}}}}'

Alternately you may want to get back a list of Accounts including Contacts. In this case you can build and send your own query using the query method.

const query = `query accounts ($filter: String, $first: Int) {
  accounts (filter: $filter, first: $first) {
    nodes {
      id
      name
      contacts {
        firstName
        lastName
        email
      }
    }
  }
}`;

const variables = {
  filter: "",
  first: 10,
};

const response = await bunny.query(query, variables);

query = <<~'GRAPHQL'
  query accounts ($filter: String, $first: Int) {
    accounts (filter: $filter, first: $first) {
      nodes {
        id
        name
        contacts {
          firstName
          lastName
          email
        }
      }
    }
  }
GRAPHQL

variables = {
  filter: '',
  first: 10
}

response = BunnyApp.query(query, variables)

curl --location 'https://SUBDOMAIN.bunny.com/graphql' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ACCESS_TOKEN' \
--data '{"query":"query accounts ($filter: String, $first: Int) { accounts (filter: $filter, first: $first) { totalCount pageInfo { startCursor endCursor hasNextPage hasPreviousPage } nodes { id  code name } }}","variables":{"filter":"","first":10}}'

GraphQL is pretty simple in the sense that you’re always just sending a HTTP POST request with a specially formatted body. Within that request body you will be asking GraphQL to perform either a query or a mutation.

• query - Use this to retrieve data.
• mutation - Use this to create or modify data.

Custom fieldsLink to Custom fields section

Any custom fields you have created will be prefixed with custom, for example customProcurementPortal.