API reference

The CashSDK REST API: base URLs, conventions, versioning, and pagination.

The CashSDK API is a RESTful interface over HTTPS. Every request and response body is JSON. Resources are addressed by stable, prefixed identifiers (for example app_, txn_, evt_), and every mutating call is authenticated with a secret key.

Base URLs#

bash

https://api.cashsdk.com

All endpoints live under the /v1 prefix, so a full URL looks like https://api.cashsdk.com/v1/apps.

Conventions#

HTTPS + JSON. Send Content-Type: application/json on requests with a body. Responses are always JSON.
Authentication. Pass a bearer token in the Authorization header on every request. See Authentication.
Identifiers. IDs are opaque strings with a type prefix. Treat them as case-sensitive and do not parse their contents.
Timestamps. All timestamps are ISO 8601 strings in UTC, for example 2026-07-17T18:24:05Z.
Money. Monetary amounts are integers in the currency's minor units (cents for USD), paired with an ISO 4217 currency code.

Versioning#

The API is versioned in the URL path (/v1). Backwards-incompatible changes ship under a new version prefix; additive changes (new fields, new endpoints, new event types) may appear within v1 without notice, so write clients that ignore unknown fields.

Deprecation policy#

Backwards-incompatible changes ship under a new version prefix, and we do not remove a version the day its successor lands. What you can plan against:

Change	Notice
Additive (a new field, endpoint, event type, or enum value)	None. Write clients that ignore unknown fields and tolerate unknown enum values.
Deprecating a field or endpoint within `/v1`	At least 90 days, announced in the changelog and by email to workspace owners. Affected responses carry a `Sunset` header with the removal date.
Retiring a major version	At least 12 months after its successor is generally available.

The same commitments cover the webhook event catalogue and the SDK public API, both are contracts you build against, so both get the same notice. A new webhook event type may appear at any time; your handler should ignore types it does not recognise rather than error.

If a change is forced on us by Apple or Google (they retire APIs on their own schedule) we will tell you as early as we are able and carry as much of the migration as we can inside the SDK, but we cannot promise 90 days for something we get 30 days of notice on ourselves.

SDK versioning and support#

Both SDKs follow semantic versioning.

The current major is supported for at least 12 months after its successor ships.
Security fixes are backported to the previous minor.
Never re-point a released tag. JitPack caches a tag's build permanently, so force-pushing one ships stale bytes silently to everyone who resolves it afterwards.

Pagination#

List endpoints are cursor-paginated. Pass limit to cap the page size and cursor to fetch the next page. Every list response is wrapped in an envelope:

json

{
  "data": [
    { "id": "txn_9f2a1c", "app_user_id": "u_812", "amount": 899 }
  ],
  "has_more": true,
  "next_cursor": "eyJpZCI6InR4bl85ZjJhMWMifQ"
}

limitinteger

Maximum number of objects to return per page. Defaults to 20, capped at 100.

cursorstring

An opaque cursor returned as next_cursor on the previous page. Omit it to start from the first page.

Keep requesting with the returned next_cursor until has_more is false.