> ## Documentation Index
> Fetch the complete documentation index at: https://docs.macropay.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Benefit

> Deliver a private note or build your own entitlement logic for paying customers

When none of the built-in benefits fit, the **Custom** benefit is your escape hatch. It does two jobs: it shows a private note that only paying customers can read, and it acts as a generic entitlement flag you can wire into your own integration logic.

Because Macropay is the merchant of record, the purchase that unlocks this benefit is already tax-compliant and dispute-managed on your behalf — you just decide what the customer receives.

## What it's good for

<CardGroup cols={2}>
  <Card title="Private notes" icon="lock">
    Reveal a secret link, a support address, or onboarding instructions only after payment clears.
  </Card>

  <Card title="Custom entitlements" icon="puzzle-piece">
    Use it as a named flag your backend reads to grant bespoke access that the standard benefits don't cover.
  </Card>
</CardGroup>

## Private note

A custom benefit can carry a note that stays hidden until a customer has an active grant. Anything you'd only want a paying customer to see works well here:

* A private scheduling link (for example, a [Cal.com](http://Cal.com) booking URL)
* A dedicated support email or priority inbox
* A coupon code, invite, or early-access instruction
* A short welcome message specific to the product they bought

The note renders for the customer in their [customer portal](/features/customer-portal) once the grant is active, and disappears if the entitlement lapses.

## Custom entitlements for integrations

Each custom benefit you create is distinct, so you can attach several to different products and tell them apart in code. When a customer is granted (or loses) a benefit, Macropay emits webhook events you can act on.

```ts theme={null}
// Listen for benefit grants and unlock your own feature flags.
// See /api-reference/webhooks/benefit_grant.created for the payload shape.
app.post("/webhooks/macropay", (req, res) => {
  const event = req.body;

  if (event.type === "benefit_grant.created") {
    const { customer_id, benefit_id } = event.data;
    // Match against the custom benefit you configured, then
    // grant whatever bespoke access this product implies.
    grantBespokeAccess(customer_id, benefit_id);
  }

  if (event.type === "benefit_grant.revoked") {
    const { customer_id, benefit_id } = event.data;
    revokeBespokeAccess(customer_id, benefit_id);
  }

  res.sendStatus(200);
});
```

<Tip>
  Pair this with [usage-based billing](/features/usage-based-billing/introduction) when the bespoke access is metered — for example, an AI agent whose access tier and per-event cost are both governed by the same purchase.
</Tip>

## Steps

<Steps>
  <Step title="Create the benefit">
    In the dashboard, add a new benefit and choose **Custom**. Give it a clear internal name so you can recognize it in webhook payloads.
  </Step>

  <Step title="Write the customer note">
    Add the private message — a link, support address, or instructions — that should appear only after purchase.
  </Step>

  <Step title="Attach it to a product">
    Add the benefit to any [product](/features/products) (one-time or subscription). Customers receive it automatically on a successful order.
  </Step>

  <Step title="React in your backend (optional)">
    Subscribe to `benefit_grant.created` and `benefit_grant.revoked` webhooks to drive your own custom integration logic.
  </Step>
</Steps>

<Note>
  Need a more specialized benefit instead? Macropay also ships [license keys](/features/benefits/license-keys), [file downloads](/features/benefits/file-downloads), [Discord access](/features/benefits/discord-access), [GitHub repository access](/features/benefits/github-access), and [prepaid credits](/features/benefits/credits).
</Note>