convenience_fees

delete_config

POST

/api/v2/convenience_fees/delete_config

Reset a per-state scope back to inherit (admin only).

delete_config › Request Body

Request payload for /api/v2/convenience_fees/delete_config. Removes a per-state scope's convenience-fee rows so reads fall back to the broader tier. Admin-only. Global cannot be reset, so location_id is required.

request-delete_config

location_id

string · uuid · required

Business-location UUID whose override should be removed.

delete_config › Responses

200

Response for /api/v2/convenience_fees/delete_config. Echoes the scope that was cleared.

response-delete_config

required

success

boolean · required

Whether the operation was successful

object · required

list_scopes

POST

/api/v2/convenience_fees/list_scopes

List configurable scopes for the Payments page

list_scopes › Request Body

Request payload for /api/v2/convenience_fees/list_scopes. Takes no parameters -- returns every business-location scope plus integration/admin flags for the Payments settings page.

request-list_scopes

list_scopes › Responses

200

Response for /api/v2/convenience_fees/list_scopes. The configurable scopes (Global is implicit; this lists the per-state business locations) with a has_custom flag, plus the payment-processor integration status and the caller's admin flag. The scopes list is redacted (empty) for non-admin callers.

response-list_scopes

required

success

boolean · required

Whether the operation was successful

object · required

retrieve_config

POST

/api/v2/convenience_fees/retrieve_config

Resolved convenience-fee config for one scope (admin only).

Code
Omit ``location_id`` for the carrier-wide global default. Returns
``convenience_fees`` (the raw values stored at this scope; NULL means
inherit) plus ``inherited_convenience_fees`` placeholders the resolver
falls through to when a field is blank. Both objects are keyed by the
snake_case logical field names.

retrieve_config › Request Body

Request payload for /api/v2/convenience_fees/retrieve_config. Returns the convenience-fee config stored at one scope plus the inherited placeholders. Admin-only.

request-retrieve_config

location_id

string | null · uuid

Business-location UUID for a per-state scope. Omit or pass null for the carrier-wide global default.

retrieve_config › Responses

200

Response for /api/v2/convenience_fees/retrieve_config. convenience_fees holds the raw values stored at the requested scope. For the legacy fee text columns (formula_*, description_*, disclosure_surcharge, disclosure_authorization) NULL is a BLANK OVERRIDE at this scope ($0 fee / blank copy), NOT 'inherit' -- re-inheriting is via delete_config (Remove state override). The INHERIT-ON-NULL fields (BC-16104) -- disclosure_style, capture_authorization, disclosure_first_party, disclosure_third_party -- fall through to the broader tier when NULL. inherited_convenience_fees holds what the resolver falls through to when the scope has no override row (what Remove state override would revert to), used as form placeholders. Both share the same nine logical keys.

response-retrieve_config

required

success

boolean · required

Whether the operation was successful

object · required

POST/api/v2/convenience_fees/retrieve_config

curl --request POST \
  --url /api/v2/convenience_fees/retrieve_config \
  --header 'Content-Type: application/json' \
  --data '
{
  "location_id": "00000000-0000-0000-0000-000000000000"
}
'

Example Request Body

{
  "location_id": "00000000-0000-0000-0000-000000000000"
}

json

Example Responses

{
  "messages": [
    "string"
  ],
  "success": true,
  "data": {
    "convenience_fees": {
      "disclosure_style": "disclosure_style",
      "formula_cc": "formula_cc",
      "formula_ach": "formula_ach",
      "formula_debit": "formula_debit",
      "description_cc": "description_cc",
      "description_ach": "description_ach",
      "description_debit": "description_debit",
      "disclosure_surcharge": "disclosure_surcharge",
      "disclosure_authorization": "disclosure_authorization",
      "capture_authorization": true,
      "disclosure_first_party": "disclosure_first_party",
      "disclosure_third_party": "disclosure_third_party"
    },
    "inherited_convenience_fees": {
      "disclosure_style": "disclosure_style",
      "formula_cc": "formula_cc",
      "formula_ach": "formula_ach",
      "formula_debit": "formula_debit",
      "description_cc": "description_cc",
      "description_ach": "description_ach",
      "description_debit": "description_debit",
      "disclosure_surcharge": "disclosure_surcharge",
      "disclosure_authorization": "disclosure_authorization",
      "capture_authorization": true,
      "disclosure_first_party": "disclosure_first_party",
      "disclosure_third_party": "disclosure_third_party"
    }
  }
}

json

application/json

store_config

POST

/api/v2/convenience_fees/store_config

Persist convenience-fee config at one scope (admin only).

Code
``payload`` carries an optional ``location_id`` (Global when omitted/null)
and a ``convenience_fees`` object of snake_case logical keys. Empty-string
clears a column to NULL (blank override at this scope); omitted keys are
left untouched (partial update). ``ConvenienceFeeConfigModel`` owns the
wire contract + casing, so the service never sees frontend key names.

store_config › Request Body

Request payload for /api/v2/convenience_fees/store_config. Persists convenience-fee config at one scope (Global when location_id is omitted/null, otherwise a per-state override). Admin-only. Every convenience_fees key is optional (partial update). BLANK-OVERRIDE fields -- the legacy fee text columns formula_*, description_*, disclosure_surcharge, disclosure_authorization: an explicit empty string clears the column to NULL, which the resolver treats as a BLANK OVERRIDE at this scope (resolves to $0 fee / blank copy) -- it does NOT re-inherit from the broader tier. To re-inherit, remove the entire scope via /api/v2/convenience_fees/delete_config (the admin Remove state override action). INHERIT-ON-NULL fields (BC-16104) -- disclosure_style, capture_authorization, disclosure_first_party, disclosure_third_party: a blank/NULL there has no override state and falls through to the broader tier rather than blanking.

request-store_config

location_id

string | null · uuid

Business-location UUID for a per-state scope. Omit or pass null for the carrier-wide global default.

object

Snake_case logical-key dict. Missing keys leave the existing column untouched. For the text columns, an empty string clears the column to NULL = a blank override at this scope ($0 fee / blank copy), NOT inherit; re-inherit only via delete_config. disclosure_style is the exception (a blank falls through to the broader tier).

store_config › Responses

200

Response for /api/v2/convenience_fees/store_config. Echoes the scope that was written.

response-store_config

required

success

boolean · required

Whether the operation was successful. False when the caller lacks admin permission or disclosure_style is outside the allowed enum.

object · required

POST/api/v2/convenience_fees/store_config

curl --request POST \
  --url /api/v2/convenience_fees/store_config \
  --header 'Content-Type: application/json' \
  --data '
{
  "location_id": "00000000-0000-0000-0000-000000000000",
  "convenience_fees": {
    "disclosure_style": "standard",
    "formula_cc": "formula_cc",
    "formula_ach": "formula_ach",
    "formula_debit": "formula_debit",
    "description_cc": "description_cc",
    "description_ach": "description_ach",
    "description_debit": "description_debit",
    "disclosure_surcharge": "disclosure_surcharge",
    "disclosure_authorization": "disclosure_authorization",
    "capture_authorization": true,
    "disclosure_first_party": "disclosure_first_party",
    "disclosure_third_party": "disclosure_third_party"
  }
}
'

Example Request Body

{
  "location_id": "00000000-0000-0000-0000-000000000000",
  "convenience_fees": {
    "disclosure_style": "standard",
    "formula_cc": "formula_cc",
    "formula_ach": "formula_ach",
    "formula_debit": "formula_debit",
    "description_cc": "description_cc",
    "description_ach": "description_ach",
    "description_debit": "description_debit",
    "disclosure_surcharge": "disclosure_surcharge",
    "disclosure_authorization": "disclosure_authorization",
    "capture_authorization": true,
    "disclosure_first_party": "disclosure_first_party",
    "disclosure_third_party": "disclosure_third_party"
  }
}

json

Example Responses

{
  "messages": [
    "string"
  ],
  "success": true,
  "data": {
    "location_id": "00000000-0000-0000-0000-000000000000"
  }
}

json

application/json

configurations copilot_skills