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

MessagesConfiguration

MessagesConfigurationDraft

CartsConfiguration

ShoppingListsConfiguration

ShippingRateInputType -CartValueType -CartClassificationType -CartScoreType

ExternalOAuth

SearchIndexingConfiguration

SearchIndexingConfigurationValues -SearchIndexingConfigurationStatus

CustomerSearchStatus

OrderSearchStatus

ProductSearchStatus

ProductSearchIndexingMode

BusinessUnitConfiguration -BusinessUnitConfigurationStatus

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

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.

`products` SearchIndexingConfigurationValues	Configuration for the Product Projection Search and Product Suggestions endpoints.
`productsSearch`BETA SearchIndexingConfigurationValues	Configuration for the Product Search feature.
`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	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 BETA

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 endpoint is fully operational.
Deactivated: indicates that the Customer Search enpoint 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.

ProductSearchStatus BETA

Specifies the status of the Product Search index.

Activated: indicates that the Search Products endpoint is fully operational.
Deactivated: indicates that the Product Search feature is currently not active.

ProductSearchIndexingMode BETA

ProductProjectionsSearch: For Product Projection Search.
ProductsSearch: For Product Search.

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

by Project Key

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

Check if Project exists

by Project Key

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

by Project Key

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` 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 Messages Configuration

Change Carts Configuration

Change CountryTaxRateFallbackEnabled

Change ShoppingLists Configuration

Change My Business Unit Status on Creation

Set My Business Unit Associate Role on Creation

Set ShippingRateInputType

Set ExternalOAuth

Change Product Search Indexing Enabled

Change Order Search Status

Change Customer Search Status

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.
`mode`BETA ProductSearchIndexingMode	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` 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"
}

Change Customer Search Status BETA

`action` String	`"changeCustomerSearchStatus"`
`status` CustomerSearchStatus	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"
}