How to build subscription and entitlement provisioning

What matters here

• Derive entitlement from the contract. A number typed into the product by a support agent is a number nobody will ever reconcile.
• Activate on the contract start date, not at signature. Those differ and billing follows the contract.
• Handle mid-term changes as amendments to the same subscription, never as a second one.
• Reconcile nightly. Entitlement edited in the product to unblock somebody is revenue leaking silently.
• Never downgrade automatically on non-payment without a human. Suspension is a commercial decision.

Who this is for

You run revenue operations or product operations at a subscription company. Contracts are signed and access is granted by hand, and nobody is quite sure the two still agree.

How it works in practice

Everything that sits between a contract being signed and a customer having what they bought.

1. 1

   Entitlement is derived from the closed contract

   Products, seats, limits and term, computed rather than typed.

2. 2

   Provisioning is scheduled for the contract start date

   Which is often not the signature date, and billing follows the contract.

3. 3

   Admin access goes to the named contact

   With an invitation, so somebody can actually get in on day one.

4. 4

   Mid-term changes amend the same subscription

   Co-terminated, prorated, and never a second subscription for one customer.

5. 5

   A nightly reconciliation compares sold against live

   Any difference is drift, and drift in either direction is a problem.

6. 6

   Expiry warns, not cuts

   Renewal in progress means access continues; a decision to suspend is made by a person.

Paste these into Claude Code or Codex with the Tray Headless plugin installed. Each stage runs on its own. The systems named in them are the worked example rather than a requirement, and every prompt says so.

Once per project, run /tray-workflows:set-workspace to pick the workspace these build in. Point it at a sandbox first.

1. 1

   Start here: map contract lines to entitlement

   Everything downstream is this mapping.

   Headless skills build-workflow

   Copy

   Use build-workflow. The systems in play are Salesforce and our
   product's admin API, or whatever we run in those seats.
   
   I need contract line items with products, quantities and term dates, and
   from the product the entitlement model: plans, seats, feature flags and
   usage limits.
   
   Then build the mapping from product code to entitlement as a table
   finance and product both understand. Every SKU we sell has to resolve to
   a concrete entitlement, and any SKU that does not is a sale nobody can
   fulfil.

2. 2

   Derive entitlement, and activate on the start date

   Signature date and start date are different, and billing follows one of them.

   Headless skills build-workflow tray-patterns

   Copy

   Use build-workflow. On closed won, derive the entitlement from the
   contract lines: plan, seat count, feature flags, usage limits, term start
   and end.
   
   Schedule activation for the contract start date rather than firing at
   signature. Those are frequently weeks apart, billing follows the
   contract, and granting access early gives away product you have not
   billed for.
   
   Provision the admin user from the named technical contact and send them
   an invitation. A subscription that is live but which nobody can log into
   is not provisioned, and it generates a support ticket on day one.
   
   Write the subscription id back to the opportunity so the two are linked
   permanently.

3. 3

   Treat mid-term changes as amendments

   A second subscription for one customer breaks the renewal figure.

   Copy

   Handle changes against the existing subscription, never by creating a
   new one:
   
     Seat increase: apply immediately, prorate to the existing term end
     Seat decrease: apply at renewal unless the contract allows otherwise,
     and never silently remove a named user
     Plan upgrade: apply immediately with proration
     Plan downgrade: apply at renewal, and flag for revenue recognition
     Term extension: co-terminate everything to the new end date
   
   Every amendment links to the parent contract. A mid-term upgrade filed as
   a new subscription produces two records for one customer, and the renewal
   number is wrong from that point onward.

4. 4

   Reconcile nightly, in both directions

   Manual edits in the product are invisible until you look.

   Headless skills tray-gotchas tray-patterns

   Copy

   Use tray-gotchas, then reconcile nightly between contract and product:
   
     Seats provisioned above what was sold, which is revenue leaking
     Seats below what was sold, which is a customer not getting what they
     paid for
     Features enabled with no contract line behind them
     Active subscriptions with no contract at all
     Contracts past their end date with access still live
   
   Report both directions. The over-provisioned list is usually longer and
   it is almost always somebody enabling something to unblock a customer,
   which is the right instinct and the wrong permanent state.
   
   Do not correct automatically. Report it and let a person decide, because
   removing access a customer is actively using is a conversation.

5. 5

   Warn at expiry, never cut automatically

   Suspension is a commercial decision, not a scheduled job.

   Copy

   At term end, warn instead of cut:
   
     30 days out, tell the account owner and customer success
     On the end date, if a renewal is in progress, continue access and flag
     it. Cutting off a customer mid-renewal loses the renewal.
     If there is no renewal and no engagement, suspend instead of delete,
     and require a person to confirm.
   
   Never automatically downgrade or suspend on non-payment. Route it to
   credit control and the account owner, and let a human decide.
   
   Then report: time from signature to working access, provisioning
   failures, drift in both directions, and expiries handled without a
   decision, which should be zero.

6. 6

   Check it end to end, then hand the mapping over

   Because the catalogue changes and the mapping has to keep up.

   Copy

   Run the per-step schema checks and the whole-workflow audit before this
   touches production.
   
   Then open the same workflow in Tray Build so revenue operations and
   product can maintain the SKU to entitlement mapping in the visual canvas.
   A new plan should be sellable and fulfillable the same week.

What it connects to

The contract says what was sold, the product grants it, and billing has to agree with both.

Named systems are the ones most teams run, not the only ones that work. Each is an authentication in your Tray workspace, referenced by name, so the workflow never holds a credential. Where we have a connector page, the name links to it.

Questions people ask

Related guides