Introduction

Welcome to the Subscribe API documentation! This guide is intended to assist developers, system administrators, and API integration stakeholders to understand, mitigate, and effectively adapt to the breaking changes in application programming interfaces (APIs). Breaking changes are modifications that can interrupt the normal functioning of dependent systems, causing compatibility issues.

This guide explains how to migrate from the older to the newer APIs that have been listed below.

This section outlines the process to be followed in order to migrate from the old Billing API endpoints to the new Payment API endpoints within the Payment, EZPay, Update EZPay Info, and Restart flows. Additionally, the "Create Payment Method" and "Get Payment Method By ID" endpoints of the Billing API have been refactored. This section also shows a comparison of the old and new APIs.

The endpoints covered in this section are as listed below:

1. Apply Payment

2. EZPay Sign Up

Introduction

This endpoint retrieves the user's information from both the integration service and the subscribe registration based on the input parameter Token (access token generated in the consumer application).

This section outlines the process to be followed in order to migrate from the Entitlements endpoints to the new EntitlementsOrchestrator API endpoints. This section also shows a comparison of the old and new APIs.

The endpoints covered in this section are as listed below:

• Access

Introduction

This section outlines the process to be followed in order to migrate from the old UserAPI endpoints to the new UsersOrchestratorAPI endpoints. This section also shows a comparison of the old and new APIs.

The endpoints covered in this section are as listed below:

User States

The UserOrchestrator API also includes the registration status in the API response.

1. The GET /Users and GET /Users/id endpoints will include the output parameter, State, which returns the status of a registration.

   • The registration's status will be returned as follows:

     • If the tenant has been associated with a third-party authentication system such as Auth0, Firefly, etc., the State will be returned as

Introduction

This endpoint handles the workflow orchestration between the integration services (such as Auth0, Gigya, SSOR, and Firefly) and Subscribe Registration API to send or resend a Verification Code by email so that users can click on the verification link provided in the email in order to start using their new registration.

Comparison

Note:

1. The old model is in PascalCase, while the new model is in CamelCase.

2. The UsersOrchestrator API only returns CRID and EncryptedCRID and does not return cookie tokens.

Send Verification Code

POST /v4/Users/VerificationCode

This endpoint is used to verify the email of a user based on the provided Email and Verification Code.

Note: The parameters marked with an asterisk (*) are mandatory and must be included in the input model.

Headers

Request Body

Events

Note:– The associated Event IDs for the Event Type Codes are specified in parentheses (i.e., EventTypeCode (EventID)) in the table below.

Introduction

This endpoint handles the workflow orchestration between the integration services (such as Auth0, Gigya, SSOR, and Firefly) and Subscribe Registration API to verify the email of a user based on the provided Email and Verification Code.

Introduction

This endpoint handles the workflow orchestration between the integration services (such as Auth0, Gigya, SSOR, and Firefly) and Subscribe Registration API to update the password of a user based on the provided CustomerRegistrationId.

Introduction

This endpoint is used to retrieve the payment method information from the Naviga System based on the provided input parameter, PaymentMethodId.

Introduction

This endpoint handles the workflow orchestration between the integration services (such as Auth0, Gigya, SSOR, and Firefly) and Subscribe Registration API to update the email of a user based on the provided CustomerRegistrationId.

Comparison

Note: The old model is in PascalCase, while the new model is in CamelCase.

Update Email

PATCH /v4/Users/{CustomerRegistrationId}/Email

This endpoint is used to update the email of a user.

Note: The parameters marked with an asterisk (*) are mandatory and must be included in the input model.

Path Parameters

Headers

Request Body

Events

Note:– The associated Event IDs for the Event Type Codes are specified in parentheses (i.e., EventTypeCode (EventID)) in the table below.

Introduction

This endpoint retrieves the user's information from both the integration service and the subscribe registration based on the input parameter Encrypted Customer Registration ID.

With the input parameter Encrypted CRID, the API gets the user's information from both the integration service and the subscribe registration. The response displays the combined information.

Comparison

Note: The old model is in PascalCase, while the new model is in CamelCase.

Get By Encrypted ID

GET /v4/Users?encryptedCustomerRegistrationId={encryptedCustomerRegistrationId}

This endpoint is used to gets the user's information from both the integration service and the subscribe registration based on the Encrypted Customer Registration ID.

Note: The parameters marked with an asterisk (*) are mandatory and must be included in the input model.

Query Parameters

Headers

Events

Note:– The associated Event IDs for the Event Type Codes are specified in parentheses (i.e., EventTypeCode (EventID)) in the table below.

Introduction

This endpoint handles the workflow orchestration between the integration services (such as Auth0, Gigya, SSOR, and Firefly) and Subscribe Registration API.

With the input parameter Customer Registration ID (CRID), the API gets the user's information from both the integration service and the subscribe registration. The response displays the combined information.

Based on the value of Flow.UserProvider and the IgnoreProvider input parameter, the API gives user information in the following way:

1. If no valid value is provided in Flow.UserProvider, the API retrieves user information from the Subscribe Registration API.

2. If a valid value is provided in Flow.UserProvider and the input parameter IgnoreProvider is set to True, the API retrieves user information from the Subscribe Registration API.

3. If a valid value is provided in Flow.UserProvider and the input parameter IgnoreProvider is set to False, the user's details are retrieved from both the integration service and the subscribe registration. The combined information is displayed in the response.

Comparison

Parameters

• The parameter, Type, has been deprecated.

• A new parameter, IgnoreProvider, has been added.

Note: The old model is in PascalCase, while the new model is in CamelCase.

Get User by Id

GET /v4/Users/{customerRegistrationId}/?ignoreProvider={boolean}

This endpoint is used to gets the user's information from both the integration service and the subscribe registration based on the CustomerRegistrationId.

Note: The parameters marked with an asterisk (*) are mandatory and must be included in the input model.

Path Parameters

Query Parameters

Headers

Events

Note:– The associated Event IDs for the Event Type Codes are specified in parentheses (i.e., EventTypeCode (EventID)) in the table below.

Introduction

This endpoint handles the workflow orchestration between the integration services (such as Auth0, Gigya, SSOR, and Firefly) and Subscribe Registration API to update a user based on the provided CustomerRegistrationId.

Comparison

Note:

1. The old model is in PascalCase, while the new model is in CamelCase.

2. Cookie tokens will not be returned by the UsersOrchestrator API.

3. For custom fields, use Metadata.

Update User

PUT /v4/Users/{customerRegistrationId}/

This endpoint is used to update a user.

Note: The parameters marked with an asterisk (*) are mandatory and must be included in the input model.

Path Parameters

Headers

Request Body

Events

Note:– The associated Event IDs for the Event Type Codes are specified in parentheses (i.e., EventTypeCode (EventID)) in the table below.

Introduction

This endpoint handles the workflow orchestration between the integration services (such as Auth0, Gigya, SSOR, and Firefly) and Subscribe Registration API to authenticate a user.

Comparison

Note:

1. The old model is in PascalCase, while the new model is in CamelCase.

2. Cookie tokens will not be returned by the UsersOrchestrator API.

3. For custom fields, use Metadata.

Authenticate

POST /v4/Users/Authentication

This endpoint is used to authenticate a user.

Note: The parameters marked with an asterisk (*) are mandatory and must be included in the input model.

Headers

Request Body

Events

Note:– The associated Event IDs for the Event Type Codes are specified in parentheses (i.e., EventTypeCode (EventID)) in the table below.

Introduction

This endpoint is used to update the payment method for a recurring payment (EZPay) in Circulation Systems (NCS Circ, CircPro, and Matrix) and assign it to a subscription in Naviga System

Introduction

This endpoint is used to create a new payment method for a Subscriber using either a Credit Card or a Bank Account and to create a new record in the PaymentMethod table in the database.

Comparison

Compared to the older model, the new input model requires just a few parameters, as explained in detail below.

Create Payment Method

POST /Billing/PaymentMethods

This endpoint is used to create a new payment method for a Subscriber using either a Credit Card or a Bank Account and to create a new record in the PaymentMethod table in the database.

Note: The parameters marked with an asterisk (*) are mandatory and must be included in the input model.

Headers

Request Body

Introduction

This endpoint handles the workflow orchestration between the integration services (such as Auth0, Gigya, SSOR, and Firefly) and Subscribe Registration API to create a user.

Comparison

Note:

1. The old model is in PascalCase, while the new model is in CamelCase.

2. Cookie tokens will not be returned by the UsersOrchestrator API.

3. For custom fields, use Metadata.

Create User

POST /v4/Users

This endpoint is used to create a user.

Note: The parameters marked with an asterisk (*) are mandatory and must be included in the input model.

Headers

Request Body

Events

Note:– The associated Event IDs for the Event Type Codes are specified in parentheses (i.e., EventTypeCode (EventID)) in the table below.

Introduction

This endpoint handles the workflow orchestration between the integration services (such as Auth0, Gigya, SSOR, and Firefly) and Subscribe Registration API to create a user.

Comparison

When creating a passwordless user, UsersOrchestrator will generate a dummy password and the proper Change Password URL.

Note:

1. The old model is in PascalCase, while the new model is in CamelCase.

2. Cookie tokens will not be returned by the UsersOrchestrator API.

3. For custom fields, use Metadata.

Create Passwordless User

POST /v4/Users

This endpoint is used to create a user without a password.

Note: The parameters marked with an asterisk (*) are mandatory and must be included in the input model.

Headers

Request Body

Events

Note:– The associated Event IDs for the Event Type Codes are specified in parentheses (i.e., EventTypeCode (EventID)) in the table below.

Introduction

This endpoint handles the workflow orchestration between the integration services (such as Auth0, Gigya, SSOR, and Firefly) and Subscribe Registration API.

With the input parameter Email (Subscriber’s email), the API gets the user's information from both the integration service and the subscribe registration. The response displays the combined information.

Based on the value of Flow.UserProvider and the IgnoreProvider input parameter, the API gives user information in the following way:

1. If no valid value is provided in Flow.UserProvider, the API retrieves user information from the Subscribe Registration API.

2. If a valid value is provided in Flow.UserProvider and the input parameter IgnoreProvider is set to True, the API retrieves user information from the Subscribe Registration API.

3. If a valid value is provided in Flow.UserProvider and the input parameter IgnoreProvider is set to False, the user's details are retrieved from both the integration service and the subscribe registration. The combined information is displayed in the response.

Comparison

Parameters

• The parameter, Type, has been deprecated.

• A new parameter, IgnoreProvider, has been added.

Note: The old model is in PascalCase, while the new model is in CamelCase.

Get By Email

GET /v4/Users?email={email}&ignoreProvider={boolean}

This endpoint is used to gets the user's information from both the integration service and the subscribe registration based on the Email.

Note: The parameters marked with an asterisk (*) are mandatory and must be included in the input model.

Query Parameters

Headers

Events

Note:– The associated Event IDs for the Event Type Codes are specified in parentheses (i.e., EventTypeCode (EventID)) in the table below.

Introduction

This endpoint handles the workflow orchestration between the integration services (such as Auth0, Gigya, SSOR, and Firefly) and Subscribe Registration API.

With the input parameter Encrypted Email (Subscriber’s encrypted email), the API gets the user's information from both the integration service and the subscribe registration. The response displays the combined information.

Comparison

Note: The old model is in PascalCase, while the new model is in CamelCase.

Get By Encrypted Email

GET /v4/Users?email={email}&ignoreProvider={boolean}

This endpoint is used to gets the user's information from both the integration service and the subscribe registration based on the Encrypted Email.

Note: The parameters marked with an asterisk (*) are mandatory and must be included in the input model.

Query Parameters

Headers

Events

Note:– The associated Event IDs for the Event Type Codes are specified in parentheses (i.e., EventTypeCode (EventID)) in the table below.

Introduction

This endpoint handles the workflow orchestration between the integration services (such as Auth0, Gigya, SSOR, and Firefly) and Subscribe Registration API to retrieve the user's information based on the provided Query String parameters.

Based on the value of Flow.UserProvider and the IgnoreProvider input parameter, the API gives user information in the following way:

Digital Access

Introduction

This endpoint is used to create Digital Access for the User based on the provided EntitlementCode and CustomerRegistrationId and create an Access Log record in the database.