The /entitled endpoint allows you to check if a customer has access to a specific feature. This endpoint is versatile and can be used for different types of features within your product.

​
Checking Boolean Features

For simple on/off features, use the endpoint to determine if a customer has access.

You can do this on the client side on page load, using a useEffect function:

async function checkAccess(customerId, featureId) {
  const response = await fetch("https://api.useautumn.com/v1/entitled", {
    method: "POST",
    headers: {
      // If using from the client side, use your Publishable key
      Authorization: `Bearer ${AUTUMN_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      customer_id: customerId,
      feature_id: featureId,
    }),
  });

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

The response will include an allowed property indicating whether the customer has access to the feature.

You can do this from the client side, eg when a user clicks a button to use a feature, or from the server side when running that feature.

Response
{
  "allowed": true,
  "balances": [
    {
      "feature_id": "premium_dashboard",
      "balance": null,
      "required": null
    }
  ]
}

​
Checking Metered Features

For features with usage limits, the response includes both access permission and current usage limits. You can

Response
{
  "allowed": true,
  "balances": [
    {
      "feature_id": "api_calls",
      "balance": 100,
      "required": 1
    }
  ]
}

​
Recording Usage with Event Data

You can check entitlement and record usage in a single API call using the event_data parameter

We recommend doing these as separate steps in your application logic, to only record usage if the event is successful.

const response = await fetch("https://api.useautumn.com/v1/entitled", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${AUTUMN_SECRET_KEY}`, // Must use Secret key for recording usage
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    customer_id: customerId,
    feature_id: featureId,
    event_data: {
      event_name: featureId, // Only if the featureID is the same as the event name
    },
  }),
});

​
Checking Required Quantity in Advance

If you know the quantity a user will consume in advance, you can specify it with the required_quantity parameter. This means you can prevent a user from starting a process that would consume more than their entitlement.

async function checkWithQuantity(customerId, featureId, quantity) {
  const response = await fetch("https://api.useautumn.com/v1/entitled", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${AUTUMN_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      customer_id: customerId,
      feature_id: featureId,
      required_quantity: quantity,
    }),
  });

  return await response.json();
}

// Example: Check if user can send 5 emails
const canSendFiveEmails = await checkWithQuantity("user-123", "email_sends", 5);

​
Creating New Customers

If the customer_id you provide doesn’t exist yet, Autumn will automatically create a new customer:

const response = await fetch("https://api.useautumn.com/v1/entitled", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${AUTUMN_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    customer_id: "new-user-456",
    feature_id: "basic_access",
    customer_data: {
      email: "user@example.com",
      name: "New User",
    },
  }),
});

The customer_data object lets you provide additional properties for the new customer.