API Reference

Settings

The Settings API allows you to manage application-wide configurations, such as rules for notifications or parameters for donation widgets. These settings are versatile and can be tailored for different types of components or features within your application.
Each setting is identified by a mountLocation and has a specific type which determines the structure of its settings object.
The Setting Object#A setting object represents a specific configuration in your application. It contains the following properties:
Property
Type
Description
id
string
Unique identifier for the setting.
livemode
boolean
true if the object exists in live mode, or false if it exists in test mode.
type
string
The type of setting (e.g., 'donate', 'notification'). This determines the schema of the settings object.
mount_location
string
An identifier for the component or location where this setting is applied.
active
boolean
true if the setting is currently active.
component_did
string
(Optional) The DID of the component associated with this setting.
description
string
A description of the setting's purpose.
settings
object
An object containing the detailed configuration. Its structure depends on the type field.
created_at
Date
The timestamp when the setting was created.
updated_at
Date
The timestamp when the setting was last updated.
Create a Setting#Creates a new setting for a specified mount location and type.
Parameters#Name
Type
Description
mountLocation
string
Required. A unique identifier for where the setting is used.
description
string
Required. A human-readable description of the setting.
type
string
Required. The type of setting to create, such as 'notification' or 'donate'.
settings
object
Required. A configuration object whose structure depends on the type. See below for examples.
settings.amount
object
For donate type. Contains amount settings: presets (string[]), preset (string), custom (boolean), minimum (string), maximum (string).
settings.btnText
string
For donate type. The text displayed on the donation button.
settings.historyType
`'table'
'avatar'`
settings.self_handle
boolean
For notification type. If true, indicates that notifications are handled by the application itself.
settings.exclude_events
string[]
For notification type. An array of event types to exclude from notifications.
settings.include_events
string[]
For notification type. An array of event types to include in notifications.
active
boolean
(Optional) Whether the setting is active. Defaults to true.
livemode
boolean
(Optional) Whether this setting applies to live mode.
componentDid
string
(Optional) The DID of the component.
Returns#Returns the newly created setting object.
Example#async function createNotificationSetting() {
  try {
    const setting = await payment.settings.create({
      type: 'notification',
      mountLocation: 'user_dashboard_notifications',
      description: 'Controls notifications for the main user dashboard.',
      active: true,
      settings: {
        self_handle: false,
        include_events: ['customer.subscription.renewed', 'invoice.paid'],
      },
    });
    console.log('Setting created:', setting);
  } catch (error) {
    console.error('Error creating setting:', error.message);
  }
}

createNotificationSetting();Example Response#{
  "id": "set_1J2K3L4M5N6O7P8Q",
  "livemode": false,
  "type": "notification",
  "mount_location": "user_dashboard_notifications",
  "active": true,
  "component_did": null,
  "description": "Controls notifications for the main user dashboard.",
  "settings": {
    "self_handle": false,
    "include_events": [
      "customer.subscription.renewed",
      "invoice.paid"
    ]
  },
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z"
}Retrieve a Setting#Retrieves the details of a specific setting by its ID or mount location.
Parameters#Name
Type
Description
mountLocationOrId
string
Required. The unique identifier or mount location of the setting to retrieve.
Returns#Returns the retrieved setting object.
Example#async function getSettingDetails(id) {
  try {
    const setting = await payment.settings.retrieve(id);
    console.log('Setting details:', setting);
  } catch (error) {
    console.error(`Error retrieving setting ${id}:`, error.message);
  }
}

getSettingDetails('set_1J2K3L4M5N6O7P8Q');Example Response#{
  "id": "set_1J2K3L4M5N6O7P8Q",
  "livemode": false,
  "type": "notification",
  "mount_location": "user_dashboard_notifications",
  "active": true,
  "component_did": null,
  "description": "Controls notifications for the main user dashboard.",
  "settings": {
    "self_handle": false,
    "include_events": [
      "customer.subscription.renewed",
      "invoice.paid"
    ]
  },
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:05:00.000Z"
}Update a Setting#Updates an existing setting's properties. You can modify its status, description, or the nested settings object.
Parameters#Name
Type
Description
mountLocationOrId
string
Required. The identifier or mount location of the setting to update.
updateData
object
Required. An object containing the fields to update.
updateData.active
boolean
(Optional) New active status for the setting.
updateData.description
string
(Optional) New description for the setting.
updateData.settings
object
(Optional) A partial object to merge with the existing settings.
Returns#Returns the updated setting object.
Example#async function updateSetting(id) {
  try {
    const updatedSetting = await payment.settings.update(id, {
      description: 'Updated dashboard notification settings.',
      settings: {
        exclude_events: ['invoice.created'],
      },
    });
    console.log('Setting updated:', updatedSetting);
  } catch (error) {
    console.error(`Error updating setting ${id}:`, error.message);
  }
}

updateSetting('set_1J2K3L4M5N6O7P8Q');Example Response#{
  "id": "set_1J2K3L4M5N6O7P8Q",
  "livemode": false,
  "type": "notification",
  "mount_location": "user_dashboard_notifications",
  "active": true,
  "component_did": null,
  "description": "Updated dashboard notification settings.",
  "settings": {
    "self_handle": false,
    "include_events": [
      "customer.subscription.renewed",
      "invoice.paid"
    ],
    "exclude_events": [
      "invoice.created"
    ]
  },
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:10:00.000Z"
}Delete a Setting#Permanently deletes a setting.
Parameters#Name
Type
Description
mountLocationOrId
string
Required. The identifier or mount location of the setting to delete.
Returns#Returns an object with a confirmation message.
Example#async function deleteSetting(id) {
  try {
    const response = await payment.settings.del(id);
    console.log(response.message);
  } catch (error) {
    console.error(`Error deleting setting ${id}:`, error.message);
  }
}

deleteSetting('set_1J2K3L4M5N6O7P8Q');Example Response#{
  "message": "Setting deleted successfully"
}
This guide has covered how to manage application settings. For tracking usage-based billing, you can proceed to the Meters section.

Property	Type	Description
`id`	`string`	Unique identifier for the setting.
`livemode`	`boolean`	`true` if the object exists in live mode, or `false` if it exists in test mode.
`type`	`string`	The type of setting (e.g., `'donate'`, `'notification'`). This determines the schema of the `settings` object.
`mount_location`	`string`	An identifier for the component or location where this setting is applied.
`active`	`boolean`	`true` if the setting is currently active.
`component_did`	`string`	(Optional) The DID of the component associated with this setting.
`description`	`string`	A description of the setting's purpose.
`settings`	`object`	An object containing the detailed configuration. Its structure depends on the `type` field.
`created_at`	`Date`	The timestamp when the setting was created.
`updated_at`	`Date`	The timestamp when the setting was last updated.

Name	Type	Description
`mountLocation`	`string`	Required. A unique identifier for where the setting is used.
`description`	`string`	Required. A human-readable description of the setting.
`type`	`string`	Required. The type of setting to create, such as `'notification'` or `'donate'`.
`settings`	`object`	Required. A configuration object whose structure depends on the `type`. See below for examples.
`settings.amount`	`object`	For `donate` type. Contains amount settings: `presets` (string[]), `preset` (string), `custom` (boolean), `minimum` (string), `maximum` (string).
`settings.btnText`	`string`	For `donate` type. The text displayed on the donation button.
`settings.historyType`	`'table'	'avatar'`
`settings.self_handle`	`boolean`	For `notification` type. If `true`, indicates that notifications are handled by the application itself.
`settings.exclude_events`	`string[]`	For `notification` type. An array of event types to exclude from notifications.
`settings.include_events`	`string[]`	For `notification` type. An array of event types to include in notifications.
`active`	`boolean`	(Optional) Whether the setting is active. Defaults to `true`.
`livemode`	`boolean`	(Optional) Whether this setting applies to live mode.
`componentDid`	`string`	(Optional) The DID of the component.

Name	Type	Description
`mountLocationOrId`	`string`	Required. The identifier or mount location of the setting to update.
`updateData`	`object`	Required. An object containing the fields to update.
`updateData.active`	`boolean`	(Optional) New active status for the setting.
`updateData.description`	`string`	(Optional) New description for the setting.
`updateData.settings`	`object`	(Optional) A partial object to merge with the existing settings.

Overview

Get Started

Core Concepts

Usage Guides

API Reference

TypeScript Support

Settings

The Setting Object#

Create a Setting#

Parameters#

Returns#

Example#

Example Response#

Retrieve a Setting#

Parameters#

Returns#

Example#

Example Response#

Update a Setting#

Parameters#

Returns#

Example#

Example Response#

Delete a Setting#

Parameters#

Returns#

Example#

Example Response#

Refunds

Meters