Loading...
Area: Episerver Content Delivery API
Applies to versions: 2.9.0 and higher

Content Delivery API and Commerce

Recommendations [hide]

Overview

The EPiServer.ContentDeliveryApi.Commerce – CD.Commerce package allows clients to acquire “Package Content”, “Product Content”, “Variation content” and all that inherits EntryContentBase. Data exposed through endpoints include general information of catalog content, its variants and/or entries, inventory, pricing, and warehouse.

Note: This document describes the Content Search API's main features and usage. For a complete list of valid endpoints and query parameters, please refer to the Content Delivery API SDK.

In this topic

Installation

The CD.Commerce package is installed with the NuGet package: EPiServer.ContentDeliveryApi.Commerce.

  • CD.Commerce package requires EPiServer.Commerce version >= 13.12.0 and < 14 to be installed in order to work.

Catalog Content

CD.Commerce adds catalog data to the existing endpoints of CD.Cms.

  1. Using a full content reference including provider name:
    /api/episerver/v2.0/content/{{contentreference}}__{{contentprovider}}​
  2. Using a content Guid:
    /api/episerver/v2.0/content/{{contentguid}}​

Fetching product data using its friendly url + content negotiation is also supported. Here are some examples:

Request:

  • Using a friendly url: /en/music-festival/tickets/single-day-ticket/ [With Accept = application/json]
  • Using content reference: api/episerver/v2.0/content/1__CatalogContent
  • Using content Guid: api/episerver/v2.0/content/1aff88a0-6db1-4436-b3eb-12adc987af9e

Response:

{
  "assets"            : [
                          "/globalassets/artist-images/pigment-of-dawn.jpg"
                        ],
  "contentLink"       : {
                          "id"           : 1,
                          "workId"       : 0,
                          "guidValue"    : "1aff88a0-6db1-4436-b3eb-12adc987af9e",
                          "providerName" : "CatalogContent",
                          "url"          : "/en/music-festival/tickets/single-day-ticket/",
                          "expanded"     : null
                        },
  "name"              : "Single Day Ticket",
  "language"          : {
                          "link"        : "/en/music-festival/tickets/single-day-ticket/",
                          "displayName" : "English",
                          "name"        : "en"
                        },
  "existingLanguages" : [
                          {
                            "link"        : "/en/music-festival/tickets/single-day-ticket/",
                            "displayName" : "English",
                            "name"        : "en"
                          }
                        ],
  "masterLanguage"    : {
                          "link"        : "/en/music-festival/tickets/single-day-ticket/",
                          "displayName" : "English",
                          "name"        : "en"
                        },
  "contentType"       : [
                          "FestivalProduct"
                        ],
  "parentLink"        : {
                          "id"           : 1073741825,
                          "workId"       : 0,
                          "guidValue"    : "fd1f026a-390f-4171-89e4-c44b1bd118af",
                          "providerName" : "CatalogContent",
                          "url"          : "/en/music-festival/tickets/",
                          "expanded"     : null
                        },
  "routeSegment"      : "single-day-ticket",
  "url"               : "/en/music-festival/tickets/single-day-ticket/",
  "changed"           : "2019-07-15T08:34:52.2Z",
  "created"           : "2019-07-15T08:34:49Z",
  "startPublish"      : "2019-07-15T08:34:49.863Z",
  "stopPublish"       : "2029-07-15T08:34:49.863Z",
  "saved"             : "2019-07-15T08:34:52.2Z",
  "status"            : "Published",
  "displayName"       : "Single Day Ticket",
  "brand"             : "",
  "longDescription"   : "",
  "sizing"            : "",
  "productTeaser"     : "",
  "availableSizes"    : [],
  "availableColors"   : [],
  "description"       : "",
  "seoInformation"    : {
                          "title"       : null,
                          "description" : null,
                          "keywords"    : null
                        },
  "seoUri"            : "Single-Day-Ticket-en.aspx",
  "code"              : "Single-Day-Ticket_1",
  "metaClassId"       : 27,
  "catalogId"         : 1
}

To avoid over-fetching, variants and entries are not returned in the normal payload, but can be retrieved using “/children”.

Request: api/episerver/v2.0/content/1__CatalogContent/children

Response:

[
  {
    "assets"             : [],
    "contentLink"        : {
                             "id"           : 3,
                             "workId"       : 0,
                             "guidValue"    : "3c69e19f-43eb-40cf-b0ba-4a61c6d443f4",
                             "providerName" : "CatalogContent",
                             "url"          : "/en/music-festival/tickets/single-day-ticket---monday/",
                             "expanded"     : null
                           },
    "name"               : "Single Day Ticket - Monday",
    "language"           : {
                             "link"        : "/en/music-festival/tickets/single-day-ticket---monday/" ,
                             "displayName" : "English",
                             "name"        : "en"
                           },
    "existingLanguages"  : [
                             {
                               "link"        : "/en/music-festival/tickets/single-day-ticket---monday/" ,
                               "displayName" : "English",
                               "name"        : "en"
                             }
                           ],
    "masterLanguage"     : {
                             "link"        : "/en/music-festival/tickets/single-day-ticket---monday/",
                             "displayName" : "English",
                             "name"        : "en"
                           },
    "contentType"        : [
                             "FashionVariant"
                           ],
    "parentLink"         : {
                             "id"           : 1073741825,
                             "workId"       : 0,
                             "guidValue"    : "fd1f026a-390f-4171-89e4-c44b1bd118af",
                             "providerName" : "CatalogContent",
                             "url"          : "/en/music-festival/tickets/",
                             "expanded"     : null
                           },
    "routeSegment"       : "single-day-ticket---monday",
    "url"                : "/en/music-festival/tickets/single-day-ticket---monday/",
    "changed"            : "2019-07-15T09:23:23.833Z",
    "created"            : "2019-07-15T09:23:08Z",
    "startPublish"       : "2019-07-15T09:23:08.653Z",
    "stopPublish"        : "2029-07-15T09:23:08.653Z",
    "saved"              : "2019-07-15T09:23:23.833Z",
    "status"             : "Published",
    "displayName"        : "Single Day Ticket - Monday",
    "size"               : "",
    "color"              : "",
    "minQuantity"        : 0.000000000,
    "taxCategoryId"      : 0,
    "seoInformation"     : {
                             "title"       : null,
                             "description" : null,
                             "keywords"    : null
                           },
    "maxQuantity"        : 0.000000000,
    "seoUri"             : "Single-Day-Ticket-Monday-en.aspx",
    "weight"             : 0.0,
    "code"               : "Single-Day-Ticket---Monday_1",
    "shippingPackageId"  : 0,
    "shippingDimensions" : {
                             "length" : 0.0,
                             "height" : 0.0,
                             "width"  : 0.0
                           },
    "trackInventory"     : false,
    "metaClassId"        : 28,
    "catalogId"          : 1
  }
]

Inventory

CD.Commerce exposes a separate endpoint /api/episerver/v2.0/inventory?contentId={{contentguid}} to query inventory info. Clients send a request to the endpoint along with the catalog content contentId in the query string to acquire inventory info.

Request: /api/episerver/v2.0/inventory?contentId=3c69e19f-43eb-40cf-b0ba-4a61c6d443f4

Response:

[
  {
    "entryCode"                 : "Single-Day-Ticket---Monday_1",
    "warehouseCode"             : "default",
    "purchaseAvailableQuantity" : 1000.0,
    "purchaseRequestedQuantity" : 0.0,
    "purchaseAvailable"         : "2019-11-30T17:00:00Z"
  }
]

Warehouse

Similar to Inventory, warehouse info is available from a separate endpoint. Clients can send requests to the endpoint along with warehouse code /api/episerver/v2.0/warehouse/{{warehouseCode]} to retrieve warehouse information.

Request: /api/episerver/v2.0/warehouse/default

Response:

{
  "name"                : "Default Warehouse",
  "modified"            : "2013-12-11T09:56:48.99Z",
  "code"                : "default",
  "contactInformation"  : {
                            "firstName"          : "",
                            "lastName"           : "",
                            "organization"       : "",
                            "line1"              : "",
                            "line2"              : "",
                            "city"               : "",
                            "state"              : "",
                            "countryCode"        : "",
                            "countryName"        : "",
                            "postalCode"         : "",
                            "regionCode"         : "",
                            "regionName"         : "",
                            "daytimePhoneNumber" : "",
                            "eveningPhoneNumber" : "",
                            "faxNumber"          : "",
                            "email"              : ""
                          },
  "isFulfillmentCenter" : true,
  "isPickupLocation"    : true,
  "isDeliveryLocation"  : false
}

Pricing

Pricing also has its own endpoint /api/episerver/v2.0/pricing?contentIds={{contentIds}}&marketId={{marketId}}&currencyCode={{currencyCode}}

The response body contains all the prices for the product. A note here to make the result clearer is that price normally is decided by minQuantity (the larger quantity you buy, the less you pay for each item). Discounted prices only exist with default price (that has minQuantity equal to zero). Other prices will not have discounted price.     

Request: /api/episerver/v2.0/pricing?contentIds=3c69e19f-43eb-40cf-b0ba-4a61c6d443f4&marketId=default&currencyCode=USD

Response:

[
  {
    "entryCode"        : "Single-Day-Ticket---Monday_1",
    "prices"           : [
                           {
                             "price"       : 50.000000000,
                             "priceType"   : "AllCustomers",
                             "priceCode"   : "",
                             "validFrom"   : "2019-11-30T17:00:00Z",
                             "validUntil"  : "2019-12-30T17:00:00Z",
                             "minQuantity" : 0.000000000
                           },
                           {
                             "price"       : 30.000000000,
                             "priceType"   : "AllCustomers",
                             "priceCode"   : "",
                             "validFrom"   : "2019-11-30T17:00:00Z",
                             "validUntil"  : "2019-12-30T17:00:00Z",
                             "minQuantity" : 10.000000000
                           }
                         ],
    "discountedPrices" : [
                           {
                             "description"     : null,
                             "discountedPrice" : 40.000000000,
                             "defaultPrice"    : 50.000000000
                           },
                           {
                             "description"     : null,
                             "discountedPrice" : 28.0000000000,
                             "defaultPrice"    : 50.000000000
                           }
                         ]
  }
]

Music Festival and CD.Commerce

This section demonstrates how to combine the Music Festival sample site and Content Delivery API for Commerce to build a commerce site.

Note: This document only demonstrates the main concept of integrating Music Festival with CD.Commerce. For more detail, check out the sample code here: https://github.com/episerver/ContentDeliveryAPI.Samples/tree/master/ContentDeliveryAPI.Samples.SPA

To make Music Festival work with CD.Commerce and display catalog content, you need to install Episerver.Commerce and CD.Commerce to the Music Festival template. After that, you need to add some components for Commerce catalog contents (Vue components, APIs, Catalog models), and rebuild the client resources.

1. The Vue components:

These components are responsible for rendering the catalog contents:

  • CategoryPage.vue. This component is for displaying a list of products.
  • ProductPage.vue. This component is for displaying a product detail that includes inventory, warehouse, and discounted price.
  • ProductCard.vue. This component is for displaying a summary of a product.

2. Add new API to work with CD.Commerce endpoints: 

Define new APIs in the api.js file to interact with the endpoints of the CD.Commerce. For example, inventory, warehouse, and pricing:

getInventory: (parameters) =>
  get(`${applicationPath}api/episerver/v2.0/`, 
      'inventory', 
      parameters, 
      {'Accept-Language': '' })

getWarehouse: (warehouseCode) =>
  get(`${applicationPath}api/episerver/v2.0/`, 
      `warehouse/${warehouseCode}`, 
      {}, 
      { 'Accept-Language': '' })

getPricing: (parameters) =>
  get(`${applicationPath}api/episerver/v2.0/`, 
      'pricing', 
      parameters, 
      {'Accept-Language': '' })

3. Catalog Models:

Define the model for each type of catalog content:

  • CategoryNode
  • FestivalBundle
  • FestivalPackage
  • FestivalProduct
  • FestivalVariant

4. Rebuild client resources

Rebuild the client resources of the Music Festival site for the changes to take effect. Open a command line at the project's root folder and type npm run build to run the build script.

After the build process finishes, go to the Commerce menu in edit view and create some catalogs. Then, view these catalogs in the view mode and Music Festival will display them accordingly.

imagencqhf.png

Note: In some cases, Commerce will try to run its migration process. However, this migration requires the user to log in. If you have not logged in, the migration causes an infinite redirect loop between the Login page and the Migration page. You will probably see the error ERR_TOO_MANY_REDIRECTS” in the browser. In this case, add this key to <appSettings> section of web.config: 
<add key="AutoMigrateEPiServer" value="true"/>.
This key tells Commerce to run the migration process without requiring the user to log in. 

 

Do you find this information helpful? Please log in to provide feedback.

Last updated: Feb 03, 2020

Recommendations [hide]