Tebex Integration

Sell properties on your Tebex store as time-limited deeds. A player buys a package, and the matching property is granted to them automatically for a set number of days. When their subscription renews the deed keeps going; when it lapses (or is refunded) the deed is reclaimed. Everything a player or admin touches is UI, there are no in-game commands to run.

How it works at a glanceCopy Anchor Link

1. An admin links a store package to a home in the tablet (deed type, subscription length, how much upkeep the buyer pays).
2. On your Tebex store, the package runs a delivery command when purchased, renewed, or refunded. Nobody types these, Tebex/FiveM fire them.
3. The buyer receives the property automatically. It appears in their My Properties list and in the new Redemptions tab.
4. The billing loop expires deeds whose subscription has lapsed and warns owners before they do. A renewal simply extends the clock, the player does nothing.

RequirementsCopy Anchor Link

Connect your server to Tebex using FiveM's built-in integration. In your server.cfg:

sv_tebexSecret yourTebexServerKey

Get the key from your Tebex panel under Integrations → Game Servers. This is the only credential the feature needs, and it lives in server.cfg, never in a script or on the client.

Verify it's connectedCopy Anchor Link

Open the admin tablet → Tebex Products. The status card at the top shows whether the secret is set, and the Test connection button confirms it live on success it names the linked store, server and currency. When connected, every package in your store is listed on the page, ready to link to a home.

Make sure the feature is enabled in the config (it is by default):

-- shared/economy.lua
Config.Tebex = {
    Enabled        = true,   -- master switch
    DefaultSubDays = 30,     -- used when a product sets no length
    ExpiryWarnDays = 3,      -- warn the owner this many days before expiry (0 = off)
    GraceHours     = 0,      -- keep access this long past expiry before reclaiming
    UpkeepPercent  = 100,    -- default upkeep a Tebex home pays, % of normal maintenance (0 = exempt)
    ExemptPlatformTax  = true, -- Tebex owners keep 100% of rent when they rent their home out
    ClaimByTransaction = true, -- players can claim older purchases with their tbx- transaction ID
    ClaimMatchAccount  = true, -- only the FiveM account that paid can claim a transaction
}

Deed typesCopy Anchor Link

When you flag a product you choose how a purchase is fulfilled:

Key termsCopy Anchor Link

• Deed # (Property ID): Every property registered in the system has a unique database ID number (e.g., 142). You will see it on the property card in My Properties (listed as Deed #142). You never need to type it when linking, the home picker is searchable by name, unit, owner or area.
• Tebex Package ID: The unique ID generated by Tebex when you create a package on your webstore (e.g., 27739).
  • Admin Usage: Use this ID on the Tebex store commands page, e.g., kp_tebex_grant 27739 {citizenid} {transaction}. Crucial: Do not confuse this with the in-game Deed # / Property ID! Passing a Deed # (like 142) instead of the Tebex Package ID to your console commands will prevent the script from finding your product templates and cause the grant to fail.
• Template property: the property a package sells. For a unique product it's the exact deed the buyer receives; for an allotment product it's the blueprint each buyer's private copy is cloned from. It can be owned by the state, a company or a job: but never by a player.
• Transaction ID: Tebex's ID for one payment, starting with tbx-. It's in the buyer's receipt email and is what {transaction} fills in.

Step 1, Link a package to a home (in-game)Copy Anchor Link

Create the package on Tebex first (Step 2) so it shows up here, or link by ID and create it afterwards.

a. Have a property to sell. Build one with the in-world creator or use an existing deed owned by the state, a company or a job (see Creating Property and Property Types). Notes:

• For a unique product, this deed is handed to the buyer, so keep it as a showcase deed until sold. It goes back to the same owner when the buyer stops paying.
• For an allotment product, the deed is only a blueprint, buyers get their own instanced copies at the same interior, so nobody ever lives in the template itself. Make sure the interior's allotment cap is high enough for how many you expect to sell.
• Walk-in (single-unit) interiors, starter-pool apartments and homes owned by a player can't be sold and won't appear in the picker.

b. Link it. Open the admin tablet → Tebex Products. Every package in your store is listed with its image, price and whether it's a subscription. Next to a package, click Link a home, then:

1. Which home?: search by name, unit, owner or area and pick the home.
2. What does the buyer get?: Their own copy (allotment) or This exact home (unique).
3. How long?: Permanent, 7, 30 or 90 days, or type any number of days.
4. Upkeep the buyer pays: Full, Half, Exempt, or type a %. See Costs for Tebex owners.
5. Save. The package row now shows the linked home and its settings.

From the package row you can then:

• Edit: change the home, type, length or upkeep.
• Unlink: stop selling it. New purchases wait as Pending until you link it again; current subscribers keep their home until it expires.
• N active: open the list of current subscribers (name, Citizen ID, transaction, expiry, home).

Step 2, Create the package on TebexCopy Anchor Link

Do this in your Tebex Creator panel (creator.tebex.io). You'll create the package, ask the buyer for their Citizen ID, then add the delivery commands.

2a. Create the packageCopy Anchor Link

1. Packages → Create Package.
2. Set the name, price, image and description as you like.
3. Choose the billing type:
   • Subscription (recurring), for a deed that renews and expires with the subscription. This is the usual choice.
   • Single payment: for a one-off. Pair it with a subscription length in the tablet (e.g. 30 days) for a "buy 30 days" model, or set the tablet's subscription days to 0 for a permanent deed.
4. Assign it to the game server you connected with sv_tebexSecret.

2b. Ask the buyer for their Citizen IDCopy Anchor Link

The grant needs to know which character to give the property to, so the store must collect the buyer's Citizen ID at checkout.

1. On the package, open Variables (a.k.a. required checkout fields).
2. Add a variable the customer must fill in:
   • Name / identifier: citizenid
   • Label shown to buyer: e.g. "Your in-game Citizen ID"
   • Required: yes
3. You'll reference it in the command below as {citizenid}.

2c. Add the delivery commandsCopy Anchor Link

On the package, open Commands and add the following. {transaction} and {citizenid} are placeholders, Tebex fills them in automatically per purchase.

Command Parameter Details:Copy Anchor Link

• <packageId>: The Tebex Package ID (e.g., 27739).
  • Example Command: kp_tebex_grant 27739 {citizenid} {transaction}
  • WARNING: Do NOT use the in-game property's Deed # (e.g. 142) here. It must be the store package ID!
• {citizenid}: The required checkout variable where the buyer enters their Citizen ID (handled by Tebex).
• {transaction}: The unique Tebex transaction ID generated on payment.

Worked exampleCopy Anchor Link

Suppose you built a new villa, which is assigned Deed #142 (Property ID) in the database. You want to offer this villa as a unique subscription package on your Tebex webstore under package ID 27739 for a duration of 30 days.

1. In-game (Tablet → Tebex Products):
   • Find package 27739 in the list and click Link a home
   • Which home?: search for the villa and select it
   • What does the buyer get?: This exact home
   • How long?: 30 days
   • Upkeep the buyer pays: Exempt (so the buyer pays no maintenance)
   • Click Save.
2. Tebex Store Panel (package 27739 → Variables): Add a required variable named citizenid so checkout collects the buyer's Citizen ID.
3. Tebex Store Panel (package 27739 → Commands):
   • Purchased → kp_tebex_grant 27739 {citizenid} {transaction} (Offline Executed: Yes)
   • Renews → kp_tebex_grant 27739 {citizenid} {transaction} (Offline Executed: Yes)
   • Expires/refunded → kp_tebex_revoke 27739 {transaction} (Offline Executed: Yes)
   • Note: In these commands, 27739 is the Tebex Package ID, NOT the in-game Deed # 142!

When the player buys the package, they enter their Citizen ID, and they are granted the villa for 30 days. It will show up in their My Properties page as a Tebex subscription property and in their Redemptions tab.

What the player seesCopy Anchor Link

Delivery is automatic, there is nothing to type. The property lands in their My Properties list, and a Redemptions tab (Public section of the tablet) shows every store purchase with its subscription status and expiry date.

If a purchase can't be completed the instant it arrives, for example the server was offline, the apartment's allotment was momentarily full, or the product hadn't been flagged yet, it shows as Pending in the Redemptions tab and is completed automatically the next time the player logs in. A Claim now button is also available there as a manual fallback.

Claiming an older purchaseCopy Anchor Link

Players who bought something before the package was linked, or whose delivery never arrived, can claim it themselves:

1. Open the tablet → Redemptions.
2. Under Bought something before?, paste the transaction ID from the Tebex receipt email (it starts with tbx-) and click Claim.
3. The server checks the payment with Tebex and delivers every linked package in it.

A claim is refused when:

Turn the box off with ClaimByTransaction = false.

Delivering a purchase by hand (admin)Copy Anchor Link

At the bottom of Tebex Products, open Deliver a purchase by hand. Use it for support tickets or deliveries that didn't arrive:

1. Citizen ID: the character who should get the home (must exist).
2. Package: one of your linked packages.
3. Transaction ID (optional), the buyer's tbx- ID. If you enter it, that purchase is marked as delivered and can't be delivered again.
4. Click Deliver.

If the player already has an active subscription on that package, it's extended instead of giving them a second home.

Costs for Tebex owners, upkeep & taxCopy Anchor Link

Players already paid real money for a Tebex home, so you choose what in-game costs they still pay.

Upkeep (maintenance): set per product in the tablet (Full / Half / Exempt or any %), defaulting to UpkeepPercent. Only the maintenance bill changes; electricity, water and services are still billed normally.

Tax: Tebex owners pay no tax on their home:

• There is no tax on the purchase itself, it's a real-money payment, so no in-game money changes hands.
• Home owners never pay a property tax. In block mode, land tax is paid by the company that owns the land block, not by the people living on it.
• If a Tebex owner rents their home out, they keep the full rent, the Config.PlatformTaxRate cut (5% by default) is skipped while ExemptPlatformTax = true. This covers the first rent at signing, every billing cycle and paid arrears.

When the deed expires or is revoked, the home is billed and taxed like any other again.

Renewals, expiry & refundsCopy Anchor Link

• Renewal: Tebex fires the grant command again; the deed's expiry is simply extended. This is completely seamless with no player action, and nothing is deleted or re-created.
• Refund / chargeback: The revoke command triggers immediately, reclaiming the property.
• Expiry: When a subscription lapses (plus any GraceHours), the billing loop triggers the reclaim function. Players get a heads-up notification ExpiryWarnDays before this happens.

What happens to the property and player items upon Expiry / Revocation?Copy Anchor Link

Unique Deed ScenarioCopy Anchor Link

1. Ownership Reverted: The property ownership is returned to its original owner (the state, company or job it was linked from). The property is not deleted from the world/registry database.
2. Access Revoked: The subscriber and all keyholders (roommates, guests) lose their keys immediately and can no longer enter.
3. Leases Closed: Any active leases or rent-splitting configurations are terminated.
4. Stashes Saved (Eviction Protection): Stash contents, lockers, and wardrobes are not destroyed. They are sealed under the city impound. The player can visit the impound recovery menu to retrieve their belongings for a small fee.

Allotment Deed ScenarioCopy Anchor Link

1. Property Deleted: The instanced copy/clone of the property is deleted outright from the database, freeing up the allotment slot.
2. Furniture Cleared: Any custom furniture placed by the player inside the property is deleted.
3. Access Revoked: All keyholders lose access.
4. Stashes Saved (Eviction Protection): Like unique deeds, all items in stashes/lockers are saved. They are moved to the city impound for a small fee so players never lose their belongings.

NotesCopy Anchor Link

• All timing runs on the standard billing loop, so expiry checks happen on the same cadence as rent and maintenance (see Utilities & Billing).
• Each Tebex transaction is single-use, a purchase is delivered once, whether it came from Tebex automatically, a player claim or a manual delivery.
• A basket with several packages delivers every linked package in it.
• Selling the same unique product while a subscriber still holds it is held as Pending until the deed is free again (one holder at a time).