/certificate-expiry

name: "GoGetSSL Certificate Expiry"
description: >
  Tracking SSL certificate expiry across every client domain in a GoGetSSL
  reseller account: which order fields carry the expiry date, how to treat
  unissued orders, grouping certificates by client domain, renewal tiers,
  batch status checks for a known set of orders, and reading one order's
  validity and renewal flags.
when_to_use: >-
  When an MSP needs to know which client certificates bought through GoGetSSL
  are expiring, already expired, or stuck before issuance. Use when: ssl
  expiry, certificate expiry report, expiring certificates, cert renewal
  list, which certs expire this month, expired ssl, gogetssl orders, or
  certificate inventory.

GoGetSSL Certificate Expiry

Overview

An expired certificate is one of the most visible outages an MSP can let happen: the client's site or mail shows a browser warning and the client notices before you do. GoGetSSL holds the record of every certificate bought through the reseller account, so it is the right source for a monthly expiry sweep. Every tool here is read tier and none is admin-gated in Conduit.

Anti-triggers

• **Pricing a renewal, checking DCV approver emails or decoding a CSR**: use

[renewal-prep](../renewal-prep/SKILL.md). This skill finds what expires; that one gets a renewal ready.

• **Certificates not bought through GoGetSSL** (Let's Encrypt, a client's own

CA account, another reseller): GoGetSSL has no record of them. Only orders in this reseller account appear.

Key Concepts

| Field | Source | Meaning | |-------|--------|---------| | `order_id` | all order tools | Numeric GoGetSSL order ID | | `common_name` | `gogetssl_orders_list`, `gogetssl_orders_get_status` | Primary domain on the certificate | | `valid_from` / `valid_till` | `gogetssl_orders_list`, `gogetssl_orders_get_status` | Certificate validity, `YYYY-MM-DD`. `null` or `0000-00-00` until issued | | `expires` | `gogetssl_orders_get_statuses` | Expiry date, returned only for active orders | | `begin_date` / `end_date` | `gogetssl_orders_get_status` | The order's subscription period, which can be longer than one certificate's validity on a multi-year order | | `status` | all order tools | `active`, `processing`, `expired`, `revoked`, `rejected` (plus other vendor statuses on single-order detail) |

**Certificate validity versus subscription.** Public TLS certificate lifetimes are capped by the CA/Browser Forum, and that cap keeps shrinking, but GoGetSSL sells multi-year subscriptions. On such an order, `valid_till` is when the current certificate expires and `end_date` is when the subscription ends. A certificate expiring inside a paid subscription needs a reissue, not a new purchase. Check `gogetssl_orders_get_status` before telling anyone to buy.

Common Workflows

Monthly expiry sweep

1. Call `gogetssl_orders_list` with `status: "active"`. The vendor does not page this list, so the status filter is what keeps it inside the response limit. If the response comes back `truncated`, or fails with the response-size error, do not report from it; use the paged fallback below. 2. Drop rows whose `valid_till` is `null` or `0000-00-00`. Those were never issued; handle them in the stuck-order check below. 3. Compute days to expiry from today and sort ascending. 4. Bucket into tiers:

| Tier | Days left | Action | |------|-----------|--------| | Critical | 14 or fewer | Renew or reissue now; validation can take days | | Due | 15-30 | Start renewal this week | | Upcoming | 31-60 | Quote the client, confirm the domain is still in use | | Healthy | over 60 | No action |

5. Group by registrable domain under `common_name` and map domains to clients. Flag domains you cannot map. 6. For each Critical and Due order, call `gogetssl_orders_get_status` to read `end_date`, the reissue and renew flags, and the domains and SANs covered. That separates "reissue inside the subscription" from "buy a renewal".

Paged fallback for a large account

When `gogetssl_orders_list` for a status is truncated or too large:

1. Page through `gogetssl_orders_list_ssl` (`limit` and `offset`) to get every order ID, and keep the ones with the status you were listing. 2. Call `gogetssl_orders_get_statuses` with those IDs in batches of 100. For active orders, use `expires` as the expiry date (`valid_till`). Expired orders get no `expires`, so call `gogetssl_orders_get_status` for each expired ID to read `valid_till` before filtering by date. If any expiry date cannot be retrieved, mark the expired-orders report incomplete and list the order IDs you could not date. 3. These results carry no domain. Call `gogetssl_orders_get_status` for each order you will report (for the expiry sweep, the ones inside the planning window) to get `common_name` and the SANs before grouping. Reuse any order detail you already retrieved in step 2.

Recently expired certificates

Call `gogetssl_orders_list` with `status: "expired"` (or the paged fallback) and keep rows whose `valid_till` is within the last 30-60 days. These are either sites that went dark or certificates that were replaced by a new order. Before treating one as replaced, read both orders with `gogetssl_orders_get_status` and check that the active order covers every name the expired one did, `common_name` and SANs. Report any name it does not cover.

Stuck orders

Call `gogetssl_orders_list` with `status: "processing"`. An order that has sat in processing for days usually failed domain validation. Read it with `gogetssl_orders_get_status`: the domain validation status and method fields tell you whether it is waiting on an approver email, a DNS record or an HTTP file. Fixing it (resending the email, switching the DCV method) happens in the GoGetSSL client area; this plugin cannot do it.

Checking a known list of orders

When you already have order IDs (from a previous report or a PSA configura