Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
DISCLAIMER
Product Information contained within this document, including technical information and functional specifications, is subject to change without notice. Naviga reserves the right to make any changes to the information in this document at any time without notice. Naviga makes no warranty, representation, or guarantee regarding the suitability of its products and services for any particular purpose.
Note: cancellation of pending address change is only possible from One CSR Portal
Also please pay attention that only one address change can be created for the same date.
This document describes the endpoints required to manage both the billing and delivery address changes a.k.a. Moves.
Call Get Availability endpoint providing subscription id and allowDigitalSubscriptions in true to check if the change address is allowed to the subscriber. If so, it will return the dates to fill the calendar
You will call Get Moves by Subscription to retrieve the pending moves for a subscription to be displayed in a table. In case there is some pending move, you can Update Move or Cancel Move.
Calling Get Subscription By Id you will be able to retrieve Subscriptions data (like Products, Service Types, Addresses). But, you can just call Get Address Information by Subscription to retrieve the addresses.
Get States and Get Locations are useful to populate forms. The first one returns a list of states for a country code. The other, providing a postal code, it will return the city and the state
As said in point before, calling Get Availability endpoint you will get the dates to display the stop calendar. If the flow involves Change Delivery Address, once you select the stop date you will be required to select a resume delivery date. For this, you can use the same resume dates provided with the previous call or you can call it again passing Stop Date as parameter to get the refreshed dates.
To Process a new move, select the proper stop date (and resume date if applicable) and a valid address is required. The same for updating a pending move. To cancel a move, only a confirmation is required.
API needs to receive five header parameters to operate:
X-MediaGroupCode, X-Clientcode, X-PaperCode: Three parameters used by the API to identify the tenant to use
X-SourceSystem: String used to identify who the consumer is
Authorization: JSON web token used for security purposes
GET /Subscriptions/{subscriptionId}
Retrieves a subscription
SubscriptionId*
Integer
Unique identifier of the Subscription in Naviga System.
Authorization*
String
X-SourceSystem*
String
X-MediaGroupCode*
String
X-ClientCode*
String
X-PaperCode*
String
GET /Address/{SubscriptionId}
Retrieves both billing and delivery information for a specific subscription
SubscriptionId*
Integer
Unique identifier of the Subscription in Naviga System
Authorization*
String
X-SourceSystem*
String
X-MediaGroupCode*
String
X-ClientCode*
String
X-PaperCode*
String
GET /Moves?SubscriptionId={subscriptionId}
Retrieves the moves for a subscription
SubscriptionId*
String
Unique identifier of the Subscription in Naviga System
Authorization*
String
X-SourceSystem*
String
X-MediaGroupCode*
String
X-ClientCode*
String
X-PaperCode*
String
GET /Moves/{MoveId}
Retrieves a specific move
MoveId*
Integer
Unique identifier of a move.
Authorization*
String
X-SourceSystem*
String
X-MediaGroupCode*
String
X-ClientCode*
String
X-PaperCode*
String
GET /States/{CountryCode}
Retrieves a list of states for a specific country code
CountryCode*
String
Short code that represents a country.
Authorization*
String
X-SourceSystem*
String
X-MediaGroupCode*
String
X-ClientCode*
String
X-PaperCode*
String
GET /Locations/{ZipCode}
Retrieves City and State for a specific postal code
ZipCode*
String
Represents a postal code
Authorization*
String
X-SourceSystem*
String
X-MediaGroupCode*
String
X-ClientCode*
String
X-PaperCode*
String
GET /TemporaryStops/Subscriptions/[subscriptionId]/Availability?stopDate{stopDate}&allowDigitalSubscriptions=true
Checks and returns the availability to do a move for a subscription. It will provide the dates allowed to change both billing and delivery address. For Change Delivery Address, call this endpoint with stop date
SubscriptionID*
String
Unique identifier of the Subscription in Naviga System
StopDate
Datetime
Represents the date when the delivery to the current address will be stopped. If provided it will retrieve the valid dates to restart the delivery
AllowDigitalSubscriptions*
Boolean
Indicates if the Digital Only subscriptions should be considered when checking the availability. This must be True
Authorization*
String
X-SourceCode*
String
X-MediaGroupCode*
String
X-ClientCode*
String
X-Papercode*
String
POST /Moves
Create a new move for a subscription. It could be for both billing and delivery addresses
Authorization*
String
X-SourceSystem*
String
X-MediaGroupCode*
String
X-ClientCode*
String
X-PaperCode*
String
SubscriptionId*
Integer
Unique identifier of the Subscription in Naviga System
AddressChangeType*
Integer
Represents the type of movement
ValidateAddress*
Boolean
Indicate if address should be validated
StopDate*
Datetime
Date in UTC when the address is no longer valid
ResumeDate
Datetimr
Date in UTC when the delivery should be restarted. Required only for delivery address change
BillingAddress.Address*
String
New billing address
BillingAddress.City*
String
New billing city
BillingAddress.State*
String
New billing state
BillingAddress.PostalCodee*
String
New billing postal code
BillingAddress.FirstName*
String
New billing first name
BillingAddress.LastName*
String
New billing last name
BillingAddress.Phone*
String
New billing address phone
DeliveryAddress.Address*
String
New delivery address
DeliveryAddress.City*
String
New delivery city
DeliveryAddress.State*
String
New delivery state
DeliveryAddress.PostalCodee*
String
New delivery postal code
DeliveryAddress.FirstName*
String
New delivery first name
DeliveryAddress.LastName*
String
New delivery last name
DeliveryAddress.Phone*
String
New delivery phone
PUT /Moves/{Id}
Updates a pending move for a subscription
*
Integer
Unique identifier of a move in Naviga System
X-PaperCode*
String
X-MediaGroupCode*
String
X-SourceSystem*
String
Authorization*
String
X-ClientCode*
String
AddressChangeType*
Integer
Represents type of movement
ValidateAddress*
Boolean
Indicated if the address should be validated
StopDate*
Datetime
Date in UTC when the address is no longer valid
SubscriptionID*
Integer
Unique identifier of the Subscription in Naviga System
BillingAddress.City*
String
New billing city
BillingAddress.Address*
String
New billing address
ResumeDate
Datetime
Date in UTC when the delivery should be restarted. Required for delivery address updates
BillingAddress.State*
String
New billing state
BillingAddress.PostalCode*
String
New billing postal code
BillingAddress.FirstName*
String
New billing first name
BillingAddress.LastName*
String
New billing last name
BillingAddress.Phone*
String
New phone for billing address
DELETE /Moves/{Id}
Deletes a pending move for a subscription. ID is a unique identifier of a move in Naviga System
*
Integer
Unique identifier of a move in Naviga System
Authorization*
String
X-SourceSystem*
String
X-MediaGroupCode*
String
X-ClientCode*
String
X-PaperCode*
String
We use the term “Newstart” to refer to the new Subscriptions created on Naviga Subscribe. In this document, we will review all the necessary steps to perform a Newstart through Subscribe API.
Please note that there is a minimum required release version for certain calls.
The finalizing new start step (Purchase API) is valid from Release 3.15.0 and above. All other APIs are available from 3.14.2.
Step Name
Minimum Release version required
3.14.2
3.14.2
3.14.2
3.14.2
3.14.2
3.15.0
Important: The Test URLs provided are example of the ones used for non-AWS customers. If you are using AWS, please add “aws-“to the beginning of the URLs.
The objective of the Offers Step is to present different options of Subscriptions that the User could purchase. The Offers displayed in this section are driven by Naviga’s Solicitor Concierge Site.
GET /Offers
This endpoint returns offers from Naviga’s Solicitor Concierge. At least, one query string parameter needs to be provided.
Prod: server-clientname-prod.subscriberconcierge.com/Offers
Test: test.subscriberconcierge.com/Offers
smartOfferSegment
String
Reflects the code of the Smart Offer segment.
vendorId
Int
ID of the vendor
couponCode
String
Coupon code (If used)
postalCode
String
Postal Code
newspaperId
Int
Newspaper Id
paperCode
String
Newspaper Code (SubCon)
offerId
Int
ID of the offer in the Solicitor Concierge.
offerGroupId
Int
ID of the offer Group in the Solicitor Concierge.
oneTimeCode
String
One time code applicable to offer.
promotionCode
String
Code of the promotion set up in the Solicitor Concierge.
siteCode
String
Newspaper Code (CMS)
salesTeamId
Int
In Old Solcon this was called Vendor, it’s the company/team that is responsible for selling a specific offer.
offerGroupCode
String
Offer group name without spaces and special characters
teamMemberId
Int
ID of the member member within the Salesteam who will be selling a specific offer.
promotionId
Int
ID of promotion (if used)
sourceSystem
String
Code that identifies the platform that creates the transaction (request).
X-PaperCode*
String
Lowest hierarchy of tenant
X-ClientCode*
String
Middle hierarchy of tenant
X-SourceSystem*
String
Code that identifies the platform that creates the transaction (request).
Authorization*
String
This is a JWT used for authorization. This token is linked to source system and tenant in any of the 3 levels to perform the validation.
X-MediaGroupCode*
String
Highest hierarchy of tenant
A document explaining tenants will be given to each client as this is not generic.
The objective of the Account Step is to make sure the user Registered during the flow. There are 2 important endpoints to consider:
GET /User/{type}?email={email}
This endpoint should be used to lookup up the entered email in Naviga’s Registrations DB. If Registration already exists, avoid calling Create User endpoint.
Prod: server-clientname-prod.subscriberconcierge.com/User/{type}?email={email}
Test: test.subscriberconcierge.com/User/{type}?email={email}
Type*
Int
This defines where the user should be looked up. 1: Auth System
2: Naviga Database
0: Both (recommended)
Authorization*
String
This is a JWT used for authorization. This token is linked to source system and tenant in any of the 3 levels to perform the validation.
X-PaperCode*
String
Lowest hierarchy of tenant
X-ClientCode*
String
Middle hierarchy of tenant
X-MediaGroupCode*
String
Highest hierarchy of tenant
X-SourceSystem*
String
Code that identifies the platform that creates the transaction (request).
POST /User
Once you verified that the entered Email doesn’t exist in Naviga’s Registration DB, use this endpoint to create the Registration.
Prod: server-clientname-prod.subscriberconcierge.com/User
Test: test.subscriberconcierge.com/User
Authorization*
String
This is a JWT used for authorization. This token is linked to source system and tenant in any of the 3 levels to perform the validation.
X-ClientCode *
String
Middle hierarchy of tenant
X-MediaGroupCode *
String
Highest hierarchy of tenant
X-SourceSystem *
String
Code that identifies the platform that creates the transaction (request).
X-PaperCode *
String
Lowest hierarchy of tenant
Email*
String
Email Address
Password*
String
Password
CreationMode*
Number
It defines where the user should be created. 1: Auth System
2: Naviga Database
0: Both (recommended)
CustomerRegistrationId
String
Unique Identifier in the Auth System.
VerifyEmail
Boolean
Default false. If True is provided, then the Registration will not be created right away. Naviga would wait until the User confirms the Registration by clicking the link in the Verification Email. (This only works with MG2Auth).
The objective of the Address Step is to collect the Delivery and Billing Address. Optionally, you could call Subscribe API’s Standardize Address endpoint to make sure the entered Address has the correct format.
GET /Address/Standardization
Call this endpoint to pass the address through Melissa Data validations.
Prod: server-clientname-prod.subscriberconcierge.com/Address/Standardization
Test: test.subscriberconcierge.com/Address/Standardization
Address.address
String
Full address
Address.state
String
State
Address.city
String
City
Address.aptunit
String
Apartment Unit
Address.street
String
Street Name
Address.country
String
Country
Address.postalcode
String
Postal Code
Address.housenumber
String
House Number
Address.streetsuffix
String
Street Suffix
Authorization*
String
This is a JWT used for authorization. This token is linked to source system and tenant in any of the 3 levels to perform the validation.
X-SourceSystem*
String
Code that identifies the platform that creates the transaction (request).
X-ClientCode *
String
Middle hierarchy of tenant
X-MediaGroupCode *
String
Highest hierarchy of tenant
X-PaperCode *
String
Lowest hierarchy of tenant
The main objective of the Billing Step is to collect the User Billing information. In case of Credit Card, the information should be tokenized through the Payment Gateway Front-end integration. To facilitate that work, we recommend using Naviga’s Payment Sessions to initialize the Front-end integration and get the token.
This step is completely optional. In case is used, it’s intended to display a summary of the entered information in addition to the subscription pricing. You could use Naviga’s Calculate Subscription Cost endpoint to get the Subscription price with the proper taxes.
POST /Subscriptions/Cost
This endpoint receives the information of the selected Solicitor Concierge Offer and collected Address information. Based on those parameters, it calculates the final price (base price + taxes). For taxes, we have 2 types of integrations: FastTax and NCS taxes (only for NCS clients).
Prod: server-clientname-prod.subscriberconcierge.com/Subscriptions/Cost
Test: test.subscriberconcierge.com/Subscriptions/Cost
Authorization*
String
This is a JWT used for authorization. This token is linked to source system and tenant in any of the 3 levels to perform the validation.
X-SourceSystem*
String
Code that identifies the platform that creates the transaction (request).
X-MediaGroupCode*
String
Highest hierarchy of tenant
X-ClientCode*
String
Middle hierarchy of tenant
X-PaperCode *
String
Lowest hierarchy of tenant
At this point, the user should have gone through all the steps. So, it’s time to create the Subscription. To do so, integrate with Naviga’s Add Subscription endpoint.
POST /Subscriptions
Prod: server-clientname-prod.subscriberconcierge.com/Subscriptions
Test: test.subscriberconcierge.com/Subscriptions
Authorization*
String
This is a JWT used for authorization. This token is linked to source system and tenant in any of the 3 levels to perform the validation.
X-SourceSystem*
String
Code that identifies the platform that creates the transaction (request).
X-MediaGroupCode *
String
Highest hierarchy of tenant
X-ClientCode*
String
Middle hierarchy of tenant
X-PaperCode*
String
Lowest hierarchy of tenant
{"StartDate":"2021-09-16","ExpirationDate":null, "CustomerRegistrationId":"auth0|612fb718c1a18f007061c58f","EmailAddress":"sun8855t@yopmail.com","OfferId":244,"PromotionCode":null,"OfferGroupId":134,"RecipientInformation":null,"DeliveryAddress":{"FirstName":"Alicia","LastName":"Sanders","Company":"","Address":"123 ABC Cloud Rd","AptNumber":"6","AptUnit":"Apt 6","City":"Phoenix","State":"AZ","ZipCode":"85086","CountryCode":"US","Phone":"6235231462"},"BillingAddress":{"FirstName":"Alicia","LastName":"Sanders","Company":"","Address":"123 ABC Cloud Rd","AptNumber":"6","City":"Phoenix","State":"AZ","ZipCode":"85086","CountryCode":"US","Phone":"6235231462"},"PaymentTypeId":1,"CreditCard":{"Type":"VISA","Number":"q/ABd1FkX29yZt/3So37OB7oduFKG8Ey","NumberFirstTwoDigits":"31","NumberLastFourDigits":"1231","ExpirationMonth":"02","ExpirationYear":"26","SecurityCode":"","OwnerName":"Alicia Sanders"},"BankAccount":null,"PayPalInfo":null,"ActivateEZPay":true,"Amount":{"AmountCharged":0.99,"ActivationFee":0.0,"TaxAmount":0.00,"SubscriptionCost":0.99},"PaymentMethodId":"40882795","CustomerId":"","ValidateAddress":true,"IgnoreExistingSubscriberCheck":false,"UserId":5244,"StartType":"NewStart","Products":[{"ExternalProductId":"100014","MerchantProductId":null,"ProductId":0,"ProductQuantity":1}],"SalesPerson":{"SalesPersonCode":"","VendorId":"0"},"ParentEventId":0,"OfferCode":"","LegacyAccountNumber":null,"PresentationName":"","CouponCode":"","StartReason":"","LocationName":"TEST","LocationId":"1","InitialCredit":{"Amount":0.0,"Currency":null,"Reason":"","Description":""},"EbillEmail":"","ApplePayPayload":null,"GooglePayPayload":null,"SendEmail":null,"Currency":"USD","EBillSignUp":false,"CreateTermsConsentEvent":true,"PianoInfo":null,"ProcessSync":true}
{"CustomerRegistrationId":"auth0|612fb718c1a18f007061c58f","EmailAddress":"sun8855t@yopmail.com","OfferId":2698,"PromotionCode":null,"OfferGroupId":1074,"RecipientInformation":null,"DeliveryAddress":null,"BillingAddress":{"FirstName":"ROSA","LastName":"ROSA","Company":"","Address":"82 Cardinal Way","AptNumber":"12","City":"Santa Rosa","State":"CA","ZipCode":"95409","CountryCode":"US","Phone":"2626266262"},"PaymentTypeId":10,"CreditCard":null,"BankAccount":null,"PayPalInfo":null,"ApplePayInfo":null,"GooglePlayInfo":null,"ActivateEZPay":true,"Amount":{"AmountCharged":0.0,"ActivationFee":0.0,"TaxAmount":0.0,"SubscriptionCost":0.0},"PaymentMethodId":null,"CustomerId":null,"StartDate":"2021-09-01","ExpirationDate":"2022-09-01","ValidateAddress":false,"IgnoreExistingSubscriberCheck":false,"UserId":-1,"StartType":"FreeTrial","Products":[{"ExternalProductId":"100002","MerchantProductId":null,"ProductId":0,"ProductQuantity":1}],"SalesPerson":null,"ParentEventId":null,"OfferCode":null,"LegacyAccountNumber":null,"PresentationName":"Subscriptionmultiproduct DefaultExport","CouponCode":null,"StartReason":"","LocationName":null,"LocationId":null,"InitialCredit":null,"EbillEmail":null,"ApplePayPayload":null,"SendEmail":null,"Currency":"USD","EBillSignUp":false,"CreateTermsConsentEvent":true,"PianoInfo":null,"ProcessSync":true}
{"StartDate":"2021-09-28T00:00:00","ExpirationDate":null,"CustomerRegistrationId":"","EmailAddress":"rvrjugbjbsal@yopmail.com","OfferId":369,"PromotionCode":null,"OfferGroupId":12264,"RecipientInformation":{"FirstName":"kristina","LastName":"krukovskaya","Email":"rvrjugbjbsal@yopmail.com","GiftMessage":"eg"},"DeliveryAddress":null,"BillingAddress":{"FirstName":"John","LastName":"Smith","Company":"","Address":"","AptNumber":"","City":"Burbank","State":"IL","ZipCode":"60459","CountryCode":"US","Phone":""},"PaymentTypeId":2,"CreditCard":null,"BankAccount":{"AccountType":"","InstitutionName":"Bank of America","AccountNumber":"873433","RoutingNumber":"029000053","NumberLastFourDigits":""},"PayPalInfo":null,"ActivateEZPay":true,"Amount":{"AmountCharged":10.98,"ActivationFee":0.99,"TaxAmount":0.0,"SubscriptionCost":9.99},"PaymentMethodId":null,"CustomerId":null,"ValidateAddress":false,"IgnoreExistingSubscriberCheck":false,"UserId":-1,"StartType":"Gift","Products":[{"ExternalProductId":"100024","MerchantProductId":null,"ProductId":0,"ProductQuantity":1},{"ExternalProductId":"100026","MerchantProductId":null,"ProductId":0,"ProductQuantity":1}],"SalesPerson":null,"ParentEventId":null,"OfferCode":null,"LegacyAccountNumber":null,"PresentationName":"PurchaseZipOnly","CouponCode":null,"StartReason":"","LocationName":null,"LocationId":null,"InitialCredit":null,"EbillEmail":null,"ApplePayPayload":null,"GooglePayPayload":null,"SendEmail":null,"Currency":"USD","EBillSignUp":false,"CreateTermsConsentEvent":true,"PianoInfo":null,"ProcessSync":true}
