# Order a service

> Choose a product, configure it on its own page with any add-ons, pay for the whole order on one invoice, and follow it while we set it up.

Source: https://www.coritan.com/docs/get-started/order-a-service/

In the dashboard:

- /dashboard/order: https://www.coritan.com/dashboard/order
- /dashboard/order/placed/…: https://www.coritan.com/dashboard/order/placed

Order anything Coritan sells from the **Order a service** page of the dashboard. Each product has an order page of its own: the plan comes first, then the product's own questions, then its *add-ons*, which are other products you can buy in the same order. One first invoice covers the whole order, and you pay it on the page the order lands on.

## Before you begin

- [Create an account](/docs/get-started/create-an-account/) and sign in.
- Most accounts pay the first invoice before setup starts. Credit on your account pays it first, so [add credit](/docs/billing/add-credit/) if you want the order to start in one go. You can also pay by card or PayPal once you have placed the order.
- Hourly billing needs a minimum total of deposits on your account before you can choose it. [How hourly billing works](/docs/billing/hourly-billing/) explains the rule.

## Choose a product

In the sidebar, select **Order service**. The **Order instance**, **Order server** and **Order floating IP** buttons elsewhere in the dashboard open the same order pages.

The page lists the products open to your account, each with its starting price. Cloud Compute and Container Apps come first, with their prices by the month and by the hour, and each shows **Sold out** when none of its plans can be ordered right now. Under **Quick start**, four common setups open a compute order with the software already chosen: a Minecraft server, an Ubuntu instance, a Node.js app and a PostgreSQL database. Every other product follows in its category:

| Category | Product | Also an add-on for | Guide |
| --- | --- | --- | --- |
| Compute | Cloud Compute | — | [Create an instance](/docs/cloud-compute/create-an-instance/) |
| Compute | Container Apps | — | [Order a server](/docs/managed-containers/order-a-server/) |
| Network and security | Floating IPs | Cloud Compute, Container Apps | [Order a floating IP](/docs/floating-ips/order-a-floating-ip/) |
| Network and security | DDoS Shield | Cloud Compute, Container Apps, Floating IPs | [Order and use a custom profile](/docs/ddos-shield/custom-profiles/) |
| Email | Mail Hosting | Cloud Compute, Container Apps | [Order Mail Hosting or SMTP Relay](/docs/mail/order-a-mail-service/) |
| Email | SMTP Relay | Cloud Compute, Container Apps, Mail Hosting | [Order Mail Hosting or SMTP Relay](/docs/mail/order-a-mail-service/) |
| Storage | Object Storage | — | [Order Object Storage](/docs/object-storage/order-object-storage/) |
| Storage | Snapshot Storage | Container Apps | [Order more snapshot storage](/docs/snapshots/add-snapshot-storage/) |
| Edge Proxy | External Server | — | [Connect a server you host elsewhere](/docs/proxies/external-servers/connect-an-external-server/) |

Select a card to open the product's order page. When your account holds credit, a line above the cards shows the balance, with **Add credit** beside it. For bare metal, colocation or more than the catalogue lists, select **Open a ticket** at the end of the page and our team sends you a quote.

## Configure an instance or a server

The **Cloud Compute** and **Container Apps** pages have five numbered sections: **Plan**, then **Operating system** for an instance or **Software** for a server, then **Location**, **Settings** and **Add-ons**. Every section except **Software** starts with an answer chosen for you, so you can order an instance without opening one. A server needs its software chosen, unless a quick start chose it.

1. Select the **Cloud Compute** or **Container Apps** card.
2. Under **Plan**, choose the billing cycle at the top of the section. Longer terms name what they save against paying monthly.
3. Choose a **Hardware tier** if the page offers more than one, then a plan under **Size**. Each row shows its price for the cycle, its vCPUs, memory and storage.
4. Under **Operating system**, choose a distribution and a release. Under **Software**, choose what the server runs, then its version.
5. Under **Location**, choose a data centre. We start with the one nearest you. A location marked **Sold out** has no room for this plan.
6. Under **Settings**, check the **Hostname** of an instance or the **Server name** of a server. An instance also takes **SSH keys** and the **Public IPv4 address** switch. Answer any **Plan options** too: an option with a price is added to every charge.
7. Under **Add-ons**, turn on anything you want to buy with it, as [Add products to the order](#add-products-to-the-order) describes.
8. Place the order, as [Place the order](#place-the-order) describes.

[Create an instance](/docs/cloud-compute/create-an-instance/) and [Order a server](/docs/managed-containers/order-a-server/) describe each section in full.

## Configure any other product

Every other order page starts with its plans as cards, each with its price for the billing cycle chosen at the top right. We start with the plan the catalogue recommends, or else the first one on sale, and with the monthly cycle when the plan sells it. The product's own questions follow, such as the region of a floating IP or the domain of a mail service, and then the add-ons it takes. The guide for each product, in the table under [Choose a product](#choose-a-product), walks through its page.

## Add products to the order

An add-on is another product bought in the same order. It goes on the order's first invoice and becomes a service of its own, which you can cancel on its own later. The **Add-ons** section lists what the product takes:

| On the order page for | You can add |
| --- | --- |
| Cloud Compute | Up to four floating IPs, a DDoS Shield profile, Mail Hosting and SMTP Relay |
| Container Apps | One dedicated IPv4 address, a DDoS Shield profile, Snapshot Storage, SMTP Relay and Mail Hosting |
| Floating IPs | A DDoS Shield profile |
| Mail Hosting | SMTP Relay |

- Each card shows the add-on's price for the order's billing cycle. An add-on that is not sold on that cycle is billed monthly, and its card says so.
- Turn on a card's switch to add it. Its fields appear under it, such as how many floating IPs to add, a profile name, a plan or a domain.
- A card that cannot be added says why in its place, and its switch stays off. For example, the address pool in the order's location may be sold out, or a DDoS Shield profile may have no address in the order to protect.
- Free plans are never add-ons. Order a free plan on its own page.
- When the services are ready, we attach the floating IPs or the dedicated address to the new instance or server, and the DDoS Shield profile protects the addresses in the order.

## Place the order

The summary under **Your order** sits beside the sections. On a phone it follows them, and **Review order** at the bottom of the screen takes you to it. It lists each choice, the lines we bill under **Billed**, and the **Total** for each billing cycle, with any one-time setup fee, what a longer term saves and what is due today. The line under the total says how the first invoice will be paid.

1. Check the summary. **Change** beside a choice takes you back to its section.
2. If the button is greyed out, read the line under it. It names the first answer still missing, such as `Choose a location.`, and selecting it takes you to that section.
3. If a verification check appears above the button, complete it. It appears on an order whose plan costs nothing.
4. Select the button. Its words follow the first payment:
   - **Place order and pay** when you pay an invoice after placing the order.
   - **Order for free** when nothing in the order costs anything.
   - **Deploy instance**, **Deploy server** or **Place order** when your credit pays the first invoice, or when your account is billed in arrears.

If we refuse the order, **Could not place the order** appears above the button with the reason, and your choices stay as they were. Otherwise the order's own page opens, as [Pay and follow the order](#pay-and-follow-the-order) describes.

## How the first payment works

When you place an order, we raise one first invoice for everything in it: one billing period of the plan (one hour on hourly billing), the first period of each add-on and any setup fees. The summary shows which of these cases applies before you place the order:

**Paid from your credit balance**
: Your credit covers the first invoice. We take it from your balance when you place the order, and setup starts straight away.

**Pay on the next page**
: Your credit does not cover the first invoice. We apply the credit you have, and the order's page asks for the rest. Setup starts once it is paid.

**Billed to your account**
: Your account is billed in arrears. Setup starts when you place the order, and the first invoice follows at the end of the period. Coritan sets an account up this way, and you cannot choose it. Hourly, daily and weekly prices are paid in advance on every account.

**Nothing to pay**
: Nothing in the order costs anything. Setup starts when you place it.

An order whose plan costs $0 needs the verification check, even when its add-ons cost money, and each account can hold one free service of each kind. The Cloud Compute and Container Apps pages never show the check, and coritan.com does not sell the free Container Apps plan.

While an invoice is unpaid, we keep trying to take it from your credit and your saved payment method. We cancel a Container Apps or floating IP order whose first invoice is still unpaid after two days, by default, so pay it soon after ordering.

## Pay and follow the order

The order's page shows three steps along the top: **Order placed**, the payment, then **Setting up**. **What you ordered** lists the service and each add-on with its status and price, and **What happens next** says what to do with each one once it is ready.

When the title reads **Order placed, payment due**, pay in the page:

1. Under **Pay invoice**, check the amount under **Due now**.
2. Choose how to pay. **Account credit** and your saved cards and PayPal accounts are under **On your account**, and a new card or PayPal under **Pay another way**.
3. Select the button under the choices. It reads **Pay with credit** when your credit covers the amount and **Apply credit** when it covers part of it. For a card, it names the amount. A new card opens a card form in the page, where you select **Pay now**, and PayPal shows its own buttons. A provider with a checkout page of its own sends you there and brings you back afterwards.

Once the payment goes through, the page shows **Paid** and moves on to **Setting up**. It checks every few seconds while we set the order up, and the title becomes **Your order is ready** when every service is active. A button at the top of the page then opens the new service, and **Order something else** takes you back to the catalogue.

When nothing is due, the page shows **Paid** with what your credit paid, or **Nothing to pay now** for an order that is free or billed in arrears, and setup has already started. To pay later, leave the page and pay the invoice under [Invoices](/docs/billing/invoices/). Setup starts on its own once it is paid.

## Result

Every service in the order appears on the [Services](/docs/get-started/services/) page with the status `pending`. It moves to `provisioning` while we set it up and to `active` when it is ready. The first invoice is under [Invoices](/docs/billing/invoices/), with a line for each service in the order and one for each setup fee.

## Troubleshooting

The button under the summary is greyed out
: The line under it names what is missing, such as `Choose a location.` Select it to go to that section.

An add-on's switch is greyed out
: The card says why under its description. Change what it names, such as the location or the public IPv4 switch, or order the product on its own page later.

`Hourly billing needs a deposit first.`
: Your account has not deposited enough yet to use hourly billing. The **Size** card says how much more it needs. Select **Top up credit** to add it, or choose another cycle.

`Every location is sold out for this plan`
: No data centre has room for this size on this tier right now. Capacity differs by plan, so try another size or hardware tier.

`That location has no capacity for this plan.`
: The location filled up after you chose it. Choose another under **Location**.

**Could not load the prices**
: The list of products did not load. Select **Try again**.

`Complete the verification check.`
: The plan costs nothing, so the order needs the check above the button. Complete it, then place the order.

`The verification check did not pass. Complete it and try again.`
: The check expired or failed. Complete it again, then place the order again.

A message that ends `Upgrade or remove one to create another.`
: You already hold the one free service of this kind that an account can have. Upgrade it or cancel it before you order another.

`Too many requests for this action. Please wait and try again.`
: Your account placed too many free orders in a short time. Wait ten minutes and try again.

The order's page shows an order you placed earlier
: You placed the same order in the last two minutes, and it is still waiting to start. We show that order again instead of creating a second one. To order a second service on the same plan, give it a different name.

`Payment cancelled; the invoice is still due.`
: You came back from a checkout page without paying. Choose a way to pay again under **Pay invoice**.

**Could not load the invoice**
: The order is placed, but its invoice did not load on the order's page. Pay it under [Invoices](/docs/billing/invoices/) instead.

The order's page still says **Setting up**
: The page stops checking after a few minutes. Reload it, or follow the service on the [Services](/docs/get-started/services/) page.

## Related

- [Manage your services](/docs/get-started/services/)
- [Pay an invoice](/docs/billing/invoices/)
- [Change a service's plan](/docs/billing/change-plan/)
- [Data centres and locations](/docs/platform/data-centres/)

## With the API

The catalogue needs no authentication. List the products with [`GET /products/`](/docs/api/reference/client/catalog/#op-get-api-v1-products). It returns up to `per_page` products (default 100, at most 200) from `page`, and `group` or `hardware_tier` (a tier's slug) narrow the list. It leaves out the free Container Apps plan, which coritan.com does not sell:

```bash
curl "https://api.coritan.com/api/v1/products/?per_page=200"
```

Each product carries what an order needs:

`id`
: The `product_id` to order.

`module_name`
: The kind of product: `vps` for Cloud Compute and `container` for Container Apps. The others are `ip`, `antiddos`, `mail`, `smtp_relay`, `object_storage`, `storage` (Snapshot Storage) and `external_server`.

`pricing`
: One entry per billing cycle. Its `id` is the `pricing_id` to order, with `billing_cycle`, `price`, `setup_fee`, `currency` and `is_active`. Only an active entry can be ordered.

`config_options`
: The plan's options, which the dashboard shows under **Plan options**. Put an option's `field_name` in `config` to take it. Its `price_modifier` is added to each charge.

`is_orderable_now`, `stock_status` and `availability_reason`
: Whether the product can be ordered anywhere right now. `stock_status` is `in_stock` or `out_of_stock`.

`locations`
: For compute products, each location's `code`, `name` and `country_code`, whether it is `orderable` for this product, and a `reason` when it is not.

[`GET /products/{product_id}`](/docs/api/reference/client/catalog/#op-get-api-v1-products-product-id) returns one product in the same shape. [`GET /locations`](/docs/api/reference/client/catalog/#op-get-api-v1-locations) lists the active locations with their airport `code`, `name`, `country_code` and `timezone`. [`GET /locations/availability`](/docs/api/reference/client/catalog/#op-get-api-v1-locations-availability) checks capacity per location for a size: it takes `module` (`vps` or `container`), and optionally `hardware_tier_id`, `memory_mb`, `disk_gb` with `template_id` for an instance, or `disk_mb` for a server. Each location in the answer has `available`, and the `reason` `No eligible capacity` when it is `false`.

Place the order with [`POST /services/order`](/docs/api/reference/client/services/#op-post-api-v1-services-order). This one needs your access token. The example orders an instance with two floating IPs and a DDoS Shield profile:

```bash
curl -X POST https://api.coritan.com/api/v1/services/order \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": 7,
    "pricing_id": 21,
    "hostname": "web-1.example.com",
    "idempotency_key": "3f1c9a52-8e0d-4d6b-b7a4-5c2e9f0a1d36",
    "config": {
      "location": "fra",
      "template_id": 4,
      "hostname": "web-1.example.com",
      "order_ipv4": true
    },
    "addons": [
      {"product_id": 31, "quantity": 2},
      {"product_id": 44, "config": {"profile_name": "web-1"}}
    ]
  }'
```

`product_id` and `pricing_id`
: The product and one of its active prices.

`hostname`
: Optional. The name the service is listed under, up to 100 characters.

`config`
: The product's settings. A compute order needs `location`, an airport code such as `fra`. [Create an instance](/docs/cloud-compute/create-an-instance/) and [Order a server](/docs/managed-containers/order-a-server/) list the other keys for each product.

`addons`
: Optional. Up to 8 products bought with this one, as [Add-ons in the order](#add-ons-in-the-order) describes.

`idempotency_key`
: Up to 64 characters. A floating IP order needs one, and a retry with the same key returns the first order. [Idempotent requests](/docs/api/idempotency/) explains how to use it.

`turnstile_token`
: Only for an order whose plan costs $0, when [`GET /auth/turnstile`](/docs/api/reference/client/authentication/#op-get-api-v1-auth-turnstile) answers `"enabled": true`. It is needed even when the order's add-ons cost money. The token comes from the verification widget in a browser, so place such orders on the website.

### Add-ons in the order

Each entry in `addons` takes these fields:

`product_id`
: The add-on product. [Add products to the order](#add-products-to-the-order) lists the products each product takes.

`pricing_id`
: Optional. One of the add-on's active prices. Without it, we take its price on the order's billing cycle, else its monthly price, else its first active price. An hourly price needs the same deposit as an hourly service.

`quantity`
: Optional, `1` when left out, at most `8`. Only a floating IP takes more than 1, and each one becomes a service of its own. An instance takes up to 4 floating IPs, and a server takes one `/32` address.

`config`
: Optional. The settings an order of that product on its own takes. A floating IP comes from a pool in the order's `location` unless you name one in `pool_id`, and takes only the prefix length its product sells. A DDoS Shield profile takes `profile_name` (up to 40 characters, the order's `hostname` when left out), `protection_mode`, `default_action`, `per_source_pps` and `aggregate_pps`. It protects the addresses in the order, so leave `ip_service_ids` out.

An instance takes floating IPs only with `"order_ipv4": true` in its `config`, because the included address stays its free primary address. A DDoS Shield profile needs an address in the order: an instance's included IPv4, a floating IP added to a server, or the floating IP being ordered. When we cannot take one add-on, we refuse the whole order and create nothing.

A new order answers `201`:

```json
{
  "service": {"id": 1042, "status": "pending", "billing_cycle": "monthly", "amount": 12.0, "hostname": "web-1.example.com"},
  "addons": [
    {"id": 1044, "status": "pending", "billing_cycle": "monthly", "amount": 3.0},
    {"id": 1045, "status": "pending", "billing_cycle": "monthly", "amount": 3.0},
    {"id": 1046, "status": "pending", "billing_cycle": "monthly", "amount": 5.0}
  ],
  "invoice_id": 5531,
  "requires_payment": true,
  "checkout_available": true,
  "amount_due": "23.00",
  "message": "Invoice created; pay to start provisioning"
}
```

`service` is the new service, in the shape [Manage your services](/docs/get-started/services/#with-the-api) describes. `addons` holds a service for each add-on, one per unit of `quantity`, in the order you listed them. An instance's included IPv4 is a service of its own too, but it is not in `addons`. When `requires_payment` is `true`, pay `invoice_id` as [Pay an invoice](/docs/billing/invoices/#with-the-api) shows; setup starts once it is paid. `message` says what happened:

| `message` | Meaning |
| --- | --- |
| `Payment applied from credit balance; provisioning started` | Credit paid the first invoice. |
| `Invoice created; pay to start provisioning` | `amount_due` is still to pay. |
| `Provisioning started` | Nothing was due first, because the order is free or the account is billed in arrears. |
| `Provisioning started (floating IP will auto-attach)` | As above, for an instance ordered with its included IPv4. |
| `Order already submitted` | The same product, price and `hostname` were ordered in the last two minutes and are still `pending`. You get that order back, with its add-ons. |
| `Replayed existing IP order` | A floating IP order was sent again with the same `idempotency_key`. |

The errors you can act on:

- `404` `Product not found` or `Pricing tier not found`: the id is wrong, or the price is not active.
- `403` `You must deposit at least $10 before using hourly billing services`: the account cannot use hourly billing yet. [`GET /billing/hourly-eligibility`](/docs/api/reference/client/billing/#op-get-api-v1-billing-hourly-eligibility) returns the deposit it still needs in `remaining`.
- `403` with `"error": "plan_not_sold_here"`: the free Container Apps plan cannot be ordered here.
- `403` with `"error": "turnstile_failed"`: the verification check was missing or did not pass on an order whose plan costs $0.
- `409` with `"error": "free_limit_reached"`: the account already holds a free service of this kind.
- `422` with `{"detail": {"errors": [...]}}`: `config` is incomplete, the location has no room, or an add-on cannot go on this order. Examples are `location is required (airport code, e.g. iad)`, `Keep the included public IPv4 to add floating IPs. It is free, and floating IPs are extra addresses on top of it.` and `A server takes one floating IP, so add at most one.`
- `422` for a floating IP, ordered on its own or as an add-on, with a `prefix_len` its product does not sell. The message ends `Leave prefix_len out or set it to 29.` for a product that sells `/29` subnets.
- `422` `idempotency_key is required for IP orders`, and `409` `An identical IP order is already in progress; retry in a moment` when the first request with that key has not finished.
- `429` with `"error": "rate_limited"`: more than 12 free orders from the account in ten minutes. [Rate limits](/docs/api/rate-limits/) lists every limit.

## API

- `POST /api/v1/services/order`: Order a platform service, and any add-ons bought with it (https://www.coritan.com/docs/api/reference/client/services/#op-post-api-v1-services-order)
- `GET /api/v1/products/`: List products (https://www.coritan.com/docs/api/reference/client/catalog/#op-get-api-v1-products)
- `GET /api/v1/products/{product_id}`: Get product (https://www.coritan.com/docs/api/reference/client/catalog/#op-get-api-v1-products-product-id)
- `GET /api/v1/locations`: List locations (https://www.coritan.com/docs/api/reference/client/catalog/#op-get-api-v1-locations)
- `GET /api/v1/locations/availability`: Locations availability (https://www.coritan.com/docs/api/reference/client/catalog/#op-get-api-v1-locations-availability)