With Entri Sell, your users can buy and connect a domain name to your application effortlessly, right within the Entri modal. After purchase, Entri automatically connects their domain to your service, applying the records you define on the dnsRecords object.

​
1. Configure Entri

To set up Sell, first configure Entri.

Be sure to use dynamic configuration variablesif your DNS records change based on the domain purchased.

​
2. Define your return URLs

Entri Sell redirects the user back to your platform if the they complete or exit the purchase flow. To ensure a seamless user experience, we require you to define two return URLs:

  • successCallbackUrl: The URL to which the user will be redirected after a successful domain purchase.
  • exitCallbackUrl: The URL to which the user will be redirected if they select Close (X) before completing the purchase flow.

See more info at Basic Configuration.

​
3. Call purchaseDomain()

Call the purchaseDomain method with your configuration object to open the Entri Purchase Domain Flow.

<button type="button" onclick="entri.purchaseDomain(config)">Purchase Domain</button>

That’s it! You’re all set. If you are using Entri’s callback events, the setupType will be set to purchase.

JavaScript
{
  domain: "purchased-domain.com",
  success: true,
  setupType: "purchase",
  provider: "Ionos",
  lastStatus: "FINISHED_SUCCESSFULLY",
}

​
Configuration object specifications

More information about the properties within the object that you’ll pass to the entri.purchaseDomain method.

​
Basic Configuration

  • applicationId (string): A unique identifier for your application, available in the Entri dashboard. Example: "12345"

  • token (string): A JWT token used for authentication and authorization. Example: "JWT_TOKEN"

  • sellVersion (string) (required): The version of the domain purchase flow that should be shown. Setting this to "v3" will activate the latest version with enhanced features. Example: "v3"

  • successCallbackUrl (string): The URL to which the user will be redirected after a successful domain purchase. The purchased domain will be added as a domain query string parameter to the success callback URL. Example: "https://myapplication.com/success" (redirects to https://myapplication.com/success?domain=mydomain.com)

  • exitCallbackUrl (string): The URL to which the user will be redirected if they select Close (X) before completing the purchase flow. Example: "https://myapplication.com/exit"

​
DNS Records

  • dnsRecords (array of objects): An array containing DNS record objects. These records will applied after a successful domain purchase.

    Example:

    [
  {
    "type": "A",
    "host": "@",
    "value": "93.184.216.34",
    "ttl": 300
  },
  {
    "type": "A",
    "host": "aipv4",
    "value": "93.184.216.34",
    "ttl": 300
  }
]

​
Theming & Branding

  • whiteLabel (object): Options for customizing the appearance of the domain purchase flow to match your brand.

    • theme (object): Customizes the colors used in the purchase flow.

      • primary (string): Main color used in your theme. It’s usually the most recognizable color in the interface. Example: "#012939"

      • onPrimary (string): Color used for text and icons that appear on top of the primary color. Example: "#ffffff"

      • secondary (string): Color that complements the primary color and is used for secondary UI elements. Example: "#012939"

      • onSecondary (string): Color used for text and icons that appear on top of the secondary color. Example: "#ffffff"

      • headerBackground (string) (optional): Background color of the header. Accepts any valid CSS color code (e.g., hex, rgb). If not defined, it will default to the primary color value. Example: "#123456"

      • interactive (string) (optional): Color for interactive elements such as radio buttons. Accepts any valid CSS color code (e.g., hex, rgb). Example: "#ffcc00"

      • premiumBadge (string) (optional): Background color of premium badge components. Accepts any valid CSS color code (e.g., hex, rgb). Example: "#00ffcc"

      • onPremiumBadge (string) (optional): Text color on the premium badge. Accepts any valid CSS color code (e.g., hex, rgb). Example: "#ffffff"

      • priceBadge (string) (optional):
        This field specifies the background color of the price badge component. Accepts any valid CSS color code (e.g., hex, rgb).
        Example: "#ff6600"

      • onPriceBadge (string) (optional):
        This field specifies the text color on the price badge. Accepts any valid CSS color code (e.g., hex, rgb).
        Example: "#ffffff"

      • activating (string) (optional): Background color of the “Search Domain” button. Accepts any valid CSS color code (e.g., hex, rgb). Example: "#ff4500"

      • onActivating (string) (optional): Text color on the “Search Domain” button. Accepts any valid CSS color code (e.g., hex, rgb). Example: "#000000"

    • hideEntriLogo (boolean): Hide the Entri logo in the purchase flow. Example: true

    • hideCompanyLogo (boolean): Hide the company logo in the purchase flow. Example: true

    • hideCompanyName (boolean): Hide the company name in the purchase flow. Example: true

    • customCopy (object): Custom text to be displayed in the purchase flow.

      • initialScreen.title.{locale} (object): Title text that appears on the initial screen of the domain purchase flow, localized by language. Example: "Search for your domain"

      • initialScreen.marketingCopy.{locale} (object): Marketing copy that appears below the domain input field, localized by language. Example: "Your website will look even better with a custom domain!"

​
Sell Object

  • whiteLabel.sell (object): Contains information specific to the cobranding and user data prefill in the domain purchase flow.

    • flowTarget (string): The target location where the purchase flow window will be displayed. If _blank is specified, the flow will open in a new browser tab. Example: "_blank"

    • overlayScreenHeight (string): The percentage of the viewport height allocated to the search domain screen overlay. Example: "80%"

    • partnerLogo (string): The URL of the partner’s logo, which will be displayed prominently in the cobranded header. Example: "https://cdn.goentri.com/mylogo.svg"

    • partnerIcon (string): The URL of the partner’s icon, which will appear in the floating cart at the bottom of the page. Example: "https://cdn.goentri.com/myicon.svg"

    • partnerName (string): The name of the partner company, displayed within the purchase flow. Example: "My Company name"

    • contact (object): Prefilled user data to be used in the contact information form during domain creation. The following fields are supported:

      • firstName (string): User’s first name. Example: "John"

      • lastName (string): User’s last name. Example: "Doe"

      • email (string): User’s email address. Example: "john.doe@example.com"

      • phone (string): User’s phone number. Example: "+1234567890"

      • address (string): User’s street address. Example: "123 Main St"

      • zip (string): User’s ZIP or postal code. Example: "12345"

      • city (string): User’s city. Example: "Exampleville"

      • state (string): User’s state or province. Example: "EX"

      • postalCode (string): User’s postal code. Example: "12345"

      • country (string): User’s country. Example: "US"

​
Other Settings

  • freeDomain (boolean): Indicates whether the domain price should be set to $0. Should only be used on paid users at the customer’s platform. Example: true

  • locale (string): The language/locale to be used in the domain purchase flow. Example: "en"

​
Advanced Security Settings for freeDomain

For additional security, you can explicitly set freeDomain:false or freeDomain:true when you create the JWT. This way, the user gets explicit authorization for running the free domain flow.

If the client tries to use a config that doesn’t match the one hashed in the JWT, it will return an error. Here’s an example of how to use this when generating the JWT:

PropertyTypeRequiredDefaultDescription
freeDomainbooleanNoN/AWhen set to true, it will only allow Entri to run under the freeDomain flow.
JavaScript
fetch('https://api.goentri.com/token', {
  method: 'POST',
  body: JSON.stringify({
    // These values come from the Entri dashboard
    applicationId: "12345",
    secret: "12345-67890",
    freeDomain: true
  }),
})
  .then(response => response.json())
  .then(data => {
    console.log('Success:', data); // { "auth_token": "exampletoken..." }
    // Save the token in a variable or state manager for later use
  });

​
Mail Upsell

By default, Entri adds an extra step to the domain purchase flow. This step offers users the opportunity to purchase mail inboxes as an upsell. A mailbox is optional, meaning users can manually skip the mail offering if they are not interested..

This property enhances the domain purchase experience by allowing you to promote additional services seamlessly, providing more value to users while keeping the flow non-intrusive.

You can turn this feature off by setting the disableMailUpsell:true in your configuration.

Example Configuration:

{
  "applicationId": "exampleapp",
  "token": "JWT_TOKEN",
  "sellVersion": "v3",
  "disableMailUpsell": true,
  "successCallbackUrl": "https://[your_success_callback_url].com",
  "exitCallbackUrl": "https://[your_exit_callback_url].com"
  "dnsRecords": [
    {
      "type": "A",
      "host": "@",
      "value": "93.184.216.34",
      "ttl": 300
    }
  ],
  "whiteLabel": {
    "logo": "https://cdn.yourpartner.com/logo.svg",
    "theme": {
      "fg": "#ffffff",
      "bg": "#012939",
      "fgSecondary": "#ffffff",
      "bgSecondary": "#012939"
    }
  }
}

​
Migrating from Entri Sell V2 => V3?

If you are currently using a previous version of the entri.purchaseDomain functionality and would like to migrate to the new version, follow these steps to ensure a smooth transition:

​
Step 1: Update the sellVersion

  • Add the sellVersion Key: Ensure that your configuration includes the sellVersion key set to "v3". This will activate the new version of the domain purchase flow.

    "sellVersion": "v3"

​
Step 2: Implement New Redirect URLs

  • Add successCallbackUrl and exitCallbackUrl: Define where users should be redirected after the domain purchase flow is completed, whether successfully or due to an error.

    "successCallbackUrl": "https://[your_success_callback_url].com",
"exitCallbackUrl": "https://[your_exit_callback_url].com"

​
Step 3: Update Theming Options

  • Expand Theme Configuration: Review and expand your theme settings to include new customizations like the onSecondary and secondary keys, which control the colors of interactive elements like buttons.

    "theme": {
  "primary": "#012939",
  "onPrimary": "#ffffff",
  "secondary": "#ffffff",
  "onSecondary": "#012939",
  "headerBackground": "#012939",
  "interactive": "#ffcc00",
  "premiumBadge": "#00ffcc",
  "onPremiumBadge": "#ffffff",
  "priceBadge": "ff6600",
  "onPriceBadge": "ffffff",
  "activating": "#ff4500",
  "onActivating": "#000000"
}

​
Step 4: Customize the sell Object (Optional)

  • Add Branding and User Data: If you want to leverage the new cobranded experience, populate the sell object with your partner branding and prefilled user data. This includes fields like partnerLogo, partnerIcon, partnerName, and the contact object.

    "sell": {
  "partnerLogo": "https://cdn.yourpartner.com/logo.svg",
  "partnerIcon": "https://cdn.yourpartner.com/icon.svg",
  "partnerName": "YourPartnerName",
  "contact": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "phone": "+1234567890",
    "address": "123 Main St",
    "zip": "12345",
    "city": "Exampleville",
    "state": "EX",
    "postalCode": "12345",
    "country": "US"
  }
}

​
Step 5: Test the New Configuration

  • Conduct Thorough Testing: After updating your configuration, thoroughly test the domain purchase flow to ensure that all new features are working correctly and that the theming, branding, and user data are displayed as expected.

​
Step 6: Deploy the Updated Configuration

  • Roll Out to Production: Once you are satisfied with the testing, deploy the updated configuration to your production environment. Monitor the transition to ensure a seamless experience for your users.

By following these steps, you can easily migrate to the new version of entri.purchaseDomain, unlocking enhanced customization and a better overall user experience.

​
FAQ

  • Who is the registrar for the domain?

    Entri has partnered with Ionos as the domain registrar.

  • How is billing handled?

    Billing, renewals, and the checkout process are handled by Ionos.

  • Who is responsible for customer support relating to the domain purchased?

    For all inquiries relating to billing, renewals, domain registration, please direct your customers to Ionos’s support team: https://contact.ionos.com/

  • Can I earn a commission for each domain purchased?

    Yes! Please contact your Entri account manager to set this up.

  • How can I test Entri Sell without purchasing a new domain on each run?

    In order to test the Sell flow without purchasing numerous domains, you can apply the following parameter to the global entri variable into the Entri config debugMode: true. This will allow you to avoid purchasing unnecessary domains while testing it. Keep in mind that you have to use a domain that was previously purchased via IONOS to use the DebugMode.

    Please find more details on our /api-reference#entri-purchasedomain-config.