Charging Credits

import { defineApplication } from 'twenty-sdk/define';

export default defineApplication({
  // ...identity, variables...
  billing: {
    description: '$20/month + $0.02 per minute recorded',
    recurring: {
      platformFee: {
        period: 'MONTH',
        amountMicroCredits: 20_000_000,
        label: 'Platform fee',
      },
    },
    operations: {
      recordMeeting: {
        operationType: 'CALL_RECORDING',
        label: 'Meeting recording',
      },
    },
  },
});

• recurring — flat and per-member fees the platform raises for you, once per billing period.
• operations — what you charge for as you use it, from a logic function.
• description — one friendly line shown to buyers on your marketplace listing.

​

Recurring charges

billing: {
  recurring: {
    platformFee: {
      period: 'MONTH',
      amountMicroCredits: 20_000_000,
      label: 'Platform fee',
    },
    seat: {
      period: 'MONTH',
      amountMicroCredits: 5_000_000,
      per: 'WORKSPACE_MEMBER',
      label: 'Per member',
    },
  },
},

• Once per workspace billing period, on the workspace’s own period boundary, not on the first of the month.
• Not prorated. An app installed mid-period is charged the full amount for that period; uninstalling stops the next period, it does not refund the current one.
• Per-member charges count all workspace members at the moment the charge is raised, so a workspace that grows mid-period pays the higher count from the next period.
• Only on monthly subscriptions. A workspace on a yearly plan is not charged a MONTH fee, rather than being charged once for the whole year.
• Bounded. A declared rate above $100, or a per-member charge whose rate multiplied by the member count would exceed$1,000 for the period, is refused and not raised. The platform raises these itself, so it will not write a debit it cannot justify.

​

Billable operations

billing: {
  operations: {
    recordMeeting: {
      operationType: 'CALL_RECORDING',
      label: 'Meeting recording',
    },
    summarizeMeeting: {
      operationType: 'AI_CHAT_TOKEN',
      label: 'Meeting summary',
    },
  },
},

​

Charging

import { chargeCredits } from 'twenty-sdk/billing';

await chargeCredits({
  operation: 'recordMeeting',
  creditsUsedMicro: 250_000,
  quantity: 12,
});

• Declaring operations is what lets Usage split your app’s spend by what it charged for. An app that declares nothing is still reported, as a single slice under its display name.
• Charging an operation your manifest does not declare is rejected. Add it to billing.operations and sync.
• Several operations may share one operationType. Two enrichment operations both metered as CODE_EXECUTION still show as two labelled slices.
• Without operation, name the billing category directly with operationType, optionally with a free-form resourceContext. The two forms are mutually exclusive: operation carries the label, operationType does not.
• Charging never fails your function. A billing error is logged and swallowed, and the call no-ops outside the logic function runtime so local runs and tests do not crash.

​

Checking before you spend

import { getCreditAvailability } from 'twenty-sdk/billing';

const { hasAvailableCredits } = await getCreditAvailability();

if (!hasAvailableCredits) {
  return;
}

• It answers whether the workspace may spend, not how much it has left. Your app does not see the balance or the plan.
• It fails open. If the check times out or the server is unreachable it reports credits available, so an infrastructure hiccup does not stop your app. Treat it as a hint worth honouring, not as an authorization decision.
• It is a snapshot. Credits can run out between the check and the work.
• The gate is not applied uniformly. Workflow runs are not credit-gated, and neither is every outbound email path, so a false here tells you the workspace is out of credits rather than predicting exactly which calls will fail.

​

Telling people what it costs

billing: {
  description: '$0.02 per minute recorded, billed to your Twenty credits',
},

​

Attribution

await chargeCredits({
  operation: 'recordMeeting',
  creditsUsedMicro: 250_000,
  quantity: 12,
  userWorkspaceId: ownerUserWorkspaceId,
});