New Start Flow
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.
Notes
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.
Flow overview
Steps breakdown
Offers Step
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
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
Query Parameters
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).
Headers
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
{
"Code": 200,
"Errors": [],
"Result": {
"Offers": [
{
"OfferId": 16,
"OfferGroupId": 6,
"OfferGroupName": "Digital Only $0.99 First Month",
"OfferGroupCode": "digitalOnly099FirstMonth",
"OfferGroupIsActive": true,
"OldPID": "2151",
"PayPalBillingPlanId": null,
"SwgSKUId": null,
"Promotions": [
{
"PromotionId": 1,
"PromotionName": "Digital Only",
"InternalPriority": null,
"PromotionCode": "Digital",
"IsActive": true
}
],
"DisplayOrder": 0,
"Name": "Digital Only $0.99 First Month ",
"TermValue": null,
"TermTypeId": null,
"TermType": null,
"IsBestPlan": false,
"IsEzPay": true,
"IsEzPayOptional": false,
"TrialDays": 0,
"ExternalBillingPlanId": 1,
"DryRunAmount": null,
"DryRunDailyAmount": null,
"Products": [
{
"ProductId": 100014,
"ExternalProductId": "100014",
"ExternalMerchantId": "100014",
"Name": "DP Digital",
"Price": 0.99,
"Currency": null,
"Active": true,
"PaperCode": "DP",
"NewspaperId": 1,
"ServiceTypeId": 14,
"IsPrint": false,
"IsDigital": true,
"ServiceType": {
"ServiceTypeId": 14,
"Name": "Digital Only",
"Description": "Digital",
"Sequence": 999,
"Days": 0,
"Code": "Digital",
"ProductCode": "DP",
"Active": true,
"eEditionAccess": true,
"AllowPreviousSunday": false,
"ServiceDays": [
{
"Day": 0,
"DayName": "Sunday",
"PrintAllowed": false,
"DigitalAllowed": true
},
{
"Day": 1,
"DayName": "Monday",
"PrintAllowed": false,
"DigitalAllowed": true
},
{
"Day": 2,
"DayName": "Tuesday",
"PrintAllowed": false,
"DigitalAllowed": true
},
{
"Day": 3,
"DayName": "Wednesday",
"PrintAllowed": false,
"DigitalAllowed": true
},
{
"Day": 4,
"DayName": "Thursday",
"PrintAllowed": false,
"DigitalAllowed": true
},
{
"Day": 5,
"DayName": "Friday",
"PrintAllowed": false,
"DigitalAllowed": false
},
{
"Day": 6,
"DayName": "Saturday",
"PrintAllowed": false,
"DigitalAllowed": true
}
]
},
"Discount": null,
"Description": "DP Digital",
"IsAddOn": false,
"DeliveryMethod": "5",
"OneTimeCharge": false,
"RegularRate": null
}
],
"ProductPriceGroups": [
{
"SolConProductId": 343,
"SolConProductPrice": 0.99,
"BillingPeriodId": 8,
"ProductId": 100014
}
],
"Premiums": null,
"IsPrint": false,
"IsDigital": true,
"IsEedition": true,
"BillingSystem": null,
"RegistrationCount": null,
"IsEmailRequired": null,
"RunProductDeliveryCheck": false,
"PaymentMethods": [
{
"PaymentMethodId": 1,
"PaymentMethodName": "Credit card",
"PaymentMethodCode": "CC"
},
{
"PaymentMethodId": 2,
"PaymentMethodName": "Bank draft",
"PaymentMethodCode": "BK"
},
{
"PaymentMethodId": 14,
"PaymentMethodName": "PayPal",
"PaymentMethodCode": "PAY"
},
{
"PaymentMethodId": 17,
"PaymentMethodName": "PayPal circ PayFlow",
"PaymentMethodCode": "PAYDTICPF"
}
],
"IsDeliveryAddressRequired": false,
"IsBillingAddressRequired": true,
"IsNoExistingSubAtAddress": false,
"IsNoExistingSubStoppedLast30": false,
"ValidateNoPreviousSubscriptionOutstandingBalance": false,
"IsSheerIdValidationRequired": false,
"ExternalDivisionId": 19,
"ExternalDivisionName": "Denver Post",
"ExternalDivisionCode": "DP",
"IsDraftVersion": false,
"IsOneTimePurchase": false,
"IsPassOrTrial": false,
"IsGiftOffer": false,
"IsAllowForRedemption": false,
"ValidityStartDate": "2020-03-18T00:00:00",
"ValidityEndDate": "2029-12-07T23:59:59",
"EzTypeId": 1,
"EzTypeName": "required",
"IsRequireCodeForAccess": false,
"CustomCode1": "MG2",
"CustomCode2": "Internet",
"CustomCode3": null,
"CustomCode4": "",
"CustomCode5": "",
"CustomCode6": "",
"CustomCode7": "",
"CustomCode8": "",
"CustomCode9": "",
"CustomCode10": "",
"BillingSystemCode1": "7DayOLPZ_N_prom",
"BillingSystemCode2": null,
"BillingSystemCode3": "all",
"BillingSystemCode4": "PZ",
"BillingSystemCode5": "Month",
"BillingSystemCode6": "Office Pay",
"BillingSystemCode7": "1",
"BillingSystemCode8": "Online",
"BillingSystemCode9": null,
"BillingSystemCode10": null,
"BillingSystemCode11": null,
"BillingSystemCode12": null,
"SalesTeamOfferOrder": 1,
"BillingPeriods": [
{
"BillingPeriodId": 8,
"BillingPeriodCycles": 3,
"BillingPeriodQuantity": null,
"BillingPeriodType": null
}
],
"Marketing": {
"MarketingTitle": "<p>Unlimited Digital Access</p>",
"MarketingBody": "<p><p>? Unlimited access to DenverPost.com</p>\n\n<p>? Access to the Digital Replica Edition</p></p>",
"MarketingInternalDescription": null,
"MarketingName": "Default digital marketing text Trial1m",
"MarketingExternalImagePath": null,
"MarketingExternalImageAltText": null,
"MarketingConfirmationName": "Unlimited Digital Access",
"MarketingPrice": "<p><p><strong>$0.99 for 1 month.</strong><br />\n$14.99 a month thereafter. Cancel anytime.</p></p>",
"MarketingPriceText": "$0.99 for 1 month.\n$14.99 a month thereafter. Cancel anytime."
},
"TermsAndConditions": {
"TermAndConditionId": 1,
"TermAndConditionBody": "<p><em>test</em> <p>By subscribing, you agree to the <a href=\"https://www.mymediagroup.com/terms-of-use/\" target=\"_blank\">Terms of Use</a>, and <a href=\"https://www. mymediagroup.com/arbitration/\" target=\"_blank\">Arbitration and Refund Terms</a>. Your subscription will renew automatically, and you will be charged in advance. <strong><u>You may cancel at any time</u></strong> by calling Member Services at 111-111-1111. The cancellation goes into effect at the start of your following billing cycle.</p></p>",
"TermAndConditionName": "Digital Terms and Conditions"
},
"Gifting": null,
"HouseHoldLevel": {
"ExternalHhLevelId": null,
"HouseHoldLevel": null
},
"SmartOffer": null,
"RelatedOffers": [
{
"RelatedOfferGroupId": null,
"OfferRelationTypeName": null
}
],
"MultiUseCodes": [
null
],
"AllowPreviousSunday": false
}
]
},
"SessionId": "36b7064e-bf13-413d-bc67-ab5d937589d3",
"RequestId": "1"
}
Account Step
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 by Email
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}
Path Parameters
Type*
Int
This defines where the user should be looked up. 1: Auth System
2: Naviga Database
0: Both (recommended)
Headers
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).
{
"Code": 200,
"Errors": null,
"Result": {
"User": {
"RegistrationId": 0,
"LoginName": "string",
"LoginPassword": "string",
"IsActive": 0,
"CustomerRegistrationId": "string",
"EncryptedCustomerRegistrationId": "string",
"FirstName": "string",
"LastName": "string",
"Email": "string",
"Gender": "string",
"PhoneAc": "string",
"PhoneEx": "string",
"PhoneExt": "string",
"Phone": "string",
"MobilePhone": "string",
"OptInEVantageSubscriberRewards": true,
"OptInSpecialOffers": true,
"OptInContestAndPromotions": true,
"OptInPaperlessBilling": true,
"OptInEEdition": true,
"OptInEEditionEmailNotification": true,
"OptInSubscriberDiscounts": true,
"OptInAdvertiserEmails": true,
"MemberEvent": true,
"ContentEngagement": true,
"SUBCOM": true,
"Survey": true,
"AccountUpdates": true,
"DateOfBirth": "string",
"BirthYear": "string",
"AcceptsEmailOffers": 0,
"AcceptsEmailAds": 0,
"AcceptsEmailPromotions": 0,
"IsOkToEmail": 0,
"IsOkToPhone": 0,
"IsOkToMail": 0,
"AcceptsEENotification": 0,
"ChangeDate": "2018-07-24T11:20:15.403Z",
"DateRegistered": "2018-07-24T11:20:15.403Z",
"IsSocial": true,
"DisplayName": "string",
"AgreeToTerms": true,
"OptOutMarketing": true,
"Photo": "string"
}
}
}
Create User
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
Headers
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
Request Body
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).
{
"Code": 200,
"Errors": null,
"Result": {
"CustomerRegistrationId": "8ddc8fa8-32b0-11ec-8d3d-0242ac130003",
"EncryptedCustomerRegistrationId": "0acdee3899d72843f0f6571e0740c25473d336c1",
"Mg2RegistrationId": 155
}
} Address Step
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.
Standardize Address
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
Query Parameters
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
Headers
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
{
"Code": 200,
"Errors": [],
"Result": {
"IsValidAddress": true,
"Reason": "",
"Address": {
"Address": "5261 Boston St",
"Address2": null,
"HouseNumber": "5261",
"StreetName": "Boston",
"StreetSuffix": "St",
"PreDirect": "",
"PostDirect": "",
"AptUnit": "",
"AptNumber": "",
"UnitType": "",
"District": null,
"City": "Denver",
"State": "CO",
"ZipCode": "80238",
"ZipCode4": "3927",
"DPVCode": "AABB",
"SuiteStatus": "V",
"Suite": "",
"DeliveryPointCheckDigit": "1",
"DPVFootnotes": "AABB",
"DeliveryPointCode": "61",
"CountyFips": "08031",
"CountyName": "Denver",
"LockBox": "",
"RouteService": "",
"Country": "US",
"CountryName": null,
"Msa": "",
"CarrierRoute": "R058",
"ParsedAddressKey": "00000052610000ST00BOSTN00000000000080238",
"PakHash": "da9e1faa98a31f44fe2411b5657ca4ed",
"StandardizationError": " ",
"StandardizationErrorMessage": "No Error",
"StandardizationResult": "AS01",
"Latitude": "39.793520",
"Longitude": "-104.879990",
"CensusBlock": "1003",
"CensusTract": "004106",
"GeoCoderResult": "GS01",
"ParsedGarbage": "",
"AddressTypeCode": "S",
"AddressType": "Street",
"DependentLocality": null
},
"Suggestions": []
},
"SessionId": "03931197-7e42-4b86-a53c-4724db14a737",
"RequestId": "1"
}Billing Step
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.
Summary Step
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.
Calculate Subscription Cost
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
Headers
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
{
"Code": 200,
"Errors": [],
"Result": {
"SubscriptionCost": 0.99,
"Taxes": null,
"ActivationFee": 0,
"TotalAmount": 0.99
},
"SessionId": null,
"RequestId": null
}Finalizing New Start
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.
Add Subscription
POST /Subscriptions
Prod: server-clientname-prod.subscriberconcierge.com/Subscriptions
Test: test.subscriberconcierge.com/Subscriptions
Headers
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
{
"Code": 200,
"Errors": [],
"Result": {
"SubscriptionCost": 0.99,
"Taxes": null,
"ActivationFee": 0,
"TotalAmount": 0.99
},
"SessionId": null,
"RequestId": null
}
Code Samples
Standard Newstart Sample
{"StartDate":"2021-09-16","ExpirationDate":null, "CustomerRegistrationId":"auth0|612fb718c1a18f007061c58f","EmailAddress":"[email protected]","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}
Comp Newstart Sample
{"CustomerRegistrationId":"auth0|612fb718c1a18f007061c58f","EmailAddress":"[email protected]","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}
Paid Pass Newstart Sample
Gift Newstart Sample
{"StartDate":"2021-09-28T00:00:00","ExpirationDate":null,"CustomerRegistrationId":"","EmailAddress":"[email protected]","OfferId":369,"PromotionCode":null,"OfferGroupId":12264,"RecipientInformation":{"FirstName":"kristina","LastName":"krukovskaya","Email":"[email protected]","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}
Last updated
Was this helpful?