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

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 usage to be activated. 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:

• customer
• none

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.

Preload with customer 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.

Preload without payment (none)

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.

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.

Subscribe with credit payment

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.

Subscribe with customer 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, Add-on.

Subscribe without payment (none)

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.

Cancel next renewal

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

Modify subscription

Terminate a subscription (terminate)

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

Terminate subscription