Get Customer Offer Details V4

This API is used to retrieve comprehensive data for a specific customer offer. A customer can request details for either an offer they created for their sub-customers or an offer assigned to them by their parent account.

Method	Path
GET	api/v4/customer/{id}/offer/{id}

Eligibility

The requestor is eligible to request information on an offer that was created by them and is available for attachment to their sub-customers, or on an offer that has been assigned to them by their parent customer.

API Request

Request Structure

Not applicable

API Response

Response Structure

Parameter	Type	M/O/CM	Description
errorCode	String	O	Failure code. See list below under the ‘Error Codes’ section.
errorMessage	String	O	Failure detailed description. See list below under the ‘Error Codes’ section.
content	Object	O	Array of main response body objects. Displayed when an API call is successful. For a failure, it will be empty.
pageable	Object	O	Paging information object. Displayed when an API call is successful. For a failure, it will be empty.

Content

Parameter	Type	M/O/CM	Description
id	UUID	M	Offer ID
name	String	M	Offer name
description	String	O	Offer description
class	String	M	Offer classification. ENUM valid values: SELL_PLAN, BUY_PLAN
type	String	M	Individual offer type. ENUM: RATE, MONEY, USAGE, POOL
cost	Decimal	M	Cost of the offer. May contain decimal value. If no cost is applied, the value presented would be zero.
currency	String	M	Cost currency. e.g., USD, GBP, EUR
creationTime	DateTime	M	Offer creation timestamp
renewalInterval	String	M	Renewal period interval. ENUM valid values: DAILY, WEEKLY, MONTHLY, QUARTERLY, SEMI_ANNUALLY, ANNUALLY, ONE_TIME
renewalIntervalMethod	String	CM	Renewal day settings. FIRST_DAY – Renewal day is the first day of the renewal interval. E.g., 1’st of the month per ‘MONTHLY’ interval. SELF_DEFINED – Renewal day is the day defined by the user. E.g., 10’th of the month per ‘MONTHLY’ interval. PLAN_ALLOCATION – Renewal day is set based on the actual plan allocation (attachment) day. Empty for ONE_TIME renewal interval.
renewalIntervalDay	Numeric	CM	Chosen renewal day of the selected period. Valid values per ENUM: DAILY: N/A WEEKLY: 1–7 MONTHLY: 1–28 QUARTERLY: 1–90 SEMI_ANNUALLY: 1–180 ANNUALLY: 1–365 ONE_TIME: N/A Populated only if SELF_DEFINED or FIRST_DAY was set per ‘renewalIntervalMethod’ attribute.
expirationType	String	O	Expiration date settings. ENUM valid values: FIXED – Fixed predefined expiration date. RELATIVE_ATTACHED – Time duration starting the time the plan was attached to the subscriber. E.g., 10 days from plan attachment to the subscriber. RELATIVE_FIRST_USE – Time duration starting the time the plan was used by the subscriber. E.g., 10 days from plan consumption by the subscriber. Plan has no expiration if it is null.
expirationDate	Date	CM	Date settings per chosen ‘expirationType’. Populated only if selected ‘expirationType’ is FIXED. Empty for other expiration types or no expiration type.
expirationUnit	String	CM	Time unit settings for expiration calculation. ENUM Valid values: DAY, WEEK, MONTH, YEAR Empty if selected ‘expirationType’ is FIXED or no expiration type.
expirationValue	Numeric	CM	Time value settings per chosen ‘expirationUnit’. Empty if selected ‘expirationType’ is FIXED or no expiration type.
isProrated	Boolean	M	Plan proration. True = Proration will be calculated when attaching this plan. False = There is no proration. Pool plan will be always marked as False.
isIncludingAccessFee	Boolean	M	Specifies 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.
money	Object	CM	Money type information object. Populated when MONEY offer type is returned. Empty if either RATE, USAGE or POOL offer type is returned.
rate	Object	CM	Rate type object. Populated when RATE offer type is returned. Empty if either USAGE, MONEY or POOL offer type is returned.
usage	Object	CM	Usage type object. Populated when USAGE offer type is populated. Empty if either RATE, MONEY or POOL offer type is returned.
pool	Object	CM	Pool plan type object. Populated when POOL offer type is returned. Empty if any other offer type is returned (USAGE, RATE, MONEY).
eligibleSubAccountIds	String	O	Array of sub account UUIDs. Specified sub account\s are the accounts that are eligible to use this plan. Array of sub account UUIDs. Specified sub account\s are the accounts that are eligible to view and manage (attach/detach) this offer as part of the self-service feature. Empty string – None of the customer’s sub-accounts are eligible to this plan. ‘ALL’ keyword (ENUM) - All the customer’s sub-accounts are eligible to this plan. May be populated for Sell Plans only. Does not exist for for Buy Plans. Developer note: Do not include the attribute for Buy Plans
availabilityZone	Object	O	Array of availability zones object which are assigned to this plan. Empty array means that the plan is available in any zone.
linkedOffers	Object	O	Array of offer\s object linked to this offer. The order of the instances in the array determines their priority for charging. Empty array means that the created offer has no linked offers.
allocatedSubAccounts	Object	O	Array of offer instances (attached plans) and their information

Money

Parameter	Type	M/O/CM	Description
activationType	String	M	Displays plan activation behavior. Valid values: REGULAR, FIRST_EVENT_PERIODIC, FIRST_EVENT_NON_PERIODIC.

Rate

Parameter	Type	M/O/CM	Description
type	String	M	Rate offer type. ENUM valid values – ACCOUNT, PLAN_FIXED, PLAN_CUSTOMIZED.
dataLimit	Decimal	O	Displays the maximal allowed DATA usage consumption.
dataLimitUnitType	String	CM	Data limit unit type. Valid values - KB, MB, GB. Populated when data limit exists.
smsLimit	Decimal	O	Displays the maximal allowed SMS usage consumption. Unit counting is always a ‘unit’.
price	Object	O	Array of plan price object. Populated if type is ‘PLAN_FIXED’ or ‘PLAN_CUSTOMIZED’. Empty if type is ‘ACCOUNT’.

Price

Parameter	Type	M/O/CM	Description
serviceType	String	M	Type of usage. ENUM valid values: DATA, SMS.
unitType	String	CM	Usage unit type. DATA ENUM valid values - KB, MB, GB. Populated for DATA usage type. Empty for SMS usage type.
type	String	M	Type of the price. ENUM valid values: REGULAR, BLOCK, PASS.
priceValue	Decimal	CM	Price per 1 unit consumption. Data – price per one KB/MB/GB consumption. SMS – price per one SMS consumption. Mandatory if ‘type’ is REGULAR.
currency	String	CM	Price currency. e.g., USD, GBP, EUR. Mandatory if ‘type’ is REGULAR.
countryCode	String	CM	ISO alpha-3 Country Code. Mandatory if rate plan type is ‘PLAN_CUSTOMIZED’.
network	Object	CM	Mobile Network object. Mandatory if rate plan type is ‘PLAN_CUSTOMIZED’.

Network

Parameter	Type	M/O/CM	Description
plmn	String	M	Public Land Mobile Network. MCCMNC representation.
mcc	String	M	Mobile Country Code (MCC).
mnc	String	M	Mobile Network Code (MNC).

Usage

Parameter	Type	M/O/CM	Description
activationType	String	M	Displays plan activation behavior. Valid values: REGULAR, FIRST_EVENT_PERIODIC, FIRST_EVENT_NON_PERIODIC.
usageType	Object	M	Array of usage types object.

usageType

Parameter	Type	M/O/CM	Description
type	String	M	Type of the usage. Valid values: DATA, SMS.
value	Decimal	M	Overall allowance value when the regular offer or pool plan is of type FIXED. Allowance value per every added subscriber when the pool plan type is ACCUMULATIVE. Data consumption for DATA type. Unit counting for SMS type.
unitType	String	CM	Usage unit type. DATA related valid values - KB, MB, GB. Populated when usage type is set to DATA.

Pool

Parameter	Type	M/O/CM	Description
type	String	M	Pool plan type. Valid values: FIXED, ACCUMULATIVE.
activationType	String	M	Displays plan activation behavior. Valid values: REGULAR, FIRST_EVENT_PERIODIC, FIRST_EVENT_NON_PERIODIC.
poolUsageType	Object	M	Array of usage types object.

poolUsageType

Parameter	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.
limitUnitType	String	CM	Limit unit type. DATA ENUM valid values: KB, MB, GB. Mandatory when setting limit for DATA usage. Empty for SMS usage type. Ignored if populated for SMS usage type.

availabilityZone

Parameter	Type	M/O/CM	Description
Id	UUID	M	Customer’s availability zone’s universal unique identity.
name	String	M	Customer’s availability zone name.

linkedOffers

Parameter	Type	M/O/CM	Description
id	UUID	M	Universal unique ID of the linked offer.
isPinned	Boolean	M	Denotes whether the linked offer can be removed from the parent offer or not. True = Linked offer is fixed and cannot be removed. False = Linked offer is not fixed and can be removed (Future feature – Currently not in use).

Parameter

Type

M/O/CM

Description

UUID

Universal unique ID of the linked offer.

isPinned

Boolean

Denotes whether the linked offer can be removed from the parent offer or not.

True = Linked offer is fixed and cannot be removed.
False = Linked offer is not fixed and can be removed (Future feature – Currently not in use).

allocatedSubAccounts

Parameter	Type	M/O/CM	Description
id	UUID	M	Attached (allocated) customer ID.
name	String	M	Attached (allocated) customer name.
simCount	Numeric	M	Number of attached (allocated) SIMs to this customer.
package	UUID	M	Package ID that contains this offer instance. If empty, the offer instance is standalone and not included in a package.

pageable

Parameter	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.
CUSTOMER_1002	Customer does not exist.
CUSTOMER_1006	Failed to retrieve customer details.

Examples

Request Body

Not applicable

Response Body Regular Plan (Money) Success ACK

Copy

{
  "errorCode": "",
  "errorMessage": "",
  "content": [
    {
      "id": "e7fcef24-5c03-41dd-9e33-995b7d6f47a7",
      "name": "roaming",
      "description": "roaming bundle",
      "class": "SELL_PLAN",
      "type": "MONEY",
      "cost": 20.5,
      "currency": "USD",
      "creationTime": "2020-07-01T00:00:00.977Z",
      "renewalInterval": "MONTHLY",
      "renewalIntervalMethod": "FIRST_DAY",
      "renewalIntervalDay": "",
      "expirationType": "FIXED",
      "expirationDate": "13092023",
      "expirationUnit": "",
      "expirationValue": "",
      "isProrated": true,
      "isIncludingAccessFee": false,
      "availabilityZone": [
        {
          "id": "1b15048b-1ed4-4d34-a074-c7e26520e12a",
          "name": "North America 05"
        }
      ],
      "money": [
        {
          "activationType": "REGULAR"
        }
      ],
      "eligibleSubAccountIds": [
        "ee74dca6-8e7f-4b85-a42b-13860913b3b1",
        "ff74dca6-8e7f-4b85-a42b-13860913b370"
      ],
      "linkedOffers": [
        {
          "id": "ee74dca6-8e7f-4b85-a42b-13860913b3b1",
          "isPinned": true
        },
        {
          "id": "ff74dca6-8e7f-4b85-a42b-13860913b370",
          "isPinned": true
        }
      ],
      "allocatedSubAccounts": [
        {
          "id": "f9f1b795-6474-4d2a-a4a0-dbbfdfba19bb",
          "name": "Lenovo",
          "simCount": "120",
          "package": "544f0911-0b93-4c94-8756-208e10a43ceb"
        },
        {
          "id": "dda92b58-2ef9-44eb-9a5f-55295c6c2799",
          "name": "Dell",
          "simCount": "101",
          "package": ""
        }
      ]
    }
  ],
  "pageable": {
    "page": 1,
    "size": 10,
    "totalPages": 1,
    "totalElements": 2
  }
}

Response Body Pool Plan Success ACK:

Copy

{
  "errorCode": "",
  "errorMessage": "",
  "content": [
    {
      "id": "e7fcef24-5c03-41dd-9e33-995b7d6f47a7",
      "name": "Family 50GB+",
      "description": "Family bundle",
      "class": "SELL_PLAN",
      "type": "POOL",
      "cost": 15,
      "currency": "USD",
      "creationTime": "2020-07-01T00:00:00.977Z",
      "renewalInterval": "MONTHLY",
      "renewalIntervalMethod": "FIRST_DAY",
      "renewalIntervalDay": "",
      "expirationType": "FIXED",
      "expirationDate": "13092023",
      "expirationUnit": "",
      "expirationValue": "",
      "isProrated": false,
      "isIncludingAccessFee": false,
      "pool": [
        {
          "type": "FIXED",
          "activationType": "REGULAR",
          "poolUsageType": [
            {
              "type": "DATA",
              "value": 50,
              "unitType": "GB",
              "limitValue": 20,
              "limitUnitType": "GB"
            },
            {
              "type": "SMS",
              "value": 100,
              "unitType": "",
              "limitValue": 10,
              "limitUnitType": ""
            }
          ]
        }
      ],
      "eligibleSubAccountIds": [
        "b8fcef24-8a03-41ed-9e43-195b7d6d42a6"
      ],
      "availabilityZone": [
        {
          "id": "1b15048b-1ed4-4d34-a074-c7e26520e12a",
          "name": "North America 05"
        }
      ],
      "linkedOffers": [
        {
          "id": "ee74dca6-8e7f-4b85-a42b-13860913b3b1",
          "isPinned": true
        },
        {
          "id": "ff74dca6-8e7f-4b85-a42b-13860913b370",
          "isPinned": true
        }
      ],
      "allocatedSubAccounts": [
        {
          "id": "f9f1b795-6474-4d2a-a4a0-dbbfdfba19bb",
          "name": "Lenovo",
          "simCount": "12",
          "package": "544f0911-0b93-4c94-8756-208e10a43ceb"
        },
        {
          "id": "dda92b58-2ef9-44eb-9a5f-55295c6c2799",
          "name": "Dell",
          "simCount": "11",
          "package": ""
        }
      ]
    }
  ],
  "pageable": {
    "page": 1,
    "size": 10,
    "totalPages": 1,
    "totalElements": 2
  }
}

Response Body Failure NAK

Copy

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