> This is Payabli documentation. For a complete page index, fetch https://docs.payabli.com/llms.txt — append .md to any page URL for lightweight markdown. For section-level indexes, query parameters, and other AI-optimized access methods, see https://docs.payabli.com/ai-agents.md

# Retrieve pricing with the billing profile API

> List an organization's billing profiles and read the pricing assigned to an entity

A **billing profile** is a named configuration of billable events, each with one or more fee schedules, that defines the pricing in effect for an entity. Profiles are created at the organization level and assigned down to paypoints, boarding templates, and applications.

When the application or template flow doesn't surface the pricing terms, use the billing profile API to read them directly. This guide covers the two read endpoints: listing the profiles that belong to an organization, then viewing the full profile assigned to a specific entity.

For the concepts behind fee structures, fee types, and who pays fees, see [Merchant processing pricing and fees](/guides/pay-ops-billing-and-fees-overview).

## Prerequisites

Before you start, make sure you have:

* A token with the `billing_profile_read` permission. A token without it gets `403 Forbidden`. Contact the Payabli team if your token can't reach these endpoints.
* The numeric ID of the organization whose profiles you want to read.

The examples use the sandbox base URL, `https://api-sandbox.payabli.com/api`. Switch to `https://api.payabli.com/api` for production.

## Steps

#### List the organization's profiles

Call the List billing profiles endpoint to see every profile that belongs to an organization. This is the same data the Profile Library table shows in the Payabli Portal.

### Request

GET [https://api-sandbox.payabli.com/api/billing/configuration/org/\{orgId}](https://api-sandbox.payabli.com/api/billing/configuration/org/\{orgId})

```curl ListProfiles
curl -G https://api-sandbox.payabli.com/api/billing/configuration/org/123 \
     -d fromRecord=0 \
     -d limitRecord=20
```

```typescript ListProfiles
import { PayabliClient } from "@payabli/sdk-node";

async function main() {
    const client = new PayabliClient();
    await client.billing.listProfiles(123, {
        fromRecord: 0,
        limitRecord: 20,
    });
}
main();

```

```python ListProfiles
from payabli import payabli

client = payabli()

client.billing.list_profiles(
    org_id=123,
    from_record=0,
    limit_record=20,
)

```

```java ListProfiles
package com.example.usage;

import io.github.payabli.api.PayabliApiClient;
import io.github.payabli.api.resources.billing.requests.ListBillingProfilesRequest;

public class Example {
    public static void main(String[] args) {
        PayabliApiClient client = PayabliApiClient
            .builder()
            .build();

        client.billing().listProfiles(
            123L,
            ListBillingProfilesRequest
                .builder()
                .fromRecord(0L)
                .limitRecord(20L)
                .build()
        );
    }
}
```

```csharp ListProfiles
using PayabliApi;
using System.Threading.Tasks;

namespace Usage;

public class Example
{
    public async Task Do() {
        var client = new PayabliApiClient();

        await client.Billing.ListProfilesAsync(
            123L,
            new ListBillingProfilesRequest {
                FromRecord = 0L,
                LimitRecord = 20L
            }
        );
    }

}

```

```go ListProfiles
package example

import (
    context "context"

    payabli "github.com/payabli/sdk-go"
    client "github.com/payabli/sdk-go/client"
)

func do() {
    client := client.NewClient()
    request := &payabli.ListBillingProfilesRequest{
        FromRecord: payabli.Int64(
            int64(0),
        ),
        LimitRecord: payabli.Int64(
            int64(20),
        ),
    }
    client.Billing.ListProfiles(
        context.TODO(),
        int64(123),
        request,
    )
}

```

```php ListProfiles
<?php

namespace Example;

use Payabli\PayabliClient;
use Payabli\Billing\Requests\ListBillingProfilesRequest;

$client = new PayabliClient();
$client->billing->listProfiles(
    123,
    new ListBillingProfilesRequest([
        'fromRecord' => 0,
        'limitRecord' => 20,
    ]),
);

```

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

url = URI("https://api-sandbox.payabli.com/api/billing/configuration/org/123?fromRecord=0&limitRecord=20")

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

request = Net::HTTP::Get.new(url)

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

```swift ListProfiles
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api-sandbox.payabli.com/api/billing/configuration/org/123?fromRecord=0&limitRecord=20")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"

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()
```

Each record identifies the profile's `serviceVertical` (`PayIn`, `PayOut`, or `PayOps`), its owning `business` entity, and the `entitiesAssigned` counts. Use `serviceVertical` and `business` to find the profile you want to inspect next.

### Response (200)

```json
{
  "summary": {
    "pageIdentifier": "E8955DBE2D534C80B9AF",
    "pageSize": 20,
    "totalPages": 1,
    "totalRecords": 2
  },
  "records": [
    {
      "id": 695,
      "versionId": 1322,
      "versionNumber": 1,
      "business": {
        "entityType": "Organization",
        "entityId": 123
      },
      "serviceVertical": "PayOut",
      "name": "PayOut Default Configuration",
      "feeType": "Flat",
      "createdAt": "2026-01-01T00:00:00Z",
      "updatedAt": "2026-01-01T00:00:00Z",
      "entitiesAssigned": {
        "organizations": 11,
        "paypoints": 2,
        "templates": 2,
        "applications": 357
      },
      "parentId": "1:123",
      "countOfEvents": 10
    },
    {
      "id": 1,
      "versionId": 4229,
      "versionNumber": 31,
      "business": {
        "entityType": "Organization",
        "entityId": 123
      },
      "serviceVertical": "PayIn",
      "name": "Default PayIn Profile",
      "feeType": "Flat",
      "createdAt": "2026-01-01T00:00:00Z",
      "updatedAt": "2026-01-01T00:00:00Z",
      "entitiesAssigned": {
        "organizations": 11,
        "paypoints": 2,
        "templates": 0,
        "applications": 13
      },
      "parentId": "1:123",
      "countOfEvents": 11
    }
  ]
}
```

Narrow the list with the `profileName`, `feeType`, `serviceVertical`, and `profileId` query parameters. For example, filter to an organization's Pay In flat-rate profiles:

### Request

GET [https://api-sandbox.payabli.com/api/billing/configuration/org/\{orgId}](https://api-sandbox.payabli.com/api/billing/configuration/org/\{orgId})

```curl FilterByVertical
curl -G https://api-sandbox.payabli.com/api/billing/configuration/org/123 \
     -d feeType=1 \
     -d fromRecord=0 \
     -d limitRecord=20 \
     -d serviceVertical=1
```

```typescript FilterByVertical
import { PayabliClient } from "@payabli/sdk-node";

async function main() {
    const client = new PayabliClient();
    await client.billing.listProfiles(123, {
        feeType: [
            1,
        ],
        fromRecord: 0,
        limitRecord: 20,
        serviceVertical: [
            1,
        ],
    });
}
main();

```

```python FilterByVertical
from payabli import payabli

client = payabli()

client.billing.list_profiles(
    org_id=123,
    fee_type=[
        1
    ],
    from_record=0,
    limit_record=20,
    service_vertical=[
        1
    ],
)

```

```java FilterByVertical
package com.example.usage;

import io.github.payabli.api.PayabliApiClient;
import io.github.payabli.api.resources.billing.requests.ListBillingProfilesRequest;
import java.util.Arrays;

public class Example {
    public static void main(String[] args) {
        PayabliApiClient client = PayabliApiClient
            .builder()
            .build();

        client.billing().listProfiles(
            123L,
            ListBillingProfilesRequest
                .builder()
                .feeType(
                    Arrays.asList(1)
                )
                .serviceVertical(
                    Arrays.asList(1)
                )
                .fromRecord(0L)
                .limitRecord(20L)
                .build()
        );
    }
}
```

```csharp FilterByVertical
using PayabliApi;
using System.Threading.Tasks;
using System.Collections.Generic;

namespace Usage;

public class Example
{
    public async Task Do() {
        var client = new PayabliApiClient();

        await client.Billing.ListProfilesAsync(
            123L,
            new ListBillingProfilesRequest {
                FeeType = new List<int>(){
                    1,
                }
                ,
                FromRecord = 0L,
                LimitRecord = 20L,
                ServiceVertical = new List<int>(){
                    1,
                }

            }
        );
    }

}

```

```go FilterByVertical
package example

import (
    context "context"

    payabli "github.com/payabli/sdk-go"
    client "github.com/payabli/sdk-go/client"
)

func do() {
    client := client.NewClient()
    request := &payabli.ListBillingProfilesRequest{
        FeeType: []*int{
            payabli.Int(
                1,
            ),
        },
        FromRecord: payabli.Int64(
            int64(0),
        ),
        LimitRecord: payabli.Int64(
            int64(20),
        ),
        ServiceVertical: []*int{
            payabli.Int(
                1,
            ),
        },
    }
    client.Billing.ListProfiles(
        context.TODO(),
        int64(123),
        request,
    )
}

```

```php FilterByVertical
<?php

namespace Example;

use Payabli\PayabliClient;
use Payabli\Billing\Requests\ListBillingProfilesRequest;

$client = new PayabliClient();
$client->billing->listProfiles(
    123,
    new ListBillingProfilesRequest([
        'feeType' => [
            1,
        ],
        'fromRecord' => 0,
        'limitRecord' => 20,
        'serviceVertical' => [
            1,
        ],
    ]),
);

```

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

url = URI("https://api-sandbox.payabli.com/api/billing/configuration/org/123?feeType=%5B1%5D&fromRecord=0&limitRecord=20&serviceVertical=%5B1%5D")

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

request = Net::HTTP::Get.new(url)

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

```swift FilterByVertical
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api-sandbox.payabli.com/api/billing/configuration/org/123?feeType=%5B1%5D&fromRecord=0&limitRecord=20&serviceVertical=%5B1%5D")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"

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()
```

Page through results with `limitRecord` (default `20`) and `fromRecord`. Passing `limitRecord=0` returns no records, so use a positive page size. An organization with no profiles returns `200 OK` with an empty `records` array.

#### View the profile assigned to an entity

After you know the vertical and entity you want to view billing details for, call the View billing profile endpoint to fetch the full profile — including its billable events and fee schedules.

The path takes the service group, the entity type, and the entity ID. The service group accepts `PayIn` or `PayOut` only. The entity type is `Organization`, `Paypoint`, `Template`, or `Application`.

### Request

GET [https://api-sandbox.payabli.com/api/billing/configuration/\{serviceGroup}/\{entityType}/\{entityId}](https://api-sandbox.payabli.com/api/billing/configuration/\{serviceGroup}/\{entityType}/\{entityId})

```curl
curl https://api-sandbox.payabli.com/api/billing/configuration/PayIn/Organization/123
```

```typescript
import { PayabliClient } from "@payabli/sdk-node";

async function main() {
    const client = new PayabliClient();
    await client.billing.getProfile(123, "Organization", "PayIn");
}
main();

```

```python
from payabli import payabli

client = payabli()

client.billing.get_profile(
    entity_id=123,
    entity_type="Organization",
    service_group="PayIn",
)

```

```java
package com.example.usage;

import io.github.payabli.api.PayabliApiClient;
import io.github.payabli.api.resources.billing.types.GetProfileBillingRequestEntityType;
import io.github.payabli.api.resources.billing.types.GetProfileBillingRequestServiceGroup;

public class Example {
    public static void main(String[] args) {
        PayabliApiClient client = PayabliApiClient
            .builder()
            .build();

        client.billing().getProfile(GetProfileBillingRequestServiceGroup.PAY_IN, GetProfileBillingRequestEntityType.ORGANIZATION, 123L);
    }
}
```

```csharp
using PayabliApi;
using System.Threading.Tasks;

namespace Usage;

public class Example
{
    public async Task Do() {
        var client = new PayabliApiClient();

        await client.Billing.GetProfileAsync(
            GetProfileBillingRequestServiceGroup.PayIn,
            GetProfileBillingRequestEntityType.Organization,
            123L
        );
    }

}

```

```go
package example

import (
    context "context"

    payabli "github.com/payabli/sdk-go"
    client "github.com/payabli/sdk-go/client"
)

func do() {
    client := client.NewClient()
    client.Billing.GetProfile(
        context.TODO(),
        payabli.GetProfileBillingRequestServiceGroupPayIn.Ptr(),
        payabli.GetProfileBillingRequestEntityTypeOrganization.Ptr(),
        int64(123),
    )
}

```

```php
<?php

namespace Example;

use Payabli\PayabliClient;
use Payabli\Billing\Types\GetProfileBillingRequestEntityType;
use Payabli\Billing\Types\GetProfileBillingRequestServiceGroup;

$client = new PayabliClient();
$client->billing->getProfile(
    123,
    GetProfileBillingRequestEntityType::Organization->value,
    GetProfileBillingRequestServiceGroup::PayIn->value,
);

```

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

url = URI("https://api-sandbox.payabli.com/api/billing/configuration/PayIn/Organization/123")

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

request = Net::HTTP::Get.new(url)

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

```swift
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api-sandbox.payabli.com/api/billing/configuration/PayIn/Organization/123")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"

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()
```

The response returns the profile's `billableEvents`, each with the `feeSchedules` that apply to it.

### Response (200)

```json
{
  "id": 1,
  "versionId": 4229,
  "versionNumber": 31,
  "business": {
    "entityType": 1,
    "entityId": 123
  },
  "name": "Default PayIn Profile",
  "feeType": 1,
  "createdAt": "2026-01-01T00:00:00Z",
  "updatedAt": "2026-01-01T00:00:00Z",
  "parentId": "1:123",
  "billableEvents": [
    {
      "id": 1,
      "name": "payin-card-sale-all",
      "vertical": 1,
      "service": 1,
      "serviceType": 0,
      "eventType": 4,
      "eventGroup": 5,
      "eventSource": 0,
      "regionType": 1,
      "feeSchedules": [
        {
          "id": 13419,
          "value": 0.3,
          "rate": 2.9,
          "passthrough": 0,
          "payor": {
            "entityType": 1,
            "entityId": 123
          },
          "collector": {
            "entityType": 1,
            "entityId": 123
          },
          "overflowPayor": null,
          "overflowCollectionSchedule": null,
          "minimumTotal": null,
          "maximumTotal": null,
          "effectiveDate": "2026-01-01T00:00:00Z",
          "expirationDate": null,
          "createdAt": "2026-01-01T00:00:00Z",
          "updatedAt": "2026-01-01T00:00:00Z",
          "createdBy": "395",
          "collectionSchedule": 2,
          "billDate": 1,
          "overrideFeeScheduleId": null,
          "feeType": 1
        }
      ]
    }
  ]
}
```

If the entity exists but has no profile assigned, the call returns `404 Not Found`.

## Read a fee schedule

Each fee schedule describes one charge. These fields carry the pricing terms:

| Field                | Description                                                                                                                                                                                                                                            |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `feeType`            | The pricing model: `1` (Flat) or `2` (ICP, interchange-plus).                                                                                                                                                                                          |
| `value`              | The flat-fee component (for example, `0.30`).                                                                                                                                                                                                          |
| `rate`               | The percentage-rate component (for example, `2.9`).                                                                                                                                                                                                    |
| `payor`, `collector` | Who pays the fee and who collects it. These map to the absorb, service, and bill-to-parent models described in [Merchant processing pricing and fees](/guides/pay-ops-billing-and-fees-overview#who-pays-the-fees). Either can be `null` when not set. |
| `collectionSchedule` | How often the fee is collected: `1` (Daily) or `2` (Monthly). When set, `billDate` is the day of the month a monthly bill is applied.                                                                                                                  |

When an event has more than one fee schedule, check both `effectiveDate` and `expirationDate` to find the one in effect — `effectiveDate` drives ordering, and a `null` `expirationDate` means no end date. For the full field list and every enum mapping, see the [View billing profile](/developers/api-reference/billing/view-billing-profile) reference.

## Related resources

See these related resources to help you get the most out of Payabli.

#### References

* **[List billing profiles](/developers/api-reference/billing/list-billing-profiles)** - List every billing profile that belongs to an organization
* **[View billing profile](/developers/api-reference/billing/view-billing-profile)** - Read the full profile assigned to an entity, with its fee schedules

#### Related topics

* **[Merchant processing pricing and fees](/guides/pay-ops-billing-and-fees-overview)** - Fee structures, fee types, and who pays fees