Capabilities¶
Capabilities let a Resource do more than store records.
They turn a Resource into something Diagonal can treat in a special way: users who can log in, people who can receive notifications, invoice-like records, payment customers, calendar events, and more.
Capabilities are configured from the Capabilities area of a Resource. Each capability has settings that usually point to Fields on that same Resource.
Identity and Communication¶
Use these capabilities when records represent people or destinations your app needs to recognize, authenticate, or contact.
Authenticatable¶
Authenticatable Resources represent people who can log in.
Use this for user-type Resources like Customers, Students, Employees, Vendors, Members, or Partners. Once enabled, records in that Resource can participate in authentication flows.
| Setting | Field type | Required | Purpose |
|---|---|---|---|
| Email field | Yes | Identifies the user during login. | |
| Password field | Password | Yes | Stores the user's password credential. |
| Login redirect | Workflow | No | Controls where users go after login. |
Multiple user types
A workspace can have more than one authenticatable Resource. For example, a school portal might have Students and Teachers as separate Resources with different pages, permissions, and policies.
Notifiable¶
Notifiable Resources can receive messages.
Use this when records represent people or destinations that should receive email, SMS, or other notifications from workflows.
| Setting | Field type | Required | Purpose |
|---|---|---|---|
| Email field | Yes | Email address used for notifications. | |
| Phone field | Phone or text | No | Phone number used for SMS or phone-based notifications. |
Good examples include Customers receiving invoice reminders, Employees receiving task updates, or Students receiving course announcements.
Payments and Commerce¶
Use these capabilities together when your app needs invoices, orders, line items, payment records, refunds, or customer payment profiles.
Most payment setups use several Resources together:
| Resource | Capability | Role in the payment model |
|---|---|---|
| Customer or Account | Payer | The party responsible for paying. |
| Invoice or Order | Payable | The thing money is owed for. |
| Invoice Line Item or Order Item | Itemizable | A billable item connected to the payable. |
| Discount, Fee, or Adjustment | Payable Adjustment | A credit or charge connected to the payable. |
| Payment or Charge | Payment | A transaction against the payable. |
| Refund | Refund | Money returned against a payment. |
Payer¶
Payer Resources represent payment customers.
Use this when a Resource should act as the party paying for something. Diagonal can manage payment-customer identity for these records when the payment integration is available.
| Setting | Field type | Required | Purpose |
|---|---|---|---|
| Email field | No | Email used for payment customer records. | |
| Name field | Text | No | Display name used for payment customer records. |
Common Payer Resources include Customers, Accounts, Organizations, or Members.
Payable¶
Payable Resources behave like invoices or bills.
Use this when records need to track totals, amounts paid, outstanding balances, currency, and payment status.
| Setting | Field type | Required | Purpose |
|---|---|---|---|
| Status field | Text | Yes | Tracks states like draft, open, paid, partially paid, overpaid, or void. |
| Amount total field | Money | Yes | Total amount due. |
| Amount paid field | Money | Yes | Amount collected so far. |
| Currency field | Text | Yes | Currency for the payable record. |
| Amount subtotal field | Money | No | Total before payable adjustments are applied. |
| Amount adjustment field | Money | No | Net adjustment amount after credits and charges. |
| Amount credit adjustment field | Money | No | Total active credit adjustments, such as discounts. |
| Amount charge adjustment field | Money | No | Total active charge adjustments, such as fees. |
| Amount outstanding field | Money | No | Remaining balance. |
| Amount overpaid field | Money | No | Amount paid above the total. |
| Paid at field | Datetime | No | Timestamp for when the payable became paid. |
| Payer field | Relation | No | Links the payable to the payer responsible for it. |
Payable records often work with Itemizable, Payable Adjustment, Payment, and Refund Resources. For example, an Invoice can have many Invoice Line Items, many Discounts or Fees, many Payments, and many Refunds through the payment records.
Itemizable¶
Itemizable Resources represent line items attached to a Payable Resource.
Use this for invoice line items, order items, subscription items, or billable services.
| Setting | Field type | Required | Purpose |
|---|---|---|---|
| Parent relation field | Relation | Yes | Connects the line item to its parent payable record. |
| Description field | Text | Yes | Describes the item or service. |
| Unit price field | Money | Yes | Price for one unit. |
| Total field | Money | Yes | Total for the line item. |
| Quantity field | Number | No | Quantity multiplied by unit price. |
| Price field | Relation | No | Links the line item to the Price it came from. Must point to a Resource that has the Price capability enabled. |
When quantity is available, Diagonal can calculate line item totals and keep the parent Payable record in sync.
When a line item references a Price and its unit price or description are left blank, Diagonal snapshots them from the Price on save: the unit price is copied from the Price's amount, and the description from the name of the product the Price belongs to. The line item only needs the Price relation — the product is reached through it. Snapshotting happens at save time, so editing the Price later never changes line items that were already created.
Payable Adjustment¶
Payable Adjustment Resources store credits and charges against a Payable Resource.
Use this for invoice discounts, coupons, write-offs, processing fees, late fees, surcharges, or other invoice-level adjustments. Each adjustment belongs to a payable record, and Diagonal recalculates the payable total when active adjustments are created, updated, archived, or restored.
| Setting | Field type | Required | Purpose |
|---|---|---|---|
| Payable field | Relation | Yes | Links the adjustment to the payable record being adjusted. |
| Status field | Select | Yes | Adjustment state. Supported values are active and void. |
| Direction field | Select | Yes | Whether the adjustment is a credit that reduces the total or a charge that increases the total. |
| Calculation type field | Select | Yes | How the amount is calculated. Supported values are fixed_amount and percentage. |
| Amount field | Money | Yes | Applied adjustment amount. Diagonal overwrites this field with the final calculated amount (see order of operations below). |
| Fixed amount field | Money | No | Amount to apply when the calculation type is fixed_amount. |
| Percent field | Number | No | Percentage to apply when the calculation type is percentage. |
| Description field | Text | Yes | Human-readable explanation shown in invoice or internal views. Used as the adjustment's display value. |
Order of operations¶
Diagonal applies adjustments in a fixed order, regardless of the order the adjustment records were created:
- Subtotal — Diagonal sums the line items into the payable subtotal.
- Credits — All active credits are applied against the subtotal. Percentage credits are calculated from the subtotal, and fixed-amount credits use their fixed value. Credits are capped so they cannot reduce the subtotal below zero.
- Charges — All active charges are then applied against the post-credit basis (subtotal minus credits). Percentage charges are calculated from that reduced basis, and fixed-amount charges use their fixed value.
Because the order is fixed in this sequence, the order in which adjustment records are created does not change the result, and reordering adjustments of the same direction does not change the total.
Diagonal overwrites each adjustment's Amount field with its final calculated amount. For a percentage charge this is the post-credit amount, not the gross amount, so the payable total is always the clean sum of every adjustment's Amount field.
Worked example. On a $100 subtotal with a 20% credit and a 10% charge:
- Credit: 20% × $100 = $20, leaving a post-credit basis of $80.
- Charge: 10% × $80 = $8 (not $10, because the charge is calculated after the credit). The charge's Amount field is stored as $8.
- Payable total: $100 − $20 + $8 = $88.
Adjustment records are normal Records. In practice, a page or workflow creates an adjustment with the standard data creation flow, using fields like payable, status, direction, calculation type, fixed amount, or percent. Because this goes through normal record creation, capability hooks, validation, relations, and policies stay in one path.
Diagonal also stores internal adjustment totals and allocation details in payable metadata. This metadata is useful for internal tracking, reporting, and future tax behavior without requiring app builders to expose every calculated field to end users.
Payment¶
Payment Resources store individual payment transactions.
Use this when you need records for charges, manual payments, checkout payments, failed payments, or payment history against a payable record.
| Setting | Field type | Required | Purpose |
|---|---|---|---|
| Payable field | Relation | Yes | Links the payment to the payable record. |
| Amount field | Money | Yes | Amount of the payment. |
| Currency field | Text | Yes | Currency for the payment. |
| Method field | Text | Yes | Payment method, such as manual or checkout. |
| Status field | Text | Yes | Payment state, such as succeeded, failed, refunded, or partially refunded. |
| Payer field | Relation | No | Links the payment to the payer. |
| Failure reason field | Text | No | Explains why a payment failed. |
| Refunded amount field | Money | No | Tracks how much has been refunded. |
| Notes field | Text | No | Internal payment notes. |
| Paid at field | Datetime | No | Timestamp for successful payment. |
Payment records can update the connected Payable record so totals, balances, and statuses stay current.
Refund¶
Refund Resources store refunds against Payment records.
Use this when you need to track partial refunds, full refunds, pending refunds, failed refunds, and refund reasons.
| Setting | Field type | Required | Purpose |
|---|---|---|---|
| Payment field | Relation | Yes | Links the refund to the payment being refunded. |
| Amount field | Money | Yes | Amount being refunded. |
| Currency field | Text | Yes | Currency for the refund. |
| Status field | Text | Yes | Refund state, such as succeeded, pending, or failed. |
| Refunded at field | Datetime | Yes | Timestamp for the refund. |
| Reason field | Text | No | Reason for the refund. |
Successful refund records can update the related Payment record's refunded amount and status.
Catalog and Pricing¶
Use these capabilities when your app sells things and needs a catalog of products with their own pricing.
Product and Price work as a pair: a Product is the sellable item, and a Price is a specific amount and billing cadence for that product. One product can have many prices, such as a monthly and a yearly option.
| Resource | Capability | Role in the catalog model |
|---|---|---|
| Product, Plan, or Service | Product | The sellable catalog item. |
| Price, Rate, or Plan Price | Price | An amount and billing cadence for a product. |
Product¶
Product Resources represent sellable catalog items that prices and subscriptions can reference.
Use this for products, plans, services, packages, or any sellable item that needs its own catalog entry.
| Setting | Field type | Required | Purpose |
|---|---|---|---|
| Name field | Text | Yes | Display name of the product. |
| Description field | Text | No | Longer description of the product. |
Price¶
Price Resources represent the pricing records for a product, each with an amount and a billing cadence.
Use this when a product needs one or more prices, such as a one-time charge, a monthly subscription, or an annual plan. A single product can have many prices.
| Setting | Field type | Required | Purpose |
|---|---|---|---|
| Product field | Relation | Yes | Links the price to its product. Must point to a Resource that has the Product capability enabled. |
| Amount field | Money | Yes | The price amount. |
| Recurrence field | Select | Yes | Billing cadence. Supported values are one_time, monthly, quarterly, and yearly. |
When you connect a Price to its product, Diagonal checks that the related Resource actually has the Product capability enabled, so catalog relationships stay valid.
Subscriptions¶
Use these capabilities when your app sells recurring agreements that bill on a schedule and generate invoices each period.
Subscription and Subscription Item work as a pair: a Subscription is the recurring agreement on one billing cadence, and each Subscription Item is one priced line on that agreement. The catalog (Product and Price) supplies what is being billed.
| Resource | Capability | Role in the subscription model |
|---|---|---|
| Subscription, Membership, or Plan | Subscription | The recurring agreement that bills each period. |
| Subscription Item, Line, or Add-on | Subscription Item | One priced line on the subscription. |
Subscription¶
Subscription Resources represent a recurring agreement that generates a payable invoice each billing period.
| Setting | Field type | Required | Purpose |
|---|---|---|---|
| Payer field | Relation | Yes | Links the subscription to the payer responsible for it. |
| Status field | Select | Yes | Lifecycle state. Supported values are draft, active, past_due, paused, canceled, and expired. |
| Collection method field | Select | Yes | How payment is collected. Supported values are send_invoice and charge_automatically. |
| Interval field | Select | No | The subscription's billing cadence. Supported values are monthly, quarterly, and yearly. The system freezes this from the first recurring item — see below. |
| Started at field | Datetime | Yes | When the subscription began. |
| Current period start field | Datetime | Yes | Start of the active billing period. |
| Current period end field | Datetime | Yes | End of the active billing period. |
| Next invoice at field | Datetime | Yes | When the next invoice is due to be generated; drives the billing cycle. |
| Canceled at field | Datetime | No | When the subscription was canceled. |
| Cancel at period end field | Boolean | No | Whether the subscription cancels at the end of the current period rather than immediately. |
| Latest invoice field | Relation | No | Points to the most recently generated payable invoice. |
One cadence per subscription¶
A subscription bills on a single interval. The first recurring item added to a subscription freezes its Interval field, and every later recurring item must share that interval. A recurring item whose price recurs on a different cadence is rejected — those belong on a separate subscription. This keeps the billing cycle unambiguous: one subscription, one clock, one invoice per period covering every item.
One-time items are the exception: a price with one_time recurrence carries no cadence, so it can be added to any subscription and is billed once on the next invoice without affecting the frozen interval.
Subscription Item¶
Subscription Item Resources represent a recurring line on a subscription that renews each billing period.
| Setting | Field type | Required | Purpose |
|---|---|---|---|
| Subscription field | Relation | Yes | Links the item to its subscription. |
| Price field | Relation | Yes | Links the item to the price it bills at. |
| Product field | Relation | No | The product being billed. Derived from the price when left empty. |
| Quantity field | Number | No | Quantity billed. |
| Price snapshot field | Money | Yes | The price amount agreed at subscription time. Snapshotted from the price when left empty. |
| Description snapshot field | Text | Yes | The product name agreed at subscription time. Snapshotted from the product when left empty. |
| Starts at field | Datetime | No | When the item begins billing. |
| Ends at field | Datetime | No | When the item stops billing. |
| Status field | Select | Yes | Item state. Supported values are active and canceled. |
When an item is created from its price alone, Diagonal snapshots the price amount and the product name onto the item, and denormalizes the product relation from the price. These snapshots are taken once, on save: editing the source price or product later never changes existing items, so each item keeps the terms agreed at subscription time. Any value you set explicitly is never overwritten.
Scheduling and Calendars¶
Use these capabilities when Resources need to appear on calendars or participate in scheduling.
Eventable is about the event itself. Schedulable is about the person, place, or thing that can be assigned to an event.
| Resource | Capability | Example |
|---|---|---|
| Appointment | Eventable | A scheduled customer appointment with a start and end time. |
| Class Session | Eventable | A recurring lesson or session on a calendar. |
| Staff Member | Schedulable | A person who can be booked. |
| Room | Schedulable | A room that can be reserved. |
| Equipment | Schedulable | Equipment that can be assigned to a booking. |
Eventable¶
Eventable Resources represent calendar events.
Use this for appointments, bookings, classes, sessions, meetings, site visits, or anything with start and end times.
| Setting | Field type | Required | Purpose |
|---|---|---|---|
| Start datetime field | Datetime | Yes | When the event starts. |
| End datetime field | Datetime | Yes | When the event ends. |
| All-day field | Boolean | No | Marks events that last all day. |
| Recurrence rule field | Recurrence | No | Defines repeating event behavior. |
| Recurrence exceptions field | Text | No | Stores exceptions to repeating schedules. |
| Label field | Text | No | Display name for calendar views. |
Eventable works well with Schedulable when you need to book people, rooms, equipment, or other availability-bearing resources.
Recurring event timezones
Recurrence rules created by Diagonal's UI include an explicit timezone hint, so local wall-clock times stay stable across daylight saving time changes. API callers that write a bare RRULE without DTSTART;TZID=... or X-DIAGONAL-TZID are interpreted as UTC-anchored rules.
Include one of those timezone hints when a recurring event should stay at the same local time, such as 9:00 AM every week in America/New_York.
API and workflow updates can include $operation.eventable.scope to choose how a recurring event update applies. Supported values are this, this_and_future, and all. When scope is omitted, updates to the recurring parent record default to all, while updates to generated occurrences default to this.
Schedulable¶
Schedulable Resources can participate in scheduling.
Use this for anything that has availability or can be assigned to events: staff members, service providers, rooms, equipment, vehicles, or locations.
| Setting | Field type | Required | Purpose |
|---|---|---|---|
| Color field | Color | No | Display color for calendars and schedules. |
| Name field | Text | No | Display name used in scheduling views. |
A Resource can be both Authenticatable and Schedulable. For example, an Employee can log in and also be booked for appointments.
Choosing Capabilities¶
Enable Capabilities only when the Resource needs platform behavior.
| If the Resource needs to... | Enable | Group |
|---|---|---|
| Let records log in. | Authenticatable | Identity and communication |
| Send messages to records. | Notifiable | Identity and communication |
| Represent payment customers. | Payer | Payments and commerce |
| Track money owed. | Payable | Payments and commerce |
| Break totals into line items. | Itemizable | Payments and commerce |
| Add discounts, fees, or other payable-level credits and charges. | Payable Adjustment | Payments and commerce |
| Store payment attempts and successes. | Payment | Payments and commerce |
| Store refunds. | Refund | Payments and commerce |
| Act as a sellable catalog item. | Product | Catalog and pricing |
| Store an amount and billing cadence for a product. | Price | Catalog and pricing |
| Bill a recurring agreement each period. | Subscription | Subscriptions |
| Add a priced line to a recurring agreement. | Subscription Item | Subscriptions |
| Appear as a calendar event. | Eventable | Scheduling and calendars |
| Be booked or assigned to events. | Schedulable | Scheduling and calendars |