This part describes how to use the REST API bindings to interface with MATRIXX Engine.
The pricing management APIs return information about all aspects of pricing, including catalog items, balance templates, product offers, billing cycles, life cycles, notifications and so forth. You can also get status information for the currently-loaded pricing.
This section describes the REST Catalog APIs.
MATRIXX Subscriber Management API provides information about the MATRIXX Engine APIs, including functions, syntax, and result codes, and the MATRIXX Engine REST and Java API implementations.
The following information is an overview of the SubMan APIs and architecture.
The following sections introduce how the various in-memory objects are managed.
The SubMan API reference includes SubMan API and MDC descriptions.
RS Gateway supports the REST API bindings for accessing subscriber data in MATRIXX Engine. RS Gateway consists of an rsgateway application and a set of REST APIs.
The following APIs are deprecated in this release of MATRIXX and support for these APIs will be removed in a future release.
The balance management APIs include the messaging required to operate on a balance, meter, or wallet object. The primitives include the messaging and data elements required to create, modify, associate, and query objects directly related to a balance or meter, including their thresholds.
The catalog APIs return information about pricing catalogs for specified devices, groups, and subscriptions. They return catalog items that the specified object is eligible to purchase.
Use the following MDCs to import data for users, subscriptions, groups, and devices and to import catalog item purchase information for a subscription.
The device management APIs include the methods and functions required to operate on the device primary object. They include the data elements required to create, modify, and query devices, to add and remove a device from a subscription, and to delete a device from the Subscriber database.
This section describes the APIs for querying catalog items based on eligibility. The APIs return catalog items that the specified object is eligible to purchase.
The event APIs include the messaging and elements to return events and notifications in the Event Repository and the event database for subscriptions, groups, and users.
External payment APIs query external payment requests and get a list of external payment request records in a wallet.
The group management APIs include the messaging required to operate on the group object. The APIs include the messaging and data elements required to create, modify, associate, and query objects directly related to the group.
The multi-tenant APIs get tenant information for individual tenants and all tenants.
My MATRIXX supports GET, PUT, and POST REST bindings. The { } notation around text represents a URL parameter.
{ }
Use these APIs to query a list of status life cycles for an offer. You can query specific offer status life cycle using the profile ID.
The integration layer REST APIs manage payment authorization tokens for the payment gateway from the integration layer. These tokens are necessary for the client to communicate directly with the payment gateway to create a payment method in the payment gateway.
The policy APIs allow you to query the Sy policy counters for a specific device.
These calls makes a request to retrieve information about balance templates, balance classes, and balance thresholds in the pricing database.
Request to retrieve a list of balances from the pricing database.
These calls return a list of billing cycle IDs and details about specific billing cycles. Billing cycles are defined as billing profile templates by pricing administrators as part of configuring pricing. For information about defining billing profile templates, see MATRIXX Pricing and Rating.
This method is used to request a catalog from the engine.
This method is used to request a list of catalogs from the engine.
The catalog item APIs query a MATRIXX Engine for a list of commercial catalog items or specific information about a single catalog item. This information can be used when purchasing a catalog item using the Purchase Offer APIs.
The contract APIs get contract information and contract ETC schedules from MATRIXX Engine and the pricing database.
This call makes a request to retrieve details about a specific event type in the pricing database. Event types and the EventTypeIdPath can be used with the Event REST APIs to query the Event Repository.
EventTypeIdPath
This call makes a request to retrieve a list of all event types in the pricing database. Event types and the EventTypeIdPath can be used with the Event REST APIs to query the Event Repository.
This call uses the notification profile ID to retrieve information about the notification profile, including the name and a list of expiration notification types.
Request to retrieve a product offer from the pricing database, including all details about the product offer. All returned data is reflected in the product offer definition in My MATRIXX. Only the currently-active revision of each offer is returned. The query time is used to determine which revision to return. You can query by offer ID or external ID. For information about querying a specific version of an offer, see the discussion about getting offers by VersionId.
VersionId
This call makes a request to retrieve the list of product offers loaded into the pricing database. The query returns the product offer ID, external ID, and name of each product offer. Use a product offer ID or external ID to query the details for a specific product offer. To get a list of global product offers only, use the parameter globalOffersOnly=true in the REST URI.
Because pricing information loaded in the MATRIXX Engine does not change often, the RS Gateway creates a lazy-loaded pricing-information cache of this information. The RS Gateway invalidates entries in this cache after a configurable time (default is 5 minutes) and when the system detects a new pricing file has been loaded into the engine.
Rate tags are defined in My MATRIXX and can be queried using the REST APIs.
The role APIs query a MATRIXX Engine for information about user roles.
These calls retrieve information a list of all active service types, information about a specific service type, and information about the service context for a service type.
This call makes a request to query the status of the currently-loaded mtx_pricing.xml configuration file. The information returned includes the time the pricing was activated in the database (either by a load or revert operation), the date the pricing configuration file was compiled, the log in ID of the user who compiled it, the name of the pricing domain, and the directory path of the pricing repository. You can optionally specify a TenantId to return information for a specific tenant.
TenantId
Get basic information for all tax class definitions and detailed information for specific tax class definitions using a TaxClassId or ExternalId.
TaxClassId
ExternalId
The product offer management APIs include the messaging to activate, purchase, cancel, and modify catalog items. You can identify a product offer by its object ID or the external ID assigned during pricing plan creation.
Use the purchase package APIs to manage catalog items in a purchase package, including adding and removing catalog items for subscriptions, groups, and devices, and suspending, resuming, and canceling purchase packages.
The MtxRequestSubscriberEstimateRecurringCharge SubMan API estimates balance impacts from recurring processing of currently failing recurring cycles and upcoming recurring cycles (active purchased items cycles, balance cycles and billing cycles).
The rehoming APIs move a subscription, group, device, or user from one customer sub-domain to a different sub-domain. For a description of the rehoming process, see the discussion about rehoming subscribers, groups, devices, and users in the object management overview.
The extended REST service APIs are implemented only in the RS Gateway. These APIs include REST services that manage subscribers, groups, and devices, including rehoming operations. In addition, you can start and stop rating sessions using the service APIs. Unlike the APIs described in MATRIXX Subscriber Management API, these APIs do not have a Python or Java equivalent. For information about the service API default filters, see the discussion about REST filters.
Use these APIs to query status life cycle information for devices, groups, subscriptions, and users from the engine.
The status modify APIs schedule status changes and delete scheduled status changes. They also suspend and resume purchased items (product offer or bundle) if the current offer status class permits the action.
The Subscriber REST APIs described here are deprecated and will be removed in a future release.
The subscription management APIs include the messaging required to operate on the subscriber object, which is a primary object for MATRIXX interactions. The API bindings include the messaging and data elements required to create, modify, and query objects directly related to the subscription. A subscription must have a wallet secondary object, which is created for the subscription at subscription creation time.
The system REST APIs query the MATRIXX Engine to check if recurring recharge is enabled, return domain and sub-domain information, return tenant IDs, and create Pay Now client tokens.
The tax APIs manage information in the US Tax database.
Use the User REST APIs to add, update, query, and delete users. You can also get and modify user authentication data, associate users with groups and subscriptions, and modify or remove those associations.
This part provides an overview of how to use the Java™ API binding for the SubMan v3 API as an interface to the MATRIXX Engine.
