Ordering through the API

Three calls: read the catalogue, place the order, follow the provisioning. Payment fits inside the order or in a separate call.

GET /catalog/products

Permissions: catalog:read

Private products and retired categories are never listed, and cannot be ordered.

GET /catalog/products/{shortname}

Permissions: catalog:read

{ "data": {
  "shortname": "vps-1",
  "category": "vps",
  "title": { "fr-fr": "VPS Xeon 1", "en-us": "VPS 1" },
  "providerType": null,
  "recurrences": ["monthly", "yearly"],
  "prices": [
    { "recurrence": "monthly", "priceCents": 500 },
    { "recurrence": "yearly", "priceCents": 5500 }
  ],
  "addons": [
    { "shortname": "extra-ram-1gb",
      "title": { "fr-fr": "+1 Go RAM", "en-us": "+1 Gb RAM" },
      "kind": "RESOURCE_DELTA", "maxQuantity": 10,
      "prices": [ { "recurrence": "monthly", "priceCents": 200 } ] }
  ],
  "characteristics": [
    { "key": "os", "label": { "fr-fr": "Système", "en-us": "OS" },
      "kind": "os-picker", "required": true, "sensitive": false,
      "defaultValue": null,
      "options": ["debian-13"],
      "choices": [ { "value": "debian", "label": { "en-us": "Debian" }, "versions": ["13"] } ],
      "companionKeys": ["osVersion"] }
  ]
} }

An add-on (addons[])

A characteristic (characteristics[])

Two companionKeys cases:

• authValue (kind: "auth-credential") needs authType beside it, as PASSWORD or SSH_KEY.
• os (kind: "os-picker") needs osVersion if you send the family and the version separately. The simpler path is to send the composite value from options (debian-13) and nothing else. It is also what POST /services/{code}/reinstall takes.

POST /orders

Permissions: orders:write, plus those of the funding you pick. Required header: Idempotency-Key.

characteristics values are always strings, even for a number.

The payment block

A funding refused before any write leaves no order behind: method not found, method inactive, balance short, cap exceeded.

A zero total, after a 100% discount, settles with no payment and the order goes straight to PAID.

Example

curl -X POST -H "Authorization: Bearer $FRESHPERF_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: 6f1c0b62-4f4b-4f8e-9b06-0c1d7a5c9e21" \
     -d '{
       "lines": [{
         "product": "vps-1",
         "recurrence": "monthly",
         "quantity": 1,
         "characteristics": {
           "os": "debian-13",
           "location": "paris",
           "authType": "SSH_KEY",
           "authValue": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... admin@laptop"
         },
         "addons": [{ "shortname": "extra-ram-1gb", "quantity": 2 }]
       }],
       "customerNote": "Web server migration",
       "payment": { "method": "balance" }
     }' \
     https://api.freshperf.fr/v1/orders

{ "data": {
  "order": {
    "orderNumber": "ORD-20260828-0001",
    "status": "PAID",
    "currency": "EUR",
    "subtotalCents": 900, "taxCents": 180, "discountCents": 0, "totalCents": 1080,
    "amountPaidCents": 1080, "remainingDueCents": 0,
    "promoCode": null, "customerNote": "Web server migration",
    "lines": [ { "productShortname": "vps-1", "recurrence": "monthly", "quantity": 1,
                 "unitPriceCents": 500, "unitTaxCents": 100, "totalCents": 1080,
                 "addons": [ { "shortname": "extra-ram-1gb", "quantity": 2, "unitPriceCents": 200 } ],
                 "configuration": { "os": "debian-13", "location": "paris" } } ],
    "serviceCodes": ["SRV-TKH243-7763"],
    "createdAt": 1787907301139, "paidAt": 1787907315110
  },
  "promoError": null,
  "payment": { "status": "CAPTURED", "paymentId": 244, "amountCents": 1080,
               "invoiceCode": "INV-202608-0084", "balanceCents": 3320 }
} }

Placing an order through the API never touches the cart open in the dashboard.

Refusals

POST /orders/{orderNumber}/pay

Permissions: billing.invoices:pay, plus billing.saved_methods:charge with saved_method. Required header: Idempotency-Key.

Pays what is left due on an order left pending.

curl -X POST -H "Authorization: Bearer $FRESHPERF_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: pay-ORD-20260828-0001" \
     -d '{"method":"saved_method","paymentMethodId":14}' \
     https://api.freshperf.fr/v1/orders/ORD-20260828-0001/pay

Answers the same payment block as POST /orders.

Plus the payment refusals from the table above.

GET /orders and GET /orders/{orderNumber}

Permissions: orders:read

The list returns a summary (orderNumber, status, currency, totalCents, amountPaidCents, remainingDueCents, createdAt, paidAt) and omits drafts. The detail returns the whole order, with lines[] and serviceCodes.

Following the provisioning

1. GET /orders/{orderNumber}: status moves to PAID, then to FULFILLED once every service is in place.
2. serviceCodes fills with the codes created. It is the link between an order and the services it produced.
3. GET /services/{code} returns provisioned: false while the infrastructure comes up, then true.

Provisioning runs in the background and takes a few minutes. Poll every 10 to 30 seconds.