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.