# Subscriptions
source: https://developer.mastercard.com/commercial-event-notifications/documentation/parameters/subscriptions/index.md

Create subscriptions to receive notifications that match the criteria specified in the subscription. The API requires at least one active subscription to create notifications.
You can initially create a subscription with an inactive status and make it active later.

Each subscription must have a specification and a subjectType. The specification defines conditions to create notifications. An empty specification creates notifications for all the events of a payment type. You use fieldmappings in the specification array to limit notifications' scope for payment event. The subjectType refers to the type of event for which the notifications are created. The API creates notifications for [supported event types](https://developer.mastercard.com/commercial-event-notifications/documentation/index.md#Overview).

## Subscription resource {#subscription-resource}

The following table shows the available endpoints and methods for the subscription resource.

|                                                                      Method                                                                       |      Endpoint       |                         Action                          |
|---------------------------------------------------------------------------------------------------------------------------------------------------|---------------------|---------------------------------------------------------|
| [POST](https://developer.mastercard.com/commercial-event-notifications/documentation/parameters/subscriptions/index.md#post-subscriptions)        | /subscriptions      | Creates a subscription                                  |
| [GET](https://developer.mastercard.com/commercial-event-notifications/documentation/parameters/subscriptions/index.md#get-subscriptions)          | /subscriptions      | Retrieves all subscriptions created for a subscriber    |
| [GET](https://developer.mastercard.com/commercial-event-notifications/documentation/parameters/subscriptions/index.md#get-subscriptions-id)       | /subscriptions/{id} | Retrieves a subscription for a specific subscription ID |
| [PUT](https://developer.mastercard.com/commercial-event-notifications/documentation/parameters/subscriptions/index.md#put-subscriptions-id)       | /subscriptions/{id} | Updates a subscription for a specific subscription ID   |
| [DELETE](https://developer.mastercard.com/commercial-event-notifications/documentation/parameters/subscriptions/index.md#delete-subscriptions-id) | /subscriptions/{id} | Deletes a subscription for a specific subscription ID   |

## Attributes {#attributes}

The subscription object contains the following attributes:

### id - string, read-only {#id---string-read-only}

The system generated unique identifier (a maximum of 255 characters) for a subscription, which is returned in the create subscription call. Access the individual subscription using its id to update, get details or delete it permanently.

### name - string, required {#name---string-required}

Specify a unique name for each subscription. It can contain 50 characters and include upper and lowercase alphabets, numbers, dashes and underscores. You can use the subscription name to pull the notifications created for a particular subscription.

### subjectType - string, required {#subjecttype---string-required}

Specify a subject type, which refer to the event that the subscription belongs to. This version of the API supports the following subject types:

|         Subject Type          |                                                    Description                                                     |
|-------------------------------|--------------------------------------------------------------------------------------------------------------------|
| **BPC_CLEARING**              | Creates notifications when a clearing event has happened for a VCN authorized by the Business Payment Controls.    |
| **BPC_PAYMENT_AUTHORIZATION** | Creates notifications whenever a VCN is authorized by Business Payment Controls.                                   |
| **PAYMENT_AUTHORIZATION**     | Creates notifications whenever a VCN is authorized by In Control for Commercial Payments (ICCP).                   |
| **CLEARING**                  | Creates notifications when a clearing event has happened for a VCN authorized by ICCP.                             |
| **PAYMENT_UPDATE**            | Creates notifications for payments that use Straight Through Processing (STP)-Business Payment Service (BPS) flow. |
| **TOKEN LIFECYCLE_EVENT**     | Creates notifications when a lifecycle event happens on tokens for VCNs generated by ICMP.                         |
| **TOKEN_PROVISIONING_EVENT**  | Creates notifications when a provisioning event happens on tokens for VCNs generated by ICMP.                      |

### subscriberId - string, read-only {#subscriberid---string-read-only}

The system generated unique identifier (a maximum of 255 characters) of the subscriber to whom the subscription belongs to. Returned in the create subscription call. Not used in any calls.

### active - boolean, required {#active---boolean-required}

Specify whether the subscription should be active (true) or inactive (false) for the API to create notifications only if the subscription is active.

### specifications - array, required {#specifications---array-required}

Specifications define conditions for the API to filter the payment type messages to create subscriptions for you.

You can define `specifications` array with zero or more fieldmappings. If using fieldmappings, then specify values and conditions for the fieldmappings.

A condition follows a format similar to a WHERE SQL clause. For example, to filter payment authorization messages for virtual cards issued using two different real cards, the SQL condition can be expressed as follows:
> WHERE rcnAlias = CITY_RCN and rcnAlias = CITY_RCN1

Similarly using specifications conditions, the above WHERE clause with conditions combined with an AND operator can be expressed as follows:

```json

     "specifications": [
            {
                "type": "FIELD",
                "operator": "WHERE",
                "children": [],
                "fieldMappingName": "purchaseRequest.rcnAlias",
                "fieldOperator": "EQUALS",
                "expectedContent": {
                    "value": "CITY_RCN",
                    "contentType": "TEXT"
                }
            },
         {
        "type": "FIELD",
          "operator": "AND",
          "fieldMappingName": "purchaseRequest.rcnAlias",
          "fieldOperator": "EQUALS",
          "expectedContent": {
            "value": "CITY_RCN1",
            "contentType": "TEXT"
                    },
          "children": []
        }
        ]
```

> Here:

|    SQL Condition    |                                                                                     Specifications Condition                                                                                     |
|---------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| WHERE, AND          | [operator](https://developer.mastercard.com/commercial-event-notifications/documentation/parameters/subscriptions/index.md#operator---string-required) : WHERE, AND                              |
| rcnAlias            | [fieldMappingName](https://developer.mastercard.com/commercial-event-notifications/documentation/parameters/subscriptions/index.md#fieldmappingname---string-required): purchaseRequest.rcnAlias |
| =                   | [fieldOperator](https://developer.mastercard.com/commercial-event-notifications/documentation/parameters/subscriptions/index.md#fieldoperator---string-required) : EQUALS                        |
| CITY_RCN, CITY_RCN1 | [value](https://developer.mastercard.com/commercial-event-notifications/documentation/parameters/subscriptions/index.md#expectedcontent---object-required) : CITY_RCN, CITY_RCN1                 |

The specifications array has the following properties:

#### id - string, read-only {#id---string-read-only-1}

The system generated unique identifier (maximum of 255 characters) for a specification. Returned in the create subscription call. Not used in any calls.

#### type - string, required {#type---string-required}

Specify the type of a specification. Currently, this is a **FIELD** to represent the fields in the payment type message and the related purchase requests in ICCP/Business Payment Controls.

## operator - string, required {#operator---string-required}

Specify an operator to combine multiple conditions in the specifications.

* **WHERE**: By default, the first condition in the specifications should always have this value to represent the WHERE clause.
* **AND**: Use this in the second condition onwards to create notifications only if all specifications conditions are true.
* **OR**: Use this in the second condition onwards to create notifications if one of the specifications conditions is true.

#### children - array, optional {#children---array-optional}

Use this to define specifications with nested conditions for a subscription.

#### fieldMappingName - string, required {#fieldmappingname---string-required}

Specify fieldmapping's name for the condition to check. For example, this value is purchaseRequest.rcnAlias in the example above. This is used in conjunction with the fieldOperator.

#### fieldOperator - string, required {#fieldoperator---string-required}

Specify the relational operator to use in the condition for the fieldmapping. This is used in conjunction with the expectedContent.

* **EQUALS** : This applies to contentType `TEXT` and \`\`INTEGER\`. Create notifications for the exact fieldmapping value specified in the condition.
* **GREATER_THAN** : This applies to contentType `INTEGER`. Creates notifications for the fieldmappings value that is greater than the value specified in the condition.
* **LESS_THAN** : This applies to contentType `INTEGER`. Create notifications for the fieldmappings value that is lesser than the value specified in the condition.
* **BETWEEN** : This applies to contentType `INTEGER`. Create notifications for the fieldmappings value that is between the value and another specified in the condition.

#### expectedContent - object, required {#expectedcontent---object-required}

Represents the fieldmapping's values to use in a condition. The expected content object has has the following attributes:

|  Attribute   |                                                     Description                                                      |  Type  | Required |
|--------------|----------------------------------------------------------------------------------------------------------------------|--------|----------|
| contentType  | Specify the type of the fields' value: **TEXT** or **INTEGER** for the EQUALS operator and **INTEGER** for the rest. | string | required |
| value        | Specify a value for a fieldmapping.                                                                                  | object | required |
| anotherValue | Specify an additional fieldmapping's value only for the BETWEEN operator.                                            | object | required |

## POST /subscriptions {#post-subscriptions}

Creates a subscription with or without [specifications](https://developer.mastercard.com/commercial-event-notifications/documentation/parameters/subscriptions/index.md#specifications-array-required).

#### Try it Out {#try-it-out}


API Reference: `POST /subscriptions`

## GET /subscriptions {#get-subscriptions}

Retrieves a list of subscriptions that are defined for a subscriber. By default returns all subscriptions with 25 subscriptions per page. You can also retrieve a set of subscriptions using an offset and a limit parameter and sort the response either by name or ID.

#### Try it Out {#try-it-out-1}


API Reference: `GET /subscriptions`

## GET /subscriptions/{id} {#get-subscriptionsid}

Retrieves the [subscription](https://developer.mastercard.com/commercial-event-notifications/documentation/parameters/subscriptions/index.md#the-subscription-object) object for a specific subscription ID. You obtain subscription IDs in response to calls to create a subscription or to list all subscriptions.

#### Try it Out {#try-it-out-2}


API Reference: `GET /subscriptions/{id}`

## PUT /subscriptions/{id} {#put-subscriptionsid}

Updates the subscription details for a specific subscription ID. You obtain subscription IDs in response to calls to create a subscription or to list all subscriptions.

#### Try it Out {#try-it-out-3}


API Reference: `PUT /subscriptions/{id}`

## DELETE /subscriptions/{id} {#delete-subscriptionsid}

Deletes the subscription details for a specific subscription ID. You obtain subscription IDs in response to calls to create a subscription or to list all subscriptions.
The system immediately stops generating notifications for the deleted subscription.

#### Try it Out {#try-it-out-4}


API Reference: `DELETE /subscriptions/{id}`