Edit domains on a pending order or reissue

PUT https://www.digicert.com/services/v2/order/certificate/{{order_id}}/dns-names

Use this endpoint to edit the domains (common_name and dns_names) on a pending TLS/SSL certificate order or reissue. This is useful when you want to change which domains a pending certificate will secure without submitting a new certificate order or reissue request.

Usage and limitations

When using this endpoint, keep the following in mind:

Editing domains does not change the price of the certificate order.
You can only replace a domain/IP address with another domain/IP address and a wildcard domain with another wildcard domain.
The total number of domains cannot exceed the number of domains on the original certificate request.
You can add domains back to the order for free, up to the original amount purchased, the next time you reissue the certificate.
To use this endpoint, the authenticated user must be an admin or manager.

Danger

This endpoint is destructive to the certificate.dns_names array. Omitting the certificate.dns_names array from your request replaces the list of dns_names on the pending order or reissue with a new list that only includes the common_name value.

Response format

OV/EV orders

When editing domains on an OV or EV order:

A successful request returns a response status code of 200 OK.
DigiCert adds new domains submitted for validation to your CertCentral account.
The API returns a list of domains with an object for each domain on the order. Each object has the name and id of the domain in your account that you must validate to prove control over the domain on the order.
Note
Multiple domains on the order may be submitted for validation under the scope of the same higher-level domain. This means the domains array may return multiple objects with the same name and id values.

DV orders

When editing domains on a DV order:

A successful request returns a response status code of 204 No Content.
DigiCert does not add new domains submitted for validation to your CertCentral account.

Validate added domains

Domains you add to a pending order or reissue are automatically submitted for validation using the same DCV method as the original order or reissue request.

After adding or replacing domains:

Use the Order validation status API endpoint to get the validation status of each added domain.
Complete domain control validation (DCV) for any unapproved domains. Learn more:
- DV certificate lifecycle – Complete domain control validation (DCV)
- OV/EV certificate lifecycle – Complete domain control validation (DCV)

Example requests and responses

Example 2. DV orders (204 No Content)

// 204 No content

Example 3. OV/EV orders (200 OK)

{
  "domains": [
    {
      "id": 4069862,
      "name": "example.org",
      "dns_name": "example.org",
      "dcv_token": {
        "token": "<random_value>",
        "expiration_date": "2023-04-29T22:52:24+00:00"
      }
    },
    {
      "id": 4069862,
      "name": "example.org",
      "dns_name": "subdomain.example.org",
      "dcv_token": {
        "token": "<random_value>",
        "expiration_date": "2023-04-29T22:52:24+00:00"
      }
    },
    {
      "id": 4069862,
      "name": "example.org",
      "dns_name": "another.subdomain.example.org",
      "dcv_token": {
        "token": "<random_value>",
        "expiration_date": "2023-04-29T22:52:24+00:00"
      }
    }
  ]
}

Path parameters

Name	Type	Req/Opt	Description
order_id	number	required	Order ID. To edit domains, the order must have a `status` of `pending` or `reissue_pending`.

Request parameters

Name	Type	Req/Opt	Description
certificate	object	required	Certificate object.
.. common_name	string	optional	Certificate common name. If not provided, the common name is not changed. Note: You cannot change the common name if your account settings require the common name in your request to match the CSR.
.. dns_names	array of strings	optional	Updated list of domains for the order. You can omit the `common_name` value from the `dns_names` list. Before updating the order, DigiCert prepends the `common_name` value to the `dns_names` list and removes any duplicate values. Important: This list overwrites the domains that already exist on the pending order or reissue. Make sure it includes any domains or IP addresses you don’t want to remove. To get a list of domains on a pending order or reissue, use the Validation status API endpoint.

Name

Type

Req/Opt

Description

certificate

object

required

Certificate object.

.. common_name

string

optional

Certificate common name. If not provided, the common name is not changed.

Note: You cannot change the common name if your account settings require the common name in your request to match the CSR.

.. dns_names

array of strings

optional

Updated list of domains for the order.

You can omit the common_name value from the dns_names list. Before updating the order, DigiCert prepends the common_name value to the dns_names list and removes any duplicate values.

Important: This list overwrites the domains that already exist on the pending order or reissue. Make sure it includes any domains or IP addresses you don’t want to remove. To get a list of domains on a pending order or reissue, use the Validation status API endpoint.

Response parameters

Note

Only requests to edit domains on OV/EV TLS orders return these parameters. See Response format.

Name	Type	Description
domains	object	List of objects for each domain on the order. Each object has the `name` and `id` of the domain in your account that you must validate to prove control over the domain (`dns_name`) on the order. Note: Multiple domains on an order can be validated under the scope of the same higher-level domain. This means that multiple objects in the `domains` array may return the same `name` and `id` values.
.. id	integer	ID of the domain in your account that must be validated to prove control over the domain (`dns_name`) on the order.
.. name	string	Name of the domain in your account that must be validated to prove control over the domain (`dns_name`) on the order.
.. dns_name	string	Common name or SAN on the order.
.. dcv_token	object	Object with details about the DCV random value. Each domain returns the same order random value, and you can use this value to complete the DCV check for any domain submitted for validation with the order. Only returned for domains using a DCV method of `dns-txt-token`, `dns-cname-token`, or `http-token`.
.. .. token	string	DCV random value.
.. .. expiration_date	string	Date and time the token expires. Format: ISO 8601 date and time
.. .. verification_value	string	Value for the DNS record target host field. Only returned if the DCV method is `dns_cname_token`.
.. .. http_token_url	string	Filename and location for the .txt file. Only returned if the DCV method is `http-token`.

In this section: