Create entitlements

What is the /set endpoint

The /set endpoint is used to create or update entitlements for a user. It serves as the primary way to define what features or usage limits a user is entitled to.

If an entitlement already exists for the given user and feature, the set call will overwrite it with the new value—making it ideal not just for initial assignment but also for updating entitlements when user plans change.

Additionally, this endpoint can be used to manually reset a consumable entitlement's usage back to 0, such as when granting a usage refresh.

How to use it

To use the /set endpoint, you would typically send a POST request to the API with the user and feature identifiers you wish to assign. Here's a conceptual example using JavaScript:

import axios from "axios";
 
const gater = axios.create({
  baseURL: "https://api.gater.dev",
  headers: { "X-Api-Key": process.env.GATER_SECRET },
});
 
const response = await gater.post("/set", {
  user: "user_123",
  macro: "premium_plan", //notice how we can just attach a user to a macro we created
});
 
console.log(response.data);

This lets you programmatically define what each user can access or consume, making it easier to implement usage-based pricing, feature gating, or custom plans.

The most straightforward way to create entitlements for users is by using a pre-set macro as we have shown in the example code above, but you could also set a user's entitlement by attaching specific features to the user:

import axios from "axios";
 
const gater = axios.create({
  baseURL: "https://api.gater.dev",
  headers: { "X-Api-Key": process.env.GATER_SECRET },
});
 
const response = await gater.post("/set", {
  user: "user_123",
  feature: "app_tokens", //instead of using a macro here we're attaching a new feature instead
  quota: 1000000, //quota is set if the feature has a limit such as credit limit, seat limit, etc.
  reset: "month", //a feature's quota can be reset daily, weekly, monthly, annually, or never!
});
 
console.log(response.data);

Note that the reset property indicates that this entitlement's usage will reset exactly one month after this entitlement was created.