Flat rate billing

If a plan uses the flat rate model, you specify a price and a billing cycle for the plan, and the customer pays that price each billing cycle. Flat rate models only allow for one grantee to use the subscription, if you need more you'll need a per-seat plan instead.

Taking payments

To receive payment for your subscription, you'll need to create a Stripe checkout. Here, a customer can add their bank card details and upon successful checkout the subscription will be created. The next payment will occur based on the plan's interval length.

JS SDK
Node SDK
Fetch
cURL

import { getCheckoutLink } from '@salable/js'

const { checkoutUrl } = await getCheckoutLink({
  apiKey: 'your-salable-api-key',
  planUuid: 'your-salable-plans-uuid',
  successUrl: 'https://your.app/payment-success'
  cancelUrl: 'https://your.app/payment-cancelled',
  granteeId: 'your-grantees-id',
  owner: 'your-grantees-organisation-id',
});

// Don't forget to: npm install @salable/node-sdk
import { Salable } from '@salable/node-sdk';

const salable = new Salable('your-salable-api-key', 'v2');

const { checkoutUrl } = await salable.plans.getCheckoutLink('your-plan-uuid', {
  successUrl: 'https://example.com/success',
  cancelUrl: 'https://your.app/cancel',
  granteeId: 'your-grantees-id',
  owner: 'your-grantees-organisation-id',
});

const params = new URLSearchParams();
params.append("granteeId", "id-of-grantee");
params.append("owner", "id-of-the-grantees-organisation");
params.append("successUrl", "https://example.com/success");
params.append("cancelUrl", "https://example.com/cancel");

const response = await fetch(`https://api.salable.app/plans/your-plan-uuid/checkoutlink?${params}`, {
  headers: {
    "x-api-key": "your-salable-api-key",
    version: "v2"
  }
})
const checkout = await response.json();

curl
  -XGET
  -H 'x-api-key: your-salable-api-key'
  -H 'version: v2'
  'https://api.salable.app/plans/your-plan-uuid/checkoutlink?successUrl=https%3A%2F%2Fyour.app%2Fsuccess&cancelUrl=https%3A%2F%2Fyour.app%2Fcancel&granteeId=your-grantees-id&owner=your-grantees-organisation-id'

Option	Description	Required
`successUrl`	The url to redirect a customer after a successful checkout.	✅
`cancelUrl`	The url to redirect a customer if they cancel the checkout.	✅
`granteeId`	The ID of the grantee which will be assigned to the first seat of the subscription, for example the user ID or a board ID. If the subscription is per-seat all additional seats created will be unassigned.	✅
`owner`	The ID of the customer's organisation.	✅
`currency`	The shortname of the currency to be used in the checkout. Default - plan's product default currency.	❌

Create subscription

Creates a subscription without a payment.

tip

If you'd like to receive payment for a subscription, create a checkout link.

Node SDK
Fetch
cURL

import { Salable } from '@salable/node-sdk';
const salable = new Salable('your-salable-api-key', 'v2');

const subscription = await salable.subscriptions.create({
  planUuid: 'your-plan-uuid',
  owner: 'orgId_1234',
  granteeId: 'userId_1',
});

const response = await fetch("https://api.salable.app/subscriptions", {
  method: "POST",
  headers: {
    "x-api-key": "your-salable-api-key",
    version: "v2"
  },
  body: JSON.stringify({
    planUuid: "a-plan-uuid",
    granteeId: "id-of-grantee",
    owner: "id-of-the-grantees-organisation"
  });
})
const subscription = await response.json();

curl
  -XPOST
  -H 'x-api-key: your-salable-api-key'
  -H 'version: v2'
  -d '{ "planUuid": "a-plan-uuid", "granteeId": "id-of-grantee", "owner": "id-of-the-grantees-organisation" }'
  'https://api.salable.app/subscriptions'

License check

Check whether a grantee can perform an action in your system. Feature values, capabilities, and plan names that belong to your user are checkable. If your grantee has multiple subscriptions, everything they have access to will be returned in the response.

JS SDK
Node SDK
Fetch
cURL

import { getGrantee } from '@salable/js';

const { hasCapability } = await getGrantee({
  apiKey: 'your-salable-api-key',
  productUuid: 'your-products-uuid',
  granteeId: 'your-grantees-id',
});

// Check for a capability
const isUserLicensedToPerformAction = hasCapability('acme-inc-whitelabelling');
// or a feature
const isUserLicensedToPerformAction = hasCapability('csv-export');
// or a plan
const isUserLicensedToPerformAction = hasCapability('pro');

import { Salable } from '@salable/node-sdk';

const salable = new Salable('your-salable-api-key', 'v2');

const { capabilities } = await salable.licenses.check({
  productUuid: 'your-product-uuid',
  granteeIds: ['your-grantees-id'],
});
// Check for a capability
const isGranteeLicensedToPerformAction = capabilities.find((c) => c.capability === 'your-capability-name');
// or a feature
const isGranteeLicensedToPerformAction = capabilities.find((c) => c.capability === 'feature-name');
// or a plan
const isGranteeLicensedToPerformAction = capabilities.find((c) => c.capability === 'plan-name');

const params = new URLSearchParams();
params.append("granteeIds", "id-of-grantee");
params.append("productUuid", "your-product-uuid");

const response = await fetch(`https://api.salable.app/licenses/check?${params}`, {
  headers: {
    "x-api-key": "your-salable-api-key",
    version: "v2"
  },
})
const check = response.status === 204 ? null : await response.json();

curl
  -XGET
  -H 'x-api-key: your_salable_api_key'
  -H 'version: v2'
  'https://api.salable.app/licenses/check?productUuid=your_product_uuid&granteeIds=your-grantees-id&grace=3'

Update seat

Change who can access the subscription.

Node SDK
Fetch
cURL

import { Salable } from '@salable/node-sdk';

const salable = new Salable('your-salable-api-key', 'v2');
await salable.subscriptions.manageSeats('your-subscription-uuid', [
  {
    type: "replace",
    granteeId: "current-grantee-id",
    newGranteeId: "new-grantee-id"
  }
]);

await fetch("https://api.salable.app/subscriptions/your-subscription-uuid/manage-seats", {
  method: "PUT",
  headers: {
    "x-api-key": "your-salable-api-key",
    version: "v2"
  },
  body: JSON.stringify([
    {
      type: "replace",
      granteeId: "current-grantee-id",
      newGranteeId: "new-grantee-id"
    }
  ]);
})

curl
  -XPUT
  -H 'x-api-key: your-salable-api-key'
  -H 'version: v2'
  -d '[{ "type": "replace", "granteeId": "current-grantee-id", "newGranteeId": "new-grantee-id" }]'
  'https://api.salable.app/subscriptions/your-subscription-uuid/seats'

Upgrade and downgrade

Useful if you need to update the plan your grantee is on. For example, if they have upgraded or downgraded you would want to update the subscription to reflect this.

Node SDK
Fetch
cURL

import { Salable } from '@salable/node-sdk';

const salable = new Salable('your-salable-api-key', 'v2');
const changeSubscriptionPlan = await salable.subscriptions.changePlan(
  'your-subscription-uuid',
  {
    planUuid: 'the-new-plan-uuid',
    proration: 'create_prorations', // optional. see table below for more options
  }
);

await fetch("https://api.salable.app/subscriptions/your-subscription-uuid/change-plan", {
  method: "PUT",
  headers: {
    "x-api-key": "your-salable-api-key",
    version: "v2"
  },
  body: JSON.stringify({
    planUuid: "the-new-plan-uuid",
  });
})

curl
  -XPUT
  -H 'x-api-key: your-salable-api-key'
  -H 'version: v2'
  -d '{ "planUuid": "the-new-plan-uuid" }'
  'https://api.salable.app/subscriptions/{subscriptionUuid}/change-plan'

info

Proration options are only applicable on subscriptions that have taken a payment.

Value	Description
create_prorations	Keeps the subscription's billing cycle start/end date and refunds for unused time on the previous plan
always_invoice	Changes the billing cycle start date to the current date and immediately invoices
none	Disables proration behaviour

Cancel subscription

You can cancel a subscription with its associated subscriptionUuid.

Node SDK
Fetch
cURL

import { Salable } from '@salable/node-sdk';

const salable = new Salable('your-salable-api-key', 'v2');
await salable.subscriptions.cancel('your-subscription-uuid', { when: 'end' });

const params = new URLSearchParams();
params.append("when", "now");

await fetch(`https://api.salable.app/subscriptions/your-subscription-uuid/cancel?${params}`, {
  method: "PUT",
})

curl
  -XPUT
  -H 'x-api-key: your-salable-api-key'
  -H 'version: v2'
  'https://api.salable.app/subscriptions/your-subscription-uuid/cancel?when=end'

info

The when query parameter represents when you want the subscription to cancel.

When	Description
`now`	Immediately cancels the Subscription. If the Subscription is paid, the customer will be immediately invoiced.
`end`	Cancels the Subscription at the end of its cycle. To undo this you can reactivate the subscription. If the Subscription is paid, the customer will be invoiced at the end of the cycle.

Demos

Flat rate billing in Next.js
Miro App with flat rate billing

Flat rate billing

Taking payments​

Create subscription​

License check​

Update seat​

Upgrade and downgrade​

Cancel subscription​

Demos​