Idempotent requests

Some requests must happen only once: a payment, an order, a new database. When the connection drops before the answer arrives, you cannot tell whether the request went through. Send a key with the request, and a retry with the same key answers what the first request did instead of doing it again.

• Make a new random key for each operation you mean to happen once. A UUID fits every route on this page, and uuidgen prints one.
• Send the same key, with the same body, on every retry of that operation.
• Wait for an answer, or for your client to time out, before you retry.
• Make a new key for a new operation, including a second try after a card is declined.

KEY=$(uuidgen)
curl -X POST https://api.coritan.com/api/v1/payments/invoices/5011/charge \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d '{"payment_method_id": 812}'

To retry, run the same command with the same $KEY.

Payments

The first payment attempt as it is now, with the same id. Nothing is charged a second time. Once that payment has paid the whole invoice, a repeat answers 400 with No remaining balance on invoice instead, so read the invoice to confirm it is paid. A declined attempt stays declined under its key: send a new key to try again.

Floating IP orders

The first order. POST /services/order sets message to Order already submitted within two minutes of the first request, and to Replayed existing IP order once the order has an invoice. POST /orgs/{org_slug}/portal/ips/order adds "replay": true. Order a floating IP describes the order and its statuses.

Databases

The database the first request created on that server, with its password. When the first request stopped part way, the repeat finishes creating it.

Support conversations and messages

The conversation or the message the first request created.

Storefront orders

The answer the first request received.

Plan changes

The answer the first request received, while it still describes the service: an upgrade whose invoice is still waiting to be paid, or a change to the plan the service is still on. Otherwise the request runs again, so a key you send after moving to another plan asks for the change again.

Store API cart completion

The status and the body the first request received. Completing a cart that already has its order answers that order again, with or without a key.

When the first request answered an error, a retry with the same key runs the request again.

Make a new key for each different storefront order or plan change. A key sent again with a different product, plan, hostname or config fails.

POST /services/order also catches a repeat that carries no key. An order for the same product, price and hostname as one you placed in the last two minutes answers that first order, with message set to Order already submitted, while the first is still pending. This holds for every product, and for a floating IP order whatever key it sends. Other products accept idempotency_key and ignore it. To order two services on the same plan at once, give each its own hostname. Order a service describes the order and its answer.

POST /orgs/{org_slug}/storefront/order does the same for an organization's customers, with or without a key, and marks the answer "replayed": true.

Other routes take no key, and a repeat is a new request. Before you retry one whose answer you did not receive, read the record it changes: list your invoices to see whether a payment went through, or your services to see whether an order arrived.

The customer portal's POST /orgs/{org_slug}/portal/invoices/{invoice_id}/charge takes no key. Once the invoice is paid, it answers 404 with Invoice not found or already paid.