Create a manage session

​

Lets a donor change or cancel a recurring gift from your account area. Returns a Roster-hosted url (https://flow…/m/{token}) that opens the manage flow for one enrollment at one of your churches. Pass that URL to Roster.open on your account-area page.

  • The donor still confirms with a code sent to their phone. You never change or cancel a gift yourself: the manage session only opens the donor's own flow.
  • url is returned once, on creation only, with a single-use token and a 30-minute TTL. Idempotent replays return the session without url.
  • donor_phone (optional) travels in the POST body and is never echoed back. Today the manage flow does not fill it in: the donor types their phone number and confirms it with the code.
  • An enrollment that is not yours — not at one of your churches, or made through another partner at a church you share — is rejected with the same 400 as one that does not exist.
  • Manage sessions do not appear in GET /v1/donor_sessions/{id} or in partner_session.* events. Changes the donor makes arrive as enrollment events.

Headers

  • Idempotency-Key
    Type: string
    min length:  
    1
    max length:  
    255
    required

    Required on every POST, before any effect: 1–255 visible ASCII characters, no spaces. The key belongs to the first body sent with it on this operation for 30 days from the moment that request arrives, including while that request is running and after a 5xx or a timeout. On an operation that creates a resource (POST /v1/churches, POST /v1/churches/import, POST /v1/church_consents, POST /v1/donor_sessions, POST /v1/manage_sessions, POST /v1/refunds and POST /v1/webhook_endpoints), a key whose request succeeded keeps its body for as long as the resource it created exists. A creation replayed with the same key and body returns the original resource with 200 and changes nothing; a 4xx releases the key.

Body·

required
application/json
  • enrollment_id
    Type: string
    required

    The recurring gift the donor will change or cancel. It must be at one of your churches and not made through another partner.

  • church_id
    Type: string

    Optional. The church of the enrollment, to find it faster.

  • donor_phone
    Type: string

    Donor phone number, including country code (for example +12025550100). Never echoed back. Today the manage flow does not fill it in: the donor types their phone number and confirms it with a code sent to it.

Responses

  • application/json
  • application/json
  • application/problem+json
  • application/problem+json
  • application/problem+json
  • application/problem+json
Request Example for post/v1/manage_sessions
curl https://api.sandbox.rostergiving.com/v1/manage_sessions \
  --request POST \
  --header 'Idempotency-Key: ' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "enrollment_id": "",
  "church_id": "",
  "donor_phone": "+12025550100"
}'

{
  "id": "ms_1a2b3c4d5e6f",
  "url": "https://example.com",
  "status": "created",
  "church_id": "string",
  "enrollment_id": "string",
  "expires_at": "2026-10-22T14:55:08.127Z"
}

Idempotent replay — same session, without url.

Previous
Get a donor session
Next
Donor flow settings