Documentation

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​
MessagesConfiguration​

Holds the configuration for the Messages Query feature.

carts​
CartsConfiguration​

Holds the configuration for the Carts feature.

shoppingLists​
ShoppingListsConfiguration​

Holds the configuration for the Shopping Lists feature. This field may not be present on Projects created before January 2020.

shippingRateInputType​
ShippingRateInputType​

Holds the configuration for the tiered shipping rates feature.

externalOAuth​
ExternalOAuth​

Represents a RFC 7662 compliant OAuth 2.0 Token Introspection endpoint.

searchIndexing​
SearchIndexingConfiguration​

Controls indexing of resources to be provided on high performance read-only search endpoints.

businessUnits​
BusinessUnitConfiguration​

Holds configuration specific to Business Units.

createdAt​
DateTime​

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: 15​Minimum: 1​Maximum: 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: 1​Maximum: 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: 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 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 Prices, whereas CartClassificationType and CartScoreType use the shipppingRateInput field on the Cart to select a tier.

CartValueType

Used when the ShippingRate maps to the sum of LineItem Prices. The value of the Cart is used to select a tier. If chosen, it is not possible to set a value for the shippingRateInput on the Cart.

type​
String​
"CartValue"

CartClassificationType

Used when 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​
String​
"CartClassification"
values​
Array of CustomFieldLocalizedEnumValue​

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

Used when the ShippingRate maps to an abstract Cart categorization expressed by integers (such as shipping scores or weight ranges).

type​
String​
"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. If the Project is hosted in the China (AWS, Ningxia) Region, verify that the URL is not blocked due to firewall restrictions.

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​
SearchIndexingConfigurationValues​

Configuration for the Product Projection Search and Product Suggestions endpoints.

orders​BETA
SearchIndexingConfigurationValues​

Configuration for the Order Search feature.

SearchIndexingConfigurationValues

status​
SearchIndexingConfigurationStatus​

Current status of resource indexing. Present on Projects from 1 February 2019.

lastModifiedAt​
DateTime​

Date and time (UTC) the Project was last updated. Only present on Projects last modified after 1 February 2019.

lastModifiedBy​BETA
LastModifiedBy​

Present on resources created after 1 February 2019 except for events not tracked.

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.

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.

BusinessUnitConfiguration

myBusinessUnitStatusOnCreation​
BusinessUnitConfigurationStatus​

Status of Business Units created using the My Business Unit endpoint.

Default: Inactive​
myBusinessUnitAssociateRoleOnCreation​
AssociateRoleKeyReference​

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": "2013-11-01T15:14:34.325Z",
  "trialUntil": "2013-11-01T15:14:34.325Z",
  "messages": {
    "enabled": false
  },
  "carts": {
    "countryTaxRateFallbackEnabled": false
  }
}

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 is returned.

actions​
Array of ProjectUpdateAction​

Update actions to be performed on the Project.

Response:
200Projectasapplication/json
200 Response Example: Projectjson
{
  "version": 1,
  "key": "test-project",
  "name": "Some project name",
  "countries": ["DE", "US"],
  "currencies": ["EUR"],
  "languages": ["en"],
  "createdAt": "2013-11-01T15:14:34.325Z",
  "trialUntil": "2013-11-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​
MessagesConfigurationDraft​

Configuration for the Messages Query feature.

Example: json
{
  "action": "changeMessagesConfiguration",
  "messagesConfiguration": {
    "enabled": true,
    "deleteDaysAfterCreation": 30
  }
}

Change Carts Configuration

action​
String​
"changeCartsConfiguration"
cartsConfiguration​
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​
ShoppingListsConfiguration​

Configuration for the Shopping Lists feature.

Change My Business Unit Status on Creation

action​
String​
"changeMyBusinessUnitStatusOnCreation"
status​
BusinessUnitConfigurationStatus​

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"
associateRole​
AssociateRoleResourceIdentifier​

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​
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​
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.
Example: json
{
  "action": "changeProductSearchIndexingEnabled",
  "enabled": true
}

Change Order Search Status BETA

action​
String​
"changeOrderSearchStatus"
status​
OrderSearchStatus​

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"
}