Project
View and manage all Project-wide settings, like countries, languages, and currencies, as well as feature-specific configurations via these endpoints.
Updating these settings is eventually consistent meaning that it can take up-to a minute until they become fully active for your Project.
Representations
Project
version Int | Current version of the Project. |
key String | User-defined unique identifier of the Project. |
name String | Name of the Project. |
countries Array of CountryCode | Country code of the geographic location. |
currencies Array of CurrencyCode | Currency code of the country. A Project must have at least one currency. |
languages Array of Locale | Language of the country. A Project must have at least one language. |
trialUntil String | Date in YYYY-MM format specifying when the trial period for the Project ends. Only present on Projects in trial period. |
messages | Holds the configuration for the Messages Query feature. |
carts | Holds the configuration for the Carts feature. |
shoppingLists | Holds the configuration for the Shopping Lists feature. This field may not be present on Projects created before January 2020. |
shippingRateInputType | Holds the configuration for the tiered shipping rates feature. |
externalOAuth | Represents a RFC 7662 compliant OAuth 2.0 Token Introspection endpoint. |
searchIndexing | Controls indexing of resources to be provided on high performance read-only search endpoints. |
businessUnits | Holds configuration specific to Business Units. |
createdAt | Date and time (UTC) the Project was initially created. |
MessagesConfiguration
Holds the configuration for the Messages Query feature for the Project.
enabled Boolean | When |
deleteDaysAfterCreation Int | Specifies the number of days each Message should be available via the Messages Query API. For Messages older than the specified period, it is not guaranteed that they are still accessible via the API. This field may not be present on Projects created before 8 October 2018. Default:15 Minimum: 1 Maximum: 90 |
MessagesConfigurationDraft
Defines the configuration for the Messages Query feature for the Project.
enabled Boolean | Setting to |
deleteDaysAfterCreation Int | Specifies the number of days each Message should be available via the Messages Query API. For Messages older than the specified period, it is not guaranteed that they are still accessible via the API. Minimum:1 Maximum: 90 |
CartsConfiguration
deleteDaysAfterLastModification Int | Default value for the This field may not be present on Projects created before January 2020. Default:90 Minimum: 1 |
countryTaxRateFallbackEnabled Boolean | Indicates if country - no state Tax Rate fallback should be used when a shipping address state is not explicitly covered in the rates lists of all Tax Categories of a Cart Line Items. This field may not be present on Projects created before June 2020. Default:false |
ShoppingListsConfiguration
deleteDaysAfterLastModification Int | Default value for the |
ShippingRateInputType
ShippingRatePriceTier can be dynamically selected in three ways. The CartValueType uses the sum of all Line Item totals and Custom Line Item totals (after discounts are applied), whereas CartClassificationType and CartScoreType use the shipppingRateInput
field on the Cart to select a tier.
CartValueType
The ShippingRate maps to the value of the Cart and is used to select a tier.
The value of the Cart is the sum of all Line Item totals and Custom Line Item totals (via the totalPrice
field) after any Product Discounts and Cart Discounts have been applied.
If chosen, it is not possible to set a value for the shippingRateInput
on the Cart.
type ShippingRateTierType | "CartValue" |
CartClassificationType
The ShippingRate maps to an abstract Cart categorization expressed by strings (for example, Light
, Medium
, or Heavy
).
Only keys defined in the values
array can be used to create a tier or to set a value of the shippingRateInput
on the Cart.
Keys must be unique.
type ShippingRateTierType | "CartClassification" |
values Array of CustomFieldLocalizedEnumValue | The classification items that can be used for specifying any ShippingRatePriceTier. |
{"type": "CartClassification","values": [{"key": "Light","label": {"en": "Light","de": "Leicht"}},{"key": "Medium","label": {"en": "Medium","de": "Mittel"}},{"key": "Heavy","label": {"en": "Heavy","de": "Schwer"}}]}
CartScoreType
The ShippingRate maps to an abstract Cart categorization expressed by integers (such as shipping scores or weight ranges).
type ShippingRateTierType | "CartScore" |
ExternalOAuth
Represents a RFC 7662 compliant OAuth 2.0 Token Introspection endpoint. For more information, see Requesting an access token using an external OAuth 2.0 server.
You can only configure one external OAuth 2.0 endpoint per Project. To authenticate using multiple external services (such as social network logins), use a middle layer authentication service.
url String | URL with authorization header. |
authorizationHeader String | Must not contain any leading or trailing whitespaces. Partially hidden on retrieval. Pattern:^[^ ].+[^ ]$ |
SearchIndexingConfiguration
Controls indexing of resources to be provided on high performance read-only search endpoints.
products | Configuration for the Product Projection Search and Product Suggestions endpoints. |
productsSearch | Configuration for the Product Search feature. |
orders BETA | Configuration for the Order Search feature. |
customers | Configuration for the Customer Search feature. |
SearchIndexingConfigurationValues
Current status of resource indexing. Present on Projects from 1 February 2019. | |
lastModifiedAt | Date and time (UTC) the Project was last updated. Only present on Projects last modified after 1 February 2019. |
lastModifiedBy BETA | IDs and references that last modified the SearchIndexingConfigurationValues. |
SearchIndexingConfigurationStatus
Status of resource indexing.
Activated
Indicates that search and suggest endpoints for the specified resource type are active.
Deactivated
Indicates that search and suggest endpoints for the specified resource type cannot be used.
Indexing
Indicates that search and suggest endpoints can temporarily not be used because the search index is being re-built.
CustomerSearchStatus
Specifies the status of the Customer Search index. You can change the status using the Change Customer Search Status update action.
Activated
indicates that the Customer Search feature is fully operational.
Deactivated
indicates that the Customer Search feature is currently not active.
OrderSearchStatus BETA
Specifies the status of the Order Search index.
Activated
indicates that the Search Orders endpoint is fully operational.
Deactivated
indicates that the Order Search feature is currently not active, but can be activated by update action.
ProductSearchIndexingMode
ProductProjectionsSearch
ProductsSearch
For Product Search.
BusinessUnitConfiguration
myBusinessUnitStatusOnCreation | Status of Business Units created using the My Business Unit endpoint. Default:Inactive |
myBusinessUnitAssociateRoleOnCreation | Default Associate Role assigned to the Associate creating a Business Unit using the My Business Unit endpoint. |
BusinessUnitConfigurationStatus
Default value for Business Unit Status configured though Project settings.
Active
The Business Unit can be used in Orders, Carts, and Quotes and can be updated using the My Business Unit endpoint.
Inactive
The Business Unit cannot be used in Orders, Carts, and Quotes and cannot be updated using the My Business Unit endpoint.
Get Project
view_project_settings:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
application/json
curl --get https://api.{region}.commercetools.com/{projectKey} -i \--header 'Authorization: Bearer ${BEARER_TOKEN}'
{"version": 1,"key": "test-project","name": "Some project name","countries": ["DE", "US"],"currencies": ["EUR"],"languages": ["en"],"createdAt": "2019-08-01T15:14:34.325Z","messages": {"enabled": false},"carts": {"countryTaxRateFallbackEnabled": false}}
Check if Project exists
Checks if a Project exists for a given projectKey
. Returns a 200 OK
status if the Project exists or a 404 Not Found
otherwise.
view_project_settings:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
curl --head https://api.{region}.commercetools.com/{projectKey} -i \--header 'Authorization: Bearer ${BEARER_TOKEN}'
Update Project
manage_project_settings:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
application/json
version Int | Expected version of the Project on which the changes should be applied. If the expected version does not match the actual version, a ConcurrentModification error will be returned. |
actions Array of ProjectUpdateAction | Update actions to be performed on the Project. |
application/json
curl https://api.{region}.commercetools.com/{projectKey} -i \--header 'Authorization: Bearer ${BEARER_TOKEN}' \--header 'Content-Type: application/json' \--data-binary @- << DATA{"version" : 1,"actions" : [ {"action" : "changeCurrencies","currencies" : [ "EUR", "USD" ]} ]}DATA
{"version": 2,"key": "test-project","name": "Some project name","countries": ["DE", "US"],"currencies": ["EUR", "USD"],"languages": ["en"],"createdAt": "2019-08-01T15:14:34.325Z","messages": {"enabled": false},"carts": {"countryTaxRateFallbackEnabled": false}}
Update actions
Change Name
action String | "changeName" |
name String | New value to set. Must not be empty. |
{"action": "changeName","name": "CTP Postman Monitor"}
Change Currencies
action String | "changeCurrencies" |
currencies Array of CurrencyCode | New value to set. Must not be empty. |
{"action": "changeCurrencies","currencies": ["EUR"]}
Change Countries
action String | "changeCountries" |
countries Array of CountryCode | New value to set. Must not be empty. |
{"action": "changeCountries","countries": ["DE", "US"]}
Change Languages
Removing a language used by a Store returns a LanguageUsedInStores error.
action String | "changeLanguages" |
languages Array of Locale | New value to set. Must not be empty. |
{"action": "changeLanguages","languages": ["en", "de", "de-DE"]}
Change Messages Configuration
action String | "changeMessagesConfiguration" |
messagesConfiguration | Configuration for the Messages Query feature. |
{"action": "changeMessagesConfiguration","messagesConfiguration": {"enabled": true,"deleteDaysAfterCreation": 30}}
Change Carts Configuration
action String | "changeCartsConfiguration" |
cartsConfiguration | Configuration for the Carts feature. |
Change CountryTaxRateFallbackEnabled
action String | "changeCountryTaxRateFallbackEnabled" |
countryTaxRateFallbackEnabled Boolean | When false |
{"action": "changeCountryTaxRateFallbackEnabled","countryTaxRateFallbackEnabled": true}
Change ShoppingLists Configuration
action String | "changeShoppingListsConfiguration" |
shoppingListsConfiguration | Configuration for the Shopping Lists feature. |
Change My Business Unit Status on Creation
action String | "changeMyBusinessUnitStatusOnCreation" |
status | Status for Business Units created using the My Business Unit endpoint. |
{"action": "changeMyBusinessUnitStatusOnCreation","status": "Active"}
Set My Business Unit Associate Role on Creation
action String | "setMyBusinessUnitAssociateRoleOnCreation" |
associateRole | Default Associate Role assigned to the Associate creating a Business Unit using the My Business Unit endpoint. |
{"action": "setMyBusinessUnitAssociateRoleOnCreation","associateRole": {"typeId": "associate-role","key": "admin"}}
Set ShippingRateInputType
action String | "setShippingRateInputType" |
shippingRateInputType | Value to set. If empty, any existing value will be removed. |
{"action": "setShippingRateInputType","shippingRateInputType": {"type": "CartScore"}}
Set ExternalOAuth
action String | "setExternalOAuth" |
externalOAuth | Value to set. If empty, any existing value will be removed. |
Change Product Search Indexing Enabled
action String | "changeProductSearchIndexingEnabled" |
enabled Boolean |
|
Controls whether the action should apply to Product Projection Search or to Product Search. Default:ProductProjectionsSearch |
{"action": "changeProductSearchIndexingEnabled","enabled": true,"mode": "ProductsSearch"}
Change Order Search Status BETA
action String | "changeOrderSearchStatus" |
status | Activates or deactivates the Order Search feature. Activation will trigger building a search index for the Orders in the Project. |
{"action": "changeOrderSearchStatus","status": "Activated"}
Change Customer Search Status
action String | "changeCustomerSearchStatus" |
status | Activates or deactivates the Customer Search feature. Activation will trigger building a search index for the Customers in the Project. |
{"action": "changeCustomerSearchStatus","status": "Activated"}