# Guide to Smart Subscriptions for Merchants source: https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/tutorials-and-guides/subscription-control-guide/index.md The [Merchant Actions endpoint](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/api-reference/index.md#apis) for the Merchant Transaction API allows merchants to communicate directly with consumers and instantly process subscription-related requests initiated within the banking channel. Through this endpoint, you can assist cardholders who are requesting modifications to their subscriptions. This approach is designed to prioritize and preserve your voice as a merchant. The Merchant Actions endpoint creates a more real time conversational-based approach that lets you potentially save a customer from canceling their subscription. Through this endpoint, you can let cardholders request modifications to their subscriptions by providing various actions, including cancel with retention offers, change plan, pause, and resume. This can decrease disputes and chargebacks while increasing customer retention. ### Sending a retention offer in the response {#sending-a-retention-offer-in-the-response} The following diagram shows a process flow for presenting a cardholder with a retention offer when they make a request to cancel a subscription. In most cases, the cardholder will provide information about their subscription and submit that to you, the merchant. You find the cardholder and check to see what options are available to them, such as whether they're eligible for a retention offer. You send back the available retention offer, and the cardholder makes their selection. You then modify the subscription. ![Flow for presenting offer to cardholder](https://static.developer.mastercard.com/content/ethoca-consumer-clarity-for-merchants/documentation/img/cancel-offer-flow.png) ```json { "offer": { "createdDate": "2019-10-12T07:20:50.52Z", "offerId": "53519dbe-7051-4739-9f93-d4f0a69ab294", "name": "30% Discount offer", "type": "DISCOUNT", "offerPeriod": { "unit": "MONTHS", "period": 3 }, "discount": { "type": "PERCENTAGE", "amount": "20", "currencyCode": "USD" }, "terms": [ { "header": "Terms of Conditions", "terms": "Detailed description of terms and condition" } ], "additionalServices": [ "string" ], }, "subscriptionChanges": { "contractType": "FIXED", "contractFrequency": "QUARTERLY", "paymentsRemaining": 20, "nextBillingDate": "2022-02-02", "nextBillingAmount": "50.00", } } ``` To submit a retention offer to a cardholder, the following information is required or conditional. The action engine validates the data. Failure to disclose the required information can result in an automatic decline of the retention offer and a request to complete the cancellation. #### Required data {#required-data} This section shows the specific Merchant Action endpoint objects and associated field IDs that are used. Without this data, the Merchant Transaction API might not present a retention offer to a cardholder, and you will be asked to complete the cancellation. These fields are required for a retention offer to be presented to a cardholder: | Name | Type | Description | minLength | maxLength | |--------------------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|-----------| | createdDate | string | The date and time the retention offer was created (e.g. 2021-06-18T17:11:05.000Z). | n/a | n/a | | offerId | string | The merchant's unique ID for the retention offer. | 10 | 50 | | type | string | The type of retention offer being sent to the cardholder. Allowed values are `DISCOUNT`, `ENTITLEMENT`, and `PAUSE`. | 0 | 50 | | name | string | The name of the retention offer the merchant wants to present to the cardholder. | 1 | 50 | | offerPeriod:unit | string | Unit of time. Allowed values are `DAYS`, `WEEKS`, `MONTHS`, `QUARTERS`, `YEARS`, and `PERPETUAL`. | 0 | 15 | | offerPeriod:period | integer | The amount of time. | 0 | 10000 | | terms | array | Defines the contractual terms of the retention offer, structured as an array containing two attributes: an optional header for summarizing key points, and a required body for the detailed terms. | n/a | n/a | | nextBillingAmount | string | Issuers and the Merchant Action Engine don't do the math for a merchant. 1. Merchants must enter the amount the cardholder will pay with the retention offer applied. 2. Specify the exact amount the cardholder will pay on their next billing invoice, factoring in any applicable discounts without taxes. If there is no payment due, enter 0.00. | 1 | 12 | | nextBillingDate | string | Indicates the date of the cardholder's next billing event, including any adjustments resulting from an accepted retention offer. | n/a | n/a | | contractType | string | Indicates the contract type (fixed-term or cancel-anytime) that the cardholder agrees to. Allowed values are `FLEXIBLE` and `FIXED`. | 1 | 15 | #### Conditional fields {#conditional-fields} If the `contractType` is **FIXED** and would create a new contract that the cardholder would be unable to cancel before a certain number of payments, the following fields are additionally required based on the specified conditions: | Name | Type | Description | minLength | maxLength | |-----------------------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|-----------| | contractFrequency | string | Indicates how often the cardholder is billed. Allowed values are `DAILY`, `WEEKLY`, `MONTHLY`, `QUARTERLY`, and `YEARLY`. | 1 | 15 | | paymentsRemaining | integer | Indicates the number of remaining payments on a fixed contract before it expires or renews. | 1 | 10000 | | discount:type | string | Indicates whether the discount is a fixed amount (for example, $10 off) or a percentage (for example, 10% off). Allowed values are `PERCENTAGE` and `FIXED`. | 10 | 50 | | discount:amount | string | The value of the discount. Decimal point period expected to denote separation of the fractional suffix from the rest of the amount, if applicable for the currency. Decimal point period must not be the first character. | 1 | 12 | | discount:currencyCode | string | Alphabetic currency code associated with value in ISO 4217 format. | 3 | 3 | | additionalServices | array | For Entitlement type retention offers, merchants can add product IDs or product names to this array of strings. | n/a | n/a | Following are the specific situations that govern the conditions that apply to the conditional fields: | Name | Condition | |---------------------|---------------------------------------------------------------------------------------------------------------------------------------| | Contract Frequency | If the contract type = `FIXED`, this field is required. | | Payments Remaining | If the contract type = `FIXED`, this field is required. | | Discount Type | If retention offer type = `DISCOUNT`, the entire discount object is required. | | Discount Amount | If retention offer type = `DISCOUNT`, the entire discount object is required. | | Discount Currency | If retention offer type = `DISCOUNT`, the entire discount object is required. | | Additional Services | If the retention offer type is an entitlement type retention offer, the `additionalServices` field is recommended but still optional. | ## Next Steps {#next-steps} * Review the [Guide to API Fields for the Merchant Transaction API](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/tutorials-and-guides/api-fields-guide/index.md) to learn more about specific Merchant Transaction API objects and associated field IDs that are used by the service to generate a digital receipt. * Run through the [Merchant API Data Dictionary](https://static.developer.mastercard.com/content/ethoca-consumer-clarity-for-merchants/uploads/merchant-data-dictionary.xlsx) to review a list of all of the fields in the Merchant Transaction API and their specific settings.