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.

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 true, the Messages Query feature is active.

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: 15Minimum: 1Maximum: 90

MessagesConfigurationDraft

Defines the configuration for the Messages Query feature for the Project.

enabled
Boolean

Setting to true activates the Messages Query feature.

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: 1Maximum: 90

CartsConfiguration

deleteDaysAfterLastModification
Int

Default value for the deleteDaysAfterLastModification parameter of the CartDraft and MyCartDraft. If a ChangeSubscription for Carts exists, a ResourceDeletedDeliveryPayload is sent upon deletion of a Cart.

This field may not be present on Projects created before January 2020.

Default: 90Minimum: 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 deleteDaysAfterLastModification parameter of the ShoppingListDraft. This field may not be present on Projects created before January 2020.

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

The classification items that can be used for specifying any ShippingRatePriceTier.

Example: json
{
"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.

Configuration for the Product Projection Search and Product Suggestions endpoints.

Configuration for the Product Search feature.

Configuration for the Order Search feature.

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.

lastModifiedByBETA

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

For Product Projection Search.

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

GET
https://api.{region}.commercetools.com/{projectKey}
OAuth 2.0 Scopes:
view_project_settings:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

Response:
200Projectasapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: Projectjson
{
"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

HEAD
https://api.{region}.commercetools.com/{projectKey}

Checks if a Project exists for a given projectKey. Returns a 200 OK status if the Project exists or a 404 Not Found otherwise.

OAuth 2.0 Scopes:
view_project_settings:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Update Project

POST
https://api.{region}.commercetools.com/{projectKey}
OAuth 2.0 Scopes:
manage_project_settings:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

Request Body:
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

Update actions to be performed on the Project.

Response:
200Projectasapplication/json
Request Example:cURL
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
200 Response Example: Projectjson
{
"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.

Example: json
{
"action": "changeName",
"name": "CTP Postman Monitor"
}

Change Currencies

action
String
"changeCurrencies"
currencies
Array of CurrencyCode

New value to set. Must not be empty.

Example: json
{
"action": "changeCurrencies",
"currencies": ["EUR"]
}

Change Countries

action
String
"changeCountries"
countries
Array of CountryCode

New value to set. Must not be empty.

Example: json
{
"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.

Example: json
{
"action": "changeLanguages",
"languages": ["en", "de", "de-DE"]
}

Change Messages Configuration

action
String
"changeMessagesConfiguration"
messagesConfiguration

Configuration for the Messages Query feature.

Example: json
{
"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 true, country - no state Tax Rate is used as fallback. See CartsConfiguration.

Default: false
Example: json
{
"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 for Business Units created using the My Business Unit endpoint.

Example: json
{
"action": "changeMyBusinessUnitStatusOnCreation",
"status": "Active"
}

Set My Business Unit Associate Role on Creation

action
String
"setMyBusinessUnitAssociateRoleOnCreation"

Default Associate Role assigned to the Associate creating a Business Unit using the My Business Unit endpoint.

Example: json
{
"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.

Example: json
{
"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
  • If false, the indexing of Product information will stop and the Product Projection Search as well as the Product Suggestions endpoint will not be available anymore for this Project. The Project's SearchIndexingConfiguration status for products will be changed to "Deactivated".
  • If true, the indexing of Product information will start and the Product Projection Search as well as the Product Suggestions endpoint will become available soon after for this Project. Proportional to the amount of information being indexed, the Project's SearchIndexingConfiguration status for products will be shown as "Indexing" during this time. As soon as the indexing has finished, the configuration status will be changed to "Activated" making the aforementioned endpoints fully available for this Project.

Controls whether the action should apply to Product Projection Search or to Product Search.

Default: ProductProjectionsSearch
Example: json
{
"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.

Example: json
{
"action": "changeOrderSearchStatus",
"status": "Activated"
}

Change Customer Search Status

action
String
"changeCustomerSearchStatus"

Activates or deactivates the Customer Search feature. Activation will trigger building a search index for the Customers in the Project.

Example: json
{
"action": "changeCustomerSearchStatus",
"status": "Activated"
}