Promotions

Add subscription promotion

Add a new promotion to an existing subscription

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

Parameters

Name	In	Type	Required	Description
org	path	string	true	Organization name
subscriptionId	path	string(uuid)	true	Subscription unique identifier
x-auth-origin-sub	header	string	false	‘none’
x-auth-origin-aud	header	string	false	‘none’
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
26


{
  "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": "ACTIVE",
  "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",
  "origin": "EXISTING_CLIENT"
}

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	PromotionStatus	true	none
activation_date	string(date-time)	false	Activation date and time the promotion is or will be available in the subscription. When provided, it is restricted to be between current billing cycle and less than a year from now. Format according to ISO 8601
expiration_date	string(date-time)	false	The date and time when the promotion expires. Format according to ISO 8601.
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
origin	string	false	Promotion process origin. If not provided, it will be set to EXISTING_CLIENT by default

Property	Values
origin	one of [MIGRATION, EXISTING_CLIENT, UNKNOWN]

Request example

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



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 "x-auth-origin-sub: string" \
  -H "x-auth-origin-aud: string" \
  -H "Authorization: Bearer {access-token}" \
 --data-raw "{
  'catalogue_promotion_id': '124',
  'activation_date': '2023-01-01T00:00:00Z',
  'origin': 'EXISTING_CLIENT'
}" 

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/{subscriptionId}/promotions

Parameters

Name	In	Type	Required	Description
org	path	string	true	Organization name
subscriptionId	path	string(uuid)	true	Subscription unique identifier
offset	query	integer	false	Pagination offset
limit	query	integer	false	Pagination limit
activation_date	query	DateFilterEnum	false	Resource activation date filter. Available filters are [eq, lt, lte, gt, gte]. Format according to ISO 8601
expiration_date	query	DateFilterEnum	false	Resource expiration date filter. Available filters are [eq, lt, lte, gt, gte]. Format according to ISO 8601
status	query	PromotionStatusFilterEnum	false	Subscription status filter

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'&status={"eq":"ACTIVE","in":["ACTIVE"]} \
  -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/{subscriptionId}/promotions/{promotionId}

Parameters

Name	In	Type	Required	Description
org	path	string	true	Organization name
subscriptionId	path	string(uuid)	true	Subscription unique identifier
promotionId	path	string(uuid)	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/27cdbb91-e380-4f83-a45f-94bf67400342 \
  -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/{subscriptionId}/promotions/{promotionId}

Parameters

Name	In	Type	Required	Description
org	path	string	true	Organization name
subscriptionId	path	string(uuid)	true	Subscription unique identifier
promotionId	path	string(uuid)	true	Promotion unique identifier
x-auth-origin-sub	header	string	false	‘none’
x-auth-origin-aud	header	string	false	‘none’
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
15
16



curl -X PATCH https://subscriptions.masstack.com/v2/orgs/yoigo/subscriptions/ce2f20cb-35df-4ffe-bca6-c0ed0c28cb39/promotions/27cdbb91-e380-4f83-a45f-94bf67400342 \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "x-auth-origin-sub: string" \
  -H "x-auth-origin-aud: string" \
  -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

Deactivate a subscription promotion

Deactivate a subscription existing promotion

POST /orgs/{org}/subscriptions/{subscriptionId}/promotions/{promotionId}/deactivate

Parameters

Name	In	Type	Required	Description
org	path	string	true	Organization name
subscriptionId	path	string(uuid)	true	Subscription unique identifier
promotionId	path	string(uuid)	true	Promotion unique identifier
x-auth-origin-sub	header	string	false	‘none’
x-auth-origin-aud	header	string	false	‘none’
body	body	PromotionTerminationRequest	true	Promotion deactivation reason

Request body - instance of PromotionTerminationRequest

1
2
3


{
  "reason": "SUBSCRIPTION_DEACTIVATION"
}

Name	Type	Required	Description
reason	string	true	Reason for the cancellation/deactivation

Property	Values
reason	one of [AUTOMATICALLY_REMOVED, MANUALLY_REMOVED, OTHER, PROMOTION_INCOMPATIBILITY, SUBSCRIPTION_DEACTIVATION]

Request example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11



curl -X POST https://subscriptions.masstack.com/v2/orgs/yoigo/subscriptions/ce2f20cb-35df-4ffe-bca6-c0ed0c28cb39/promotions/27cdbb91-e380-4f83-a45f-94bf67400342/deactivate \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "x-auth-origin-sub: string" \
  -H "x-auth-origin-aud: string" \
  -H "Authorization: Bearer {access-token}" \
 --data-raw "{
  'reason': 'SUBSCRIPTION_DEACTIVATION'
}" 

Responses

Code	Meaning	Description	Schema
202	Accepted	Deactivation process started	None
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

Cancel a subscription promotion

Cancel a subscription existing promotion that is not already active

POST /orgs/{org}/subscriptions/{subscriptionId}/promotions/{promotionId}/cancel

Parameters

Name	In	Type	Required	Description
org	path	string	true	Organization name
subscriptionId	path	string(uuid)	true	Subscription unique identifier
promotionId	path	string(uuid)	true	Promotion unique identifier
x-auth-origin-sub	header	string	false	‘none’
x-auth-origin-aud	header	string	false	‘none’
body	body	PromotionTerminationRequest	true	Promotion cancellation reason

Request body - instance of PromotionTerminationRequest

1
2
3


{
  "reason": "SUBSCRIPTION_DEACTIVATION"
}

Name	Type	Required	Description
reason	string	true	Reason for the cancellation/deactivation

Property	Values
reason	one of [AUTOMATICALLY_REMOVED, MANUALLY_REMOVED, OTHER, PROMOTION_INCOMPATIBILITY, SUBSCRIPTION_DEACTIVATION]

Request example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11



curl -X POST https://subscriptions.masstack.com/v2/orgs/yoigo/subscriptions/ce2f20cb-35df-4ffe-bca6-c0ed0c28cb39/promotions/27cdbb91-e380-4f83-a45f-94bf67400342/cancel \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "x-auth-origin-sub: string" \
  -H "x-auth-origin-aud: string" \
  -H "Authorization: Bearer {access-token}" \
 --data-raw "{
  'reason': 'SUBSCRIPTION_DEACTIVATION'
}" 

Responses

Code	Meaning	Description	Schema
202	Accepted	Cancellation process started	None
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