Get started with Service API

4 min

The Optimizely Service API is a service layer that lets system integrators update and retrieve information from Optimizely Commerce, ensuring a seamless integration with external systems, such as product information management, data assessment management, and ERPs.

Use cases

The Optimizely Service API provides a programming interface for performing operations like:

Bulk import of mediamedia in Commerce.

Bulk import and export of catalog datacatalog data in Commerce.

Bulk asset linking between media and catalog contentmedia and catalog content .

Import and export of "episerverdata" content type of files.

Import and export of formsforms data.

RESTful CRUD operations for managing data integration with CatalogsCatalogs, Cart operations, Order operationsOrder operations, Customer operationsCustomer operations, and Content operationsContent operations.

The Optimizely Service API is installed as a NuGet package EPiServer.ServiceApi. The Service API is available for Optimizely Commerce version 8.5 and higher. See Installation and configuration how to install and set up the integration.

See also Service API for the REST API service layer.

The Service API integration service uses OWIN-based authentication and ASP.NET Identity, see Installation and configuration and Overview of bulk importing.

serviceapi.png

Requests and responses

Below is an example illustrating the usage of the REST API for managing CRUD operations.

GET carts by name and customer ID

/episerverapi/commerce/carts/{customerId}/{name}

Base path (base URL/host): episerverapi

Endpoint: commerce/carts/

Query string parameter(s): /{customerId}/{name}

GET	/episerverapi/commerce/carts/{customerId}/{cartName}/{marketId}

Example: Request GET method using C#/.NET

var client = new HttpClient()
  {
    BaseAddress = new Uri(ConfigurationManager.AppSettings["integrationUrl"])
  };

client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token.AccessToken);                                       

var result = client.GetAsync("/episerverapi/commerce/carts/`{customerId}`/`{name}`").Result.Content.ReadAsStringAsync().Result

JSON response

{
  "AddressId": "string",
  "AffiliateId": "00000000-0000-0000-0000-000000000000",
  "BillingCurrency": "string",
  "CustomerId": "00000000-0000-0000-0000-000000000000",
  "CustomerName": "string",
  "HandlingTotal": 0,
  "InstanceId": "00000000-0000-0000-0000-000000000000",
  "MarketId": "string",
  "Name": "string",
  "OrderAddresses": [
    {
      "OrderGroupAddressId": 0,
      "Name": "string",
      "FirstName": "string",
      "LastName": "string",
      "Organization": "string",
      "Line1": "string",
      "Line2": "string",
      "City": "string",
      "State": "string",
      "CountryCode": "string",
      "CountryName": "string",
      "PostalCode": "string",
      "RegionCode": "string",
      "RegionName": "string",
      "DaytimePhoneNumber": "string",
      "EveningPhoneNumber": "string",
      "FaxNumber": "string",
      "Email": "string",
      "Properties": [
        {
          "Key": "string",
          "Value": "string"
        }
      ]
    }
  ],
  "OrderForms": [
    {
      "Shipments": [
        {
          "DiscountsModel": [
            {
              "DiscountId": 0,
              "DiscountAmount": 0,
              "DiscountCode": "string",
              "DiscountName": "string",
              "DisplayMessage": "string",
              "DiscountValue": 0
            }
          ],
          "ShipmentId": 0,
          "ShippingMethodId": "00000000-0000-0000-0000-000000000000",
          "ShippingMethodName": "string",
          "ShippingTax": 0,
          "ShippingAddressId": "string",
          "ShipmentTrackingNumber": "string",
          "ShippingDiscountAmount": 0,
          "ShippingSubTotal": 0,
          "ShippingTotal": 0,
          "Status": "string",
          "PrevStatus": "string",
          "PickListId": 0,
          "SubTotal": 0,
          "WarehouseCode": "string",
          "LineItems": [
            {
              "LineItemId": 0,
              "Code": "string",
              "DisplayName": "string",
              "PlacedPrice": 0,
              "ExtendedPrice": 0,
              "DiscountedPrice": 0,
              "Quantity": 0,
              "ReturnQuantity": 0,
              "InventoryTrackingStatus": 0,
              "IsInventoryAllocated": true,
              "IsGift": true,
              "Properties": [
                {
                  "Key": "string",
                  "Value": "string"
                }
              ]
            }
          ],
          "Properties": [
            {
              "Key": "string",
              "Value": "string"
            }
          ]
        }
      ],
      "LineItems": [
        {
          "LineItemId": 0,
          "Code": "string",
          "DisplayName": "string",
          "PlacedPrice": 0,
          "ExtendedPrice": 0,
          "DiscountedPrice": 0,
          "Quantity": 0,
          "ReturnQuantity": 0,
          "InventoryTrackingStatus": 0,
          "IsInventoryAllocated": true,
          "IsGift": true,
          "Properties": [
            {
              "Key": "string",
              "Value": "string"
            }
          ]
        }
      ],
      "Payments": [
        {
          "Amount": 0,
          "AuthorizationCode": "string",
          "BillingAddressId": "string",
          "CustomerName": "string",
          "ImplementationClass": "string",
          "PaymentId": 0,
          "PaymentMethodId": "00000000-0000-0000-0000-000000000000",
          "PaymentMethodName": "string",
          "PaymentTypeModel": 0,
          "Status": "string",
          "TransactionType": "string",
          "ValidationCode": "string",
          "Properties": [
            {
              "Key": "string",
              "Value": "string"
            }
          ]
        }
      ],
      "Discounts": [
        {
          "DiscountId": 0,
          "DiscountAmount": 0,
          "DiscountCode": "string",
          "DiscountName": "string",
          "DisplayMessage": "string",
          "DiscountValue": 0
        }
      ],
      "ReturnComment": "string",
      "ReturnType": "string",
      "ReturnAuthCode": "string",
      "OrderFormId": 0,
      "Name": "string",
      "BillingAddressId": "string",
      "ShippingTotal": 0,
      "HandlingTotal": 0,
      "TaxTotal": 0,
      "DiscountAmount": 0,
      "SubTotal": 0,
      "Total": 0,
      "Status": "string",
      "RmaNumber": "string",
      "AuthorizedPaymentTotal": 0,
      "CapturedPaymentTotal": 0,
      "Properties": [
        {
          "Key": "string",
          "Value": "string"
        }
      ]
    }
  ],
  "OrderGroupId": 0,
  "OrderNotes": [
    {
      "OrderNoteId": 0,
      "Created": "2021-04-14T09:47:07.246Z",
      "CustomerId": "00000000-0000-0000-0000-000000000000",
      "Detail": "string",
      "Title": "string",
      "Type": "string",
      "LineItemId": 0
    }
  ],
  "Owner": "string",
  "OwnerOrg": "string",
  "ProviderId": "string",
  "ShippingTotal": 0,
  "Status": "string",
  "SubTotal": 0,
  "TaxTotal": 0,
  "Total": 0,
  "Modified": "2021-04-14T09:47:07.246Z",
  "Created": "2021-04-14T09:47:07.246Z",
  "Properties": [
    {
      "Key": "string",
      "Value": "string"
    }
  ]
}

Overview of request and response interactions between the application and the REST API.

restapioverview.png