This article describes a set of steps that can be used to complete an AdvancePay renewal through CostGuard Web APIs.

Determine If Service Is Eligible for Renewal

To determine if a service is eligible for renewal it must have an active AdvancePay product with a favorite price point indicated. Having a favorite price point is critical because they will be used during the renewal process to renew the service. To determine renewal eligibility the following steps can be performed.

Determine Service ID

CostGuard Web APIs use internal IDs to identify resources which are generally not known externally. To determine the internal ID externally known information will need to be used to look up the internal ID. The most common way of accomplishing this is through a Service Number Detail search using the service number of the service that is to be renewed.

API: Customer Service – Service Number Detail Search

Example Call: https://api.idibilling.com/customer/1xa/{environment}/CoreDataService/ServiceNumberDetail()?$filter=ServiceNumber eq ‘{serviceNumber}’

• environment: Name of the environment you are working in.
• serviceNumber: Service number of the service you are attempting to lookup

Important Response Information:

• CustomerID: This field is the customer internal ID for future API Calls.
• ServiceID: This field is the service internal ID fused for future API Calls.
• ServiceStatus: This field will be used to determine whether a restore order should be performed prior to the renewal step.

Evaluate Favorite Price Points

Prior to renewing a service, you can validate the service’s eligibility for renewal to avoid error conditions when trying to construct the order. There may also be times when you may want to retrieve additional information about the service and its favorite AdvancePay items. The following API can be used for either of these purposes.

API: Customer Management Service – List Favorite Advance Pay Price Points

Example Call: https://api.idibilling.com/ServiceAndFeatureManagement/2x/{environment}/api/service/{serviceId}/favoriteAdvancePayPricePoint

• environment: Name of the environment you are working in.
• serviceId: Internal service ID retrieved using Determine Service ID

Important Response Information: If any active records come back from this call then the service can be renewed.

Create and Submit Restore Service Order *Optional*

If a service is in a hotline status, as indicated by a ServiceStatus of ‘Hotlined’ being returned from Determine Service ID call, it may be desirable to first restore the service so that the customer can use their phone once they have renewed. To restore the service, you must submit an order with a restore service information item in it using the steps below.

Create an Order

The first step in restoring a service is to create an empty order. During the renewal phase a new order will be created and place holder service information item will be added to the order. In addition to the service being added

API: Order Placement Service – Create Cart

Content-Type: application/soap+xml; charset=utf-8; action=”https://webservices.idibilling.com/OrderPlacementService1/CreateCart”

Example Call: https://api.idibilling.com/orderplacement/1xa/{environment}/

<CreateCart>
    <Requestor>
        <AuthorizationToken>AuthToken</AuthorizationToken>
    </Requestor>
    <Request>
        <AdditionalCartInformation>
            <OrderTypeID>{OrderTypeID}</OrderTypeID>
        </AdditionalCartInformation>
        <CustomerID>
            <AuthenticatedKey>AuthKey</AuthenticatedKey>
            <ID>{CustomerID}</ID>
        </CustomerID>
    </Request>
</CreateCart>

• environment: Name of the environment you are working in.
• CustomerID: Internal customer ID retrieved using Determine Service ID
• OrderTypeID: This value will need to be populated so that the order can be properly converted into a billing order and processed.

Example Response:

<CreateCartResponse>
    <Result>
        <Cart>
            <CartDetails>
                <CreateDate>2019-05-01T16:21:21.7343696-04:00</CreateDate>
                <CreateUser>JDOE</CreateUser>
                <LastModifiedDate>2019-05-01T16:21:21.7343696-04:00</LastModifiedDate>
                <LastModifiedUser>JDOE</LastModifiedUser>
                <OrderTypeID>1</OrderTypeID>
                <Description/>
            </CartDetails>
            <CartID>
                <AuthenticatedKey>AuthKey</AuthenticatedKey>
                <ID>{OrderID}</ID>
            </CartID>
            <CustomerID>
                <AuthenticatedKey>AuthKey</AuthenticatedKey>
                <ID>10</ID>
            </CustomerID>
            <IsVoid>false</IsVoid>
            <NeedsRefresh>false</NeedsRefresh>
        </Cart>
    </Result>
    <Messages/>
</CreateCartResponse>

• OrderID: Order internal ID used for future updates to the order.

Add Restore Service to Order

Once the shell order is created the next step is to add a service information item to the order with a set of AdvancePay products which will renew the AdvancePay product with the favorite AdvancePay price points.

API: Order Placement Service – Modify Cart

Content-Type: application/soap+xml; charset=utf-8; action=”https://webservices.idibilling.com/OrderPlacementService1/ModifyCart”

Example Call: https://api.idibilling.com/orderplacement/1xa/{environment}/

<ModifyCart>
    <Requestor>
        <AuthorizationToken>AuthToken</AuthorizationToken>
    </Requestor>
    <Request>
        <AdditionalCartInformation>
            <ServiceInformation>
                <ServiceInformationItem i:type="ServiceInformationItemForRestore">
                    <ServiceID>{ServiceID}</ServiceID>
                    <ReasonID>4</ReasonID>
                </ServiceInformationItem>
            </ServiceInformation>
        </AdditionalCartInformation>
        <CartID>
            <AuthenticatedKey>AuthKey</AuthenticatedKey>
            <ID>{OrderID}</ID>
        </CartID>
        <SalesCodeID/>
    </Request>
</ModifyCart>

• environment: Name of the environment you are working in.
• OrderID: Internal order ID from the response to Create an Order

Example Response:

<ModifyCartResponse>
    <Result>
        <Cart>
            <CartDetails>
                <CreateDate>2019-05-01T16:21:21.7343696-04:00</CreateDate>
                <CreateUser>JDOE</CreateUser>
                <LastModifiedDate>2019-05-01T16:24:21.7343696-04:00</LastModifiedDate>
                <LastModifiedUser>JDOE</LastModifiedUser>
                <OrderTypeID>1013</OrderTypeID>
                <ServiceDetails>
                    <ServiceDetail>
                        <ActionType>Restore</ActionType>
                        <AlternateServiceNumber>5555555555</AlternateServiceNumber>
                        <CatalogID>18</CatalogID>
                        <Description>Equal Access</Description>
                        <ReasonID>4</ReasonID>
                        <ServiceID>169053</ServiceID>
                        <ServiceInformationItemID>88443</ServiceInformationItemID>
                        <ServiceNumber>5555555555</ServiceNumber>
                        <StartDate>2005-01-01T00:00:00</StartDate>
                        <TaxAccountType>Business</TaxAccountType>
                        <IsSimplePortIn>false</IsSimplePortIn>
                    </ServiceDetail>
                </ServiceDetails>
            </CartDetails>
            <CartID>
                <AuthenticatedKey>AuthKey</AuthenticatedKey>
                <ID>7010</ID>
            </CartID>
            <CustomerID>
                <AuthenticatedKey>AuthKey</AuthenticatedKey>
                <ID>10</ID>
            </CustomerID>
            <IsVoid>false</IsVoid>
            <NeedsRefresh>false</NeedsRefresh>
        </Cart>
    </Result>
    <Messages/>
</ModifyCartResponse>

Checkout Order

After the restore service had been added to the order you may checkout the order. This step is required for all orders and runs additional verification checks to ensure the order can be submitted. Since there should not be any tender requirements for this order you should be able to proceed directly to the final step from here.

API: Order Placement Service – Checkout

Content-Type: application/soap+xml; charset=utf-8; action=”https://webservices.idibilling.com/OrderPlacementService1/Checkout”

Example Call: https://api.idibilling.com/orderplacement/1xa/{environment}/

<Checkout>
    <Requestor>
        <AuthorizationToken>AuthToken</AuthorizationToken>
    </Requestor>
    <Request>
        <CartID>
            <AuthenticatedKey>AuthKey</AuthenticatedKey>
            <ID>{OrderID}</ID>
        </CartID>
    </Request>
</Checkout>

• environment: Name of the environment you are working in.
• OrderID: Internal order ID from the response to Create an Order

Example Response:

<CheckoutResponse>
    <Result/>
    <Messages/>
</CheckoutResponse>

Submit Order

After the order creation and checkout process has completed the final step in the process is to submit the order for processing. Once the order is submitted a workflow will pick up the order and convert it to a billing order. After billing order conversion has taken place the billing system should be updated, and the service will be restored.

API: Order Placement Service – Submit Cart

Content-Type: application/soap+xml; charset=utf-8; action=”https://webservices.idibilling.com/OrderPlacementService1/SubmitCart”

Example Call: https://api.idibilling.com/orderplacement/1xa/{environment}/

<SubmitCart>
    <Requestor>
        <AuthorizationToken>AuthToken</AuthorizationToken>
    </Requestor>
    <Request>
        <CartID>
            <AuthenticatedKey>AuthKey</AuthenticatedKey>
            <ID>{OrderID}</ID>
        </CartID>
    </Request>
</SubmitCart>

• environment: Name of the environment you are working in.
• OrderID: Internal order ID from the response to Create an Order

Example Response:

<SubmitCartResponse>
    <Result>
        <CartSummary>
            <CartID>
                <AuthenticatedKey>AuthKey</AuthenticatedKey>
                <ID>10</ID>
            </CartID>
            <CartItemCount>0</CartItemCount>
            <EstimatedMRC>0</EstimatedMRC>
            <Subtotal>0</Subtotal>
            <TaxSubtotal>0</TaxSubtotal>
        </CartSummary>
    </Result>
    <Messages/>
</SubmitCartResponse>

Create and Submit AdvancePay Renewal Order

The final phase of the AdvancePay renewal process is to ‘renew’ the service by selling the favorited price points associated with any active AdvancePay products that are associated to the service.

Create an Order

The first step in renewing a service is to create an empty order. Unlike the Create an Order for service restore step this order will need to be associated with a register id so that the order can be properly taxed and tendered in later steps.

API: Order Placement Service – Create Cart

Example Call: https://api.idibilling.com/orderplacement/1xa/{environment}/

<CreateCart>
    <Requestor>
        <AuthorizationToken>AuthToken</AuthorizationToken>
        <RegisterID>12</RegisterID>
    </Requestor>
    <Request>
        <AdditionalCartInformation>
            <OrderTypeID>{OrderTypeID}</OrderTypeID>
        </AdditionalCartInformation>
        <CustomerID>
            <AuthenticatedKey>AuthKey</AuthenticatedKey>
            <ID>{CustomerID}</ID>
        </CustomerID>
    </Request>
</CreateCart>

• environment: Name of the environment you are working in.
• CustomerID: Internal customer ID retrieved using Determine Service ID
• OrderTypeID: This value will need to be populated so that the order can be properly converted into a billing order and processed.

Important Response Information:

<CreateCartResponse>
    <Result>
        <Cart>
            <CartDetails>
                <CreateDate>2019-05-01T16:25:21.7343696-04:00</CreateDate>
                <CreateUser>JDOE</CreateUser>
                <LastModifiedDate>2019-05-01T16:21:21.7343696-04:00</LastModifiedDate>
                <LastModifiedUser>JDOE</LastModifiedUser>
                <OrderTypeID>1</OrderTypeID>
                <Description/>
            </CartDetails>
            <CartID>
                <AuthenticatedKey>AuthKey</AuthenticatedKey>
                <ID>11</ID>
            </CartID>
            <CustomerID>
                <AuthenticatedKey>AuthKey</AuthenticatedKey>
                <ID>10</ID>
            </CustomerID>
            <IsVoid>false</IsVoid>
            <NeedsRefresh>false</NeedsRefresh>
        </Cart>
    </Result>
    <Messages/>
</CreateCartResponse>

• OrderID: Order internal ID used for future updates to the order.

Add Renew AdvancePay Service to Order

Once a shell order is created the service can be renewed. Calling the API below will cause a placeholder service to added to the order and one purchase item per active AdvancePay product that has favorite price point marked.

API: Order Management Service – Renew Advance Pay Service

Content-Type: application/json

Example Call: https://api.idibilling.com/OrderManagement/2x/{environment}/api/order/{orderId}/renewAdvancePay/{serviceId}

• environment: Name of the environment you are working in.
• orderId: Internal order ID from the response to Create an Order
• serviceId: Internal service ID retrieved using Determine Service ID

Example Response:

{
	"renewedAdvancePayProductCount": 1,
	"serviceInformationItemID": 11
}

Checkout Order

After adding the renew items to the order a checkout call needs to be made. The checkout call will update the order and calculate the taxes and any promotions that should be applied to the order. This call is necessary so that the total amount due can be determined the appropriate tender can be applied in the next steps.

API: Order Placement Service – Checkout

Content-Type: application/soap+xml; charset=utf-8; action=”https://webservices.idibilling.com/OrderPlacementService1/Checkout”

Example Call: https://api.idibilling.com/orderplacement/1xa/{environment}/

<Checkout>
    <Requestor>
        <AuthorizationToken>AuthToken</AuthorizationToken>
    </Requestor>
    <Request>
        <CartID>
            <AuthenticatedKey>AuthKey</AuthenticatedKey>
            <ID>{OrderID}</ID>
        </CartID>
    </Request>
</Checkout>

• environment: Name of the environment you are working in.
• OrderID: Internal order ID from the response to Create an Order

Example Response:

<CheckoutResponse>
    <Result>
	<CartSummary>
            <CartID>
                <AuthenticatedKey>AuthKey</AuthenticatedKey>
                <ID>11</ID>
            </CartID>
            <CartItemCount>1</CartItemCount>
            <EstimatedMRC>0</EstimatedMRC>
            <Subtotal>11.99</Subtotal>
            <TaxSubtotal>2.35</TaxSubtotal>
        </CartSummary>
    <Result>
    <Messages/>
</CheckoutResponse>

• Subtotal: Amount due before taxes
• TaxSubtotal: Amount of taxes due for order

Tender Order

After calling checkout the total amount due should now be known. Using the values returned from checkout the appropriate offsetting tender records can be added to the order. For simplicity only one cash tender record is being added below but multiple tenders can be added to offset the total amount due within a single call or multiple calls.

API: Order Placement Service – Modify Cart

Content-Type: application/soap+xml; charset=utf-8; action=”https://webservices.idibilling.com/OrderPlacementService1/ModifyCart”

Example Call: https://api.idibilling.com/orderplacement/1xa/{environment}/

<ModifyCart>
    <Requestor>
        <AuthorizationToken>AuthToken</AuthorizationToken>
    </Requestor>
    <Request>
        <CartID>
            <AuthenticatedKey>AuthKey</AuthenticatedKey>
            <ID>11</ID>
        </CartID>
        <SalesCodeID/>
        <TenderInformation>
            <TenderInformationItem i:type="TenderInformationItemCash">
                <Amount>14.34</Amount>
                <TenderStatus>Captured</TenderStatus>
                <TenderTypeID>2</TenderTypeID>
            </TenderInformationItem>
        </TenderInformation>
    </Request>
</ModifyCart>

• environment: Name of the environment you are working in.
• OrderID: Internal order ID from the response to Create an Order
• Amount: This value should be calculated by adding the Subtotal and TaxSubtotal from response call to Checkout Order.

Example Response:

<ModifyCartResponse>
    <Result>
        <Cart>
            <CartDetails>
                <CheckoutDate>2019-05-01T17:21:23.0497522-04:00</CheckoutDate>
                <CreateDate>2019-05-01T17:20:05.9206114-04:00</CreateDate>
                <CreateUser>idi_good</CreateUser>
                <LastModifiedDate>2019-05-01T17:21:18.0206717-04:00</LastModifiedDate>
                <LastModifiedUser>JDOE</LastModifiedUser>
                <OrderTypeID>1</OrderTypeID>
            </CartDetails>
            <CartID>
                <AuthenticatedKey>AuthKey</AuthenticatedKey>
                <ID>11</ID>
            </CartID>
            <CustomerID>
                <AuthenticatedKey>AuthKey</AuthenticatedKey>
                <ID>10</ID>
            </CustomerID>
            <IsVoid>false</IsVoid>
            <NeedsRefresh>false</NeedsRefresh>
            <ReceiptNumber>STORE-01-0076</ReceiptNumber>
            <TenderDetails>
                <TenderDetail>
                    <Amount>14.34</Amount>
                    <TenderInformationItemID>17</TenderInformationItemID>
                    <TenderInformationItemType>Cash</TenderInformationItemType>
                    <TenderStatus>Captured</TenderStatus>
                    <TenderTypeID>2</TenderTypeID>
                </TenderDetail>
            </TenderDetails>
        </Cart>
    </Result>
    <Messages />
</ModifyCartResponse>

Submit Order

Once the total amount due has been offset the final step is to submit the order for processing. Once the order is submitted a workflow will pick up the order and convert it to a billing order. After billing order conversion has taken place the billing system should be updated, and the service will be renewed.

API: Order Placement Service – Submit Cart

Content-Type: application/soap+xml; charset=utf-8; action=”https://webservices.idibilling.com/OrderPlacementService1/SubmitCart”

Example Call: https://api.idibilling.com/orderplacement/1xa/{environment}/

<SubmitCart>
    <Requestor>
        <AuthorizationToken>AuthToken</AuthorizationToken>
    </Requestor>
    <Request>
        <CartID>
            <AuthenticatedKey>AuthKey</AuthenticatedKey>
            <ID>{OrderID}</ID>
        </CartID>
    </Request>
</SubmitCart>

• environment: Name of the environment you are working in.
• OrderID: Internal order ID from the response to Create an Order

Example Response:

<SubmitCartResponse>
    <Result>
        <CartSummary>
            <CartID>
                <AuthenticatedKey>AuthKey</AuthenticatedKey>
                <ID>11</ID>
            </CartID>
            <CartItemCount>1</CartItemCount>
            <EstimatedMRC>0</EstimatedMRC>
            <Subtotal>11.99</Subtotal>
            <TaxSubtotal>2.35</TaxSubtotal>
        </CartSummary>
    </Result>
    <Messages/>
</SubmitCartResponse>