For developers: Predefine carrier services

Services represent different methods of shipping from a provider. Usually the prices of these rates are based on the weight of the package, the distance the package must travel and the speed of delivery. For example, FedEx provides services such as “First Overnight”, “2 Day” and “International Priority”.

If your custom shipping provider is retrieving the services for the shipping carrier via an external service, you may want to setup the provider’s services in the backend, and then display only the active/defined services to your customer in the front end. For example, your external shipping carrier may provide 20 different service rates, but you may only want to display 4 or 5 of those rates to your customer. In this case you will define these 4 or 5 services in the backend and then use them to filter the services, returned by the provider.

To setup services for your shipping carrier provider, perform the following:

1. Log in to Sitefinity CMS backend.
2. In the main menu in the upper part of the screen, click Administration » Settings.
3. Go to the Advanced settings by clicking the Advanced link.
4. In the treeview on the left, click Shipping » ShippingServiceSettings.

   NOTE: The Shipping Service Settings screen may already display a number of services for any existing shipping providers.

5. To add a new service, click Create New.
6. Populate the fields of the service.
   The service has the following fields:
   • Name
     A name for your service. The service name should be unique (across all your shipping providers) and should not contain any spaces.
   • Shipping Carrier Name
     Enter the name of your shipping carrier provider exactly as it is defined in the provider settings.
   • Title
     This is the name of the service as displayed to your customers.
   • Code
     This is a unique code that identifies the service as related to your provider. Existing shipping services such as FedEx, UPS, and USPS have predefined lists of codes associated with their services. You will have to refer to the documentation from the third party shipping service in order to obtain this code.
   • Description (optional)
     A brief description of your service.
   • Surcharge
     If you want to add a fixed surcharge to the rate returned by an external shipping service, enter the surcharge amount here. Do not include the $ sign (just numbers and a decimal point). If there is no surcharge for this service, enter “0”.
   • MaxWeight
     If there is a maximum shipping weight that this service will allow, enter the amount here. If there is no maximum weight leave this field blank.
   • Sort Order
     Enter a value from 1 to x for the order you want to display multiple services to the customer (provided the provider returns rates for more than one service).
7. Click Save changes.

To query the predefined services for your provider, you must perform the following:

1. Get the shipping manager.
   Get an instance of the ShippingManager object.
2. Get the services.
   To get the services, call the GetShippingServiceSettings method of the manager. Filter the collection by the name of the provider and by value of the IsActive property.

The list of shipping services will come in handy when processing the data that is returned from an external shipping carrier and that contains the shipping services and their rates. When parsing the service data that is returned from the shipping carrier, retrieve its service code and check if there is a service with the same code in your list of shipping services. If it does, then parse the rate of the service and wrap it in a GenericShippingResponse object. Use the values of the Title and SortOrder properties of the ShippingServiceSettings instance for the ServiceName and SrotOrder properties of the GenericServerResponse instance. If a service with the same code is not present, then do not add this service to your ShippingResponse list. Using this method, you can filter the set of external provider’s services down to a subset of just those services you want to provide to your customers.

Use the following code example for parsing a sample XML response of a shipping carrier’s external service: