System context

1browses and buys [HTTPS]2picks and ships [HTTPS]3charges cards [REST]4quotes tax [REST]5buys labels [REST]6sends email [REST]7sends SMS [REST]

LegendPERSONpersonSYSTEMsoftware systemEXTexternal systemoutside the boundaryusesasync / optionalthe system in scope

Platform shape

“Explain the shape of the platform to a new backend engineer: services, databases, third parties.”

RecommendedC4 diagramc4+4 more

SECTION 01 · API endpoint

POST/v1/ordersBearer api_key

Submit line items and a shipping address. The order starts in PAYMENT_PENDING and the gateway captures the payment asynchronously.

Parameters

Name	In	Type	Description
Idempotency-Key required	header	string	Unique per attempt. Reuse it on retry to get the original response.

Request body

Field	Type	Description
items required	LineItem[]	One or more of { sku, qty }. qty is 1..99.
shipping_address required	Address	name, line1, line2, city, postal_code, country (ISO 3166-1 alpha-2).
currency required	string	ISO 4217 code, for example USD.
payment_method_id required	string	Token from the hosted payment gateway, prefix pm_.
customer_reference	string	Free text the client can search by later, max 64 chars.

Responses

Status	Description
201	Order created; status is PAYMENT_PENDING.
400	Malformed JSON or a field fails validation.
401	Missing or invalid API key.
409	Idempotency-Key reused with a different body.
422	A sku is unknown or has no stock (code sku_unknown or out_of_stock).

Example request

{
  "items": [{ "sku": "MUG-BLUE-12OZ", "qty": 2 }],
  "shipping_address": {
    "name": "Ada Lovelace", "line1": "12 Analytical St",
    "city": "London", "postal_code": "N1 9GU", "country": "GB"
  },
  "currency": "GBP",
  "payment_method_id": "pm_9f3k2",
  "customer_reference": "web-checkout-77120"
}

Example response

{
  "id": "ord_01J8Q2ZK4M",
  "status": "PAYMENT_PENDING",
  "currency": "GBP",
  "total_cents": 2400,
  "items": [{ "sku": "MUG-BLUE-12OZ", "qty": 2, "unit_price_cents": 1200 }],
  "created_at": "2026-09-13T10:02:11Z",
  "updated_at": "2026-09-13T10:02:11Z"
}

Orders REST API

“Document the public REST API for the orders service.”

SECTION 01 · Entity model

ER

Legend#primary key→foreign keyUunique⌘indexed1 / Ncardinalityschema groupaggregate root

Billing data model

“Explain the data model behind subscriptions, plans, invoices, and payments.”

RecommendedER diagramerd+4 more

SECTION 01 · Steps

1
Find the active role
The active role is the one Vault serves today. The other role is the target of this rotation.
bash
```
vault kv get -field=username secret/payments/db
```
If the output is payments_app_a, the target is payments_app_b, and the reverse.
2
Generate the new password and set it on the target role
The password is 32 bytes from /dev/urandom. It never appears in shell history because it lives in a variable.
bash
```
NEWPW=$(openssl rand -base64 32)
psql "$PAYMENTS_ADMIN_DSN" -c "ALTER ROLE payments_app_b WITH PASSWORD '$NEWPW' VALID UNTIL 'infinity';"
```
3
Prove the target role connects
A failed login here costs nothing. A failed login after step 4 costs a pod.
bash
```
PGPASSWORD="$NEWPW" psql -h payments-db.internal -U payments_app_b -d payments -c "select 1;"
```
Stop if this fails. The pods still use the old credential.
4
Write the new credential to Vault
Vault keeps the previous version, so the old username and password stay readable for the rollback.
bash
```
vault kv put secret/payments/db username=payments_app_b password="$NEWPW"
```
5
Reload the pods one at a time
On SIGHUP a pod opens a new pool with the new credential. It drains the old pool over 30 seconds. Wait for the pod to report healthy before the next one.
bash
```
for p in $(kubectl -n payments get pods -l app=payments-api -o name); do
  kubectl -n payments exec "$p" -- kill -HUP 1
  kubectl -n payments wait --for=condition=Ready "$p" --timeout=90s
done
```
Watch the payments-api error rate during the loop. Stop the loop on any rise above 0.1%.
6
Confirm no session uses the old role
The old pools drain 30 seconds after the last reload. A session that stays means one pod did not reload.
bash
```
psql "$PAYMENTS_ADMIN_DSN" -c "select count(*) from pg_stat_activity where usename = 'payments_app_a';"
```
7
Expire the old role's password
The old role keeps its grants, so the next rotation reuses it. Only its password ends.
bash
```
psql "$PAYMENTS_ADMIN_DSN" -c "ALTER ROLE payments_app_a VALID UNTIL '$(date -u -d '+1 hour' +%FT%TZ)';"
```
One hour, not now. A pod that restarts during the drain must still be able to reconnect with the old credential.
Record the rotation
Post the date, the new active role, and your name in

Rotate the payments database credentials

“Runbook for rotating the payments database credentials without downtime.”

Recommendedrunbooksteps+3 more

SECTION 01 · Roadmap