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:

Search for available subnets
Add a subnet to cart
Review cart and cart items
Attach billing address
Attach payment method (and optionally credits)
Checkout cart
Verify created order

Each step builds on identifiers returned by the previous one.

1) Search for available subnets

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

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

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

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

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

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

Inspect what exactly has been added to the cart.

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

A billing address is required before checkout.

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

Assign the selected billing address to the cart.

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

Retrieve saved payment methods for the tenant.

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

Assign the selected payment method to the cart.

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

9) (Optional) Check available credit balance

Before checkout, you can check if credits are available.

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

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

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

Finalize the cart and create an order.

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

Verify the order status and totals.

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

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

Guides

API Reference

Lease an IPv4 Subnet

Lease an IPv4 Subnet

Prerequisites

Flow overview

1) Search for available subnets

What this does

What to save from the response

2) Add the selected subnet to cart

What this does

Response

3) View cart summary

What to save from the response

4) List cart items

Why this is useful

5) List company billing addresses

What to save from the response

6) Attach billing address to cart

What this does

7) List available payment methods

What to save from the response

8) Attach payment method to cart

What this does

9) (Optional) Check available credit balance

10) (Optional) Apply credits to cart

11) Checkout cart and create order

What happens here

What to save from the response

12) Retrieve order details

Successful outcome

Variables created in this flow

​Lease an IPv4 Subnet

​Prerequisites

​Flow overview

​1) Search for available subnets

​What this does

​What to save from the response

​2) Add the selected subnet to cart

​What this does

​Response

​3) View cart summary

​What to save from the response

​4) List cart items

​Why this is useful

​5) List company billing addresses

​What to save from the response

​6) Attach billing address to cart

​What this does

​7) List available payment methods

​What to save from the response

​8) Attach payment method to cart

​What this does

​9) (Optional) Check available credit balance

​10) (Optional) Apply credits to cart

​11) Checkout cart and create order

​What happens here

​What to save from the response

​12) Retrieve order details

​Successful outcome

​Variables created in this flow

Lease an IPv4 Subnet

Prerequisites

Flow overview

1) Search for available subnets

What this does

What to save from the response

2) Add the selected subnet to cart

What this does

Response

3) View cart summary

What to save from the response

4) List cart items

Why this is useful

5) List company billing addresses

What to save from the response

6) Attach billing address to cart

What this does

7) List available payment methods

What to save from the response

8) Attach payment method to cart

What this does

9) (Optional) Check available credit balance

10) (Optional) Apply credits to cart

11) Checkout cart and create order

What happens here

What to save from the response

12) Retrieve order details

Successful outcome

Variables created in this flow