Device Modify Offer

Requests to modify one or more offers purchased by the device. Only those fields with values supplied are modified in the device object.

If the catalog item defines a cycle which allows for purchase-time specification, you can set the OfferCycleType field to determine the purchased item cycle offset, and the cycle time of day if aligned to an existing cycle. Values are:
  • 1 - billing_cycle
  • 2 - purchase_time
  • 3 - balance_cycle
  • 4 - offer_cycle
  • 5 - fixed_offset

Product offers can include Attr field values that extend the base purchased offer. For example, a purchased offer could be customized to include custom purchase offer parameters such as a recharge amount, an offer price override, an offer code, a discount percentage, and locale. For more information, see the discussion about working with private MDCs in MATRIXX Subscriber Management API.

MATRIXX Engine generates an MtxPurchasedItemModifyEvent EDR when you modify any of the following purchased item fields using the ModifyOffer SubMan APIs:
  • StartTime
  • EndTime
  • ParameterArray
  • EndTimeExtensionOffset
  • Attr
Note: You can modify the EndTime or the EndTimeExtensionOffset field, but not both.

MATRIXX Engine generates an MtxPurchasedItemModifyEvent EDR when you modify the EndTime of a contract offer using the ModifyOffer SubMan APIs. When you modify a purchased item, an MtxPurchasedItemModifyEvent EDR is generated that includes the owner ID of the owner of the purchased item and arrays of offers and bundles that have been modified. For information about renegotiating contract offer end dates, see MATRIXX Pricing and Rating.

MATRIXX Engine generates an MtxPeriodEndTimeChangeEvent EDR when you modify an offer CycleEndTime to end at a specific date and time to record purchased item cycles and balance periods end times that are modified by the change. An MtxPeriodEndTimeChangeEvent EDR is generated for all purchased item cycles and balance periods whose end time has been modified.

If the purchased item has cycles, and the cycle definition is modified by the API, a single MtxPurchasedItemCycleChangeEvent EDR is generated for the directly modified purchased item cycle, and an MtxPeriodEndTimeChangeEvent EDR is generated for each purchased item cycle and each periodic balance impacted by the Cycle End Time modification.

Parameters

You can modify parameter values for a purchased catalog item any time after a purchase by making a ModifyOffer request. The ModifyOffer API uses the input ParameterArray field to replace the parameter array stored for the purchased catalog item. If the catalog item is purchased with no parameter value, call the ModifyOffer API with an array of parameter values to use the new value. If the catalog item is purchased with parameter values, call the ModifyOffer API with an empty parameter array to use the default value.

You can use the MtxRequestDeviceQuery API to get parameter values for purchased catalog items.

Use the MtxRequestPricingQueryCatalogItem API to get parameter information for a specific catalog item. The SubMan calls to get the list of catalog items and to get a single catalog item include any default parameter bindings.

Example: Modify a Product Offer

URL 
PUT http://host:port/rsgateway/data/v3/device/0-1-5-1/offers/1>
Request XML 
<MtxRequestDeviceModifyOffer>
  <StartTime>2013-11-01T00:00:00</StartTime>
  <EndTime>2013-12-01T00:00:00</EndTime>
</MtxRequestDeviceModifyOffer>
Response 
<MtxResponse>
    <RouteId>1</RouteId>
    <Result>0</Result>
    <ResultText>OK</ResultText>
</MtxResponse>
MATRIXX Engine generates an MtxDeviceModifyEvent EDR is generated when one or more of the following fields are modified in an MtxRequestDeviceModify message:
  • ExternalId
  • DeviceType
  • Attr
  • Imsi
  • LoginId
MATRIXX Engine generates an MtxPurchasedItemModifyEvent EDR when you modify any of the following purchased item fields using the ModifyOffer SubMan APIs:
  • StartTime
  • EndTime
  • Attr

MATRIXX Engine generates a MtxPurchasedItemModifyEvent EDR when you modify the EndTime of a contract offer using the ModifyOffer SubMan APIs. For information about renegotiating contract offer end dates, see MATRIXX Pricing and Rating.

For more information about EDRs, see MATRIXX Integration.