Settings API

Home
Essential Knowledge
By Type
Building Blocks
APIs
Releases

Essential knowledge

Author:

Fluent Commerce

Changed on:

3 July 2024

Overview

Settings API is used to set configurations used by the platform, accounts and retailers. See Commerce Apps documentation for specific settings keys and their function.

Configurations have a hierarchy of contexts in which they can be applied. GLOBAL, ACCOUNT and RETAILER are the levels in decreasing order of context, where GLOBAL is reserved by platform use and ACCOUNT and RETAILER are available to developers to override the GLOBAL defaults.

Key points

Setting Properties
What you can do with the Settings API
Response on Failures

Deprecation Notice

This REST API has been deprecated and replaced with GraphQL APIs. Please process the entity using the appropriate GQL mutations.

Setting Properties

Below are the properties available in the Setting object which can be updated/retrieved through the APIs in this document.

1. key

Type: String

Description:

1"key" : "PAYMENT.PROVIDER"

Language: java

Name: Description

Description:

[Warning: empty required content area]

Key is a mandatory parameter. It uniquely identifies a configuration option. For instance, PAYMENT.PROVIDER, PAYMENT.CURRENCY.

2. value

Type: Object

Description:

1"value": [{"name":"BRAINTREE"},{"name":"CYBERSOURCE"},{"name":"PAYPAL"},{"name":"GIVEX"},{"name":"AFTERPAY"},{"name":"FAT_ZEBRA"}]

Language: java

Name: Description

Description:

[Warning: empty required content area]

Value contains the actual value of the configuration setting. The type of the object is represented as string in the type field.

For instance, if the value is a JSON, type field should match it and have the value "JSON".

3. type

Type: String

Description:

1"type" : "JSON"

Language: java

Name: Description

Description:

[Warning: empty required content area]

Represents the data type for the value. It is an enum with following possible values -

Enum { LOB, STRING, INTEGER, BOOLEAN, JSON}

4. level

Type: String

1"level" : "ACCOUNT"

Language: java

Name: Description

Description:

[Warning: empty required content area]

Represents the level of the setting. It is an enum with following possible values -

Enum { GLOBAL, ACCOUNT, RETAILER }

Note

GLOBAL level is reserved by platform and can not be set using API calls. Clients can override this by using the ACCOUNT or RETAILER level.

What you can do with the Settings API

Create/Update an account configuration setting

This endpoint can be used to create or update an ACCOUNT level configuration setting for an account. The user of the API must have SETTINGS_EDIT permission. Currently ADMIN role has that permission.

Note

If there is no existing account setting against a key, it will CREATE a new account setting
If there is an existing account setting against a key, it will REPLACE the existing setting values by the new setting values.

PUT:

`/api/v4.1/settings/account/{accountId}/{key}`

Params:

accountId: string
key: string

1`/api/v4.1/settings/account/1111/PAYMENT.PROVIDER `

Language: text

Name: URL Example

Description:

[Warning: empty required content area]

Request Object

1setting {
2    key(string),
3    value(object),
4    type(string)
5}

Language: java

Name: Request Object

Description:

[Warning: empty required content area]

Example:

key:
```
`"PAYMENT.PROVIDER"`
```

value:

`[{"name":"BRAINTREE"},{"name":"CYBERSOURCE"},{"name":"PAYPAL"},{"name":"GIVEX"},{"name":"AFTERPAY"},{"name":"FAT_ZEBRA"}]`

type:

`{ LOB, STRING, INTEGER, BOOLEAN, JSON}`

Example request

1{
2    "setting":
3        {
4            "key": "PAYMENT.PROVIDER",
5            "value": [{"name":"BRAINTREE"},{"name":"CYBERSOURCE"},{"name":"PAYPAL"},{"name":"GIVEX"},{"name":"AFTERPAY"},{"name":"FAT_ZEBRA"}],
6            "type": "JSON"
7        }
8
9}

Language: json

Name: Example Request

Description:

[Warning: empty required content area]

Response Object

1{
2    "id": integer
3}

Language: java

Name: Response object

Description:

[Warning: empty required content area]

Id for the configuration setting that was created or updated.

Example response

1{
2 "id":"100"
3}

Language: java

Name: Example response

Description:

[Warning: empty required content area]

View account configuration setting

This endpoint can be used to view the configuration settings for given keys for an account.

GET:

`/api/v4.1/settings/account/{accountId}/{keys}`

Params:

accountId: string
keys: string.

Comma separated

example 1:
```
`PAYMENT.PROVIDER,PAYMENT.CURRENCY`
```
example 2:
```
`PAYMENT.PROVIDER`
```

Response Object

1[{
2key: string,
3    example "PAYMENT.PROVIDER"
4value: object,
5    the value of the object should be of the type passed as string in "type" attribute
6    example [{"name":"BRAINTREE"},{"name":"CYBERSOURCE"},{"name":"PAYPAL"},{"name":"GIVEX"},{"name":"AFTERPAY"},{"name":"FAT_ZEBRA"}]
7type: string,
8    Enum { LOB, STRING, INTEGER, BOOLEAN, JSON }
9    example "JSON"
10level: string
11    Enum { GLOBAL, ACCOUNT, RETAILER }
12    example: "GLOBAL"
13}]

Language: java

Name: Response Object

Description:

[Warning: empty required content area]

Example 1

1/api/v4.1/settings/account/1111/PAYMENT.PROVIDER,PAYMENT.CURRENCY

Language: text

Name: URL Example

Description:

[Warning: empty required content area]

Setting response

1{
2    "settings": [
3        {
4            "key": "PAYMENT.PROVIDER",
5            "value": [{"name":"BRAINTREE"},{"name":"CYBERSOURCE"},{"name":"PAYPAL"},{"name":"GIVEX"},{"name":"AFTERPAY"},{"name":"FAT_ZEBRA"}],
6            "type": "JSON",
7            "level": "ACCOUNT"
8        },
9        {
10            "key": "PAYMENT.CURRENCY",
11            "value": true,
12            "type": "[{"name":"AUD"},{"name":"NZD"}]",
13            "level": "GLOBAL"
14        }
15    ]
16}

Language: java

Name: Setting response - Example 1

Description:

[Warning: empty required content area]

Example 2

1/api/v4.1/settings/account/1111/PAYMENT.PROVIDER

Language: text

Name: URL Example

Description:

[Warning: empty required content area]

Example response

1{
2    "settings": [
3        {
4            "key": "PAYMENT.PROVIDER",
5            "value": [{"name":"BRAINTREE"},{"name":"CYBERSOURCE"},{"name":"PAYPAL"},{"name":"GIVEX"},{"name":"AFTERPAY"},{"name":"FAT_ZEBRA"}],
6            "type": "JSON",
7            "level": "GLOBAL"
8        }
9    ]
10}

Language: java

Name: Setting response - Example 2

Description:

[Warning: empty required content area]

Note

GLOBAL level indicates out-of-the-box settings that have not been overridden by clients.

Create/Update a retailer configuration setting

This endpoint can be used to create or update a RETAILER level configuration setting for a retailer. The user of the API must have SETTINGS_EDIT permission. Currently ADMIN role has that permission.

Note

If there is no existing retailer setting against a key, it will CREATE a new retailer setting
If there is an existing retailer setting against a key, it will REPLACE the existing setting values by the new setting values.

PUT:

`/api/v4.1/settings/retailer/{retailerId}/{key}`

Params:

retailerId: string
key: string

1/api/v4.1/settings/retailer/2222/PAYMENT.PROVIDER

Language: text

Name: URL

Description:

[Warning: empty required content area]

1{
2    "setting":
3        {
4            "key": "PAYMENT.PROVIDER",
5            "value": [{"name":"BRAINTREE"},{"name":"CYBERSOURCE"},{"name":"PAYPAL"},{"name":"GIVEX"},{"name":"AFTERPAY"},{"name":"FAT_ZEBRA"}],
6            "type": "JSON"
7        }
8
9}

Language: text

Name: Example request

Description:

[Warning: empty required content area]

Response Object

1{
2    "id": integer
3}

Language: java

Name: Response object

Description:

[Warning: empty required content area]

Id for the configuration setting that was created or updated.

Example response

1{
2 "id":"123456"
3}

Language: java

Name: Example response

Description:

[Warning: empty required content area]

View retailer configuration settings

This endpoint can be used to view the configuration settings for the retailer for the given keys.

GET:

`/api/v4.1/settings/retailer/{retailerId}/{keys}`

Params:

retailerId: string
keys: string.

Comma separated

example 1:

`PAYMENT.PROVIDER,PAYMENT.CURRENCY`

example 2:

`PAYMENT.PROVIDER`

Response Object

1[{
2key: string,
3    example "PAYMENT.PROVIDER"
4value: object,
5    the value of the object should be of the type passed as string in "type" attribute
6    example [{"name":"BRAINTREE"},{"name":"CYBERSOURCE"},{"name":"PAYPAL"},{"name":"GIVEX"},{"name":"AFTERPAY"},{"name":"FAT_ZEBRA"}]
7type: string,
8    Enum { LOB, STRING, INTEGER, BOOLEAN, JSON }
9    example "JSON"
10level: string
11    Enum { GLOBAL, ACCOUNT, RETAILER }
12    example: "GLOBAL"
13}]

Language: java

Name: Response Object

Description:

[Warning: empty required content area]

Request 1

1/api/v4.1/settings/retailer/2222/PAYMENT.PROVIDER

Language: text

Name: URL Example

Description:

[Warning: empty required content area]

Setting response

1{
2    "settings": [
3        {
4            "key": "PAYMENT.PROVIDER",
5            "value": [{"name":"BRAINTREE"},{"name":"CYBERSOURCE"},{"name":"PAYPAL"},{"name":"GIVEX"},{"name":"AFTERPAY"},{"name":"FAT_ZEBRA"}],
6            "type": "JSON",
7            "level": "RETAILER"
8        }
9    ]
10}

Language: java

Name: Setting response - Request 1

Description:

[Warning: empty required content area]

Request 2

1/api/v4.1/settings/retailer/2222/PAYMENT.PROVIDER,PAYMENT.CURRENCY

Language: text

Name: URL Example

Description:

[Warning: empty required content area]

Example response

1{
2    "settings": [
3        {
4            "key": "PAYMENT.PROVIDER",
5            "value": [{"name":"BRAINTREE"},{"name":"CYBERSOURCE"},{"name":"PAYPAL"},{"name":"GIVEX"},{"name":"AFTERPAY"},{"name":"FAT_ZEBRA"}],
6            "type": "JSON",
7            "level": "RETAILER"
8        },
9        {
10            "key": "PAYMENT.CURRENCY",
11            "value": [{"name":"AUD"},{"name":"NZD"}],
12            "type": "JSON",
13            "level": "GLOBAL"
14        }
15    ]
16}

Language: java

Name: Setting response - Request 2

Description:

[Warning: empty required content area]

Note

GLOBAL level indicates out-of-the-box settings that have not been overridden by clients.

Response on Failures

NAME	TYPE	DESCRIPTION
error	Array	Array of errors
message	String	Additional information on the code Unauthorized \| Bad Request \| Forbidden \| Not Found \| Status 500 Error
code	String	Status Code for the above messages 401 \| 400 \| 403 \| 404 \| 500

Settings API

Overview

Key points

Setting Properties

1. key

2. value

3. type

4. level

What you can do with the Settings API

Create/Update an account configuration setting

View account configuration setting

Example 1

Create/Update a retailer configuration setting

View retailer configuration settings

Request 1

Response on Failures

Fluent Commerce

Building Blocks

By Type

Helpful Resources

Quick Links