Support

Contact Recurring Payments Team

Peter Wilmenius

Vice President Sales
Phone: +46 739 444 438
Email: peter.wilmenius@riverty.com

Breaking Changes

Dec 11, 2023 - Discount feature v2

Discount Feature v2, provides merchants the functionality to create custom discount types and periods. This feature allows merchants the ability to match Riverty’s Recurring Product to a large variety of different discount scenarios, which can help Merchants increase customer retention.

The changes in the API include:

  • The deprecation of the periodAmount object in the Discount resources
  • periodAmount.grossAmount is no longer used to determine discount. Instead, we have introduced a durationobject and additional fields such as type, value and startin the payload.

Is my service affected by this update?

Your service is not impacted unless you are using the discount feature. In this case, some fields will be deprecated, and new fields will be introduced due to recent changes in the Discount API resource. Please note, your existing discount data will be migrated to be consistent with our new discount approach.

What is the deadline for the change?

The API resource of the Discount will be changed on 11 December 2023, existing discount programs will continue to run as long as the below instructions are followed.

What do I need to do?

Please make sure your service is compliant with deprecated and newly introduced objects as shown below.

API Resource: /v1/clients/{clientId}/subscriptions/{subscriptionId}/discounts/{discountId}

Current Request Payload

{
  "description": "Discount due to promotion code",
  "numberOfPeriods": 2,
  "periodAmount": {
    "grossAmount": 62.5,
    "vatPercentage": 25
  },
  "metadata": [
    {
      "key": "order-id",
      "value": "a9ee9996-e941-4aa8-90b9"
    }
  ]
}

New Request Payload

{
	"description": "12.5% off discount",
	"type": "PERCENTAGE",
	"value": 12.5,
	"start": "2023-09-10",
	"duration": {
		"type": "REPEATING",
		"count": 5
	},
	"metadata": [
    {
      "key": "order-id",
      "value": "a9ee9996-e941-4aa8-90b9"
    }
  ]
}

New Response Payload

{
	"id": "discount-1",
	"description": "12.5% off discount",
	"type": "PERCENTAGE",
	"value": 12.5,
	"start": "2023-09-10",
	"duration": {
		"type": "REPEATING",
		"count": 5
	},
	"metadata": [{ "key": "order-id", "value": "a9ee9996-e941-4aa8-90b9"}],
	"createdAt": "2022-09-01T07:29:04.407Z",
	"status": "ACTIVE"
}

Please Note:

  • Merchants can specify the discount amount that should be allocated to each subscription period.
  • You cannot allow a discount amount greater than the subscription amount and discounts cannot be applied during the trial period.
  • The Type affects how the discount is shown in the Value field. If Typeis specified as PERCENTAGE, the reduced price is expressed as a percentage in the field. If Typeis AMOUNT, then the reduced price is expressed as a currency amount in the Valuefield.
  • If the Duration.Type is set to REPEATING, then you should provide a value in Duration.Count
    • Once: Represents that the discount is applied only once.
    • Repeating: Represents that the discount is applied repeatedly for a specified number of counts.
    • Always: Represents that the discount is applied continuously.

Request parameters

The details of the parameters in the discount request payload are as follows:

Input name Type Description
Description string Specifies the description of the discount
Type string Indicates whether a discount by a fixed amount or by a percentage. Valid values are: AMOUNT, PERCENTAGE
Value decimal(18,4) Indicates how much the subscription will be discounted
Start date Indicates the date that the discount was applied or started
Duration.Type string Indicates how long the discount will be applied Valid values are: ONCE, REPEATING, ALWAYS
Duration.Count short Specifies the discount duration if type REPEATING is selected
Metadata string Specifies metadata for which custom values can be used
Apr 10, 2023 - Product itemization

Product Itemization allows merchants to differentiate different fees within their subscription invoices. The functionality means that consumers will be able to distinguish the product/service price from other costs on their invoices, such as shipping or equipment. This invoicing flexibility increases transparancy between the merchant and consumers by allowing consumers to recieve a clearer understanding of what they are paying for.

The changes in the API include:

  • The deprecation of Period.Price object in the Subscription Product resources. Price objects will no longer be used to determine product price.
  • Introduction of an Items object with price and additional fields in the root level of the payload (as an Array) that will be used for itemization.

Is my product or service affected by this?

Your service is impacted by this change as this is deprecating one object and introducing a new one in the Subscription Product API resource. However, your existing product data will be migrated to be consistent with our new itemization approach. This means your past products will contain only one item that will reflect the actual product/service price in the new system.

What is the deadline for the change?

The API resource of the Subscription product will be changed on 10 April 2023.

After 10 April 2023, your existing services will continue to run as we will migrated your existing product data. However, if you decided to add additional item offerings in the future, you may need to reconfigure your subscription products to fulfill the itemization requirements below.

What do I need to do?

Please make sure your service is compliant with deprecated and newly introduced objects as shown below.

API Resource: /v1/clients/{clientId}/subscription-products/{subscriptionProductId}

Sample Request

{
   "id": "subscription-product-id-1",
   "period": {
      "type": "MONTH",
      "start": {
         "type": "ACTIVATION"
      }
   },
   "items": [
      {
         "name": "Internet 100M / 25M, monthly fee",
         "description": "Home internet services",
         "price": {
            "grossAmount": 27,
            "vatPercentage": 20
         },
         "metadata": [
            {
               "key": "order-id",
               "value": "a9ee9996-e941-4aa8-90b9-4b047c4afe87"
            }
         ]
      },
      {
         "name": "Router Technicolor DGA4330, monthly fee",
         "description": "Equipment rent",
         "price": {
            "grossAmount": 2.99,
            "vatPercentage": 20
         },
         "isRefundable": false
      }
   ]
}

Please Note:

  • With itemization, each item will reflect as an invoice line. The first item will be represented in the first line, and so on. thereby creating a consistent sequence.
  • Item's name and description fields will now appear in the invoice lines.
  • By default, the item will be refundable
  • If Period.Start.Type is FIXED, then the itemization object expects to specify an additional field (PartialPeriodAmountCalculation) to support partial periodization per item. (See payload example below). By default, the item amount will be calculated partially, in other words, based on used days
    • Partial: Represents the calculation of the amount will be based on the days used
    • Full: Represents the calculation of the amount will be based on the specified gross amount
    • Ignore: Represents the calculation of the amount that will be ignored. (i.e. zero amount)

Response Payload

{
   "id": "subscription-product-id-1",
   "period": {
      "type": "MONTH",
      "start": {
         "type": "FIXED",
         "day": 10,
         "month": null
      }
   },
   "items": [
      {
         "name": "Internet 100M / 25M, monthly fee",
         "description": "Home internet services",
         "price": {
            "grossAmount": 27,
            "vatPercentage": 20
         },
         "partialPeriodAmountCalculation": "Partial"
      },
      {
         "name": "Router Technicolor DGA4330, monthly fee",
         "description": "Equipment rent",
         "price": {
            "grossAmount": 2.99,
            "vatPercentage": 20
         },
         "isRefundable": false,
         "partialPeriodAmountCalculation": "Full"
      }
   ]
}

Request parameters

The details of the parameters in the Items array are as follows:

Input Name Type Description
Name String Specifies the name of the product item
Description String Specifies the description of the product item
Price.GrossAmount decimal(18,4) Specifies the gross amount of the product item
Price.VatPercentage decimal(18,4) Specifies the VAT percentage of the product item
Metadata String Specifies metadata for which custom values can be used
IsRefundable boolean Specifies whether the item can be refund. Default: true
PartialPeriodAmountCalculation String Specifies the type of amount calculation in case of partial periodization. Default: PARTIAL Only applicable for fixed period start type. Valid values are: PARTIAL, FULL, IGNORE