> 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

# API response and request conventions

> Understand Payabli's response shapes, field casing, date formats, and query conventions, and how to handle them

**When in doubt, check the endpoint's API reference.** It's the source of truth for a specific endpoint's fields, formats, and response shape. The conventions below show up across many Payabli endpoints but aren't applied uniformly, so don't assume one endpoint behaves like another. Handle them defensively.

## Response shapes

Payabli responses come in three shapes. Don't assume one envelope or reuse another call's shape. Check each endpoint's reference page.

| Shape                                                     | Where you see it                                                             | How success reads                                                                            |
| --------------------------------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `code`, `reason`, `data`                                  | v2 Pay In (`/v2/MoneyIn/*`)                                                  | A `code` with an `A` prefix                                                                  |
| `isSuccess`, `responseData`                               | Many v1 endpoints (Customer, Vendor, Invoice, Bill, Subscription, Money Out) | `isSuccess: true`, with `responseCode`, `responseText`, and `responseData` (often a bare ID) |
| Varies (bare object, or `{ Summary, Records }` for lists) | Single reads (`GET /Customer/{id}`) and Query lists (`GET /Query/...`)       | Confirm the shape per endpoint, and treat a `2xx` status as success                          |

The unified `A`-prefixed response codes apply to **v2 Pay In endpoints only**, not the whole platform. Other endpoints carry their own `responseCode`/`resultCode` and `isSuccess` flag. See the [Pay In unified response codes reference](/guides/pay-in-unified-response-codes-reference).

## Field casing and field names

Casing and field names aren't consistent across the API. The customer ID is one example: it's `customerId` on a customer record, but `PayorId` or `Customer.customerId` on a transaction. Other variations you'll run into (not a complete list):

* **Request vs. response casing:** for example, you send `firstname` and read back `Firstname`.
* **The same value in two casings:** for example, both `vendorId` and `VendorId` appear across endpoints.
* **Mixed casing within one record:** for example, `customerId` and `customerNumber` (camelCase) next to `Firstname`, `Email`, and `Balance` (PascalCase).
* **`Id` as a prefix or a suffix:** for example, `IdBill` vs. `billId`, or `idInvoice` vs. `invoiceId`.

Don't try to memorize the variations. Confirm the exact field names for an endpoint in its API reference, and normalize at the boundary. Treat response field names as case-insensitive, and map each response into your own typed model as soon as you receive it. A small tolerant helper does it once:

```javascript
function field(obj, ...names) {
  for (const n of names) if (obj?.[n] != null) return obj[n];
  const lower = Object.fromEntries(
    Object.entries(obj ?? {}).map(([k, v]) => [k.toLowerCase(), v])
  );
  for (const n of names) if (lower[n.toLowerCase()] != null) return lower[n.toLowerCase()];
  return undefined;
}
```

When you join records, collect the identifier from any of the names it might use. The customer ID on a transaction is the common trap.

## Date formats

Accepted date formats vary by endpoint and aren't confirmed uniform across the API. Check the endpoint's reference for what it accepts. Where you have a choice, use ISO `YYYY-MM-DD` and keep it consistent. Some fields also accept sentinels. For example, a subscription's `endDate` accepts `untilcancelled` for an open-ended autopay.

## Querying data

The Query API is the read, list, and reporting layer. Send a GET request to `/api/Query/{resource}/{entry}` for customers, transactions, invoices, bills, subscriptions, chargebacks, and more.

The supported filters, pagination, and response shape **vary by query endpoint**, so check the endpoint's reference for what it accepts. Common patterns:

* **Filters:** `field(op)=value`, where `op` is typically `eq`, `gt`, `ge`, `lt`, `le`, `ne`, `ct` (contains), or `in`. Which fields and operators an endpoint accepts differ.
* **Pagination:** `limitRecord` (page size) and `fromRecord` (offset), where supported.
* **Envelope:** list responses commonly come back as `{ Summary, Records }` (with `Summary.totalRecords` and `totalPages`), but not every endpoint follows this. Confirm the shape per endpoint.

Where an endpoint takes filters, an unrecognized filter field can be silently ignored, returning all records instead of an error. Verify a scoped query (check the returned count, or confirm a known value in the results) rather than assuming the filter applied.

For the full query syntax and the filter fields each endpoint supports, see the [reporting overview](/guides/pay-ops-reporting-overview).

## Using an SDK

The official SDKs handle authentication, typing, serialization, and field casing for you, so most of the conventions above don't surface when you use one. If you run into a gap, contact the Payabli team. Examples include an operation the SDK doesn't expose, or a request or response that doesn't match what the API accepts.