List Mandates

curl "https://sandbox.api.prava.space/v1/mandates?customer_id=user_123&standing_only=true" \
  -H "Authorization: Bearer sk_test_..."

import requests

resp = requests.get(
    "https://sandbox.api.prava.space/v1/mandates",
    headers={"Authorization": "Bearer sk_test_..."},
    params={"customer_id": "user_123", "standing_only": "true"},
)

const resp = await fetch(
  "https://sandbox.api.prava.space/v1/mandates?customer_id=user_123&standing_only=true",
  {
    headers: {
      Authorization: "Bearer sk_test_...",
    },
  }
);

{
  "mandates": [
    {
      "id": "mdt_123",
      "status": "active",
      "state": "available",
      "recurringFrequency": "monthly",
      "merchantScope": "listed",
      "merchantName": "Acme Store",
      "approvedAmount": "40.00",
      "remaining": "40.00",
      "currency": "USD",
      "validUntil": "2027-07-26T00:00:00Z",
      "renewsAt": "2026-08-26T00:00:00Z",
      "lastCharge": null,
      "createdAt": "2026-07-26T00:00:00Z",
      "updatedAt": "2026-07-26T00:00:00Z"
    }
  ]
}

{
  "error": { "code": "AUTH_REQUIRED", "message": "Missing or invalid credentials" }
}

{
  "error": { "code": "FORBIDDEN", "message": "Caller may not list these mandates" }
}

GET

mandates

curl "https://sandbox.api.prava.space/v1/mandates?customer_id=user_123&standing_only=true" \
  -H "Authorization: Bearer sk_test_..."

import requests

resp = requests.get(
    "https://sandbox.api.prava.space/v1/mandates",
    headers={"Authorization": "Bearer sk_test_..."},
    params={"customer_id": "user_123", "standing_only": "true"},
)

const resp = await fetch(
  "https://sandbox.api.prava.space/v1/mandates?customer_id=user_123&standing_only=true",
  {
    headers: {
      Authorization: "Bearer sk_test_...",
    },
  }
);

{
  "mandates": [
    {
      "id": "mdt_123",
      "status": "active",
      "state": "available",
      "recurringFrequency": "monthly",
      "merchantScope": "listed",
      "merchantName": "Acme Store",
      "approvedAmount": "40.00",
      "remaining": "40.00",
      "currency": "USD",
      "validUntil": "2027-07-26T00:00:00Z",
      "renewsAt": "2026-08-26T00:00:00Z",
      "lastCharge": null,
      "createdAt": "2026-07-26T00:00:00Z",
      "updatedAt": "2026-07-26T00:00:00Z"
    }
  ]
}

{
  "error": { "code": "AUTH_REQUIRED", "message": "Missing or invalid credentials" }
}

{
  "error": { "code": "FORBIDDEN", "message": "Caller may not list these mandates" }
}

List the caller’s mandates. Merchant keys pass customer_id; control-plane callers (dashboard) scope by dashboard_user_id (+ agent_id). GET /v1/mandates · Authenticated with your secret key. Need to create a mandate? Mandate creation is part of the Session APIs — create a mandate with a mandate_setup block on Create Session.

Query parameters

string

Filter to one customer — the external_user_id (the user_id used at session creation) or a cus_ id.

boolean

When true, return only standing mandates (exclude the transient per-checkout mandates that every ordinary checkout creates internally).

Response

object[]

Show mandate properties

string

Mandate id (mdt_…).

string

Display-derived usability: available, consumed, or expired.

string

pending, active, paused, consumed, cancelled, or expired.

string

one_time, weekly, monthly, yearly.

string

any or listed.

string

Authorized per-charge cap.

string

Remaining spend this window — indicative for display; the enforced ceiling is the amount cap at the card-network level.

string

string | null

Next cycle boundary for recurring mandates.

object | null

{ status, at }.

string

Notes

Use the returned id with Get a Mandate, Charge a Mandate, or the lifecycle actions.

Error responses

Status	Code	Cause
401	`AUTH_REQUIRED`	Missing or invalid credentials
403	`FORBIDDEN`	Caller may not list these mandates

curl "https://sandbox.api.prava.space/v1/mandates?customer_id=user_123&standing_only=true" \
  -H "Authorization: Bearer sk_test_..."

import requests

resp = requests.get(
    "https://sandbox.api.prava.space/v1/mandates",
    headers={"Authorization": "Bearer sk_test_..."},
    params={"customer_id": "user_123", "standing_only": "true"},
)

const resp = await fetch(
  "https://sandbox.api.prava.space/v1/mandates?customer_id=user_123&standing_only=true",
  {
    headers: {
      Authorization: "Bearer sk_test_...",
    },
  }
);

{
  "mandates": [
    {
      "id": "mdt_123",
      "status": "active",
      "state": "available",
      "recurringFrequency": "monthly",
      "merchantScope": "listed",
      "merchantName": "Acme Store",
      "approvedAmount": "40.00",
      "remaining": "40.00",
      "currency": "USD",
      "validUntil": "2027-07-26T00:00:00Z",
      "renewsAt": "2026-08-26T00:00:00Z",
      "lastCharge": null,
      "createdAt": "2026-07-26T00:00:00Z",
      "updatedAt": "2026-07-26T00:00:00Z"
    }
  ]
}

{
  "error": { "code": "AUTH_REQUIRED", "message": "Missing or invalid credentials" }
}

{
  "error": { "code": "FORBIDDEN", "message": "Caller may not list these mandates" }
}

Server-Side API

Reference

Query parameters

Response

Notes

Error responses

​Query parameters

​Response

​Notes

​Error responses

Query parameters

Response

Notes

Error responses