Manage Subscriptions

A subscription acts as a contract between the sales vendor and the customer. Usually, the platform is configured so that a subscription for an offer is created after the corresponding sales order is paid for.

The platform exposes operations with its subscriptions on the /subscriptions endpoints.

List Subscriptions

An API client can get the full list of orders or narrow down the returned list by adding certain search criteria to a request.

List All Subscriptions

To get the full list of a subscriptions, send the following request:

GET /subscriptions HTTP/1.1
Authorization: Bearer eyJwcm...0fQtrLk4RToj51HAmsRXO78
X-Subscription-Key: 066a6b...33b16

The response looks similar to the following:

HTTP/1.1 200 OK

{
  "data": [
    {
      "id": "1000177",
      "customerId": "1000275",
      "status": "active",
      "renewalStatus": true,
      "creationDate": "2019-10-25",
      "renewalDate": "2020-10-23",
      "lastModifiedDate": "2019-10-25"
    }
  ],
  "pagination": {
    "offset": 0,
    "limit": 10,
    "total": 1
  }
}

List Selected Subscriptions

The returned list of subscriptions can be narrowed down by the following query parameters:

• customerId: the ID of the subscriber

• status: the subscription status that can be one of [“pending”, “active”, “hold”, “terminated”, “removed”]

The following request illustrates how to retrieve all active subscriptions of a certain customer:

GET /subscriptions?customerId=1000001&status=active

Get Subscription Details

To view details of a certain subscription, send a request with the subscription ID as the suffix of the URL, for example:

GET /subscriptions/1000177 HTTP/1.1
Authorization: Bearer eyJwcm...0fQtrLk4RToj51HAmsRXO78
X-Subscription-Key: 066a6b...33b16

The response looks similar to the following:

HTTP/1.1 200 OK

{
  "id": "1000177",
  "customerId": "1000275",
  "status": "active",
  "renewalStatus": true,
  "creationDate": "2019-10-25",
  "renewalDate": "2020-10-23",
  "lastModifiedDate": "2019-10-25",
  "totalPrice": {
    "currency": "USD",
    "amount": "22.1"
  },
  "products": [
    {
      "mpn": "53fc25f7-6639-4f78-bb44-3c2dfec3ed40",
      "quantity": "2.0",
      "unitPrice": {
        "currency": "USD",
        "amount": "1.15"
      },
      "extendedPrice": {
        "currency": "USD",
        "amount": "2.3"
      }
    },
    {
      "mpn": "91fd106f-4b2c-4938-95ac-f54f74e9a239",
      "quantity": "1.0",
      "unitPrice": {
        "currency": "USD",
        "amount": "19.8"
      },
      "extendedPrice": {
        "currency": "USD",
        "amount": "19.8"
      }
    }
  ],
  "fulfillmentParameters": [
    {
      "name": "adminLogin",
      "value": "admin@example.onmicrosoft.com"
    },
    {
      "name": "adminPassword",
      "value": "F4a[&jsio3"
    }
  ]
}

A sales order can request several products from an offer; all of them will be in the same subscription. If products in the order are from multiple offers, multiple subscriptions will be created, one for each offer referenced.

Subscription Operations

All operations with subscriptions are initiated by placing certain orders:

• Upgrade or downgrade (change limits on products or add more products): Change Order

• Renew for the next subscription period: Renewal Order

• Cancel: Cancellation Order

When upgrading or downgrading a subscription, you can choose which date to use as subscription period start date after the change: start date of the current subscription period or the date the subscription was changed.

To select the date, add the upgradeStartType order property with one of these values:

• FROM_DATE_OF_UPGRADE (used as the default in billing configuration)

• FROM_OLD_START_DATE

For example:

POST /orders HTTP/1.1
Authorization: Bearer eyJwcm...0fQtrLk4RToj51HAmsRXO78
Content-Type: application/json
X-Subscription-Key: 066a6b...33b16

{
   "customerId": "1012954",
   "poNumber": "PO2244",
   "type": "change",
   "upgradeStartType": FROM_OLD_START_DATE,
   "products": [
      {
         "subscriptionId": "1211331",
         "mpn": "SQXAMSENS",
         "quantity": "20"
      }
   ]
}

Conclusion

This is the final step in the typical workflow, which results in a customer being subscribed to a product and the provisioning of this product’s services to the customer. Periodically, a reseller needs consolidated data for the commercial activity of the previous period. The next step in the workflow describes how to collect such reports.

Previous Topic

Next Topic