Creating Orders for an Associated eSIM Device as a Subservice

Article Contents

This article describes a set of steps that shows how to create an order that will activate a new service as a subservice. This subservice is associated with a main service on an account. The subservice’s device could be, for example, an Apple Watch or other wearable device that must be associated with a main device.

Prerequisites

This article assumes that the developer understands how to obtain a Simple Web Token for use in requests to the IDI APIs.

NOTE: It is imperative to understand that all requests to the IDI APIs have the potential to return errors and/or warnings in their responses back to the caller. These can occur for various reasons and require different actions to be taken, but generally the cause of any business rule validations (sometimes based upon system configuration) will need to be addressed in the caller before the request is able to be successfully tried again. The Web API documentation that we link to throughout will contain more specific details about what values are valid under various circumstances.

Subscriber Authentication via CPNI

CPNI information is sometimes used by an application to authenticate the subscriber that is attempting to use it. If this is needed, the Customer Service CustomerLookup can be used to retrieve this information.

Finding Existing Services on an Account

The Customer Service provides multiple OData APIs for finding the services that exist on an account.

Service – Provides parent service information when a service is a subservice.
ServiceSummary – Additionally provides feature and subservice counts for each service.
CustomerService – Provides a little more information about the account for each service.

Reserving Service Numbers for a New Subservice

The Number Inventory Service CreateReservation allows you to search for available Service Numbers and/or MINs and reserve them for the new service, along with a Reservation ID which is also used in the order. The following example obtains both a Service Number and a MIN. As with all the examples, any IDs and other information in requests, including the environment name, must be replaced with valid information from your own CostGuard environment.

NOTE: As with all SOAP requests, the sequence of properties is very important. If you need to utilize any additional properties that are not shown in these examples, be sure to specify them in the proper sequence, which is defined in the WSDL provided for the version of your CostGuard environment. Do not assume the sequence shown in the API documentation is correct as this is generally alphabetical.

CreateReservation Example URL: https://api.idibilling.com/numberinventory/1xa/{environment}/

<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
  <s:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
    <wsa:Action>https://webservices.idibilling.com/SecurityService1/CreateReservation</wsa:Action>
  </s:Header>
  <s:Body>
    <CreateReservation xmlns="http://webservices.idibilling.com/Security/1.0">
      <Requestor xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <AuthorizationToken>AuthorizationToken</AuthorizationToken>
      </Requestor>
      <Request xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <CustomerID>
          <AuthenticatedKey>NA</AuthenticatedKey>
          <ID>15940</ID>
        </CustomerID>
        <ReservationItems>
          <ReservationItem i:type="ReservationItemForServiceNumber">
            <InventoryGroupID>42</InventoryGroupID>
            <ServiceCatalogID>37517</ServiceCatalogID>
            <TemporaryItemID>-1</TemporaryItemID>
          </ReservationItem>
          <ReservationItem i:type="ReservationItemForMIN">
            <InventoryGroupID>42</InventoryGroupID>
            <ServiceCatalogID>37517</ServiceCatalogID>
            <TemporaryItemID>-2</TemporaryItemID>
          </ReservationItem>
        </ReservationItems>
      </Request>
    </CreateReservation>
  </s:Body>
</s:Envelope>

NOTE: Besides returning the InventoryItem value for the Service Number and/or MIN, the ReservationID will also be returned as follows. This is another value that will be needed during order placement.

<ReservationID>
  <AuthenticatedKey>2192</AuthenticatedKey>
  <ID>2192</ID>
</ReservationID>

Finding Products and Features to Add to an Order

The Catalog Service offers a CatalogSearch where all your available products and their associated SKUs and IDs can be filtered down in various ways including via Browse Tags. This can be used to search for certain SKUs to find their catalog IDs which are sometimes required in upcoming requests used to assemble an order.

Getting an eSIM for Provisioning a Device

eSIMs are a new alternative to the traditional physical SIM card. Their serial numbers and other identifying information are like the previous technology, so they have a lot in common, however they require you to have a handset or device that can accommodate an eSIM. These devices will have another identifier built-in to them called an EID that is generally required for provisioning with an eSIM. Some devices can only use eSIMs and not SIM cards, so those will require an EID to be provided in the order.

CostGuard allows you to pre-load SIM information of either type into the system, but this is not a requirement. eSIM serial numbers can be obtained dynamically from a provider and then used directly in an order to activate a service in CostGuard.

Creating the Order for the New Subservice

The Order Placement Service CreateCart operation will be used to assemble an order that will activate a new subservice using information gathered in previous steps. Note that when many items are included in a single request, some may get successfully added to the order while others receive errors and do not get added to the order. Before submittal, further changes to the order to either fix items that had errors or add new items including the required tender items after checkout, would be accomplished using the ModifyCart operation.

Notes about the following Create Order Example:

The first service item is the main service, which already exists on the account with the specified ServiceID value (as obtained earlier).
1. We gave this a Temporary ID of -2 so it can be linked as the parent of the new subservice.
The second service item is the new subservice which we are activating here for the associated wearable device.
1. We gave this a Temporary ID of -1 so we can link products and features under it.
2. We gave this a Parent ID of -2 so it will be linked as a child or subservice of the existing main service.
3. The inventoried numbers obtained earlier are specified here with the MIN specified as AlternateServiceNumber.
4. CatalogID indicates the type of service associated with the wearable device, as configured in the Product Catalog.
  1. This ID must be configured with subservice rules that allow it to be a child of the parent service type.
5. We are specifying contact information as that is always required on a new service.
6. HandsetCatalogID indicates the type of the handset or device on this service, as configured in the Product Catalog.
7. Generally, a handset or device’s MEID or IMEI is specified for the HandsetSerialNumber.
8. SIMCardSerialNumber will contain the ICCID or SIM Number that was obtained from your eSIM provider.
  1. All X’s, i.e. a “Temporary Number”, can be specified here as long as provisioning for this type of service has been implemented such that it will obtain an eSIM dynamically.
9. We are also specifying the EID for the device as that is generally required for provisioning with an eSIM.
  1. The EID or ‘Embedded Identity Document’ is a unique identifier built-in to the handset or device.
CustomerID is used to indicate the account this order is associated to.
ReservationID is the value returned from the Number Inventory Service above.
1. This allows the Order Placement Service to manage cancellation of any reservations that are not used by the order.
Purchase Items should be included for any plans, features, or other products that belong on the new subservice.
1. We give these a service ID of -1 so they will be linked under the new subservice.
2. Certain products will likely be required here to facilitate provisioning of the associated wearable device.

Create Order Example URL: https://api.idibilling.com/orderplacement/1xa/{environment}/

<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
  <s:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
    <wsa:Action>https://webservices.idibilling.com/OrderPlacementService1/CreateCart</wsa:Action>
  </s:Header>
  <s:Body>
    <CreateCart xmlns="http://webservices.idibilling.com/OrderPlacement/1.0">
      <Requestor xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <AuthorizationToken>AuthToken</AuthorizationToken>
      </Requestor>
      <Request xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <AdditionalCartInformation>
          <OrderTypeID>1013</OrderTypeID>
          <ServiceInformation>
            <ServiceInformationItem xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ServiceInformationItem">
              <ServiceID>105364</ServiceID>
              <TemporaryServiceInformationItemID>-2</TemporaryServiceInformationItemID>
            </ServiceInformationItem>
            <ServiceInformationItem xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ServiceInformationItem">
              <AlternateServiceNumber>XXXXXXXXXX</AlternateServiceNumber>
              <CatalogID>37517</CatalogID>
              <HandsetCatalogID>37360</HandsetCatalogID>
              <HandsetSerialNumber>XXXXXXXXXX</HandsetSerialNumber>
              <ParentServiceInformationItemID>-2</ParentServiceInformationItemID>
              <SIMCardSerialNumber>XXXXXXXXXX</SIMCardSerialNumber>
              <ServiceContact>
                <ContactID>12609</ContactID>
              </ServiceContact>
              <ServiceNumber>XXXXXXXXXX</ServiceNumber>
              <TemporaryServiceInformationItemID>-1</TemporaryServiceInformationItemID>
              <EID>abcdef123456789</EID>
            </ServiceInformationItem>
          </ServiceInformation>
          <Description>Cart for Associated Wearable Subservice</Description>
          <ReservationID>2192</ReservationID>
        </AdditionalCartInformation>
        <CustomerID>
          <AuthenticatedKey>NA</AuthenticatedKey>
          <ID>5376</ID>
        </CustomerID>
        <PurchaseItems>
          <PurchaseItem>
            <AdditionalPurchaseItemInformation>
              <ServiceInformationItemID>-1</ServiceInformationItemID>
            </AdditionalPurchaseItemInformation>
            <Quantity>1</Quantity>
            <SKU>WATCH_PLAN</SKU>
          </PurchaseItem>
          <PurchaseItem>
            <AdditionalPurchaseItemInformation>
              <ServiceInformationItemID>-1</ServiceInformationItemID>
            </AdditionalPurchaseItemInformation>
            <Quantity>1</Quantity>
            <SKU>WATCH_PROVISIONING</SKU>
          </PurchaseItem>
        </PurchaseItems>
      </Request>
    </CreateCart>
  </s:Body>
</s:Envelope>

NOTE: A CartID is returned as follows within the response from the CreateCart operation whenever it is successful creating one, even if there were errors preventing some items from getting added to the order. The ID value shown here will be used to identify the Order ID in any subsequent operations on the order.

<CartID>
  <AuthenticatedKey>AuthKey</AuthenticatedKey>
  <ID>11</ID>
</CartID>

Perform Checkout on the Order

Before an order can be submitted, it must go through the Order Placement Service Checkout operation to perform additional validation as well as calculation of subtotals and taxes for any amounts that may need to be tendered.

Checkout Order Example URL: https://api.idibilling.com/orderplacement/1xa/{environment}/

<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
  <s:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
    <wsa:Action>https://webservices.idibilling.com/OrderPlacementService1/Checkout</wsa:Action>
  </s:Header>
  <s:Body>
    <Checkout>
      <Requestor>
        <AuthorizationToken>AuthToken</AuthorizationToken>
      </Requestor>
      <Request>
        <CartID>
          <AuthenticatedKey>AuthKey</AuthenticatedKey>
          <ID>{Order ID}</ID>
        </CartID>
      </Request>
    </Checkout>
  </s:Body>
</s:Envelope>

Submit the Order for Processing

The final operation after all other validation has passed is the Order Placement Service SubmitCart. Note that there are some final validations that occur here as well, so as always, be sure to check for any error or warning messages that may be returned in the response which will indicate whether the order was successfully submitted or not.

Generally based on the Order Type that was specified, a Workflow Definition is configured to take each web order through various processing stages. A Task Plan may also be configured to begin once a web order becomes a billing order in CostGuard. Provisioning actions are sent to network elements in one of those two places.

Submit Order Example URL: https://api.idibilling.com/orderplacement/1xa/{environment}/

<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
  <s:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
    <wsa:Action>https://webservices.idibilling.com/OrderPlacementService1/SubmitCart</wsa:Action>
  </s:Header>
  <s:Body>
    <SubmitCart>
      <Requestor>
        <AuthorizationToken>AuthToken</AuthorizationToken>
      </Requestor>
      <Request>
        <CartID>
          <AuthenticatedKey>AuthKey</AuthenticatedKey>
          <ID>{Order ID}</ID>
        </CartID>
      </Request>
    </SubmitCart>
  </s:Body>
</s:Envelope>

Updated on April 1, 2021

Was this article helpful?

Yes No

About The Author

IDI Development Team

Questions or comments on this article can be sent to the IDI development team at cg-apisupport@idibilling.com.