⚠️ prerequisite: You have a Firmhouse project set up

In this guide, we will explain how to use our GraphQL API to create a new subscription for your project. The process consists of generating an access token to authenticate with and then calling our GraphQL API with the required fields to actually create the subscription.

Generate a Subscription Creation project access token

The first thing you will need to do is generate a token to authenticate with our API. The way to do this, is to go to the Firmhouse Portal, select your project and then click on "Integrations". 

You will now see an overview of your "Access Tokens", click on "Generate new token" to create a new one:

You will then get prompted to select an "access type", please make sure to select "Create subscription" here:

Click on "Create project access token" to continue. After this, you should see a screen that looks similar to this:

Click on "Copy" to copy the token to your clipboard for later use when connecting with our API.

Creating a subscription through our GraphQL API

When connecting to our API, make sure to pass in your access token as a HTTP header with the header name: X-PROJECT-ACCESS-TOKEN  .

The endpoint you should use to send your requests to is https://portal.firmhouse.com/graphql .

👍Tip: use GraphiQL app to explore our full documentation and find all capabilities of our API.

Example request

mutation($name: String!, $address: String!, $houseNumber: String!, $zipcode: String!, $city: String!, $country: String!, $phoneNumber: String!, $email: String!, $termsAccepted: Boolean!, $returnUrl: String!, $paymentPageUrl: String!, $planId: ID){
    input: {
      name: $name,
      address: $address,
      houseNumber: $houseNumber,
      zipcode: $zipcode,
      city: $city,
      country: $country,
      phoneNumber: $phoneNumber,
      email: $email,
      termsAccepted: $termsAccepted,
      returnUrl: $returnUrl,
      paymentPageUrl: $paymentPageUrl,
      planId: $planId,
  ) {
    errors {

This example request will sign up the customer to a predefined plan. You will need to pass in the plan_id which you can find in the portal. You can find this in the plans overview in the portal, which should look similar to this:

The other (required) fields that you need to pass in are the following:

name: The full name of the customer
address: The address of the customer
zipcode: The zip code of the customer
city: The city of the customer
country: The country code of the customer (ISO 3166)
phoneNumber: The phone number of the customer
email: The email address of the customer
termsAccepted: Either "true" or "false"
houseNumber: The house number of the customer
returnUrl: The URL the user gets redirected to when payment has been successful
paymentPageUrl: The URL where the user can sign up for a new subscription
planId: The identifier of the plan where the user should be signed up to

Example query variables:

  "name": "John Doe",
  "address": "Mainstreet",
  "houseNumber": "1",
  "zipcode": "1234AA",
  "city": "Rotterdam",
  "country": "NL",
  "phoneNumber": "+31612345678",
  "email": "john@example.com",
  "termsAccepted": true,
  "returnUrl": "http://example.com/thank-you",
  "paymentPageUrl": "http://example.com/sign-up",
  "planId": 194

Using the API response to redirect the user to the payment page

A successful response from our API could look something like this:

  "data": {
    "createSubscription": {
      "paymentUrl": "https://www.mollie.com/xxx",
      "subscriptionToken": "RNb93gtqs2y2wUuVqWPaTMt8"
      "errors": []

The subscriptionToken is our internal token that can later be used to retrieve the subscription. The paymentUrl is the URL on which your customer can fulfil the initial payment. You should redirect your user to this URL after a successful response, when the payment has been completed, we will return the user to your website on the URL you provide on return_url .

🙋‍♂️Got stuck? We're here to help! 

This guide should help you to get started, but there is more to it if you want to make use of our more advanced features. So if you get stuck, please don't hesitate to reach out to us so we can help you moving forward.

Did this answer your question?