Adding an AdvancePay Product

This article describes the steps required to add an AdvancePay Product and associated
Price Point to a service using IDI Web APIs. While assigning a favorite AdvancePay
Price Point is optional, doing so at this stage can simplify future renewal handling.

Overview

1. Ensure the service is active and already present in the order
2. Retrieve the service’s ServiceInformationItemID
3. Locate an eligible AdvancePay Product
4. Retrieve available Price Points
5. Modify the existing cart to add the AdvancePay Product to the service
6. Add an AdvancePay Price Point to the product order item
7. Optionally assign a favorite Price Point to simplify future renewals

Note: For renewal-specific processing, see:

AdvancePay Renewal Processing

Retrieve ServiceInformationItemID

Retrieve the ServiceInformationItemID for the service from the order.

API: Order Management – Search Service Item Summaries

GET https://api.idibilling.com/OrderManagement/2x/{environment}/api/order/{orderID}/serviceItemSummary

Relevant Response Fields:

• serviceInformationItemID – Required when adding purchase items
• serviceID – Internal service identifier
• serviceNumber – Externally known service number

The returned ServiceInformationItemID must be supplied as
AdditionalPurchaseItemInformation.ServiceInformationItemID when adding the
AdvancePay Product.

IMPORTANT
Do not attempt to derive or infer ServiceInformationItemID from
ServiceID. The value must come directly from the order.

Identify Available AdvancePay Products

AdvancePay Products are retrieved from the Product Catalog and are identified by a specific product type.

API: Catalog Management – Search Catalog Entry

GET https://api.idibilling.com/CatalogManagement/2x/{environment}/api/catalogEntry

Required Filter:

• productTypeID eq 10 (AdvancePay Product)

Optional Filters:

• startDate
• endDate

Relevant Response Fields:

• catalogEntryID – Used as the CatalogID when adding the product to the order
• description – Human-readable product name
• sku

Identify Available AdvancePay Price Points

Once an AdvancePay Product has been selected, retrieve the available Price Points associated with that product.

API: Catalog Management – Search Product Catalog AdvancePay Price Point

GET https://api.idibilling.com/CatalogManagement/2x/{environment}/api/productCatalogAdvancePayPricePoint

Relationships of Note:

• catalogID must match the AdvancePay Product’s catalogEntryID
• Each Price Point definition may contain one or more charges

Relevant Response Fields:

• advancePayPricePointDefinitionID – Used to set the favorite AdvancePay Price Point
• charges – Contains charge-level identifiers
• numberOfDays – Duration of the AdvancePay Price Point

NOTE
The Price Point definition represents the logical AdvancePay term, while the charge represents the billable component added to the order.

Modify the Order Cart and Add the AdvancePay Product

Begin by modifying an existing cart and adding the AdvancePay Product as a parent order item.

API: Order Placement Service – Modify Cart (SOAP)

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

Why ModifyCart?

This article assumes the service is already present in the order. Because of this, ModifyCart is used instead of CreateCart.
ModifyCart allows additional purchase items—such as AdvancePay Products—to be added to an existing order without re-creating
the cart or re-adding the service. This avoids conflicting order states and ensures the AdvancePay Product is associated with
the correct service instance already in the order.

Required Fields

• PurchaseItem.CatalogID
  • Set to the AdvancePay Product’s catalogEntryID
• AdditionalPurchaseItemInformation.ServiceInformationItemID
  • Set to the service’s ServiceInformationItemID

Optional

• AdditionalPurchaseItemInformation.FavoriteAdvancePayPricePointDefinitionID
  • Set to the selected advancePayPricePointDefinitionID

Although not required, setting the favorite AdvancePay Price Point when the product is added can simplify future renewal handling
and reduce the need for additional validation later.

Example: ModifyCart (Add AdvancePay Product)

<ModifyCart>
  <Requestor>
    <AuthorizationToken>AuthToken</AuthorizationToken>
  </Requestor>
  <Request>
    <CartID>
      <AuthenticatedKey>AuthKey</AuthenticatedKey>
      <ID>{orderID}</ID>
    </CartID>

    <PurchaseItems>
      <PurchaseItem>
        <CatalogID>{advancePayProductCatalogEntryID}</CatalogID>
        <AdditionalPurchaseItemInformation>
          <ServiceInformationItemID>{serviceInformationItemID}</ServiceInformationItemID>
          <FavoriteAdvancePayPricePointDefinitionID>
            {advancePayPricePointDefinitionID}
          </FavoriteAdvancePayPricePointDefinitionID>
        </AdditionalPurchaseItemInformation>
      </PurchaseItem>
    </PurchaseItems>
  </Request>
</ModifyCart>

IMPORTANT
Capture the CartItemID of the newly added AdvancePay Product from the ModifyCart response.
The CartItemID is functionally equivalent to the OrderItemID used by the Add Price Point API
and must be supplied as the {orderItemID} path parameter in the next step.

Add the AdvancePay Price Point to the Order Item

After the AdvancePay Product has been added to the cart, add the Price Point as a child order item to the AdvancePay Product.

API: Order Management – Add Price Point (REST)

POST https://api.idibilling.com/OrderManagement/2x/{environment}/api/orderItem/{orderItemID}/addPricePoint

Parameters

Path Parameter

• orderItemID – Parent AdvancePay Product order item ID

Request Body

• advancePayPricePointChargeID – Charge-level identifier (retrieved from the Price Point catalog)
• quantity – Must be greater than or equal to 1

Example: Add Price Point

{
  "advancePayPricePointChargeID": 12345,
  "quantity": 1
}

Example Response

{
  "orderItemID": 67890
}

The returned orderItemID represents the newly created child order item for the AdvancePay Price Point.

Price Point Validation Requirements

• The parent orderItemID must exist
• The parent order item must be an AdvancePay Product
• Only one Price Point per definition may exist under a parent AdvancePay Product
• The Price Point charge must belong to the same catalog entry as the parent product
• The Price Point charge must be active
• Quantity must be greater than or equal to 1

Checkout-Time Validation

During checkout, an order will fail if an AdvancePay Product does not have at least one Price Point.

• Error Code: 500764
• Message: AdvancePay Product requires at least one Price Point