> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.ipxo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Lease an IPv4 Subnet

> End-to-end flow for leasing an IPv4 subnet using the IPXO API (search → cart → checkout → order).

# Lease an IPv4 Subnet

This guide walks through the complete process of leasing an IPv4 subnet using the IPXO API — from discovering available subnets to successfully placing an order.

By the end of this flow, you will have:

* Selected an available IPv4 subnet
* Added it to a cart
* Completed checkout
* Created an active order (and subscription)

## Prerequisites

Before starting this flow, make sure you have:

* A valid access token (`{access_token}`)
* Your tenant UUID (`{tenant_uuid}`)
* At least one:
  * billing address
  * payment method (card or credits)

If not, see **Authentication** and **Portal setup** first.

## Flow overview

At a high level, leasing a subnet consists of these steps:

1. Search for available subnets
2. Add a subnet to cart
3. Review cart and cart items
4. Attach billing address
5. Attach payment method (and optionally credits)
6. Checkout cart
7. Verify created order

Each step builds on identifiers returned by the previous one.

***

## 1) Search for available subnets

> [Try it](/api-reference/market/search-available-subnets)

Start by searching the IP market for IPv4 subnets that match your requirements.

```bash theme={null}
curl 'https://apigw.ipxo.com/billing/v1/{tenant_uuid}/market/search?prefix_length=24&geo_country_code=US&limit=2&sort=price' \
-X GET \
-H 'Authorization: Bearer {access_token}'
```

### What this does

* Queries the IPXO marketplace
* Returns available subnets filtered by:
  * prefix length (`/24`)
  * country (`US`)
  * sorted by lowest price first

### What to save from the response

From the selected subnet, store:

* `address` → `{address}`
* `prefix_length` → `{cidr}`

These values are required to add the subnet to your cart.

***

## 2) Add the selected subnet to cart

> [Try it](/api-reference/cart/add-item-to-shopping-cart)

Once you choose a subnet, add it to the tenant’s cart.

```bash theme={null}
curl 'https://apigw.ipxo.com/billing/v1/{tenant_uuid}/cart/items' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {access_token}' \
--data-raw '{
    "product_type": "ipv4",
    "billing_cycle": 1,
    "product_fields": {
      "address": "{address}",
      "cidr": {cidr}
    }
  }'
```

### What this does

* Creates (or reuses) an active cart
* Adds the IPv4 subnet as a ***recurring monthly product***

### Response

* No response body
* `HTTP 204 No Content`

The cart now exists and contains your subnet.

***

## 3) View cart summary

> [Try it](/api-reference/cart/current-cart)

Retrieve the current cart to get totals and the cart identifier.

```bash theme={null}
curl 'https://apigw.ipxo.com/ecommerce/public/{tenant_uuid}/cart' \
-X GET \
-H 'Authorization: Bearer {access_token}'
```

### What to save from the response

* `uuid` → `{cart_uuid}`

This UUID is required for all remaining cart operations.

***

## 4) List cart items

> [Try it](/api-reference/cart/list-cart-lines)

Inspect what exactly has been added to the cart.

```bash theme={null}
curl 'https://apigw.ipxo.com/ecommerce/public/{tenant_uuid}/cart/{cart_uuid}/lines' \
-X GET \
-H 'Authorization: Bearer {access_token}'
```

### Why this is useful

* Verify the correct subnet is in the cart
* Confirm pricing and billing period
* Retrieve cart line identifiers if needed later

***

## 5) List company billing addresses

> [Try it](/api-reference/address/list-customer-billing-addresses)

A billing address is required before checkout.

```bash theme={null}
curl 'https://apigw.ipxo.com/ecommerce/public/{tenant_uuid}/addresses?filter%5Baddressable_type%5D=customer' \
-X GET \
-H 'Authorization: Bearer {access_token}'
```

### What to save from the response

* `uuid` → `{address_uuid}`

***

## 6) Attach billing address to cart

> [Try it](/api-reference/cart/create-cart-address)

Assign the selected billing address to the cart.

```bash theme={null}
curl 'https://apigw.ipxo.com/ecommerce/public/{tenant_uuid}/cart/{cart_uuid}/addresses/{address_uuid}' \
-X POST \
-H 'Authorization: Bearer {access_token}' \
-H 'Content-Type: application/json' \
--data-raw '{"type":"billing"}'
```

### What this does

* Associates the cart with a billing address
* Enables checkout and invoice generation

***

## 7) List available payment methods

> [Try it](/api-reference/payment/list-payment-methods)

Retrieve saved payment methods for the tenant.

```bash theme={null}
curl 'https://apigw.ipxo.com/ecommerce/public/{tenant_uuid}/payment-methods?per_page=999' \
-X GET \
-H 'Authorization: Bearer {access_token}'
```

### What to save from the response

* `uuid` → `{payment_method_uuid}`

***

## 8) Attach payment method to cart

> [Try it](/api-reference/cart/update-cart-payment-method)

Assign the selected payment method to the cart.

```bash theme={null}
curl 'https://apigw.ipxo.com/ecommerce/public/{tenant_uuid}/cart/{cart_uuid}/payment-method/{payment_method_uuid}' \
-X PATCH \
-H 'Authorization: Bearer {access_token}' \
-H 'Content-Type: application/json' \
--data-raw '{}'
```

### What this does

* Sets the payment method used during checkout
* Required even if credits cover part of the total

> ⚠️ **Important:** Currently, it is not possible to complete checkout (pay by card) due to 3DS card security. Please use **Credit balance** to pay for the cart.

***

## 9) (Optional) Check available credit balance

> [Try it](/api-reference/balance/show-balance)

Before checkout, you can check if credits are available.

```bash theme={null}
curl 'https://apigw.ipxo.com/credits/public/{tenant_uuid}/balances?filter[currency]=USD' \
-X GET \
-H 'Authorization: Bearer {access_token}'
```

***

## 10) (Optional) Apply credits to cart

> [Try it](/api-reference/cart/apply-credits-to-cart)

If credits are available, apply them to reduce the payable amount.

```bash theme={null}
curl 'https://apigw.ipxo.com/ecommerce/public/{tenant_uuid}/cart/{cart_uuid}/credits/apply' \
-X POST \
-H 'Authorization: Bearer {access_token}' \
-H 'Content-Type: application/json' \
--data-raw '{"amount": 9}'
```

***

## 11) Checkout cart and create order

> [Try it](/api-reference/cart/checkout-cart)

Finalize the cart and create an order.

```bash theme={null}
curl 'https://apigw.ipxo.com/ecommerce/public/{tenant_uuid}/cart/{cart_uuid}/checkout' \
-X POST \
-H 'Authorization: Bearer {access_token}' \
-H 'Content-Type: application/json' \
--data-raw '{}'
```

### What happens here

* An order is created
* Payment is initiated
* A subscription for the subnet is created in the background

### What to save from the response

* `order.uuid` → `{order_uuid}`

***

## 12) Retrieve order details

> [Try it](/api-reference/order/show-order)

Verify the order status and totals.

```bash theme={null}
curl 'https://apigw.ipxo.com/ecommerce/public/{tenant_uuid}/orders/{order_uuid}' \
-X GET \
-H 'Authorization: Bearer {access_token}'
```

### Successful outcome

* Order status moves to `completed`
* Subnet becomes active
* Recurring billing starts based on the billing cycle

> ℹ️ If order status is `processing`, it’s most likely due to the attached payment method (as mentioned above, card payments via API will not be completed).

***

## Variables created in this flow

| Variable                | Source            | Purpose             |
| ----------------------- | ----------------- | ------------------- |
| `{address}`             | Subnet search     | Add subnet to cart  |
| `{cidr}`                | Subnet search     | Add subnet to cart  |
| `{cart_uuid}`           | Cart summary      | All cart operations |
| `{address_uuid}`        | Addresses list    | Billing assignment  |
| `{payment_method_uuid}` | Payment methods   | Checkout            |
| `{order_uuid}`          | Checkout response | Order tracking      |