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}