Create Customer Offer

This API is used to create an individual offer (Regular Plan) or a Pool Plan for a sub-account (customer).

HTTP URL  
POST api/v2/customer/{id}/offer

Eligibility

The Requester is eligible to create new individual offers or Pool Plans for his sub-customers use. The Requester is not eligible to create new individual offers or new Pool Plans for its own profile use.

API Request

Request Structure

Parameter Type M/O/CM Description
name String M Individual offer or Pool Plan offer name. Must be unique.
type String M Type of the offer. ENUM valid values: USAGE, RATE, MONEY, POOL
renewalInterval String M Renewal period interval. ENUM valid values: DAILY, WEEKLY, MONTHLY, QUARTERLY, SEMI_ANNUALLY, ANNUALLY, ONE_TIME
isProrated Boolean O Determines whether proration is calculated when plan is attached to a subscriber. Pool plan is not supported, so a True setting is ignored for a Pool plan. Rate plan is not yet supported, so this parameter has no effect for a Rate plan. Range:
  • True = Proration is calculated when a plan is attached to a subscriber.
  • False = This plan is not prorated (upon plan attachment).
Default = False
isIncludingAccessFee Boolean O Determine if the offer price already includes inherent access fee and surcharge fee.
  • True – Offer price includes access\surcharge fees. Once a calendar month, when registering on the network, the system will not charge additionally on top of the offer price.
  • False – Offer price does not include access\surcharge fee. Once a calendar month, when registering on the network, the system will charge the access\surcharge fees in addition to the offer price.
Default – False
money Object CM Money type information object. Mandatory when MONEY offer type was selected. Ignored if either a RATE or USAGE offer type was selected.
rate Object O Rate type limits definition object. Filled-in only if limits are set at least for DATA or SMS consumption. Ignored if either a USAGE or MONEY offer type was selected.
usage Object CM Usage type information object. Mandatory when USAGE offer type was selected. Ignored if either a RATE or MONEY offer type was selected.
pool Object CM Pool plan type information object. Mandatory when POOL offer type was selected. Ignored if any other offer type was selected (USAGE, RATE, MONEY).
availabilityZone UUID O Array of availability zone IDs which are assigned to this plan. Empty array means that the plan is available in any zone.

Money data objects

Element Type M/O/CM Description
value Decimal M Offer monetary value. May contain decimal value.

currency

String

M

 Offer currency. For example, USD, GBP, EUR

activationType

String

M

 Defines plan activation behavior. ENUM: REGULAR, FIRST_EVENT_PERIODIC, FIRST_EVENT_NON_PERIODIC

Rate data objects

Element Type M/O/CM Description
dataLimit Decimal O Define the maximum allowed DATA usage consumption.
dataLimitUnitType String CM

Data limit unit type. ENUM valid values: KB, MB, GB

  • Mandatory when setting limit for data usage (‘dataLimit’).
  • Ignored if ‘dataLimit’ element is empty.
smsLimit Decimal O Define the maximum allowed SMS usage consumption. Unit counting is always a ‘unit’ for SMS type.

Usage data objects

Element

 Type M/O/CM Description
cost Decimal M Cost of the offer. May contain decimal value.

currency

 String M Offer currency. for example, USD, GBP, EUR

activationType

 String M

Defines plan activation behavior.

ENUM: REGULAR, FIRST_EVENT_PERIODIC, FIRST_EVENT_NON_PERIODIC
offerDepletion Boolean CM Rater behavior when offer allowances were depleted.

Range:

  • True = Continue charging according to offer rate: invalid for a Usage-type plan.
    If set to True, an error message is sent indicating that this setting is invalid.
  • False = Block charging.
Default = False
usageType Object M Array of usage types object.

Usage Type data objects

Element Type M/O/CM Description
type String M

Type of the usage.

ENUM valid values: DATA, SMS
value Decimal M Allowance value. Data consumption for DATA type. Unit counting for SMS type.
unitType String CM

Usage unit type. DATA . ENUM valid values: KB, MB, GB

  • Mandatory for DATA usage type. Empty for SMS usage type.
  • Ignored if populated for SMS usage type.
limitValue Decimal O

Define usage limit value.

  • Data consumption for DATA type.
  • Unit counting for SMS type.
  • Limit added to both services only.
  • Ignored for a Usage-type plan and an error message is returned.
limitUnitType String CM Limit unit type. DATA ENUM valid values: KB, MB, GBMandatory when setting limit for DATA usage. Empty for SMS usage type.Ignored for a Usage-type plan and an error message is returned.

Pool data objects

Element Type M/O/CM Description
subAccountID UUID M UUID (Universal Unique ID) of the sub account that the new pool plan will serve.

NOTE: No longer valid. Always populate with a NULL string.
type

String

M

Pool plan type. ENUM valid values: FIXED, ACCUMULATIVE

cost

Decimal

M

Cost of the offer. May contain decimal value.

currency

String

M

Offer currency. for example, USD, GBP, EUR

activationType

String

M

Defines pool plan activation behavior.

ENUM: REGULAR, FIRST_EVENT_PERIODIC, FIRST_EVENT_NON_PERIODIC

usageType

Object

M

Array of usage types object.

API Response

Response Structure

Element

Type

M/O/CM

Description

errorCode

String

O

Failure code.

errorMessage

String

O

Failure message.

content

Object

O

Array of main response body object displayed when an API call was successful. For a failure, it will be empty.
pageable

Object

O

Paging information object displayed when an API call was successful. For a failure, it will be empty.

Content data objects

Element

Type

M/O/CM

Description

offerId

UUID

M

The UUID generated by a new offer

requestId

UUID

M

Request instance ID.

To be used by external systems to query the call (operation) status:

In progress

Successful

Failed.

Pageable data objects

Element

Type

M/O/CM

Description

page

Numeric

M

Page number

size

Numeric

M

Page size. Number of requested elements per page

totalPages

Numeric

M

Total amount of available pages per requested page size

totalElements

Numeric

M

Total amount of retrieved elements

Error Codes

In addition to the general success and failure codes, the following error codes are possible.

Code

Message

GLOBAL_1001

Service unavailable. Please try again

Examples

Request Body: Regular Plan

Copy 
{  
  "name": "Basic roaming bundle",
  "type": "USAGE",
  "renewalInterval": "ONE_TIME",
  "isProrated": true,
  "isIncludingAccessFee": false,
  "availabilityZone": [
      "ab74dca1-8d7f-4b85-a42b-13822913c3b3"
    ],
  "usage": {
    "cost": 20.5,
    "currency": "USD",
    "activationType": "REGULAR",
    "offerDepletion": false,
    "eligibleSubAccountIds": [
      "ee74dca6-8e7f-4b85-a42b-13860913b3b1",
      "ff74dca6-8e7f-4b85-a42b-13860913b370"
    ],
    "usageType": [
      {
        "type": "DATA",
        "value": 50,
        "unitType": "MB",
        "limitValue": 20,
        "limitUnitType": "MB"
      },
      {
        "type": "SMS",
        "value": 100,
        "unitType": "",
        "limitValue": 10,
        "limitUnitType": ""
      }
    ]
  }
}

Request Body: Pool Plan

Copy 
{  
  "name": "Accumulative Basic Pool Plan",
  "type": "POOL",    
  "renewalInterval": "MONTHLY",
  "isProrated": false,
  "isIncludingAccessFee": false,
  "availabilityZone": [
      "ab74dca1-8d7f-4b85-a42b-13822913c3b3"
    ],
  "pool": {
    "subAccountId": "ee74dca6-8e7f-4b85-a42b-13860913b3b1",
    "type": "ACCUMULATIVE",
    "cost": 20.5,
    "currency": "USD",
    "activationType": "REGULAR",
    "usageType": [
      {
        "type": "DATA",
        "value": 50,
        "unitType": "MB",
        "limitValue": 20,
        "limitUnitType": "MB"
      },
      {
        "type": "SMS",
        "value": 100,
        "unitType": "",
        "limitValue": 10,
        "limitUnitType": ""
      }
    ]
  }
}

Response Body: Success ACK

Copy 
{
  "errorCode": "",
  "errorMessage": "",
  "content": [
    {
      "requestId": "ff74dca6-8e7f-4b85-a42b-13860913b370",
      "offerId": "ee74dcd7-8e7f-4c45-a42b-13860913b129"
    }
  ],
  "pageable": {
    "page": 0,
    "size": 10,
    "totalPages": 1,
    "totalElements": 1
  }
}

Response Body: Failure NAK

Copy 
{
  "errorCode": "GLOBAL_1001",
  "errorMessage": "Service unavailable. Please try again",
  "content": "",
  "pageable": ""
}