> ## Documentation Index
> Fetch the complete documentation index at: https://exsited.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Instance settings

> Read and change instance settings: currencies, taxes, warehouses, payment terms, field settings, general settings and more.

Settings hold the configuration of an Exsited instance: currencies, taxes, time zones, warehouses, item groups, variations, discount, shipping and payment setup, custom objects, field settings and the general settings groups. You can read every area and create, change or delete most of its records. This area has 86 endpoints, and all seven SDKs call every one.

> [!WARNING]
>
> **Updating the `general` group of general settings sets eight other instance settings, such as `accountingPeriod` and `fiscalYear`, to null, and no API call can set them back.**

## At a glance

| Endpoint | Method | Path | What it does |
| - | - | - | - |
| [List custom objects](https://exsited.mintlify.site/api-reference/instance-settings/list-custom-objects.md) | GET | `/custom_objects` | Returns a page of custom objects under `data`, with paging details under `pagination`. |
| [List settings areas](https://exsited.mintlify.site/api-reference/instance-settings/list-settings-areas.md) | GET | `/settings` | Returns the settings areas of the instance, under `settings.resources`. |
| [Retrieve a custom object](https://exsited.mintlify.site/api-reference/instance-settings/retrieve-a-custom-object.md) | GET | `/custom_objects/{custom_object_id}` | Returns one custom object by its `id`, under `custom_object`. |
| [List currencies](https://exsited.mintlify.site/api-reference/instance-settings/list-currencies.md) | GET | `/settings/currencies` | Returns a page of currencies under `data`, with paging details under `pagination`. |
| [List custom logic scripts](https://exsited.mintlify.site/api-reference/instance-settings/list-custom-logic-scripts.md) | GET | `/settings/custom_logic_scripts` | Returns a page of custom logic scripts under `data`, with paging details under `pagination`. |
| [Create a custom object in settings](https://exsited.mintlify.site/api-reference/instance-settings/create-a-custom-object-in-settings.md) | POST | `/settings/custom_objects` | Creates a custom object and returns it under `custom_object`. |
| [List discount profiles](https://exsited.mintlify.site/api-reference/instance-settings/list-discount-profiles.md) | GET | `/settings/discount_profiles` | Returns a page of discount profiles under `data`, with paging details under `pagination`. |
| [List item groups](https://exsited.mintlify.site/api-reference/instance-settings/list-item-groups.md) | GET | `/settings/item_groups` | Returns a page of item groups under `data`, with paging details under `pagination`. |
| [Create an item group](https://exsited.mintlify.site/api-reference/instance-settings/create-an-item-group.md) | POST | `/settings/item_groups` | Creates an item group and returns it under `item_group`. |
| [List payment processors](https://exsited.mintlify.site/api-reference/instance-settings/list-payment-processors.md) | GET | `/settings/payment_processors` | Returns a page of payment processors under `data`, with paging details under `pagination`. |
| [List payment terms](https://exsited.mintlify.site/api-reference/instance-settings/list-payment-terms.md) | GET | `/settings/payment_terms` | Returns a page of payment terms under `data`, with paging details under `pagination`. |
| [List pricing levels](https://exsited.mintlify.site/api-reference/instance-settings/list-pricing-levels.md) | GET | `/settings/pricing_levels` | Returns a page of pricing levels under `data`, with paging details under `pagination`. |
| [List shipping profiles](https://exsited.mintlify.site/api-reference/instance-settings/list-shipping-profiles.md) | GET | `/settings/shipping_profiles` | Returns a page of shipping profiles under `data`, with paging details under `pagination`. |
| [List taxes](https://exsited.mintlify.site/api-reference/instance-settings/list-taxes.md) | GET | `/settings/taxes` | Returns a page of taxes under `data`, with paging details under `pagination`. |
| [List time zones](https://exsited.mintlify.site/api-reference/instance-settings/list-time-zones.md) | GET | `/settings/time_zones` | Returns a page of time zones under `data`, with paging details under `pagination`. |
| [List variations](https://exsited.mintlify.site/api-reference/instance-settings/list-variations.md) | GET | `/settings/variations` | Returns a page of variations under `data`, with paging details under `pagination`. |
| [Create a variation](https://exsited.mintlify.site/api-reference/instance-settings/create-a-variation.md) | POST | `/settings/variations` | Creates a variation with its options and returns it under `variation`. |
| [List warehouses](https://exsited.mintlify.site/api-reference/instance-settings/list-warehouses.md) | GET | `/settings/warehouses` | Returns a page of warehouses under `data`, with paging details under `pagination`. |
| [Retrieve a currency](https://exsited.mintlify.site/api-reference/instance-settings/retrieve-a-currency.md) | GET | `/settings/currencies/{currency_id}` | Returns one currency by its `id`, under `currency`. |
| [Retrieve a custom logic script](https://exsited.mintlify.site/api-reference/instance-settings/retrieve-a-custom-logic-script.md) | GET | `/settings/custom_logic_scripts/{custom_logic_script_id}` | Returns one custom logic script by its `id`, under `custom_logic_script`. |
| [Delete a custom object in settings](https://exsited.mintlify.site/api-reference/instance-settings/delete-a-custom-object-in-settings.md) | DELETE | `/settings/custom_objects/{custom_object_id}` | Deletes a custom object. The response has no body. |
| [Update a custom object in settings](https://exsited.mintlify.site/api-reference/instance-settings/update-a-custom-object-in-settings.md) | PATCH | `/settings/custom_objects/{custom_object_id}` | Changes the fields you send on a custom object and returns it under `custom_object`. |
| [Update account field settings](https://exsited.mintlify.site/api-reference/instance-settings/update-account-field-settings.md) | PATCH | `/settings/field_settings/account` | Turns account fields on or off, or makes them required, and returns the field settings. |
| [Update item field settings](https://exsited.mintlify.site/api-reference/instance-settings/update-item-field-settings.md) | PATCH | `/settings/field_settings/item` | Turns item fields on or off, or makes them required, and returns the field settings. |
| [Update account general settings](https://exsited.mintlify.site/api-reference/instance-settings/update-account-general-settings.md) | PATCH | `/settings/general_settings/account` | Changes settings in the `account` group of general settings and returns the group under `general_settings`. |
| [Update item general settings](https://exsited.mintlify.site/api-reference/instance-settings/update-item-general-settings.md) | PATCH | `/settings/general_settings/item` | Changes settings in the `item` group of general settings and returns the `item` and `product` settings. |
| [Delete an item group](https://exsited.mintlify.site/api-reference/instance-settings/delete-an-item-group.md) | DELETE | `/settings/item_groups/{item_group_id}` | Deletes an item group. |
| [Retrieve an item group](https://exsited.mintlify.site/api-reference/instance-settings/retrieve-an-item-group.md) | GET | `/settings/item_groups/{item_group_id}` | Returns one item group by its `id`, under `item_group`. |
| [Update an item group](https://exsited.mintlify.site/api-reference/instance-settings/update-an-item-group.md) | PATCH | `/settings/item_groups/{item_group_id}` | Changes the fields you send on an item group and returns it under `item_group`. |
| [Retrieve a time zone](https://exsited.mintlify.site/api-reference/instance-settings/retrieve-a-time-zone.md) | GET | `/settings/time_zones/{time_zone_id}` | Returns one time zone by its `id`, under `time_zone`. |
| [Retrieve a variation](https://exsited.mintlify.site/api-reference/instance-settings/retrieve-a-variation.md) | GET | `/settings/variations/{variation_id}` | Returns one variation by its `id`, under `variation`. |
| [Update a variation](https://exsited.mintlify.site/api-reference/instance-settings/update-a-variation.md) | PATCH | `/settings/variations/{variation_id}` | Changes the fields you send on a variation and returns it under `variation`. |
| [Customise a custom object's attributes](https://exsited.mintlify.site/api-reference/instance-settings/customise-a-custom-objects-attributes.md) | POST | `/settings/custom_objects/{custom_object_id}/customize` | Sets which custom attributes a custom object holds, and in what order. |
| [Update an item group's billing preferences](https://exsited.mintlify.site/api-reference/instance-settings/update-an-item-groups-billing-preferences.md) | POST | `/settings/item_groups/{item_group_id}/billing_preferences` | Sets an item group's billing preferences and returns the item group under `item_group`. |
| [List enabled custom objects](https://exsited.mintlify.site/api-reference/instance-settings/list-enabled-custom-objects.md) | GET | `/settings/custom_objects` | Returns a page of custom objects under `data`, with paging details under `pagination`. |
| [Retrieve a custom object from settings](https://exsited.mintlify.site/api-reference/instance-settings/retrieve-a-custom-object-from-settings.md) | GET | `/settings/custom_objects/{custom_object_id}` | Returns one custom object by its `id`, under `custom_object`. |
| [Create a custom object](https://exsited.mintlify.site/api-reference/instance-settings/create-a-custom-object.md) | POST | `/custom_objects` | Creates a custom object and returns it under `custom_object`. |
| [Update a custom object](https://exsited.mintlify.site/api-reference/instance-settings/update-a-custom-object.md) | PATCH | `/custom_objects/{custom_object_id}` | Changes the fields you send on a custom object and returns it under `custom_object`. |
| [Delete a custom object](https://exsited.mintlify.site/api-reference/instance-settings/delete-a-custom-object.md) | DELETE | `/custom_objects/{custom_object_id}` | Deletes a custom object. The response has no body. |
| [Create a currency](https://exsited.mintlify.site/api-reference/instance-settings/create-a-currency.md) | POST | `/settings/currencies` | Creates a currency and returns it under `currency`. |
| [Update a currency](https://exsited.mintlify.site/api-reference/instance-settings/update-a-currency.md) | PATCH | `/settings/currencies/{currency_id}` | Changes a currency's rounding, cash rounding interval, conversion rate or status. |
| [Create a custom logic script](https://exsited.mintlify.site/api-reference/instance-settings/create-a-custom-logic-script.md) | POST | `/settings/custom_logic_scripts` | Creates a custom logic script and returns it under `custom_logic_script`. |
| [Update a custom logic script](https://exsited.mintlify.site/api-reference/instance-settings/update-a-custom-logic-script.md) | PATCH | `/settings/custom_logic_scripts/{custom_logic_script_id}` | Changes the fields you send on a custom logic script and returns it under `custom_logic_script`. |
| [Delete a custom logic script](https://exsited.mintlify.site/api-reference/instance-settings/delete-a-custom-logic-script.md) | DELETE | `/settings/custom_logic_scripts/{custom_logic_script_id}` | Deletes a custom logic script. The response has no body. |
| [Create a discount profile](https://exsited.mintlify.site/api-reference/instance-settings/create-a-discount-profile.md) | POST | `/settings/discount_profiles` | Creates a discount profile and returns it under `discount_profile`. |
| [Retrieve a discount profile](https://exsited.mintlify.site/api-reference/instance-settings/retrieve-a-discount-profile.md) | GET | `/settings/discount_profiles/{discount_profile_id}` | Returns one discount profile by its `id`, under `discount_profile`. |
| [Update a discount profile](https://exsited.mintlify.site/api-reference/instance-settings/update-a-discount-profile.md) | PATCH | `/settings/discount_profiles/{discount_profile_id}` | Changes the fields you send on a discount profile and returns it under `discount_profile`. |
| [Delete a discount profile](https://exsited.mintlify.site/api-reference/instance-settings/delete-a-discount-profile.md) | DELETE | `/settings/discount_profiles/{discount_profile_id}` | Deletes a discount profile. The response has no body. |
| [List field settings](https://exsited.mintlify.site/api-reference/instance-settings/list-field-settings.md) | GET | `/settings/field_settings` | Returns a page of field settings under `data`, with paging details under `pagination`. |
| [Retrieve a field setting](https://exsited.mintlify.site/api-reference/instance-settings/retrieve-a-field-setting.md) | GET | `/settings/field_settings/{field_setting_id}` | Returns one field setting by its `id`, under `field_setting`. |
| [Retrieve a general settings group](https://exsited.mintlify.site/api-reference/instance-settings/retrieve-a-general-settings-group.md) | GET | `/settings/general_settings/{group}` | Returns one group of general settings, keyed by the group, under `general_settings`. |
| [Retrieve a general setting](https://exsited.mintlify.site/api-reference/instance-settings/retrieve-a-general-setting.md) | GET | `/settings/general_settings/{group}/{general_setting_id}` | Returns one general setting by its `gs_` id within a group. |
| [Update dashboard general settings](https://exsited.mintlify.site/api-reference/instance-settings/update-dashboard-general-settings.md) | PATCH | `/settings/general_settings/dashboard` | Changes settings in the `dashboard` group of general settings and returns the group under `general_settings`. |
| [Update date and time general settings](https://exsited.mintlify.site/api-reference/instance-settings/update-date-and-time-general-settings.md) | PATCH | `/settings/general_settings/date_and_time` | Changes settings in the `date_and_time` group of general settings and returns the group under `general_settings`. |
| [Update display general settings](https://exsited.mintlify.site/api-reference/instance-settings/update-display-general-settings.md) | PATCH | `/settings/general_settings/display` | Changes settings in the `display` group of general settings and returns the group under `general_settings`. |
| [Update the general group of general settings](https://exsited.mintlify.site/api-reference/instance-settings/update-the-general-group-of-general-settings.md) | PATCH | `/settings/general_settings/general` | Changes settings in the `general` group. It also resets eight other instance settings that no call can set back. |
| [Update labour general settings](https://exsited.mintlify.site/api-reference/instance-settings/update-labour-general-settings.md) | PATCH | `/settings/general_settings/labour` | Changes settings in the `labour` group of general settings and returns the group under `general_settings`. |
| [Update order general settings](https://exsited.mintlify.site/api-reference/instance-settings/update-order-general-settings.md) | PATCH | `/settings/general_settings/order` | Changes settings in the `order` group of general settings and returns the group under `general_settings`. |
| [Update portal general settings](https://exsited.mintlify.site/api-reference/instance-settings/update-portal-general-settings.md) | PATCH | `/settings/general_settings/portal` | Changes settings in the `portal` group of general settings and returns the group under `general_settings`. |
| [Update purchase general settings](https://exsited.mintlify.site/api-reference/instance-settings/update-purchase-general-settings.md) | PATCH | `/settings/general_settings/purchase` | Changes settings in the `purchase` group of general settings and returns the group under `general_settings`. |
| [Update security general settings](https://exsited.mintlify.site/api-reference/instance-settings/update-security-general-settings.md) | PATCH | `/settings/general_settings/security` | Changes settings in the `security` group of general settings and returns the group under `general_settings`. |
| [Update transaction general settings](https://exsited.mintlify.site/api-reference/instance-settings/update-transaction-general-settings.md) | PATCH | `/settings/general_settings/transaction` | Changes settings in the `transaction` group of general settings and returns the group under `general_settings`. |
| [Create a payment processor](https://exsited.mintlify.site/api-reference/instance-settings/create-a-payment-processor.md) | POST | `/settings/payment_processors` | Creates an offline payment processor and returns it under `payment_processor`. |
| [Retrieve a payment processor](https://exsited.mintlify.site/api-reference/instance-settings/retrieve-a-payment-processor.md) | GET | `/settings/payment_processors/{payment_processor_id}` | Returns one payment processor by its `id`, under `payment_processor`. |
| [Update a payment processor](https://exsited.mintlify.site/api-reference/instance-settings/update-a-payment-processor.md) | PATCH | `/settings/payment_processors/{payment_processor_id}` | Changes the fields you send on a payment processor and returns it under `payment_processor`. |
| [Delete a payment processor](https://exsited.mintlify.site/api-reference/instance-settings/delete-a-payment-processor.md) | DELETE | `/settings/payment_processors/{payment_processor_id}` | Deletes a payment processor. The response has no body. |
| [Create a payment term](https://exsited.mintlify.site/api-reference/instance-settings/create-a-payment-term.md) | POST | `/settings/payment_terms` | Creates a payment term and returns it under `payment_term`. |
| [Retrieve a payment term](https://exsited.mintlify.site/api-reference/instance-settings/retrieve-a-payment-term.md) | GET | `/settings/payment_terms/{payment_term_id}` | Returns one payment term by its `id`, under `payment_term`. |
| [Update a payment term](https://exsited.mintlify.site/api-reference/instance-settings/update-a-payment-term.md) | PATCH | `/settings/payment_terms/{payment_term_id}` | Changes the fields you send on a payment term and returns it under `payment_term`. |
| [Delete a payment term](https://exsited.mintlify.site/api-reference/instance-settings/delete-a-payment-term.md) | DELETE | `/settings/payment_terms/{payment_term_id}` | Deletes a payment term. The response has no body. |
| [Create a pricing level](https://exsited.mintlify.site/api-reference/instance-settings/create-a-pricing-level.md) | POST | `/settings/pricing_levels` | Creates a pricing level and returns it under `pricing_level`. |
| [Retrieve a pricing level](https://exsited.mintlify.site/api-reference/instance-settings/retrieve-a-pricing-level.md) | GET | `/settings/pricing_levels/{pricing_level_id}` | Returns one pricing level by its `id`, under `pricing_level`. |
| [Update a pricing level](https://exsited.mintlify.site/api-reference/instance-settings/update-a-pricing-level.md) | PATCH | `/settings/pricing_levels/{pricing_level_id}` | Changes the fields you send on a pricing level and returns it under `pricing_level`. |
| [Delete a pricing level](https://exsited.mintlify.site/api-reference/instance-settings/delete-a-pricing-level.md) | DELETE | `/settings/pricing_levels/{pricing_level_id}` | Deletes a pricing level. The response has no body. |
| [Create a shipping profile](https://exsited.mintlify.site/api-reference/instance-settings/create-a-shipping-profile.md) | POST | `/settings/shipping_profiles` | Creates a shipping profile and returns it under `shipping_profile`. |
| [Retrieve a shipping profile](https://exsited.mintlify.site/api-reference/instance-settings/retrieve-a-shipping-profile.md) | GET | `/settings/shipping_profiles/{shipping_profile_id}` | Returns one shipping profile by its `id`, under `shipping_profile`. |
| [Update a shipping profile](https://exsited.mintlify.site/api-reference/instance-settings/update-a-shipping-profile.md) | PATCH | `/settings/shipping_profiles/{shipping_profile_id}` | Changes the fields you send on a shipping profile. |
| [Delete a shipping profile](https://exsited.mintlify.site/api-reference/instance-settings/delete-a-shipping-profile.md) | DELETE | `/settings/shipping_profiles/{shipping_profile_id}` | Deletes a shipping profile. The response has no body. |
| [Create a warehouse](https://exsited.mintlify.site/api-reference/instance-settings/create-a-warehouse.md) | POST | `/settings/warehouses` | Creates a warehouse and returns it under `warehouse`. |
| [Retrieve a warehouse](https://exsited.mintlify.site/api-reference/instance-settings/retrieve-a-warehouse.md) | GET | `/settings/warehouses/{warehouse_id}` | Returns one warehouse by its `id`, under `warehouse`. |
| [Update a warehouse](https://exsited.mintlify.site/api-reference/instance-settings/update-a-warehouse.md) | PATCH | `/settings/warehouses/{warehouse_id}` | Changes the fields you send on a warehouse and returns it under `warehouse`. |
| [Delete a warehouse](https://exsited.mintlify.site/api-reference/instance-settings/delete-a-warehouse.md) | DELETE | `/settings/warehouses/{warehouse_id}` | Deletes a warehouse. The response has no body. |
| [Create a tax](https://exsited.mintlify.site/api-reference/instance-settings/create-a-tax.md) | POST | `/settings/taxes` | Creates a country tax and returns it under `tax`. |
| [Retrieve a tax](https://exsited.mintlify.site/api-reference/instance-settings/retrieve-a-tax.md) | GET | `/settings/taxes/{tax_id}` | Returns one tax by its `id`, under `tax`. |
| [Update a tax](https://exsited.mintlify.site/api-reference/instance-settings/update-a-tax.md) | PATCH | `/settings/taxes/{tax_id}` | Changes a tax, or enables or disables it. |
| [Delete a variation](https://exsited.mintlify.site/api-reference/instance-settings/delete-a-variation.md) | DELETE | `/settings/variations/{variation_id}` | Deletes a variation. The response has no body. |

## Before you call

Register your API credentials once when your app starts, as shown in
[Authentication](https://exsited.mintlify.site/authentication.md). Every SDK sample on these pages then gets its client in one line.
With cURL, send the access token in an `Authorization` header: `Authorization: Bearer $ACCESS_TOKEN`.

## Things to know

* **Each record sits under its own key.** A currency is under `currency`, a warehouse under `warehouse` and general settings under `general_settings`, and writes use the same key.
* **General settings are read and written one group at a time.** `group` is one of `account`, `item`, `date_and_time`, `order`, `purchase`, `labour`, `transaction`, `security`, `dashboard`, `portal`, `display` or `general`; the `item` and `order` groups also carry `product`. The dashboard and security groups store flags as `"1"` and `"0"`.
* **Currencies and taxes cannot be deleted.** There is no delete call for either, so a currency or tax you create stays on the instance.
* **Some writes return a different shape from the read.** A payment term create returns a flat `period` and `duration`, and a payment processor write returns `gateway_name` and `credentials` where a read has `provider`.
* **Listings page by cursor.** Records sit under `data`; pass `pagination.next_cursor` as `cursor` to read the next page, and stop when `pagination.has_more` is `false`.
* **Custom objects have two paths.** `/custom_objects` and `/settings/custom_objects` serve the same records; the settings listing shows enabled ones only.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.