> For the complete documentation index, see [llms.txt](https://docs.cuxial.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cuxial.com/scripts/vehicles/cuxial-gasstations/developers.md).

# Exports & events

Public API of Cuxial Gas Stations: exports to connect a fuel script, read prices and reputation, and request a wash.

Connect your fuel script to the station tanks, read prices, promotions and reputation, or send owner notices to another resource. Cuxial Fuel already uses these exports; you only need them for your own integrations.

Station ids are the keys of `data/stations.lua`, such as `gas_station_1`.

## Server exports

### FindStation

Returns the station a position belongs to. A position belongs to a station when it is inside its `pumps` sphere.

```lua
local stationId = exports.cuxial_gasstations:FindStation(coords)
```

| Parameter | Type             | Description                                       |
| --------- | ---------------- | ------------------------------------------------- |
| `coords`  | vector3 \| table | Position with `x`, `y` and `z`, usually the pump. |

**Returns:** `string` or `nil` when the position is outside every station.

```lua
local stationId = exports.cuxial_gasstations:FindStation(GetEntityCoords(pump))
```

### GetFuelPrices

Prices and stock of every fuel at a station, with the admin limits and the current happy hour already applied.

```lua
local data = exports.cuxial_gasstations:GetFuelPrices(stationId, countVisit)
```

| Parameter    | Type    | Description                                                                                              |
| ------------ | ------- | -------------------------------------------------------------------------------------------------------- |
| `stationId`  | string  | Station id.                                                                                              |
| `countVisit` | boolean | Adds one visit to the station statistics. Defaults to `true`; pass `false` when you only re-read prices. |

**Returns:** `nil` when the station does not exist or has no owner. Otherwise a table:

| Field    | Type  | Description                                                                                     |
| -------- | ----- | ----------------------------------------------------------------------------------------------- |
| `prices` | table | Price per litre or kWh, keyed by fuel id. `0` means the owner has set no price.                 |
| `stock`  | table | Litres in the tank for petrol fuels; `true` or `false` for electric chargers (unlocked or not). |

```lua
local data = exports.cuxial_gasstations:GetFuelPrices('gas_station_1', false)
if data then
    print(data.prices.regular, data.stock.regular)
end
```

### GetFuel

Short form for `regular` only.

```lua
local stock, price = exports.cuxial_gasstations:GetFuel(stationId, countVisit)
```

| Parameter    | Type    | Description                                      |
| ------------ | ------- | ------------------------------------------------ |
| `stationId`  | string  | Station id.                                      |
| `countVisit` | boolean | `true` adds one visit. Defaults to not counting. |

**Returns:** `stock` (litres) and `price` (per litre), or `nil` when the station does not exist or has no owner.

### SellFuel

Reports a sale. Takes the litres from the tank and adds the money to the cash box.

```lua
local sold = exports.cuxial_gasstations:SellFuel(stationId, fuel, paid, liters, kind, src)
```

| Parameter   | Type   | Description                                                                                             |
| ----------- | ------ | ------------------------------------------------------------------------------------------------------- |
| `stationId` | string | Station id.                                                                                             |
| `fuel`      | string | Fuel id from `fuels` in the config.                                                                     |
| `paid`      | number | What the customer paid.                                                                                 |
| `liters`    | number | Litres sold, or kWh for a charge.                                                                       |
| `kind`      | string | `'pump'`, `'can'` (jerry can) or `'charge'` (electric).                                                 |
| `src`       | number | Server id of the buyer. Optional. With it, the buyer can earn a wash voucher and is asked for a rating. |

**Returns:** `boolean`. `false` when the station has an owner and lacks the stock or the charger, or the fuel id is unknown: refund the customer. `true` in every other case, including stations with no owner.

```lua
local stationId = exports.cuxial_gasstations:FindStation(pumpCoords)
if stationId and not exports.cuxial_gasstations:SellFuel(stationId, 'regular', 120, 40, 'pump', source) then
    -- no stock: give the money back
end
```

### RefundFuel

Returns unused litres to the tank and takes the refund out of the cash box.

```lua
local refunded = exports.cuxial_gasstations:RefundFuel(stationId, fuel, refund, liters, src)
```

| Parameter   | Type   | Description                                                                                         |
| ----------- | ------ | --------------------------------------------------------------------------------------------------- |
| `stationId` | string | Station id.                                                                                         |
| `fuel`      | string | Fuel id.                                                                                            |
| `refund`    | number | Amount to give back to the customer.                                                                |
| `liters`    | number | Litres that were paid and not delivered.                                                            |
| `src`       | number | Server id of the buyer. Optional. Cancels a wash voucher that no longer reaches the minimum litres. |

**Returns:** `number`, the amount actually taken from the cash box. It can be lower than `refund` when the cash box is short, or `0`. For a station with no owner it returns `refund` unchanged.

### GetPromos

Promotions of a station, for public displays such as a price sign.

```lua
local promos = exports.cuxial_gasstations:GetPromos(stationId)
```

**Returns:** `nil` when the station does not exist. Otherwise a table:

| Field     | Type     | Description                                                                                                                                                                               |
| --------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `label`   | string   | Default name of the station.                                                                                                                                                              |
| `fuelPct` | number   | Current discount on fuel, in percent.                                                                                                                                                     |
| `washPct` | number   | Current discount on washes, in percent.                                                                                                                                                   |
| `live`    | table\[] | Promotions active now. A happy hour has `kind = 'happy_hour'`, `pct`, `applies` and `endsIn` (seconds). A voucher has `kind = 'fuel_voucher'`, `minLiters`, `service` and `validMinutes`. |
| `next`    | table    | Next happy hour, with `pct`, `applies` and `startsIn` (seconds). Absent when there is none today or tomorrow.                                                                             |

### GetReputation

```lua
local rep = exports.cuxial_gasstations:GetReputation(stationId)
```

**Returns:** `nil` when the station does not exist or the reputation module is off. Otherwise a table:

| Field      | Type   | Description                                 |
| ---------- | ------ | ------------------------------------------- |
| `avg`      | number | Rating from 1 to 5.                         |
| `count`    | number | Recent ratings counted.                     |
| `factor`   | number | Multiplier applied to NPC customer traffic. |
| `bonusPct` | number | Extra supplier discount, in percent.        |

### RequestMobileWash

Opens a mobile detailing request on behalf of a player, as `/detailing` does after the player confirms.

```lua
local result = exports.cuxial_gasstations:RequestMobileWash(src, service, netId)
```

| Parameter | Type   | Description                           |
| --------- | ------ | ------------------------------------- |
| `src`     | number | Server id of the customer.            |
| `service` | string | `'rinse'`, `'foam'` or `'wax'`.       |
| `netId`   | number | Network id of the customer's vehicle. |

**Returns:** a table with `ok` (boolean), `id` and `quote` on success, or `error` (a code such as `module_disabled`) on failure.

```lua
local result = exports.cuxial_gasstations:RequestMobileWash(source, 'foam', netId)
if not result.ok then print(result.error) end
```

### RegisterNoticeProvider

Receives every owner notice in your own resource, for example to forward it to another messaging system.

```lua
local ok = exports.cuxial_gasstations:RegisterNoticeProvider(name, fn)
```

| Parameter | Type     | Description                                          |
| --------- | -------- | ---------------------------------------------------- |
| `name`    | string   | Unique name, up to 40 characters.                    |
| `fn`      | function | Called with one `notice` table for each notice sent. |

Fields of `notice`:

| Field          | Type   | Description                                                                                                         |
| -------------- | ------ | ------------------------------------------------------------------------------------------------------------------- |
| `citizenid`    | string | Identifier of the station owner.                                                                                    |
| `station`      | string | Station id.                                                                                                         |
| `stationLabel` | string | Name of the station.                                                                                                |
| `kind`         | string | `low_stock`, `mobile_wait`, `mobile_missed`, `npc_cap`, `rental`, `daily`, `reputation`, `abandon_risk` or `spill`. |
| `title`        | string | Title, already translated.                                                                                          |
| `text`         | string | Body, already translated.                                                                                           |
| `at`           | number | Time in milliseconds.                                                                                               |

**Returns:** `boolean`. The provider is removed on its own when your resource stops.

```lua
exports.cuxial_gasstations:RegisterNoticeProvider('my_mail', function(notice)
    print(notice.stationLabel, notice.kind, notice.text)
end)
```

### UnregisterNoticeProvider

```lua
exports.cuxial_gasstations:UnregisterNoticeProvider(name)
```

### Spill

For fuel scripts. Creates a fuel puddle when a vehicle drives off with the nozzle attached. The station decides whether the spill happens and how many litres it loses.

```lua
local spilled = exports.cuxial_gasstations:Spill(stationId, coords, src, liters, fuel, netId)
```

| Parameter   | Type    | Description                                 |
| ----------- | ------- | ------------------------------------------- |
| `stationId` | string  | Station id.                                 |
| `coords`    | vector3 | Ground position under the nozzle.           |
| `src`       | number  | Server id of the player who was refuelling. |
| `liters`    | number  | Litres paid and not delivered.              |
| `fuel`      | string  | Fuel id.                                    |
| `netId`     | number  | Network id of the vehicle.                  |

**Returns:** `number`, the litres that do not go back to the tank. `0` means no puddle was created.

## Client exports

### FindStation

Same as the server export.

```lua
local stationId = exports.cuxial_gasstations:FindStation(GetEntityCoords(cache.ped))
```

### IsWaxed

Tells whether a vehicle has an active wax coat.

```lua
local waxed = exports.cuxial_gasstations:IsWaxed(vehicle)
```

| Parameter | Type   | Description                   |
| --------- | ------ | ----------------------------- |
| `vehicle` | number | Entity handle of the vehicle. |

**Returns:** `boolean`.

## Events

Cuxial Gas Stations exposes no events for other resources. Its internal events are validated on the server and are not meant to be triggered from outside.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.cuxial.com/scripts/vehicles/cuxial-gasstations/developers.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.