Documentation

Project

View and manage all Project-wide settings, such as countries, languages, and currencies, as well as feature-specific configurations via these endpoints. You can create Projects only in the Merchant Center.

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.
discounts​
DiscountsConfiguration​

Holds configuration specific to discounts, including how Product and Cart Discounts are combined in every Cart of the Project.

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.
Default: 90​Minimum: 1​Maximum: 365250​
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​
priceRoundingMode​
RoundingMode​
Default value for the priceRoundingMode parameter of the CartDraft. Indicates how the total prices on LineItems and CustomLineItems are rounded when calculated.
Default: HalfEven​
taxRoundingMode​
RoundingMode​
Default value for the taxRoundingMode parameter of the CartDraft. Indicates how monetary values are rounded when calculating taxes for taxedPrice.
Default: HalfEven​

ShoppingListsConfiguration

deleteDaysAfterLastModification​
Int​
Default value for the deleteDaysAfterLastModification parameter of the ShoppingListDraft. This field may not be present on Projects created before January 2020.
Default: 360​Minimum: 1​Maximum: 365250​

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 Search Term Suggestions APIs.
productsSearch​
SearchIndexingConfigurationValues​
Configuration for the Product Search feature.
orders​BETA
SearchIndexingConfigurationValues​
Configuration for the Order Search feature.
customers​
SearchIndexingConfigurationValues​
Configuration for the Customer Search feature.
businessUnits​
SearchIndexingConfigurationValues​
Configuration for the Business Unit 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

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.

BusinessUnitSearchStatus B2B

Specifies the status of the Business Unit Search index. You can change the status using the Change Business Unit Search Status update action.
Activated

indicates that the Business Unit Search feature is fully operational.

Deactivated

indicates that the Business Unit 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 B2B

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 B2B

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.

DiscountsConfiguration

Holds the configuration for behavior of Product and Cart Discounts.

discountCombinationMode​
DiscountCombinationMode​
Indicates how Product Discounts and Cart Discounts should be combined. Default value is Stacking.

DiscountCombinationMode

Defines how Product Discounts and Cart Discounts are combined for every Cart in a Project.

BestDeal

Either Product Discounts or Cart Discounts are chosen based on best deal for the customer. Only one type applies per Cart.

Stacking

Product Discounts and Cart Discounts are both applied to the Cart, potentially increasing the total discount.

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:
200

Project

as
application/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
  },
  "discounts": {
    "discountCombinationMode": "Stacking"
  }
}

Check if Project exists

HEAD
https://api.{region}.commercetools.com/{projectKey}
Checks if a Project exists for a given projectKey. Returns a 200 status if the Project exists, or a 404 status 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:
200

Project

as
application/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
  },
  "discounts": {
    "discountCombinationMode": "Stacking"
  }
}

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.
Example: json
{
  "action": "changeCartsConfiguration",
  "cartsConfiguration": {
    "deleteDaysAfterLastModification": 42,
    "countryTaxRateFallbackEnabled": false,
    "priceRoundingMode": "HalfEven",
    "taxRoundingMode": "HalfEven"
  }
}

Set Discounts Configuration

action​
String​
"setDiscountsConfiguration"
discountsConfiguration​
DiscountsConfiguration​

Configuration for the behavior of Cart and Product Discounts in the Project.

Example: json
{
  "action": "setDiscountsConfiguration",
  "discountsConfiguration": {
    "discountCombinationMode": "Stacking"
  }
}

Change Price RoundingMode

action​
String​
"changePriceRoundingMode"
priceRoundingMode​
RoundingMode​
Project-level default rounding mode for calculating the total prices on LineItems and CustomLineItems. See CartsConfiguration.
Example: json
{
  "action": "changePriceRoundingMode",
  "priceRoundingMode": "HalfDown"
}

Change Tax RoundingMode

action​
String​
"changeTaxRoundingMode"
taxRoundingMode​
RoundingMode​
Project-level default rounding mode for tax calculation. See CartsConfiguration.
Example: json
{
  "action": "changeTaxRoundingMode",
  "taxRoundingMode": "HalfDown"
}

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.
Example: json
{
  "action": "changeShoppingListsConfiguration",
  "shoppingListsConfiguration": {
    "deleteDaysAfterLastModification": 42
  }
}

Change My Business Unit Status on Creation B2B

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 B2B

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

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

Change Business Unit Search Status B2B

action​
String​
"changeBusinessUnitSearchStatus"
status​
BusinessUnitSearchStatus​
Activates or deactivates the Search Business Units feature. Activation will trigger building a search index for the Business Units in the Project.
Example: json
{
  "action": "changeBusinessUnitSearchStatus",
  "status": "Activated"
}