With this update, we are transitioning from the previous payload structure to a new format for the Customer Lookup endpoint. We are adding 2 new fields - CustomerNumber and IndividualRiskScore. CustomerNumber can be used to send us a custom customer number from the merchants side. Risk score is used to steer risk for different types of customer.

New Payload:

{
"customerNumber": "TestCustomer67860",
"individualRiskScore": 0,
"lookup": {
    "type": "PhoneNumber",
    "value": "{{ssn}}"
  }
}

Old Payload:

{
    "lookupField": "IdentificationNumber",
    "lookupValue": "string"
}

Optional Fields

• customerNumber
• individualRiskScore

Impacted Endpoint

Customer Lookup

Action Required

To ensure uninterrupted service, please update your integration to accommodate the new payload structure as outlined above before the specified effective date. Failure to do so may result in errors or disruption of service.

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

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