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.

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	GET	/custom_objects	Returns a page of custom objects under data, with paging details under pagination.
List settings areas	GET	/settings	Returns the settings areas of the instance, under settings.resources.
Retrieve a custom object	GET	/custom_objects/{custom_object_id}	Returns one custom object by its id, under custom_object.
List currencies	GET	/settings/currencies	Returns a page of currencies under data, with paging details under pagination.
List custom logic scripts	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	POST	/settings/custom_objects	Creates a custom object and returns it under custom_object.
List discount profiles	GET	/settings/discount_profiles	Returns a page of discount profiles under data, with paging details under pagination.
List item groups	GET	/settings/item_groups	Returns a page of item groups under data, with paging details under pagination.
Create an item group	POST	/settings/item_groups	Creates an item group and returns it under item_group.
List payment processors	GET	/settings/payment_processors	Returns a page of payment processors under data, with paging details under pagination.
List payment terms	GET	/settings/payment_terms	Returns a page of payment terms under data, with paging details under pagination.
List pricing levels	GET	/settings/pricing_levels	Returns a page of pricing levels under data, with paging details under pagination.
List shipping profiles	GET	/settings/shipping_profiles	Returns a page of shipping profiles under data, with paging details under pagination.
List taxes	GET	/settings/taxes	Returns a page of taxes under data, with paging details under pagination.
List time zones	GET	/settings/time_zones	Returns a page of time zones under data, with paging details under pagination.
List variations	GET	/settings/variations	Returns a page of variations under data, with paging details under pagination.
Create a variation	POST	/settings/variations	Creates a variation with its options and returns it under variation.
List warehouses	GET	/settings/warehouses	Returns a page of warehouses under data, with paging details under pagination.
Retrieve a currency	GET	/settings/currencies/{currency_id}	Returns one currency by its id, under currency.
Retrieve a custom logic script	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	DELETE	/settings/custom_objects/{custom_object_id}	Deletes a custom object. The response has no body.
Update a custom object in settings	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	PATCH	/settings/field_settings/account	Turns account fields on or off, or makes them required, and returns the field settings.
Update item field settings	PATCH	/settings/field_settings/item	Turns item fields on or off, or makes them required, and returns the field settings.
Update account general settings	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	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	DELETE	/settings/item_groups/{item_group_id}	Deletes an item group.
Retrieve an item group	GET	/settings/item_groups/{item_group_id}	Returns one item group by its id, under item_group.
Update an item group	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	GET	/settings/time_zones/{time_zone_id}	Returns one time zone by its id, under time_zone.
Retrieve a variation	GET	/settings/variations/{variation_id}	Returns one variation by its id, under variation.
Update a variation	PATCH	/settings/variations/{variation_id}	Changes the fields you send on a variation and returns it under variation.
Customise a custom object’s attributes	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	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	GET	/settings/custom_objects	Returns a page of custom objects under data, with paging details under pagination.
Retrieve a custom object from settings	GET	/settings/custom_objects/{custom_object_id}	Returns one custom object by its id, under custom_object.
Create a custom object	POST	/custom_objects	Creates a custom object and returns it under custom_object.
Update a custom object	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	DELETE	/custom_objects/{custom_object_id}	Deletes a custom object. The response has no body.
Create a currency	POST	/settings/currencies	Creates a currency and returns it under currency.
Update a currency	PATCH	/settings/currencies/{currency_id}	Changes a currency’s rounding, cash rounding interval, conversion rate or status.
Create a custom logic script	POST	/settings/custom_logic_scripts	Creates a custom logic script and returns it under custom_logic_script.
Update a custom logic script	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	DELETE	/settings/custom_logic_scripts/{custom_logic_script_id}	Deletes a custom logic script. The response has no body.
Create a discount profile	POST	/settings/discount_profiles	Creates a discount profile and returns it under discount_profile.
Retrieve a discount profile	GET	/settings/discount_profiles/{discount_profile_id}	Returns one discount profile by its id, under discount_profile.
Update a discount profile	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	DELETE	/settings/discount_profiles/{discount_profile_id}	Deletes a discount profile. The response has no body.
List field settings	GET	/settings/field_settings	Returns a page of field settings under data, with paging details under pagination.
Retrieve a field setting	GET	/settings/field_settings/{field_setting_id}	Returns one field setting by its id, under field_setting.
Retrieve a general settings group	GET	/settings/general_settings/{group}	Returns one group of general settings, keyed by the group, under general_settings.
Retrieve a general setting	GET	/settings/general_settings/{group}/{general_setting_id}	Returns one general setting by its gs_ id within a group.
Update dashboard general settings	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	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	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	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	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	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	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	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	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	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	POST	/settings/payment_processors	Creates an offline payment processor and returns it under payment_processor.
Retrieve a payment processor	GET	/settings/payment_processors/{payment_processor_id}	Returns one payment processor by its id, under payment_processor.
Update a payment processor	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	DELETE	/settings/payment_processors/{payment_processor_id}	Deletes a payment processor. The response has no body.
Create a payment term	POST	/settings/payment_terms	Creates a payment term and returns it under payment_term.
Retrieve a payment term	GET	/settings/payment_terms/{payment_term_id}	Returns one payment term by its id, under payment_term.
Update a payment term	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	DELETE	/settings/payment_terms/{payment_term_id}	Deletes a payment term. The response has no body.
Create a pricing level	POST	/settings/pricing_levels	Creates a pricing level and returns it under pricing_level.
Retrieve a pricing level	GET	/settings/pricing_levels/{pricing_level_id}	Returns one pricing level by its id, under pricing_level.
Update a pricing level	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	DELETE	/settings/pricing_levels/{pricing_level_id}	Deletes a pricing level. The response has no body.
Create a shipping profile	POST	/settings/shipping_profiles	Creates a shipping profile and returns it under shipping_profile.
Retrieve a shipping profile	GET	/settings/shipping_profiles/{shipping_profile_id}	Returns one shipping profile by its id, under shipping_profile.
Update a shipping profile	PATCH	/settings/shipping_profiles/{shipping_profile_id}	Changes the fields you send on a shipping profile.
Delete a shipping profile	DELETE	/settings/shipping_profiles/{shipping_profile_id}	Deletes a shipping profile. The response has no body.
Create a warehouse	POST	/settings/warehouses	Creates a warehouse and returns it under warehouse.
Retrieve a warehouse	GET	/settings/warehouses/{warehouse_id}	Returns one warehouse by its id, under warehouse.
Update a warehouse	PATCH	/settings/warehouses/{warehouse_id}	Changes the fields you send on a warehouse and returns it under warehouse.
Delete a warehouse	DELETE	/settings/warehouses/{warehouse_id}	Deletes a warehouse. The response has no body.
Create a tax	POST	/settings/taxes	Creates a country tax and returns it under tax.
Retrieve a tax	GET	/settings/taxes/{tax_id}	Returns one tax by its id, under tax.
Update a tax	PATCH	/settings/taxes/{tax_id}	Changes a tax, or enables or disables it.
Delete a variation	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. 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.