Edit domains on a pending order or reissue

  5 minute read  

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.

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.

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:

  1. Use the Order validation status API endpoint to get the validation status of each added domain.
  2. Complete domain control validation (DCV) for any unapproved domains. Learn more:

Example requests and responses

cURL

curl --request PUT 'https://www.digicert.com/services/v2/order/certificate/{{order_id}}/dns-names' \
--header 'X-DC-DEVKEY: {{api_key}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "certificate": {
    "common_name": "sub1.example.com",
    "dns_names": [
      "sub2.example.com",
      "sub3.example.com"
    ]
  }
}'

// 204 No content
{
  "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

NameTypeReq/OptDescription
order_idnumberrequiredOrder ID. To edit domains, the order must have a status of pending or reissue_pending.

Request parameters

NameTypeReq/OptDescription
certificateobjectrequiredCertificate object.
.. common_namestringoptionalCertificate 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_namesarray of stringsoptionalUpdated 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

NameTypeDescription
domainsobjectList 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.
.. idintegerID of the domain in your account that must be validated to prove control over the domain (dns_name) on the order.
.. namestringName of the domain in your account that must be validated to prove control over the domain (dns_name) on the order.
.. dns_namestringCommon name or SAN on the order.
.. dcv_tokenobjectObject 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.
.. .. tokenstringDCV random value.
.. .. expiration_datestringDate and time the token expires.
Format: ISO 8601 date and time
.. .. verification_valuestringValue for the DNS record target host field. Only returned if the DCV method is dns_cname_token.
.. .. http_token_urlstringFilename and location for the .txt file. Only returned if the DCV method is http-token.