Share quota (no group)

This POST operation shares plan quota from a specific donor to a list of recipients specified in the payload. If successful, you receive an HTTP response code of 200 and a JSON response listing the information along with an id.

See HTTP response codes for other response codes.

POST /sqs/api/donations + JSON request payload

HEADER INFO

authorisation: HTTP Basic Auth

tenant: <tenantName>

content-type: application/JSON

accept: application/JSON

By default, accept is XML. You must explicitly set accept in your header to application/JSON to receive a JSON response.

permissions: SQS_DONATION_PERMISSION

JSON request payload

The example below shares a certain quota amount with two recipients. This quota share comes out of the donor plan 456 from the donor 967178860. See SQS donations data type descriptions for more details on data types.

  • Specify "quotaType": "amount" to share an exact amount.

    This is specified in bytes in the JSON request. However, subscribers typically share in MB from their mobile.

  • Specify "quotaType": "share" to share a percentage of a data plan.

    The percentage of quota shared is expressed as an integer between 0 and 10000000. So for example, 5% is 5/100 * 10000000 which equals 500000 which would be what you specify in the payload.
Share specific amount
{
  "donorId" : "967178860",
  "donorPlanId" : 456,
  "quotaType" : "amount",
  "recipients" : [
    {
        "recipientId" : "123123",
        "quota" : 1000000000
    },
    {
        "recipientId" : "234234",
        "quota" : 1500000000
    }
  ]
}
Share percentage of plan
{
  "donorId" : "967178860",
  "donorPlanId" : 456,
  "quotaType" : "share",
  "recipients" : [
    {
        "recipientId" : "123123",
        "quota" : 500000
    },
    {
        "recipientId" : "234234",
        "quota" : 800000
    }
  ]
}


JSON response

The JSON response includes the information passed in the JSON payload with an auto-assigned id.

{
  "id": "Tv6pDuPz2Gm1Gax0zl7a",
  "errorCode" : 0,
  "recipients" : [
    {
        "errorCode" : 0,
        "recipientId" : "123123"
    },
    {
        "errorCode" : 0,
        "recipientId" : "234234"
    }
  ]
}

SQS donations data type descriptions

Field Type Description

id

string

The auto-assigned ID given to a donation upon creation.

donorId

string

The MSISDN of the donor subscriber.

The subscriber’s MSISDN in international format.

donorPlanId

integer

The ID of the donor’s shareable plan.

quotaType

string

Specifies the quota type. This is share or amount.

share is a percentage of quota and amount is a specific amount (whether that is data, time, or credit). The type itself is determined from the donor plan definition’s unitMeteringType.

recipients

array

An array that lists recipients of the donation. Recipients will have a recipientId and a quota which determines how much is shared with them.

recipientId

string

The unique ID for the recipient. This is typically the MSISDN.

The subscriber’s MSISDN in international format.

quota

integer

The quota being shared with the recipient.

groupId

string

The unique ID of the group. Group IDs are auto-assigned upon creation.

HTTP response codes

Code Description

200

success!

207

Multistatus response

Check out HTTP statuses for more details.
This is not applicable to all operations.

400

malformed request

401

unauthorised; bad username or password

403

forbidden; user does not have appropriate privileges

404

donor not found

409

conflict with target resource

This often occurs if the item already exists, such as a plan, group, or name.
This is not applicable to all operations.

412

failed validation; this typically means that a property was not set or a value is out of range.

example
HTTP 412
{
  "errors" : [
        {
          "field" : "name",
          "description" : "name is mandatory"
        }
    ]
}

422

failed processing (after passing validation).

example
HTTP 422
{
    "message": "Subscriber max plan count exceeded",
    "errorCode": 1
}
Example 1. SQS response codes

  • 0 = no error

  • 1 = undefined general error

  • 2 = group owner/name pair is not unique

  • 3 = group owner cannot be a member

  • 4 = total member quota exceeds 100%

  • 5 = group does not exist

  • 6 = maximum group size exceeded

  • 7 = the donor does not exist

  • 8 = the shareable plan does not exist

  • 9 = the shareable plan is not a recurring plan

  • 10 = charging group owner unsupported

  • 11 = the recurring donation for this plan already exists

  • 12 = the recipient does not exist

  • 13 = the donor plan max recipient limit was exceeded

  • 14 = subscriber not found

500

internal error

503

request rejected due to overload