Loading...
Area: Optimizely Service API
Applies to versions: 1 and higher

Catalog entries

Recommended reading 

This topic describes how to work with RESTful operations for catalogs entries in the Optimizely Service API. The Service API supports published versions of catalogs (from version 1.0 and higher), as well as common draft versions of catalogs (from version 5.1.0). 

In this topic

    Example models

    [Serializable]
    public class NameValue
      {
        public string Name { get; set; }
        public string Value { get; set; }
      }
    [Serializable]
    public class ResourceLink
      {
        public string Title { get; set; }
        public string Type { get; set; }
        public string Href { get; set; }
        public List<NameValue> Properties { get; set; }
      }  
    
    [Serializable]
    public class SeoInfo
      {
        public string Title { get; set; }
        public string Uri { get; set; }
        public string UriSegment { get; set; }
        public string Description { get; set; }
        public string Keywords { get; set; }
        public string LanguageCode { get; set; }
      }
        
    [Serializable]
    public class MetaFieldData
      {
        public string Language { get; set; }
        public string Value { get; set; }
      }
    
    [Serializable]
    public class MetaFieldProperty
      {
        public string Name { get; set; }
        public string Type { get; set; }
        public List<MetaFieldData> Data { get; set; }
      }
    
    [Serializable]
    public class VariationProperties
      {
        public decimal MinQuantity { get; set; }
        public decimal MaxQuantity { get; set; }
        public double Weight { get; set; }
        public String TaxCategory { get; set; }
      }
    
    [Serializable]
    public class DimensionProperties
      {
        public double Length { get; set; }
        public double Heigth { get; set; }
        public double Width {get; set; }
      }
    
    [Serializable]
    public class Entry
      {
        public Entry()
          {
            SeoInformation = new List<SeoInfo>();
            Assets = new List<ResourceLink>();
            Associations = new List<ResourceLink>();
            MetaFields = new List<MetaFieldProperty>();
            WarehouseInventories = new List<ResourceLink>();
            Prices = new List<ResourceLink>();
            ChildCatalogEntries = new List<ResourceLink>();
            Nodes = new List<ResourceLink>();
            ParentCatalogEntry = new ResourceLink();
            Variation = null;
          }
        public string Code { get; set; }
        public Guid? ApplicationId { get; set; }
        public string Name { get; set; }
        public ResourceLink ParentCatalogEntry { get; set; }
        public DateTime StartDate { get; set; }
        public DateTime EndDate { get; set; }
        public bool IsActive { get; set; }
        public string MetaClass { get; set; }
        public string Catalog { get; set; }
        public List<MetaFieldProperty> MetaFields { get; set; }
        public List<SeoInfo> SeoInformation { get; set; }
        public List<ResourceLink> Prices { get; set; }
        public string EntryType { get; set; }
        public List<ResourceLink> ChildCatalogEntries { get; set; }
        public string InventoryStatus { get; set; }
        public List<ResourceLink> WarehouseInventories { get; set; }
        public List<ResourceLink> Associations { get; set; }
        public List<ResourceLink> Assets { get; set; }
        public List<ResourceLink> Nodes { get; set; }
        public VariationProperties Variation { get; set; }
        public DimensionProperties Dimension {get; set; }
      }
    
    [Serializable]
    public class Entries
      {
        public Entries()
          {
            EntryResults = new List<Entry>();
            TotalCount = 0;
            TotalPages = 0;
          }
        public List<Entry> EntryResults { get; set; }
        public int TotalCount { get; set; }
        public int TotalPages { get; set; }
      }

    Published catalog entries

    Get all entries

    By default this method gets all languages for the entries. If you want only one specific language, use the Accept-Language header. 

    get/episerverapi/commerce/entries/{startPage}/{pageSize}

    JSON response type

    C# code sample

    var client = new HttpClient()
      {
        BaseAddress = new Uri(ConfigurationManager.AppSettings["integrationUrl"])
      };
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token.AccessToken);		
    var result = client.GetAsync("/episerverapi/commerce/entries/{startPage}/{pageSize}").Result.Content.ReadAsStringAsync().Result

    XML response type

    Get a specific entry

    By default this method gets all languages for the entry. If you want only one specific language use the Accept-Language header.

    get/episerverapi/commerce/entries/{entryCode}

    JSON response type

    C# code sample

    var client = new HttpClient()
      {
        BaseAddress = new Uri(ConfigurationManager.AppSettings["integrationUrl"])
      };
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token.AccessToken);		
    var result = client.GetAsync("/episerverapi/commerce/entries/{entry code}").Result.Content.ReadAsStringAsync().Result

    XML response type

    Create entry

    post/episerverapi/commerce/entries

    JSON response type

    C# code sample

    var model = new Entry()
      {
        Code = "WhoKnewBaby",
        Catalog = "Departmental Catalog",
        EndDate = DateTime.UtcNow.AddDays(100),
        EntryType = "Product",
        InventoryStatus = "Enabled",
        IsActive = true,
        MetaClass = "Fashion_Product_Class",
        Name = "Test",
        StartDate = DateTime.UtcNow,
        MetaFields = new List<MetaFieldProperty>()
          {
            new MetaFieldProperty()
              {
                Name = "DisplayName",
                Type = "ShortString",
                Data = new List<MetaFieldData>()
                  {
                    new MetaFieldData()
                      {
                        Language="en",
                        Value = "DisplayName"
                      }
                  }
              }
          },
        SeoInformation = new List<SeoInfo>()
          {
            new SeoInfo()
              {
                Description = "description",
                Keywords="",
                LanguageCode = "en",
                Title = "title",
                Uri = "whoknew",
                UriSegment = "whoknew"
              }
          }
      };
    var json = JsonConvert.SerializeObject(model);
    var client = new HttpClient()
      {
        BaseAddress = new Uri(ConfigurationManager.AppSettings["integrationUrl"])
      };
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token.AccessToken);    
    var result = client.PostAsync("/episerverapi/commerce/entries",
                 new StringContent(json, Encoding.UTF8, "application/json")).Result.Content.ReadAsStringAsync().Result

    XML response type

    Update entry

    put/episerverapi/commerce/entries/{entryCode}

    JSON response type

    C# code sample

    var model = new Entry()
      {
        Code = "Dresses-Cocktail-Silk",
        Catalog = "Departmental Catalog",
        EndDate = DateTime.UtcNow.AddDays(100),
        EntryType = "Product",
        InventoryStatus = "Enabled",
        IsActive = true,
        MetaClass = "Fashion_Product_Class",
        Name = "Test",
        StartDate = DateTime.UtcNow,
        MetaFields = new List<MetaFieldProperty>()
          {
            new MetaFieldProperty()
              {
                Name = "DisplayName",
                Type = "ShortString",
                Data = new List<MetaFieldData>()
                  {
                    new MetaFieldData()
                      {
                        Language="en",
                        Value = "Dresses-Cocktail-Silk"
                      }
                  }
              }
          },
        SeoInformation = new List<SeoInfo>()
          {
            new SeoInfo()
              {
                Description = "description",
                Keywords="",
                LanguageCode = "en",
                Title = "title",
                Uri = "Dresses-Cocktail-Silk",
                UriSegment = "Dresses-Cocktail-Silk"
              }
          }
      };
    var json = JsonConvert.SerializeObject(model);
    var client = new HttpClient()
      {
        BaseAddress = new Uri(ConfigurationManager.AppSettings["integrationUrl"])
      };
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token.AccessToken);    
    var result = client.PutAsync("/episerverapi/commerce/entries/{entry code}",
                 new StringContent(json, Encoding.UTF8, "application/json")).Result.Content.ReadAsStringAsync().Result

    XML response type

    Delete entry

    delete/episerverapi/commerce/entries/{entryCode}

    JSON response type

    C# code sample

    var client = new HttpClient()
      {
        BaseAddress = new Uri(ConfigurationManager.AppSettings["integrationUrl"])
      };
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token.AccessToken);		
    var result = client.DeleteAsync("/episerverapi/commerce/entries/{entry code}").Result.Content.ReadAsStringAsync().Result

    XML response type

    Common draft entries [New in Service API 5.1.0]

    Use the endpoints listed below to get common draft versions, create new common drafts, and update or delete existing drafts.

    Get common draft entry

    get/episerverapi/commerce/entries/{entryCode}/commondraft/{lang}

    JSON response type

    C# code sample

    var client = new HttpClient()
      {
        BaseAddress = new Uri(ConfigurationManager.AppSettings["integrationUrl"])
      };
    client.DefaultRequestHeaders.Authorization = new AuthorizationHeaderValue("Bearer", token.AccessToken);
    var result = client.GetAsync("/episerverapi/commerce/entries/Code_1/commondraft/en").Result.Content.ReadAsStringAsync().Result;

    XML response type

    Create common draft entry

    Note: The Optimizely Service API does not support creating common drafts for non-existing content. You can create a first draft version by using an endpoint for published content (without “commondraft”) and setting IsActive to “false”.

    post/episerverapi/commerce/entries/commondraft/{lang}

    JSON response type

    C# code sample

    var _model = new DraftEntry
      {
        Code = "Code 3",
        Catalog = "TESTROOTCATALOG",
        EndDate = DateTime.UtcNow.AddDays(100),
        EntryType = "Variation",
        InventoryStatus = "Enabled",
        MetaClass = DefaultEntryMetaClassName,
        Name = "Test",
        StartDate = DateTime.UtcNow,
        MetaFields = new List<DraftMetaFieldProperty>
          {
             new DraftMetaFieldProperty
               {
                 Name = "Description",
                 Type = MetaDataType.LongHtmlString.ToString(),
                 Data = "Description"
                },
             new DraftMetaFieldProperty()
               {
                 Name = "DisplayName",
                 Type = MetaDataType.ShortString.ToString(),
                 Data = "DisplayName"
               },
             new DraftMetaFieldProperty
               {
                  Name = "DecimalType",
                  Type = MetaDataType.Decimal.ToString(),
                  Data = $"{13.44.ToString(culture)}"
               },
             new DraftMetaFieldProperty
               {
                  Name = "AnotherMultilanguageString",
                  Type = MetaDataType.ShortString.ToString(),
                  Data = "Set with lang key EN for en"
               },
             new DraftMetaFieldProperty
               {
                   Name = "AStringDictionaryMetaField",
                   Type = MetaDataType.StringDictionary.ToString(),
                   Data = "Hello;world"
                },
             new DraftMetaFieldProperty
                {
                   Name = "StringList",
                   Type = MetaDataType.LongString.ToString(),
                   Data = "[\"Item 1\",\"Item 2\"]"
                },
              new DraftMetaFieldProperty
                {
                   Name = "IntList",
                   Type = MetaDataType.LongString.ToString(),
                   Data = $"[{10},{11},{12}]"
                },
              new DraftMetaFieldProperty
                {
                   Name = "DoubleList",
                   Type = MetaDataType.LongString.ToString(),
                   Data = $"[{100.05.ToString(culture)},{100.06.ToString(culture)},{100.07.ToString(culture)},{100.08.ToString(culture)}]"
                },
              new DraftMetaFieldProperty
                {
                   Name = "DateTimeList",
                   Type = MetaDataType.LongString.ToString(),
                   Data = $"[\"{DateTime.Now.ToString(culture)}\",\"{DateTime.Now.AddDays(1).ToString(culture)}\"]"
                }
          },
        Variation = new VariationProperties
          {
            MaxQuantity = 100,
            MinQuantity = 0,
            TaxCategory = "",
            Weight = 5.1,
          },
        Dimension = new DimensionProperties 
          { 
            Length= 100.34,
            Height = 0,
            Width= 5.1 
          }
      }
    var json = JsonConvert.SerializeObject(model);
    var client = new HttpClient()
      {
        BaseAddress = new Uri(ConfigurationManager.AppSettings["integrationUrl"])
      };
    client.DefaultRequestHeaders.Authorization = new AuthorizationHeaderValue("Bearer", token.AccessToken);
    var result = client.PostAsync("/episerverapi/commerce/entries/commondraft/en",
                 new StringContent(json, Encoding.UTF8, "application/json")).Result.Content.ReadAsStringAsync().Result;

    XML response type

    Update common draft entry

    Notes: If common draft content is in “Published” state, a new common draft version is created (same behavior as Post common draft). If common draft content is in a DelayedPublish/AwaitingApproval/CheckedIn state, then it skips updating content and returns a Conflict status code (409).

    put/episerverapi/commerce/entries/{entryCode}/commondraft/{lang}

    JSON response type

    C# code sample

    var entryLink = ReferenceConverter.GetContentLink(“Code_1”, CatalogContentType.CatalogEntry);
    var entry = ContentLoader.Get<EntryContentBase>(entryLink);
    if (entry != null)
      {
        _model = ServiceLocator.Instance.GetInstance<EntryModelFactory>()
        .CreateDraftEntryModel(entry, "");
        _model.Name = "Put Test";
        _model.SeoInformation.Uri = "NewEntryUri";
       
        var json = JsonConvert.SerializeObject(_model);
        var client = new HttpClient()
          {
            BaseAddress = new Uri(ConfigurationManager.AppSettings["integrationUrl"])
          };
        client.DefaultRequestHeaders.Authorization = new AuthorizationHeaderValue("Bearer", token.AccessToken);
        var result = client.PutAsync("/episerverapi/commerce/entries/Code_1/commondraft/en", 
                     new StringContent(json, Encoding.UTF8, "application/json")).Result.Content.ReadAsStringAsync().Result;  
      }

    XML response type

    Delete common draft entry

    delete/episerverapi/commerce/entries/{entryCode}/commondraft/{lang}

    JSON response type

    C# code sample

    var client = new HttpClient()
      {
        BaseAddress = new Uri(ConfigurationManager.AppSettings["integrationUrl"])
      };
    client.DefaultRequestHeaders.Authorization = new AuthorizationHeaderValue("Bearer", token.AccessToken);
    var result = client.DeleteAsync("/episerverapi/commerce/entries/Code_1/commondraft/en").Result.Content.ReadAsStringAsync().Result;

    XML response type

    Special strings and characters

    Special strings

    Theses properties require special values to function properly.

    InventoryStatus

    • Enabled
    • Disabled
    • Ignored

    EntryType

    • Product
    • Variation
    • Package
    • Bundle
    • DynamicPackage

    Special characters in entry code [New version 5.4.2]

    As of version 5.4.2, the Service API supports special characters (such as "/", "%" or "+") in the entry code for all actions (get all, get a specific, post, put or delete) for these objects:

    • Catalog entry
    • Catalog entry association
    • Catalog entry relation
    • Catalog item asset
    • Catalog entry price

    The special characters must be double-encoded then sent to the Service API. For example, the slash character (/) is double-encoded as %252F.

    Note: Because double escaping in URLs involves security risks, it is preferable to avoid this approach.

    To enable double-encoding support, edit the site 's web.config file as shown below:

    <system.webServer>
        <security>
            <requestFiltering allowDoubleEscaping="true"/>
        </security>
    </system.webServer>
    
    <httpRuntime requestPathInvalidCharacters="&lt;,&gt;,*,&amp;,:,\,?" />
    

    Note: The characters listed after requestPathInvalidCharacters are only an example of special characters for which you can enable double-encoding support. You can modify the list as needed.

    Related topics

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

    Last updated: Apr 23, 2021

    Recommended reading