Renew a TLS certificate explicitly

This recipe covers the case where a certificate should not simply be reissued on the same order, but should move into the next contract or billing period as a new order. That is exactly what renewal_of_certificate_id on POST /tls/certificate is for.

The distinction from re-issue matters: re-issue keeps the same certificate id and the same order. An explicit renewal creates a new order with a new certificate id, while still pointing to the previous certificate so the provider can apply any remaining validity.

Prerequisites

an API key with access to the TLS and DNS endpoints
the certificate id of the currently active certificate
a new CSR for the renewal
DNS access for domain control validation
a deployment step that can switch over to the newly issued certificate and track its new certificate id

Step 1: Read the current certificate and store the renewal source

Read the currently active certificate so you can document the starting point and use the correct renewal_of_certificate_id.

curl --request GET \
  --url 'https://api.regfish.com/tls/certificate/7K9QW3M2ZT8HJ' \
  --header 'x-api-key: YOUR_API_KEY'

Persist at least:

id
common_name
dns_names
contract_valid_until
valid_until
status

Step 2: Create the new order with explicit renewal intent

Create the new order through the same endpoint as a first-time order, but add renewal_of_certificate_id.

curl --request POST \
  --url 'https://api.regfish.com/tls/certificate' \
  --header 'content-type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '
{
  "sku": "RapidSSL",
  "common_name": "www.example.com",
  "dns_names": ["api.example.com"],
  "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIIC...NEXT...\n-----END CERTIFICATE REQUEST-----",
  "dcv_method": "dns-cname-token",
  "renewal_of_certificate_id": "7K9QW3M2ZT8HJ",
  "validity_days": 199
}
'

The response contains a new id. That new certificate id becomes the control value for the rest of the renewal flow.

Remember that validity_days remains the purchased base order validity. After issuance, valid_until is authoritative for the effective lifetime, and renewal_bonus_days may appear once the provider has confirmed any carried-over remaining validity.

Step 3: Apply DCV for the new order

Take the validation data from validation.dns_records and apply it for the new order. Even in a renewal flow, do not assume that previous DCV data remains valid automatically.

curl --request POST \
  --url 'https://api.regfish.com/dns/rr' \
  --header 'content-type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '
{
  "type": "CNAME",
  "name": "_dnsauth.example.com",
  "data": "0123456789abcdef.dcv.digicert.com.",
  "ttl": 300
}
'

Step 4: Poll the new order until issuance

From here on, monitor the new certificate id, not the previous certificate.

curl --request GET \
  --url 'https://api.regfish.com/tls/certificate/9M4TR8C6X2HP7' \
  --header 'x-api-key: YOUR_API_KEY'

Pay particular attention to:

status
order_state
contract_valid_until
valid_until
renewal_bonus_days
certificate_pem_available

Step 5: Download the renewed certificate through the new certificate `id`

Once the renewal has been issued, download the certificate through the new order and roll it out.

curl --request GET \
  --url 'https://api.regfish.com/tls/certificate/9M4TR8C6X2HP7/download/pem' \
  --header 'x-api-key: YOUR_API_KEY' \
  --output 'certificate-9M4TR8C6X2HP7.pem'

After that, update at least:

previous_certificate_id = 7K9QW3M2ZT8HJ
active_certificate_id = 9M4TR8C6X2HP7
renewed_from_certificate_id = 7K9QW3M2ZT8HJ
contract_valid_until
renewal_bonus_days, if present
the new valid_until

Practical notes for production workflows

use renewal for the next contract or billing cycle, not for an emergency replacement on the same order
use re-issue when the same order and the same certificate id should remain in place
persist the relationship between the old and new certificate IDs so reporting and deployment stay consistent
leave enough lead time before expiry instead of starting renewal at the last possible moment
apply the DCV data returned by the renewal explicitly instead of relying on old tokens

Result

This flow creates a new certificate order that the provider explicitly treats as a renewal of the previous certificate. That gives you a cleanly documented next contract cycle and keeps the case clearly separated from re-issue on the same order.