# Order Object Storage with the API, gyro CLI and Terraform

https://www.gyrohosting.com/en/knowledgebase/article/order-object-storage-with-api

- **What you will learn**: How to open an Object Storage (S3) or Protected Storage service without the panel: list the plans, get a quote, place the order, reach the first bucket and key, cancel.
- **Time**: 6 minutes

## 1. See the plans and prices

```
gyro storage plans
```

| Plan (`plan`) | Kind | Space | Buckets | Traffic included per month |
| --- | --- | --- | --- | --- |
| `standard-250gb` | Standard | 250 GB | 5 | 250 GB |
| `standard-1tb` | Standard | 1 TB | 10 | 1 TB |
| `standard-5tb` | Standard | 5 TB | 25 | 3 TB |
| `standard-10tb` | Standard | 10 TB | 50 | 5 TB |
| `protected-250gb` … `protected-10tb` | Protected (versioning on) | same | same | same |

Prices are fixed in euro, exclude VAT and are charged in your account currency at today's rate. Each plan lists its `monthly`, `quarterly`, `semiannually` and `annually` price and the list price before the discount (`list_amount`). A plan with `available: false` cannot be ordered right now because of capacity.

Add-ons:

- **Extra traffic** (`extra_traffic`: `1tb` or `5tb`): one-time, valid until the end of the calendar month of purchase.
- **Object lock** (`object_lock_buckets`: 1-50): Protected plans only; the right to create locked (WORM) buckets, billed every cycle.

## 2. Place the order

Get a quote first (nothing is created, nothing is charged):

```
gyro storage create --plan standard-1tb --cycle monthly --name gyro-proje-yedek --dry-run
```

Then order. The CLI asks for confirmation (`--yes` skips it). The price is taken from your balance; a stored card is never used:

```
gyro storage create --plan standard-1tb --cycle monthly --name gyro-proje-yedek
```

The same with the API:

```
curl -X POST https://www.gyrohosting.com/api/v1/client/cloud/storage \
  -H "Authorization: Bearer $GYRO_TOKEN" -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"plan":"standard-1tb","cycle":"monthly","name":"gyro-proje-yedek","confirm":true}'
```

- A real order needs `"confirm": true` and an `Idempotency-Key` header. Sending the same key again never opens a second order; you get the first answer back.
- `quantity` opens several services in one order (max 25). `{n}` in the name becomes the number: `"name": "gyro-yedek-{n}"`.
- Protected plan with object lock and extra traffic: `{"plan":"protected-250gb","object_lock_buckets":2,"extra_traffic":"1tb","confirm":true}`.
- `project_id` puts the service in a project. With a reseller key, `end_customer_id` assigns it to an end customer.

The service is ready in about **one minute** (`inprocess` → `active`). The first bucket and the first access key are created automatically:

```
gyro storage get 12345           # plan, endpoint, region
gyro storage bucket list 12345   # first bucket
gyro storage connect 12345       # S3 connection details
```

The secret of the first key is shown once in the panel. To get a new key over the API use `gyro storage key create 12345` and save the secret at once.

## 3. With Terraform

```
resource "gyro_storage" "yedek" {
  plan  = "standard-1tb"
  cycle = "monthly"
  name  = "gyro-proje-yedek"

  lifecycle {
    prevent_destroy = true   # destroy deletes every bucket and object
  }
}

resource "gyro_storage_bucket" "dosyalar" {
  service_id = gyro_storage.yedek.service_id
  name       = "gyro-proje-dosyalar"
}
```

- `name` changes in place.
- `plan`, `cycle` and `object_lock_buckets` cannot be changed in Terraform; `terraform plan` reports an error. Terraform never re-creates the service, because that would delete the data.
- `terraform destroy` cancels at once and deletes the data. With `delete_immediately = false` only a cancellation request is filed.

## 4. Cancel

```
gyro storage delete 12345 --yes
```

`DELETE /cloud/storage/12345?confirm=true&immediate=true` cancels at once. Access keys, the website and custom domains stop within about a minute. Buckets and objects are **deleted permanently** within minutes and cannot be restored. On Protected Storage, versions under a COMPLIANCE lock or legal hold stay until the lock ends and are billed. Without `immediate` only a cancellation request is filed.

## 5. Error codes

| Code | Meaning | What to do |
| --- | --- | --- |
| `confirm_required` (422) | No confirmation | Check the `quote` in the answer, add `"confirm": true` |
| `insufficient_balance` (402) | The balance does not cover the order | Top up the balance |
| `capacity_unavailable` (409) | No space for this plan right now | Pick a smaller plan or open a ticket |
| `product_not_orderable`, `cycle_invalid` (422) | Wrong plan or cycle | Pick from `gyro storage plans` |
| `invalid_object_lock` (422) | Object lock on a standard plan or out of range | Pick a protected plan, give a number between 1 and the bucket limit |
| `daily_limit` (429) | Daily limit of paid operations reached | Try again tomorrow or ask support to raise it |

## 6. Frequently asked questions

**Is a service ordered with the API different from one ordered in the panel?**

No. Same product, same price, same invoice. It shows in the panel too.

**Is an invoice issued?**

Yes. The order is paid from the balance and an invoice is created. Renewals are paid from the balance at the end of each cycle.

**Can my AI agent order?**

Yes. Give it an API key with ordering permission. We recommend getting a `dry_run` quote and approving it first.

## Next step

- [Mount a bucket on your server](https://www.gyrohosting.com/en/knowledgebase/article/mount-object-storage-bucket-on-server)