Promotions

Add subscription promotion

Add a new promotion to an existing subscription

POST /orgs/{org}/subscriptions/{id}/promotions

Parameters

Name	In	Type	Required	Description
org	path	string	true	Organization name
id	path	string	true	Subscription unique identifier
body	body	Promotion	true	Promotion input data

Request body - instance of Promotion

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


{
  "id": "ce2f20cb-35df-4ffe-bca6-c0ed0c28cb39",
  "legacy_id": 457345,
  "catalogue_promotion_id": "124",
  "commitments": [
    {
      "id": "ce2f20cb-35df-4ffe-bca6-c0ed0c28cb39",
      "legacy_id": 345,
      "expiration_date": "2025-01-05T03:30:15Z",
      "cancellation_date": "2025-02-13T10:35:05Z",
      "cancellation_system": "killflex.auth.masmovil.com",
      "cancellation_user": "john.doe@masorange.es"
    }
  ],
  "creation_date": "2022-12-01T00:00:00Z",
  "creation_system": "killflex.auth.masmovil.com",
  "creation_user": "john.doe@masorange.es",
  "last_updated_date": "2023-01-08T12:00:05Z",
  "status": "CANCELLED",
  "activation_date": "2023-01-01T00:00:00Z",
  "expiration_date": "2025-01-05T03:30:15Z",
  "deactivation_date": "2025-01-05T03:30:15Z",
  "deactivation_system": "killflex.auth.masmovil.com",
  "deactivation_user": "john.doe@masorange.es"
}

Name	Type	Required	Description
id	string	true	Promotion ID
legacy_id	integer	false	Legacy promotion ID
catalogue_promotion_id	string	true	Catalogue promotion ID
commitments	[Commitment]	false	none
creation_date	string(date-time)	true	Promotion creation date. Format according to ISO 8601
creation_system	string	true	Info about the system that requested the promotion creation. It contains the mas-stack authentication audience info. N/A if not available
creation_user	string	true	Info about the specific user that requested the promotion creation. N/A if not available
last_updated_date	string(date-time)	true	Date and time when any field of the promotion was last updated. Format according to ISO 8601
status	string	true	Promotion status
activation_date	string(date-time)	false	Activation date and time, promotion is considered available for the user from this time on. Format according to ISO 8601
expiration_date	string(date-time)	false	End date
deactivation_date	string(date-time)	false	Deactivation date and time, promotion is considered cancelled or inactive for the user from this time on. Format according to ISO 8601
deactivation_system	string	false	Info about the system that requested the promotion deactivation. It contains the mas-stack authentication audience info when deactivation is requested by mas-stack authenticated user, N/A for legacy systems created promotions
deactivation_user	string	false	Info about the specific user that requested the promotion deactivation. It contains the mas-stack authentication subject info when deactivation was requested by mas-stack authenticated user, other user info for legacy systems deactivations if available or N/A otherwise

Property	Values
status	one of [REQUESTED, ACTIVE, CANCELLED, DEACTIVATED, EXPIRED]

Request example

1
2
3
4
5
6
7
8
9



curl -X POST https://subscriptions.masstack.com/v2/orgs/yoigo/subscriptions/ce2f20cb-35df-4ffe-bca6-c0ed0c28cb39/promotions \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer {access-token}" \
 --data-raw "{
  'catalogue_promotion_id': '124'
}" 

Responses

Code	Meaning	Description	Schema
201	Created	Promotion successfully added to the subscription	Promotion
400	Bad Request	Bad request	ErrorResponse
403	Forbidden	Forbidden access	ErrorResponse
404	Not Found	A subscription with the specified id was not found	ErrorResponse
500	Internal Server Error	Internal server error	ErrorResponse
default	Default	Any client or server error	ErrorResponse

Get subscription promotions

Get promotions of subscription

GET /orgs/{org}/subscriptions/{id}/promotions

Parameters

Name	In	Type	Required	Description
offset	query	integer	false	Pagination offset
limit	query	integer	false	Pagination limit
org	path	string	true	Organization name
id	path	string	true	Subscription unique identifier
activation_date	query	DateFilterEnum	false	Promotions started matching date filter. Available filters are [eq, lt, lte, gt, gte]. Format according to ISO 8601
expiration_date	query	DateFilterEnum	false	Promotions active or expired matching date filter. Available filters are [eq, lt, lte, gt, gte]. Format according to ISO 8601

Request example

1
2
3
4
5



curl -X GET https://subscriptions.masstack.com/v2/orgs/yoigo/subscriptions/ce2f20cb-35df-4ffe-bca6-c0ed0c28cb39/promotions?offset='0'&limit='50'&activation_date='2023-01-05T03:30:15Z'&expiration_date='2023-01-05T03:30:15Z' \
  -H "Accept: application/json" \
  -H "Authorization: Bearer {access-token}"

Responses

Code	Meaning	Description	Schema
200	OK	Promotions found for the subscription	PromotionsSet
403	Forbidden	Forbidden access	ErrorResponse
404	Not Found	A subscription with the specified id was not found	ErrorResponse
500	Internal Server Error	Internal server error	ErrorResponse
default	Default	Any client or server error	ErrorResponse

Get subscription promotion

Get info for a specific promotion of subscription

GET /orgs/{org}/subscriptions/{id}/promotions/{promotionId}

Parameters

Name	In	Type	Required	Description
org	path	string	true	Organization name
id	path	string	true	Subscription unique identifier
promotionId	path	string	true	Promotion unique identifier

Request example

1
2
3
4
5



curl -X GET https://subscriptions.masstack.com/v2/orgs/yoigo/subscriptions/ce2f20cb-35df-4ffe-bca6-c0ed0c28cb39/promotions/abcf20cb-35df-4ffe-bca6-c0ed0c28cabc \
  -H "Accept: application/json" \
  -H "Authorization: Bearer {access-token}"

Responses

Code	Meaning	Description	Schema
200	OK	Promotion found for the subscription	Promotion
403	Forbidden	Forbidden access	ErrorResponse
404	Not Found	A promotion with the specified id was not found	ErrorResponse
500	Internal Server Error	Internal server error	ErrorResponse
default	Default	Any client or server error	ErrorResponse

Update subscription promotion

Update data of a subscription promotion

PATCH /orgs/{org}/subscriptions/{id}/promotions/{promotionId}

Parameters

Name	In	Type	Required	Description
org	path	string	true	Organization name
id	path	string	true	Subscription unique identifier
promotionId	path	string	true	Promotion unique identifier
body	body	OperationsSet	true	Array of operations to apply to subscription promotion

Request body - JsonObject

1
2
3
4
5
6
7
8


[
  {
    "op": "add",
    "path": "/status",
    "value": "DEACTIVATED",
    "reason": "SUBSCRIBER_REQUESTED"
  }
]

Name	Type	Required	Description
anonymous	[Operation]	false	none

Request example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14



curl -X PATCH https://subscriptions.masstack.com/v2/orgs/yoigo/subscriptions/ce2f20cb-35df-4ffe-bca6-c0ed0c28cb39/promotions/abcf20cb-35df-4ffe-bca6-c0ed0c28cabc \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer {access-token}" \
 --data-raw "[
  {
    'op': 'add',
    'path': '/status',
    'value': 'DEACTIVATED',
    'reason': 'SUBSCRIBER_REQUESTED'
  }
]" 

Responses

Code	Meaning	Description	Schema
200	OK	OK	Promotion
400	Bad Request	Bad request	ErrorResponse
403	Forbidden	Forbidden access	ErrorResponse
404	Not Found	A promotion with the specified id was not found	ErrorResponse
500	Internal Server Error	Internal server error	ErrorResponse
default	Default	Any client or server error	ErrorResponse