Manage payment operationsPricing & fees

Retrieve pricing with the billing profile API

List an organization's billing profiles and read the pricing assigned to an entity
View as MarkdownOpen in Claude
Applies to:DevelopersPartners

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.

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

1

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.

GET
/api/billing/configuration/org/:orgId
1curl -G https://api-sandbox.payabli.com/api/billing/configuration/org/123 \
2     -d fromRecord=0 \
3     -d limitRecord=20
Try it

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
1{
2  "summary": {
3    "pageIdentifier": "E8955DBE2D534C80B9AF",
4    "pageSize": 20,
5    "totalPages": 1,
6    "totalRecords": 2
7  },
8  "records": [
9    {
10      "id": 695,
11      "versionId": 1322,
12      "versionNumber": 1,
13      "business": {
14        "entityType": "Organization",
15        "entityId": 123
16      },
17      "serviceVertical": "PayOut",
18      "name": "PayOut Default Configuration",
19      "feeType": "Flat",
20      "createdAt": "2026-01-01T00:00:00Z",
21      "updatedAt": "2026-01-01T00:00:00Z",
22      "entitiesAssigned": {
23        "organizations": 11,
24        "paypoints": 2,
25        "templates": 2,
26        "applications": 357
27      },
28      "parentId": "1:123",
29      "countOfEvents": 10
30    },
31    {
32      "id": 1,
33      "versionId": 4229,
34      "versionNumber": 31,
35      "business": {
36        "entityType": "Organization",
37        "entityId": 123
38      },
39      "serviceVertical": "PayIn",
40      "name": "Default PayIn Profile",
41      "feeType": "Flat",
42      "createdAt": "2026-01-01T00:00:00Z",
43      "updatedAt": "2026-01-01T00:00:00Z",
44      "entitiesAssigned": {
45        "organizations": 11,
46        "paypoints": 2,
47        "templates": 0,
48        "applications": 13
49      },
50      "parentId": "1:123",
51      "countOfEvents": 11
52    }
53  ]
54}

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

GET
/api/billing/configuration/org/:orgId
1curl -G https://api-sandbox.payabli.com/api/billing/configuration/org/123 \
2     -d feeType=1 \
3     -d fromRecord=0 \
4     -d limitRecord=20 \
5     -d serviceVertical=1
Try it

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.

2

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.

GET
/api/billing/configuration/:serviceGroup/:entityType/:entityId
1curl https://api-sandbox.payabli.com/api/billing/configuration/PayIn/Organization/123
Try it

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

Response
1{
2  "id": 1,
3  "versionId": 4229,
4  "versionNumber": 31,
5  "business": {
6    "entityType": 1,
7    "entityId": 123
8  },
9  "name": "Default PayIn Profile",
10  "feeType": 1,
11  "createdAt": "2026-01-01T00:00:00Z",
12  "updatedAt": "2026-01-01T00:00:00Z",
13  "parentId": "1:123",
14  "billableEvents": [
15    {
16      "id": 1,
17      "name": "payin-card-sale-all",
18      "vertical": 1,
19      "service": 1,
20      "serviceType": 0,
21      "eventType": 4,
22      "eventGroup": 5,
23      "eventSource": 0,
24      "regionType": 1,
25      "feeSchedules": [
26        {
27          "id": 13419,
28          "value": 0.3,
29          "rate": 2.9,
30          "passthrough": 0,
31          "payor": {
32            "entityType": 1,
33            "entityId": 123
34          },
35          "collector": {
36            "entityType": 1,
37            "entityId": 123
38          },
39          "overflowPayor": null,
40          "overflowCollectionSchedule": null,
41          "minimumTotal": null,
42          "maximumTotal": null,
43          "effectiveDate": "2026-01-01T00:00:00Z",
44          "expirationDate": null,
45          "createdAt": "2026-01-01T00:00:00Z",
46          "updatedAt": "2026-01-01T00:00:00Z",
47          "createdBy": "395",
48          "collectionSchedule": 2,
49          "billDate": 1,
50          "overrideFeeScheduleId": null,
51          "feeType": 1
52        }
53      ]
54    }
55  ]
56}

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:

FieldDescription
feeTypeThe pricing model: 1 (Flat) or 2 (ICP, interchange-plus).
valueThe flat-fee component (for example, 0.30).
rateThe percentage-rate component (for example, 2.9).
payor, collectorWho 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. Either can be null when not set.
collectionScheduleHow 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 reference.

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