OCS products

Learn about OCS products and their dedicated APIs

Introduction

A product represents a service plan that can be subscribed in order to provide connectivity services to a subscriber. Products are defined inside catalogs that you can consult using OCS catalog API.

Several categories of product exist with their dedicated lifecycle:

• One-off: For a one time plan with a fixed end date
• Recurring: For a multi period plan, renewing itself automatically
• Add-on: For an additional plan added on top of a parent product and which inherits the same expiration date

Product categories

One-off

A One-off product is a type of plan offering connectivity services for a pre-defined validity period. Once the validity comes to an end, the product will automatically expire together with its remaining balances.

Example: 10GB for 30 days.

Lifecycle for One-off products

Recurring

A Recurring product is a type of plan offering connectivy services per defined periods and which renew itself automatically at each new period. The total number of periods can either be specified or be unlimited. Once reached the final period or if the product is canceled, the product will automatically expire together with its remaining balances.

Examples:

• Recurring product with fixed number of occurrences: 10GB per month for a year
• Recurring product with unlimited number of occurrences: 10GB per month

Lifecycle for Recurring products with fixed number of occurrences

Lifecycle for Recurring products with unlimited number of occurrences

Add-on

An Add-on product is a type of plan offering connectivy services for a validity period aligned on an already subscribed parent product. Once the validity comes to an end, the product will automatically expire together with its remaining balances. It is generally used to offer complementary service plans on top of an already exhausted plan.

Example: 5GB valid for the remaining of the current period.

Lifecycle for Add-on products

Subscription statuses

	Status	Description
	pending	The subscription has been planned and is waiting for its activation on the specified date.
	pendingForFirstUse	The subscription has been preloaded and is waiting the first usage of the SIM to activate.
	readyForUse	The subscription is waiting the first usage of its resources on the network.
	scheduled	The subscription has been scheduled to replace the current recurring one at next renewal date.
	active	The subscription is active.
	terminated	The subscription has reached its expiration date or has been forcefully terminated.

Product Catalog

This API allows you to retrieve product(s) from a catalog. Several filters are available to return only relevant information:

• availabilityStatus:
  • AVAILABLE: you can find all products ready for sales on your catalog.
  • ALL: you can find all products even past ones.
• categories: you can find only products of the provided categories (One-off, Recurring & Add-on). By default, we return all categories. You can filter products using one or several categories.
• childOf: using this filter you can retrieve all Add-on for a given product.
• tags: you can retrieve products having the provided tags.

Retrieve all products by COS

Operation used to retrieve all products in your catalog.
A context parameter can be provided. This msisdn parameter allows you to return if the products can be subscribed for the given subscriber.

Retrieve a given product

Operation used to retrieve a given product from your catalog given its productId.

Product Inventory

This API allows you to retrieve inventory of subscriptions for your subscribers.

Retrieve subscriber product(s) inventory

Operation used to retrieve a subscriber product(s) inventory given their MSISDN.
You can optionally filter the results in order to only include subscription with specific statuses.

Retrieve subscription details

Operation used to retrieve details of a single subscription given its ID.

Product Subscriptions

This operation allows you to provision Transatel OCS with products for your subscribers and manage their subscriptions.

Below are the supported type of order:

• preload
• subscribe
• cancelRenewal
• modify
• terminate

Preload a product (preload)

This order lets you provision a mobile plan on a pre-activated subscriber. This mobile plan will be in a pending state (pendingForFirstUse) waiting for the first SIM usage. If the product is configured with deferred activation, the subscription will switch to either active or readyForUse status during SIM activation depending on whether the fist SIM usage is within or outside the mobile plan coverage. Only then the product allowances will be allocated and the subscription ready to use. The operation is synchronous, a successful response will contain the new subscription id.

Supported payment provider:

• credit
• customer
• none

credit:

• Applicable if you are using Transatel prepaid platform and allowing wallet (credit) to be used as payment method to purchase mobile product.
• Supported products: One-off, Recurring bundle with upfront payment, Recurring bundle with recurring payment.
• For Recurring bundle with recurring payment, the wallet (credit) will be impacted only at the first renewal (i.e the first occurrence will not impact the wallet balance).

customer:

• Available if you are under Real-Time Controlled Paym option (RTCP) or Mobile Workplace Connect (MWC) commercial offers.
• Supported products: One-off, Recurring bundle with upfront payment, Recurring bundle with recurring payment.

none:

• Available if you manage payment transactions on your billing system, can also be used for commercial gesture or a promotion.
• Supported products: One-off, Recurring bundle with upfront payment, Recurring bundle with recurring payment.

Subscribe a product (susbcribe)

Subscribe to a mobile plan is the main use case of the API. You can add allowances of any kind (voice, data, sms). Please refer to your Transatel product documentation for more details on available plans.

The operation is synchronous, a successful response will contain the new subscription id.

By default, the mobile plan will start immediately, however, if an activation date is provided in the request, the subscription will be placed in a pending state for activation (see example: Schedule subscription in the API reference).
This is currently only available for payment provider none.

If a product is set up with deferred activation, the subscription will have a readyForUse status and will await the initial use of the mobile plan at the destination to activate automatically.

When a Recurring product is already subscribed for a given subscriber and is part of an exclusion group in the catalog definition, then subscribing to another Recurring product in the same exclusion group will trigger an automatic switch between the products.

• Recurring product with fixed number of occurrences:
  • Switch execution: At the expiration of the initial product. The previous product subscription will expire as planned and the new product subscription is scheduled to start after the first product's last occurrence.
  • Apply to: Both fixed and unlimited Recurring products
• Recurring product with unlimited number of occurrences:
  • Switch execution: At the next renewal of the initial product. The previous product subscription is cancelled and the new product subscription is scheduled to start at next renewal.
  • Apply to: Only unlimited Recurring product

An exclusion group in the catalog allows to define products which cannot be active in the inventory of a subscriber at the same time.

Supported payment provider:

• credit
• customer
• none

credit:

• Applicable if you are using Transatel prepaid platform and allowing wallet (credit) to be used as payment method to purchase mobile product.
• Supported products: One-off, Recurring bundle with upfront payment, Add-on.

customer:

• Available if you are under Real-Time Controlled Paym option (RTCP) or Mobile Workplace Connect (MWC) commercial offers.
• Supported products: One-off, Recurring bundle with upfront payment, Recurring bundle with recurring payment, Add-on.

none:

• Available if you manage payment transactions on your billing system, can also be used for commercial gesture or a promotion.
• Supported products: One-off, Recurring bundle with upfront payment, Recurring bundle with recurring payment, Add-on.

Cancel next renewal (cancelRenewal)

This order is reserved to cancel a subscription to a recurring product with unlimited renewal. Upon request, the subscription will be terminated automatically at the end of the current period.

Modify a subscription (modify)

This order allows adjusting balances or the expiration date of an active subscription. Some restrictions may apply depending on the type of subscribed product:

• One-off: Both balances and expiration may be adjusted
• Recurring: Balances may be adjusted, however the expiration date can only be modified for product with fixed number of renewals
• Add-on: Only balances may be adjusted

Balances modification possibilities

Balances current value may be adjusted in two different ways:

• Either you can replace the current value with a new one
• Or you can increase or decrease it by a given amount, a positive amount will add the given value to the balances while a negative amount will remove it

Terminate a subscription (terminate)

Termination has an immediate effect. It expires remaining balances and terminate the subscription. This order cannot be rolled-back.