Create a Recharge Offer

This example demonstrates how to include a recharge amount in a SubscriberPurchaseOffer SubMan API call and how to construct a one time product offer to use the recharge amount. You should have a good understanding of the concepts described in MATRIXX Pricing and Rating.

Before you begin

This example assumes that pricing and rating components such as balances, normalizers, decision tables and so forth have already been created. The example does not include all of the product offer configuration steps. It only focuses on details necessary for using a recharge amount in the SubMan APIs when purchasing an offer.

About this task

To add custom fields to a product offer template, you must use the create_config.py script to add a custom MDC that extends the MtxPurchasedOffer MDC, and add the custom fields to it. This custom MDC has an external representation that ends in Extension, for example CorporatePurchasedOfferExtension. To make the fields available for rating formulas, you must add the field to the Field Definitions in My MATRIXX and then when creating the rating formula, set the Quantity Definition value to Field and select the new field. When an extension offer is specified in an offer purchase provisioning command, all custom fields can be set in the offer purchase (or offer modify). For information about field definitions, see the discussion about field definitions in My MATRIXX Help.

Procedure

  1. During engine configuration, create a custom MDC that extends MtxPurchasedOffer and add a field to use in the purchased offer.
    For example, create the following custom MDC:
    • CorporatePurchasedOffer

    For information about extending purchased offers, see the discussion about extending purchased offers in MATRIXX Pricing and Rating. For information about creating custom MDCs and adding fields to them, see MATRIXX Integration.

  2. In Field Definitions in My MATRIXX, define the custom field to use for rating.
    For example:
    • Name: Recharge Amount
    • Container: CorporatePurchasedOffer
    • Field: charge
    • Tier: offer

    The value in the Name field is displayed in the grant definition in My MATRIXX. In this example, it is this field that is used to determine the recharge amount.

    Note: The CorporatePurchasedOffer field Charge must be populated by the provisioning system. If it is not, then the purchase will fail.
  3. In My MATRIXX, create a grant price component.
    For example:
    • Name: Corporate Purchase Offer Recharge Grant
    • Description: Recharge the grant using the value passed in the recharge amount field.
    • External ID: 12345
    • Start Date/Time: 2017-11-01
    • Target: Event Initiator
    • Application: Purchase
    • Price Type: Grant
  4. In the grant price component, create a new rate table.
    For example:
    • Name: Recharge Table
    • Description: Sets the recharge amount.
    • External ID: 6789
    • Balance Impact: United States Dollar Recharge Balance
    • Units: None
    • Quantity Definition: Field
    • Scale Field: Recharge Amount
    • Default Formula: $1.000 every 1.000 * Recharge Amount
  5. In the grant definition rate table, select a decision table and assign a formula to each row.

What to do next

With this configuration, it is now possible to use the REST API to pass in a recharge amount (such as $100.00), as demonstrated in the following example. 
<MtxRequestSubscriberPurchaseOffer>
  <SubscriberSearchData>
    <MtxSubscriberSearchData>
      <ObjectId>1-2-3-4</ObjectId>            
    </MtxSubscriberSearchData>
  </SubscriberSearchData>
  <OfferRequestArray>
    <MtxPurchasedOfferData>
      <ProductOfferId>39</ProductOfferId>
        <Attr>
          <CorporatePurchasedOfferExtension>
            <charge>100</charge>
          </CorporatePurchasedOfferExtension>
        </Attr>
      <ProductOfferVersion>39-0</ProductOfferVersion>
    </MtxPurchasedOfferData>
  </OfferRequestArray>
</MtxRequestSubscriberPurchaseOffer>
Note: You can call the purchase offer API in advice mode (advice of charge) to estimate the costs and any recurring charges associated with the offer purchase. For more information, see the discussion about execute mode.