This is the early access documentation preview for Custom Views. This documentation might not be in sync with our official 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

MessagesConfiguration

MessagesConfigurationDraft

CartsConfiguration

ShoppingListsConfiguration

ShippingRateInputType -CartValueType -CartClassificationType -CartScoreType

ExternalOAuth

SearchIndexingConfiguration

SearchIndexingConfigurationValues -SearchIndexingConfigurationStatus

OrderSearchStatus

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

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