Order a Domain Name
Using OVHcloud APIs requires advanced knowledge. If you experience any difficulties, please contact OVHcloud partners.
To follow this guide, make sure you are connected to OVHcloud API. You may find more information on the API introduction page if needed.
Table of Contents
- Introduction
- Order a Domain Name
- Tasks Management
- Manage Contacts of a Domain Name
- Managing Eligibility Rules
- Configure the Display of Contact Data in the Whois
- Configure the DNS of your Domain Name
- Transfer a Domain Name
Order API
Before ordering your domain names, we describe the different objects which can be accessed and manipulated through the API.
The Cart
The cart object from the API represents an order cart. Different actions are possible:
- Create: can be performed without authentication
- Assign to a Nic: required to validate a cart
- Add products to the cart
- Preview cart
- Request validation in "dry-run" mode (without generating a purchase order)
- Generate a purchase order from the cart contents
These API routes start with /order/cart/
The Products
An item represents a product which can be added to a cart. Possible actions:
- Check product availability
- Add/update/remove a product in a cart
- Get required product configurations before the cart can be validated
- Add/remove a product configuration
The API routes used to perform these actions start with /order/cart/{cartId}/item/
Workflow
In general, ordering an OVHcloud product with the API will follow these steps:
- Create a cart
- Fetch available offers for the requested product
- Add the requested product to the cart
- Preview a cart summary (optional)
- Fetch required configurations for the product
- Add the required configurations
- "Dry-run" validation of the cart (optional)
- Validate the cart
Cart Creation
The first step when ordering a domain name is to create a cart with this API route:
Write down the cartId attribute somewhere, as it will be used in the next steps.
Fetch Available Offers
The second step consists in fetching available offers for a domain name.
There are 4 important values in this payload:
action: what can be done on the domain name, it could be acreateor atransferduration: represents the period during which the domain name may be ordered, in ISOÂ 8601 format. For a domain name, P1Y (Period 1 Year) orders the domain name for 1Â year, P2Y for 2Â years, etc.offerId: name of the offer, which should be included when adding the domain name to the cartpricing-mode: offer detail, which will also be included when adding the domain name
To determine the domain name status, the following mapping table can be used, according to the pricing-mode.
For now, even if the response is an array, only 1 offer is returned. In the future, it could happen than several offers are returned for a single domain name. For example, a domain name could be at the same time transferable from another registrar, or available on an aftermarket platform.
Add a Domain Name to the Cart
While the second step is optional, this one is mandatory to order a domain name. The following call allows to add the desired domain to the cart:
Write down the itemId value, as it will be used in the next steps.
Cart Summary
This step is optional. It returns a preview of the cart contents, but does not check cart consistency or configuration.
Without looking into the details of this payload, a couple of things are worth noting:
- Adding an item to the cart produces two lines of details on the purchase order
- An extra line is added when a promotion is used (
detailType=GIFT) - The
pricesobject represents the cart total price, with and without taxes - The contract list is empty in the summary. It will be filled after validation, or purchase order creation
You may be surprised by the returned DNS zone (represented with two lines of details), since it was not added to the cart. This is a frequently ignored notion. A domain name and a DNS zone are two distinct things (products in the cart): the domain name may be registered with OVHcloud while the DNS zone may be hosted elsewhere.
However, since the two are strongly tied and to ease the order process, we chose to add a DNS zone automatically when a domain name is ordered. Of course, you may add it manually to add options such as DNSSEC or DNS Anycast. We will write about it later, when considering product options.
Assigning the Cart
Even though this operation may be done right after the cart creation, it is mandatory to proceed. As we will see later indeed, domain configurations and their validation depends on the OVHcloud nic assigned to the cart.
Configurations Management
At this point, the cart contains a domain name. It is necessary to add required configurations to be able to validate it and generate a purchase order.
Fetch Required Configurations
To know which configurations are required, you should call this API endpoint.
The above response represents the most standard return value found when creating a domain name. It depends on the desired action (transfer, creation), extension or the type of domain (premium, aftermarket).
Below is the exhaustive list of required configurations for a domain name.
Be aware that this API is designed for most OVHcloud products.
Domain names have specific and much more complex rules regarding some configuration values.
It is the case for the ADMIN_ACCOUNT, OWNER_CONTACT and DOMAIN_CONFIG in particular, since they are related to specific registry rules.
For example, to obtain a .berlin domain name, either the holder or the admin contact must be based in Berlin. However, this API can not describe such constraints.
In order to handle these cases, there are other API routes to send required data in a more precise way. These routes correspond to an advanced usage, and may be used outside of the order process (such as contact update), so they are described in section Rules Management.
Here, the OWNER_CONTACT represents a "resource" API, namely /me/contact, or more precisely /domain/contact.
The API routes used to create these contacts are described in section Contact Management.
CRUD on Product Configurations
Now that we have fetched the required configurations list, we should add them to the product.
Add Configuration
Fetch Product Configurations
Fetch Configuration Value
Configuration Removal
Cart Management
Of course, at any time, you may visualize and manipulate the cart with the following API routes:
Fetch Items
Fetch Item Details
Item Removal
Cart Validation
This step is probably the most important of the order process, and can be performed with this API call.
It allows to get the final purchase order, without generating it (it is a "dry-run"). The returned object contains the contracts associated with the different products.
This call also validates the configurations, like holder eligibility for a domain name.
Create Purchase Order
Pay Purchase Order
If the purchase order was not paid automatically with default payment method in the previous step, you will have to use purchase order management APIs. We assume that at least 1 payment method is registered in your account (if not, there are API routes to manage them).
Fetch Available Payment Methods
First, let us fetch available payment methods for the purchase order above with the following route.
Pay Purchase Order
The purchase order can be paid using the API route below. It does not return any data, but status 200 indicates that it succeeded.
Purchase Order Follow-up
The following API route allows to get the purchase order status.