Save donor-flow appearance and data declarations

​

Without church_id, replaces the partner default: read the current settings first and send every property you want to keep, with the version you read as expected_version. A save made by someone else since your read, from the API or the partner portal, is never overwritten: you get 409 with the current settings and version instead. With church_id, replaces that church's own settings and stores only what you send; every property you omit follows the partner default, including later changes to it. To change a church, start from church_settings in GET, apply your change and send it back whole: settings already carries the partner values (and manage_url, refused with church_id), and a property missing from what you send is removed from the church. Uses the same storage as the portal. This does not create a donation or change a donor authorization. Vendor screens are not styled by these properties.

Body·

required
application/json

Without church_id (your default), button_label and the three properties of customization (css, collected_fields, customize_churches) are required. With church_id, send only what the church changes. A property not listed here gets 400, and detail names the field to fix.

  • customization
    Type: object
    required

    Appearance settings and declaration of donor fields your platform intends to prefill. Always sent; with church_id it can be empty, and what it omits comes from the partner default.

    Properties: 3
  • expected_version
    Type: integer
    min:  
    0
    required

    The version from the settings you read (GET /v1/flow-settings, with the same church_id). If someone saved in the meantime, from the API or the partner portal, nothing is saved and you get 409 with the current settings and version.

  • brand_color
    Type: string | null

    Main brand color, written as a hash sign followed by six hexadecimal digits. Without church_id, omitting it (or sending null) removes the saved color and the donor flow uses its standard look. With church_id, omitting it uses the partner default.

  • button_label
    Type: string
    min length:  
    1
    max length:  
    40

    Text on the button in your own website that opens the donor flow. Required without church_id. With church_id, omit it to use the partner default.

  • church_id
    Type: string
    min length:  
    1

    Church whose own appearance you save. Omit it to save the partner default. With it, only the properties you send are stored for the church; the rest follow the partner default.

  • cta_label
    Type: string
    min length:  
    1
    max length:  
    40

    Text on the continue button inside the Roster donor flow. Today the donor flow shows it only on the amount screen, and donor sessions you create start after that screen.

  • display_name
    Type: string
    min length:  
    1
    max length:  
    40

    Name of your platform shown to the donor, kept on one line: line breaks become a space and invisible characters are removed.

  • logo_url
    Type: stringFormat: uri

    HTTPS address of the logo image you host. Today the donor flow shows it only on the amount screen, and donor sessions you create start after that screen. A space or control character anywhere in the address is rejected, and the address is stored and returned in normalized form.

  • manage_url
    Type: stringFormat: uri

    HTTPS address of the page in your account area where donors change or cancel their gift; that page opens a manage session with roster.js. It must be on one of your registered sites. Emails to donors who came through you link there instead of to Roster. A space or control character anywhere in the address is rejected, and the address is stored and returned in normalized form. Workspace-level only: rejected with church_id.

  • support_contact
    Type: stringFormat: email

    Support email address shown to the donor.

Responses

  • application/json
  • application/problem+json
  • application/problem+json
  • application/problem+json
  • application/problem+json
  • application/problem+json
Request Example for put/v1/flow-settings
curl https://api.sandbox.rostergiving.com/v1/flow-settings \
  --request PUT \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "expected_version": 0,
  "church_id": "",
  "button_label": "",
  "brand_color": null,
  "display_name": "",
  "support_contact": "",
  "logo_url": "",
  "cta_label": "",
  "manage_url": "",
  "customization": {
    "customize_churches": true,
    "collected_fields": [
      "donor_phone"
    ],
    "css": {
      "background_color": "",
      "text_color": "",
      "button_color": "",
      "button_text_color": "",
      "input_background": "",
      "input_text_color": "",
      "border_color": "",
      "modal_width": "",
      "border_radius": "",
      "button_radius": "",
      "input_radius": "",
      "font_size": "",
      "padding": "",
      "gap": "",
      "line_height": "",
      "font_family": "Inter"
    }
  }
}'

{
  "version": 0,
  "settings": {
    "button_label": "string",
    "brand_color": null,
    "display_name": "string",
    "support_contact": "hello@example.com",
    "logo_url": "https://example.com",
    "cta_label": "string",
    "manage_url": "https://example.com",
    "customization": {
      "customize_churches": true,
      "collected_fields": [
        "donor_phone"
      ],
      "css": {
        "background_color": "string",
        "text_color": "string",
        "button_color": "string",
        "button_text_color": "string",
        "input_background": "string",
        "input_text_color": "string",
        "border_color": "string",
        "modal_width": "string",
        "border_radius": "string",
        "button_radius": "string",
        "input_radius": "string",
        "font_size": "string",
        "padding": "string",
        "gap": "string",
        "line_height": "string",
        "font_family": "Inter"
      }
    }
  },
  "church_settings": {
    "button_label": "string",
    "brand_color": null,
    "display_name": "string",
    "support_contact": "hello@example.com",
    "logo_url": "https://example.com",
    "cta_label": "string",
    "manage_url": "https://example.com",
    "customization": {
      "customize_churches": true,
      "collected_fields": [
        "donor_phone"
      ],
      "css": {
        "background_color": "string",
        "text_color": "string",
        "button_color": "string",
        "button_text_color": "string",
        "input_background": "string",
        "input_text_color": "string",
        "border_color": "string",
        "modal_width": "string",
        "border_radius": "string",
        "button_radius": "string",
        "input_radius": "string",
        "font_size": "string",
        "padding": "string",
        "gap": "string",
        "line_height": "string",
        "font_family": "Inter"
      }
    }
  },
  "removed": [
    "string"
  ]
}

Settings saved. Without church_id, the partner default as saved. With church_id, the appearance that applies to that church (its own settings over the partner default), the same as GET. removed lists the properties the save took away.

Previous
Read donor-flow appearance and data declarations
Next
Read the sites where the donor flow opens