Freezing subscriptions

Introduction

The following describes how freezing subscriptions is supported in the Vimond Platform, how to enable the functionality and how to integrate with it.

📘 The database configuration is handled by Vimond

Please create issue in support portal specifying the details described below.

Configuration

In order to be allowed to freeze a subscription of a certain PRODUCT it needs to be configured in the table METADATA_PRODUCT_GROUP for the given PRODUCT_GROUP. The following configurations are required:

Metadata key	Supported values	Description
FreezeOrder.Enabled	true || false	Freezing a subscription is only supported if it is enabled

//Insert statement for declaring the metadata field FreezeOrder.Enabled in METADATA_DEFINITION
INSERT INTO METADATA_DEFINITION (NAME, TITLE, DESCRIPTION, SORT_ORDER, REQUIRED, SEARCHABLE, VALIDATION, FIELD_TYPE, DATA_TYPE, OPTIONS, ENABLED, HIDDEN, DEFAULT_VALUE, SOLR_FIELD_TYPE, APPLIES_TO, MULTILINGUAL, PROTECTED, DEFAULT_VISIBLE, FILTERABLE) VALUES ('FreezeOrder.Enabled', 'FreezeOrderEnabled', 'Needed for freeze orders', 0.00000, '0', '0', null, 'TEXT', 'STRING', null, '1', '0', '100.0', 'text', 'productgroup', '1', '0', '0', '0');

//Enabling subscription freeze for a certain product group
INSERT INTO METADATA_PRODUCT_GROUP (ID, PRODUCT_GROUP_ID, LANGUAGE, NAME, VALUE, UPDATE_TIME) VALUES (SEQ_METADATA_X.nextval, <product-group-id>, '*', 'FreezeOrder.Enabled', 'true', sysdate);

Optional configurations

In addition there are some configurations that are optional:

Metadata key	Supported values	Description
FreezeOrder.StartDate	Date string in format “dd/MM/yyyy”	Specifies when a subscription can be frozen
FreezeOrder.EndDate	Date string in format “dd/MM/yyyy”	Specifies when a frozen subscription will be unfreezed

//Insert statements for declaring the metadata fields FreezeOrder.StartDate and FreezeOrder.EndDate in METADATA_DEFINITION
INSERT INTO METADATA_DEFINITION (NAME, TITLE, DESCRIPTION, SORT_ORDER, REQUIRED, SEARCHABLE, VALIDATION, FIELD_TYPE, DATA_TYPE, OPTIONS, ENABLED, HIDDEN, DEFAULT_VALUE, SOLR_FIELD_TYPE, APPLIES_TO, MULTILINGUAL, PROTECTED, DEFAULT_VISIBLE, FILTERABLE) VALUES ('FreezeOrder.StartDate', 'FreezeOrderStartDate', 'Needed for freeze orders', 0.00000, '0', '0', null, 'TEXT', 'STRING', null, '1', '0', '100.0', 'text', 'productgroup', '1', '0', '0', '0');

INSERT INTO METADATA_DEFINITION (NAME, TITLE, DESCRIPTION, SORT_ORDER, REQUIRED, SEARCHABLE, VALIDATION, FIELD_TYPE, DATA_TYPE, OPTIONS, ENABLED, HIDDEN, DEFAULT_VALUE, SOLR_FIELD_TYPE, APPLIES_TO, MULTILINGUAL, PROTECTED, DEFAULT_VISIBLE, FILTERABLE) VALUES ('FreezeOrder.EndDate', 'FreezeOrderEndDate', 'Needed for freeze orders', 0.00000, '0', '0', null, 'TEXT', 'STRING', null, '1', '0', '100.0', 'text', 'productgroup', '1', '0', '0', '0');

//Setting the allowed freeze period
INSERT INTO METADATA_PRODUCT_GROUP (ID, PRODUCT_GROUP_ID, LANGUAGE, NAME, VALUE, UPDATE_TIME) VALUES (SEQ_METADATA_X.nextval, <product-group-id>, '*', 'FreezeOrder.StartDate', '31/05/2018', sysdate);

INSERT INTO METADATA_PRODUCT_GROUP (ID, PRODUCT_GROUP_ID, LANGUAGE, NAME, VALUE, UPDATE_TIME) VALUES (SEQ_METADATA_X.nextval, <product-group-id>, '*', 'FreezeOrder.EndDate', '01/08/2018', sysdate);

Logic, rules and integration manual

Checking if a subscription can be freezed: To check the freeze capabilities of an order, the following endpoint can be called:

GET /api/{platform}/order/{orderId}/freeze/capabilities

Response:
<freezeCapability>
  <freezeCapability>Supported || PeriodicallySupported || NotSupported</freezeCapability>
  <freezePeriod> <!-- Only present if both FreezeOrder.StartDate and FreezeOrder.EndDate is configured -->
     <freezeDate>{The date which the subscription will be frozen}</freezeDate>
     <unfreezeDate>{The date which the frozen subscription will be unfreezed}</unfreezeDate>
  </freezePeriod>
</freezeCapability>

The response will be a _freezeCapability _stucture

• freezeCapability will be either Supported, PeriodicallySupported or NotSupported.
• If freezeCapability is PeriodicallySupported, the freezePeriod will contain the following values:
  • freezeDate equal to currentDate (which is the the time where the customer can freeze)
  • unfreezeDate equal to the configured value of metadata FreezeOrder.EndDate.
• If freezeCapability is Supported, this means that the customer can decide when the order should be automatically unfreezed.

In order for freezeCapability=Supported, the following rules apply:

• Order must be ACTIVE
• Order must have autorenewStatus ACTIVE
• Order must have a startDate that has passed
• The paymentProvider which the order is purchased with, must support freezing. iTunes, BlueSnap, tPay and GooglePlay do not support the operation.
• FreezeOrder.Enabled=true must be configured in the table METADATA_PRODUCT_GROUP for the given PRODUCT_GROUP
• FreezeOrder.StartDate and FreezeOrder.EndDate should either not be configured or configured with empty or NULL values

In order for freezeCapability=PeriodicallySupported, the following rules apply:

• Order must be ACTIVE
• Order must have autorenewStatus ACTIVE
  *Order must have a startDate that has passed
• The paymentProvider which the order is purchased with, must support freezing. iTunes, BlueSnap, tPay and GooglePlay do not support the operation.
• FreezeOrder.Enabled=true must be configured in the table METADATA_PRODUCT_GROUP for the given PRODUCT_GROUP
• FreezeOrder.StartDate and FreezeOrder.EndDate must be configured (in the format “dd/MM/yyyy”) in the table METADATA_PRODUCT_GROUP for the given PRODUCT_GROUP
  • FreezeOrder.StartDate must be before currentDate
  • FreezeOrder.EndDate must be after currentDate
  • FreezeOrder.EndDate must be after the endDate of the order.

Freezing a subscription

To freeze a subscription, the following endpoint can be called:

PUT /api/{platform}/order/{orderId}/freeze
Body:
<freezeDates>
  <unfreezeDate>{A Date object specifying when the order should be automatically unfreezed}<unfreezeDate>
</freezeDates>

In order to freeze a subscription, the following rules apply:

• The freezeCapability of the order must be either Supported or PeriodicallySupported.
• If the freezeCapability is PeriodicallySupported, the unfreezeDate will be based on the configured value of metadata FreezeOrder.EndDate. In that case an empty freezeDates-structure should be passed on in the request body.
• If the freezeCapability is Supported, the freezeDates-structure passed on in the request body must contain an unfreezeDate.

If the above mentioned API-call is a success, the frozen order will be returned:

• AutorenewStatus = FROZEN (10)
• Enddate will be set equal to the unfreezeDate provided by either the user or the productGroupMetadata configurations. The timestamp of the endDate is randomized, avoiding a scenario where all frozen orders will have the exact same renew time.
• If earliest enddate is in the future, it will be adjusted according to the adjustment made on the endDate
• StatusText = “Order frozen until {unfreezeDate}”

🚧 When order is frozen, the user will still have access until accessEnddate expires

When an order is frozen, an orderDomainEvent with eventType = FREEZE is sent to kafka.

Unfreezing a subscription before it is automatically unfrozen

To unfreeze a subscription manually, the following endpoint can be called:

PUT /api/{platform}/order/{orderId}/unfreeze

In order to unfreeze a subscription, the following rules apply:

• Order must have autorenewStatus FROZEN
• Order must have status ACTIVE

When an order is manually unfrozen, the following logic is applied:

• If accessEnddate is expired, the new accessEnddate is set to currentDate plus the value of Property api.payment.access.enddate.duration.to.add. If accessEnddate has not passed, it will remain unchanged.
• New endDate is set to the new accessEnddate minus the value of Property api.payment.access.enddate.duration.to.add.
• If earliestEnddate is in the future, the new earliestEnddate is adjusted according to the adjustments made on the endDate
• AutorenewStatus is set to ACTIVE
• StatusText is updated to “Order unfrozen ({unfreezeDate})”

When an order is unfrozen, an orderDomainEvent with eventType = UNFREEZE is sent to kafka.

Unfreezing orders automatically

The query that fetches expired subscriptions for renewal is updated to include orders that have autorenewStatus FROZEN. If the order is frozen, it will be unfreezed before it gets renewed. When unfreezing, the following logic is applied:

• AutorenewStatus is set to ACTIVE
• StatusText is updated to “Order unfrozen ({unfreezeDate})”

When an order is unfrozen, an orderDomainEvent with eventType = UNFREEZE is sent to kafka.