The simplest way to check entitlements is by using Autumn’s /entitled endpoint, to check if a user has access to a specific feature whenever it’s requested.

However, you may also use the /customer endpoint, which will return all of a user’s active entitlements at once. This is useful if you want to:

  • Display a list of entitlements or usage balances to a user
  • Minimize the number of API calls you make
  • Sync up Autumn with your internal access control system

​
Overview

To sync up your application with Autumn, here are the steps you can follow:

1

Fetch a customer's entitlements on login

Call the /customer endpoint to get all active entitlements

2

Sync entitlements with application

Update your application logic to use the entitlements you fetched

3

Send usage events to Autumn

Track usage for metered features by sending events

4

Refresh customer entitlements

Update entitlements after recording new usage

​
Fetching Customer Entitlements from Autumn

When a user logs in, retrieve their current entitlements using the /customer endpoint. You should use the customer_id of the user that you set when you created the customer (typically your internal user ID).

Javascript
async function getAutumnEntitlements(customerId) {
  const response = await fetch(
    `https://api.useautumn.com/v1/customers/${customer_id}`,
    {
      method: "GET",
      headers: {
        // You can use your Publishable or Secret key here
        Authorization: `Bearer ${process.env.AUTUMN_API_KEY}`,
        "Content-Type": "application/json",
      },
    }
  );

  const data = await response.json();
  return data.entitlements;
}

The response will include an array of entitlements:

Response
{
  "entitlements": [
    //boolean feature
    {
      "feature_id": "premium_dashboard"
    },
    //metered feature
    {
      "feature_id": "api_calls",
      "interval": "monthly",
      "balance": 850,
      "unlimited": false,
      "used": 150
    }
  ]
}

​
Syncing Autumn Entitlements with your application

When a user logs in, sync their entitlements to ensure your application has the most up-to-date information. You’ll need to create a mapping function to do this.

Javascript
async function syncEntitlementsOnLogin(userId) {
  // Fetch entitlements from Autumn (see above)
  const autumnEntitlements = await getAutumnEntitlements(userId);

  const internalEntitlements = await mapAutumnEntitlements(
    userId,
    autumnEntitlements
  );

  return internalEntitlements;
}

async function mapAutumnEntitlements(userId, autumnEntitlements) {
  const entitlementsMap = {};

  // Map Autumn entitlements into the format you use in your applicaiton
  autumnEntitlements.forEach((entitlement) => {
    entitlementsMap[entitlement.feature_id] = {
      feature_id: entitlement.feature_id,
      interval: entitlement.interval,
      balance: entitlement.balance,
      used: entitlement.used,
      unlimited: entitlement.unlimited,
    };
  });

  // Optionally, store the mapped entitlements in your database
  await db.users.updateOne(
    { id: userId },
    { $set: { entitlements: entitlementsMap } }
  );

  return entitlementsMap;
}

​
Sending Usage Events for Metered Features

For metered features, you’ll need to send usage events to Autumn whenever a user consumes a unit of that feature:

Javascript
async function sendUsageEvent(userId, featureId) {
  const response = await fetch("https://api.useautumn.com/v1/events", {
    method: "POST",
    headers: {
      // Must use Secret key for events
      Authorization: `Bearer ${process.env.AUTUMN_SECRET_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      customer_id: userId,
      event_name: featureId, // Assuming your feature_id matches your event_name
    }),
  });
}

​
Refreshing Entitlements After Usage

After sending a usage event, refresh the customer’s entitlements to reflect the updated balance. Here’s the full function covering the steps above:

Javascript
async function trackUsageAndRefreshEntitlements(userId, featureId) {
  // 1. Send the usage event
  await sendUsageEvent(userId, featureId);

  // 2. Fetch the updated entitlements
  const updatedEntitlements = await getAutumnEntitlements(userId);

  // Map Autumn entitlements to local entitlements
  await mapAutumnEntitlements(userId, updatedEntitlements);

  // Return the updated feature entitlement (eg to get new balance)
  const featureEntitlement = updatedEntitlements.find(
    (e) => e.feature_id === featureId
  );
  return featureEntitlement;
}