> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.rebateright.com.au/api-reference/mbs/benefit-calculator/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.rebateright.com.au/_mcp/server.

# Benefit Calculator

POST https://api.rebateright.com.au/CalculateBenefit
Content-Type: application/json

That is the question this endpoint answers. Send the item, how many patients were seen and
whether the service is in hospital. It works out the schedule fee, the benefit for one patient
and the total for the patients seen, with the working behind every figure.

This endpoint needs no patient details. To check whether a particular patient can claim the
item, use
[Eligibility Check](/api-reference/medicare-eligibility/eligibility-check), which quotes the
same benefit.

## What you get back

| Field          | What it holds                                                           |
| -------------- | ----------------------------------------------------------------------- |
| `ScheduleFee`  | The MBS fee for one patient. `"53.35"`                                  |
| `Benefit`      | What Medicare pays for one patient. `"53.35"`                           |
| `TotalBenefit` | `Benefit` multiplied by `PatientsSeen`. `"160.05"`                      |
| `Reason`       | How the figures were worked out, in one sentence you can show as it is. |
| `ReasonCode`   | A code for that reason, for analytics only.                             |

The response also carries `ItemNumber`, `PatientsSeen` and `InHospitalTreatment`, with any
default filled in, so you always see which values were used.

## Every request field is optional

| Field                 | When omitted                     |
| --------------------- | -------------------------------- |
| `ItemNumber`          | `23`, a standard GP consultation |
| `PatientsSeen`        | `1`                              |
| `InHospitalTreatment` | `false`, out of hospital         |

An empty body `{}` is a valid request.

## How the benefit is worked out

**Published fee.** The benefit is the amount the MBS publishes for the item. Where an item
pays differently in and out of hospital, `InHospitalTreatment` decides which amount applies.

**Derived fee.** Some attendance items, such as a general practitioner seeing several
residents in one visit to an aged care facility, have a fee that depends on `PatientsSeen`.
The fee follows the item's rule in the MBS, as published in the Ready Reckoner, and Medicare
pays 100% of it. `Reason` shows the arithmetic.

## When there is no figure

When the benefit cannot be worked out, the response is still `200`: `Benefit` and
`TotalBenefit` are `null`, and `Reason` and `ReasonCode` say why. Only a body that cannot be
parsed, or that names a field this endpoint does not recognise, returns `400`.

Reference: https://docs.rebateright.com.au/api-reference/mbs/benefit-calculator

## Authentication

- `x-api-key` header (required) — API Key authentication via header
- `x-minor-id` header (required) — Your Minor ID is three uppercase letters followed by five digits, such as `MDE00001`. Send the Minor ID exactly as issued. A malformed value gets a 400 with "The Minor ID is not valid." on every endpoint.

## Servers

- `https://api.rebateright.com.au` (Production, default)
- `https://test-api.rebateright.com.au` (Test)

## Request

### Body (application/json)

This endpoint expects an object.

- `ItemNumber` (string, optional) — The MBS item number. Defaults to `23`, a standard GP consultation (Level B), when omitted.
- `PatientsSeen` (integer, optional) — How many patients the practitioner sees on the same occasion at the same place. `TotalBenefit` is the benefit multiplied by this number, and on group attendance items the fee itself depends on it. Defaults to `1` when omitted. A value below `1` returns `200` with `ReasonCode` `InvalidRequest`.
- `InHospitalTreatment` (boolean, optional) — Whether the service is provided to an in-hospital patient. Decides the benefit on items that pay differently in and out of hospital. Defaults to `false` when omitted.

## Response

### 200

OK

- `ItemNumber` (string, required) — The item the figures are for, with the default applied if you omitted it.
- `PatientsSeen` (integer, required) — The patient count used, with the default applied if you omitted it.
- `InHospitalTreatment` (boolean, required) — The setting used, with the default applied if you omitted it.
- `ScheduleFee` (string, required, nullable) — The MBS schedule fee for one patient, in dollars, as a string such as `"53.35"`. It is `null` when the fee could not be determined.
- `Benefit` (string, required, nullable) — What Medicare pays for one patient, in dollars, as a string such as `"53.35"`. It is `null` when the benefit could not be worked out, and `Reason` says why.
- `TotalBenefit` (string, required, nullable) — `Benefit` multiplied by `PatientsSeen`. It is `null` whenever `Benefit` is.
- `Reason` (string, required) — How the figures were worked out, in one sentence you can show as it is. Never parse it, because the wording changes.
- `ReasonCode` (string, required) — A code for that reason, for analytics only. | Code | Meaning | |---|---| | `Calculated` | The fee and the benefit were worked out. | | `InvalidRequest` | A request value is not allowed, such as `PatientsSeen` below `1`. `Reason` names it. | | `ItemNotFound` | The item number is not in the current MBS. | | `ScheduleFeeNotAvailable` | The item exists but the MBS data has no fee for it. | | `FeeDependsOnOtherServices` | The fee depends on details this endpoint does not have, such as the other services performed or the time taken. `Reason` quotes the MBS rule. | | `BenefitNotDetermined` | The fee is known but the benefit could not be determined. | New codes appear as coverage grows and are not a breaking change.

## Examples

### Defaults

**Request**

```json
{}
```

**Response**

```json
{
  "ItemNumber": "23",
  "PatientsSeen": 1,
  "InHospitalTreatment": false,
  "ScheduleFee": "45.05",
  "Benefit": "45.05",
  "TotalBenefit": "45.05",
  "Reason": "Medicare item 23 has a schedule fee of $45.05. Medicare pays a benefit of $45.05, as published in the MBS.",
  "ReasonCode": "Calculated"
}
```

**SDK Code**

```python Defaults
import requests

url = "https://api.rebateright.com.au/CalculateBenefit"

payload = {}
headers = {
    "x-api-key": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Defaults
const url = 'https://api.rebateright.com.au/CalculateBenefit';
const options = {
  method: 'POST',
  headers: {'x-api-key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Defaults
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.rebateright.com.au/CalculateBenefit"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Defaults
require 'uri'
require 'net/http'

url = URI("https://api.rebateright.com.au/CalculateBenefit")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java Defaults
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.rebateright.com.au/CalculateBenefit")
  .header("x-api-key", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php Defaults
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.rebateright.com.au/CalculateBenefit', [
  'body' => '{}',
  'headers' => [
    'Content-Type' => 'application/json',
    'x-api-key' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp Defaults
using RestSharp;

var client = new RestClient("https://api.rebateright.com.au/CalculateBenefit");
var request = new RestRequest(Method.POST);
request.AddHeader("x-api-key", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Defaults
import Foundation

let headers = [
  "x-api-key": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.rebateright.com.au/CalculateBenefit")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Ready Reckoner

**Request**

```json
{
  "ItemNumber": "5010",
  "PatientsSeen": 3
}
```

**Response**

```json
{
  "ItemNumber": "5010",
  "PatientsSeen": 3,
  "InHospitalTreatment": false,
  "ScheduleFee": "53.35",
  "Benefit": "53.35",
  "TotalBenefit": "160.05",
  "Reason": "Medicare item 5010 has a derived fee: the fee for item 5000 ($34.70), plus $55.95 divided by the number of patients seen (3), rounded to the nearest 5 cents. The schedule fee is $53.35 per patient, and Medicare pays a benefit of 100% of that fee, as published in the MBS Ready Reckoner.",
  "ReasonCode": "Calculated"
}
```

**SDK Code**

```python Ready Reckoner
import requests

url = "https://api.rebateright.com.au/CalculateBenefit"

payload = {
    "ItemNumber": "5010",
    "PatientsSeen": 3
}
headers = {
    "x-api-key": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Ready Reckoner
const url = 'https://api.rebateright.com.au/CalculateBenefit';
const options = {
  method: 'POST',
  headers: {'x-api-key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"ItemNumber":"5010","PatientsSeen":3}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Ready Reckoner
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.rebateright.com.au/CalculateBenefit"

	payload := strings.NewReader("{\n  \"ItemNumber\": \"5010\",\n  \"PatientsSeen\": 3\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Ready Reckoner
require 'uri'
require 'net/http'

url = URI("https://api.rebateright.com.au/CalculateBenefit")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"ItemNumber\": \"5010\",\n  \"PatientsSeen\": 3\n}"

response = http.request(request)
puts response.read_body
```

```java Ready Reckoner
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.rebateright.com.au/CalculateBenefit")
  .header("x-api-key", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"ItemNumber\": \"5010\",\n  \"PatientsSeen\": 3\n}")
  .asString();
```

```php Ready Reckoner
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.rebateright.com.au/CalculateBenefit', [
  'body' => '{
  "ItemNumber": "5010",
  "PatientsSeen": 3
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'x-api-key' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp Ready Reckoner
using RestSharp;

var client = new RestClient("https://api.rebateright.com.au/CalculateBenefit");
var request = new RestRequest(Method.POST);
request.AddHeader("x-api-key", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"ItemNumber\": \"5010\",\n  \"PatientsSeen\": 3\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Ready Reckoner
import Foundation

let headers = [
  "x-api-key": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "ItemNumber": "5010",
  "PatientsSeen": 3
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.rebateright.com.au/CalculateBenefit")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### In Hospital

**Request**

```json
{
  "ItemNumber": "104",
  "InHospitalTreatment": true
}
```

**Response**

```json
{
  "ItemNumber": "104",
  "PatientsSeen": 1,
  "InHospitalTreatment": true,
  "ScheduleFee": "103.95",
  "Benefit": "78.00",
  "TotalBenefit": "78.00",
  "Reason": "Medicare item 104 has a schedule fee of $103.95. The service is in hospital. Medicare pays a benefit of $78.00, as published in the MBS.",
  "ReasonCode": "Calculated"
}
```

**SDK Code**

```python In Hospital
import requests

url = "https://api.rebateright.com.au/CalculateBenefit"

payload = {
    "ItemNumber": "104",
    "InHospitalTreatment": True
}
headers = {
    "x-api-key": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript In Hospital
const url = 'https://api.rebateright.com.au/CalculateBenefit';
const options = {
  method: 'POST',
  headers: {'x-api-key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"ItemNumber":"104","InHospitalTreatment":true}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go In Hospital
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.rebateright.com.au/CalculateBenefit"

	payload := strings.NewReader("{\n  \"ItemNumber\": \"104\",\n  \"InHospitalTreatment\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby In Hospital
require 'uri'
require 'net/http'

url = URI("https://api.rebateright.com.au/CalculateBenefit")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"ItemNumber\": \"104\",\n  \"InHospitalTreatment\": true\n}"

response = http.request(request)
puts response.read_body
```

```java In Hospital
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.rebateright.com.au/CalculateBenefit")
  .header("x-api-key", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"ItemNumber\": \"104\",\n  \"InHospitalTreatment\": true\n}")
  .asString();
```

```php In Hospital
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.rebateright.com.au/CalculateBenefit', [
  'body' => '{
  "ItemNumber": "104",
  "InHospitalTreatment": true
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'x-api-key' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp In Hospital
using RestSharp;

var client = new RestClient("https://api.rebateright.com.au/CalculateBenefit");
var request = new RestRequest(Method.POST);
request.AddHeader("x-api-key", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"ItemNumber\": \"104\",\n  \"InHospitalTreatment\": true\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift In Hospital
import Foundation

let headers = [
  "x-api-key": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "ItemNumber": "104",
  "InHospitalTreatment": true
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.rebateright.com.au/CalculateBenefit")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Invalid Request

**Request**

```json
{
  "ItemNumber": "23",
  "PatientsSeen": 0
}
```

**Response**

```json
{
  "ItemNumber": "23",
  "PatientsSeen": 0,
  "InHospitalTreatment": false,
  "ScheduleFee": null,
  "Benefit": null,
  "TotalBenefit": null,
  "Reason": "PatientsSeen must be 1 or more.",
  "ReasonCode": "InvalidRequest"
}
```

**SDK Code**

```python Invalid Request
import requests

url = "https://api.rebateright.com.au/CalculateBenefit"

payload = {
    "ItemNumber": "23",
    "PatientsSeen": 0
}
headers = {
    "x-api-key": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Invalid Request
const url = 'https://api.rebateright.com.au/CalculateBenefit';
const options = {
  method: 'POST',
  headers: {'x-api-key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"ItemNumber":"23","PatientsSeen":0}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Invalid Request
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.rebateright.com.au/CalculateBenefit"

	payload := strings.NewReader("{\n  \"ItemNumber\": \"23\",\n  \"PatientsSeen\": 0\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Invalid Request
require 'uri'
require 'net/http'

url = URI("https://api.rebateright.com.au/CalculateBenefit")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"ItemNumber\": \"23\",\n  \"PatientsSeen\": 0\n}"

response = http.request(request)
puts response.read_body
```

```java Invalid Request
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.rebateright.com.au/CalculateBenefit")
  .header("x-api-key", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"ItemNumber\": \"23\",\n  \"PatientsSeen\": 0\n}")
  .asString();
```

```php Invalid Request
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.rebateright.com.au/CalculateBenefit', [
  'body' => '{
  "ItemNumber": "23",
  "PatientsSeen": 0
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'x-api-key' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp Invalid Request
using RestSharp;

var client = new RestClient("https://api.rebateright.com.au/CalculateBenefit");
var request = new RestRequest(Method.POST);
request.AddHeader("x-api-key", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"ItemNumber\": \"23\",\n  \"PatientsSeen\": 0\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Invalid Request
import Foundation

let headers = [
  "x-api-key": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "ItemNumber": "23",
  "PatientsSeen": 0
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.rebateright.com.au/CalculateBenefit")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```