API Example: Searching, Ordering, and Assigning Subnets in the IPXO Marketplace.

This comprehensive guide will walk you through the process of using the IPXO API to search for subnets in the Marketplace, add a subnet to your cart, successfully place an order, and assign the leased subnet to your ASN. Additionally, you will learn how to list your leased subnets and download the associated LOA (Letter of Authorization) documents using the API.

All operations in this context utilize the Billing API and E-commerce API

Before using the API, please make sure to review any API limitations pertaining to the actions you intend to perform.

1. 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)

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

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

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 the 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.

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.

Why is this 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.

6. Attach billing address to cart

Assign the selected billing address to the cart.

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.

8. Attach payment method to cart

Assign the selected payment method to the cart.

What this does

• Sets the payment method used during checkout

• Required even if credits cover part of the total

9. Check available credit balance (Optional Step)

Before checkout, you can check if credits are available.

10. Apply credits to cart (Optional Step)

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

11. Checkout cart and create order

Finalize the cart and create an order.

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.

Successful outcome

• Order status moves to completed

• Subnet becomes active

• Recurring billing starts based on the billing cycle

Variables created in this flow

Terminate a Subscription (Subnet / Service)

This guide explains how to terminate an active subscription (for example, an IPv4 subnet lease) using the IPXO API.

A termination can be:

• End of period – service remains active until the current billing period ends

• Immediate – service is terminated right away (irreversible)

Prerequisites

Before starting this flow, you need:

• A valid access token ({{access_token}})

• Your tenant UUID ({{tenant_uuid}})

• At least one active subscription

Flow overview

At a high level, terminating a subscription consists of:

1. Listing active subscriptions

2. Selecting a subscription to terminate

3. Creating a termination request

4. (Optional) Cancelling a pending termination

1. List active subscriptions

Start by retrieving all active subscriptions for the tenant.

What this does

• Returns all currently active subscriptions

• Each subscription represents a recurring service (e.g. subnet lease)

What to save from the response

From the selected subscription:

• uuid → {{subscription_uuid}}

2. Terminate a subscription

Create a termination request for the selected subscription.

Termination types

• end_of_period -Service remains active until current billing period ends

• immediate -Service is terminated immediately (cannot be undone)

Note: Immediate terminations are irreversible.
End-of-period terminations can be cancelled before the period ends.

Termination reason

There are more termination reasons, but for the API example, only 1 is provided/selected. If needed, this part of the documentation can be expanded

What this does

• Creates a termination request

• Marks the subscription for termination

• Does not immediately delete the service (unless immediate)

What to save from the response

• uuid → {{subscription_termination_uuid}}

3. List termination requests (Optional Step)

If you need to:

• verify termination status

• retrieve the termination UUID

• check whether a termination can be cancelled

List pending termination requests for the subscription.

When this is useful

• You didn’t store the termination UUID

• You want to check if termination is still pending

• You want to allow the user to undo termination

4. Cancel a pending termination (Optional Step)

If the termination type was end_of_period, it can be cancelled before it is executed.

What this does

• Cancels a pending termination request

• Keeps the subscription active

• Restores normal recurring billing

Subscription lifecycle summary

7. Variables created in this flow

Leased Subnet Management: Assign ASN (Create LOA)

This flow shows how to attach an ASN to a leased IPv4 subnet by purchasing a LOA (Letter of Authorization) add-on, and then how to check LOA status for the service.

Use this when a customer has an active leased subnet and wants:

• ROA / RPKI support

• route objects (RADB / ROUTE)

• inetnum automation (WHOIS)

Conceptually: you validate ASN → add LOA product to cart → checkout → LOA gets created for the service.

Prerequisites

You need:

• {{access_token}} (Auth flow)

• {{tenant_uuid}}

• {{asn}} (the ASN to assign)

• {{subnet}} (notation string, e.g. 82.27.122.0/24)

• {{company_name}} (used in LOA product fields)

• A billing {{address_uuid}} available for the tenant (from address list)

• A payment method {{payment_method_uuid}} available for the tenant (from payment method list)

If you plan to check LOA status afterwards, you also need:

• {{service_uuid}} of the leased subnet service (typically from “List Services” step in the lease flow)

Flow overview

1. Validate ASN for the subnet

2. Add LOA/ASN item to cart

3. Complete checkout (standard cart steps)

4. List LOAs for the service to confirm status (Pending/Active)

1. Validate ASN for the subnet

Before adding LOA to cart, validate that the ASN is eligible for the provided subnet(s).

2. Add LOA / ASN item to cart

This adds a LOA product (one-time) to the cart, configured with your ASN + subnet.

What this does

• Adds a one-time purchasable LOA item to the cart

• Specifies optional automation:

  • roa (RPKI / ROA support)

  • radb + route (routing objects)

  • inetnum creation preferences

Response

Often 204 No Content (same behavior as adding IPv4 item). If you need confirmation, use List Cart Items.

3. Complete checkout (standard cart steps)

From here the flow becomes the “standard checkout block” you already have in Lease Subnet.

3.1 List cart (get cart_uuid)

Save: {{cart_uuid}}

3.2 Attach billing address to cart

(Uses the address you already have from earlier List Company Addresses step.)

3.2 Attach billing address to cart

(Uses the address you already have from earlier List Company Addresses step.)

3.3 Apply credits to cart (Optional Step)

If credits are insufficient, you’ll still need a payment method assigned before checkout.

3.4 Checkout and create order

Save: {{order_uuid}} from response (if you want order verification)

4. List LOAs for the service (Pending / Active)

After checkout, LOA creation may take a bit of processing time. This endpoint lets you confirm status.

What this returns

• LOAs associated with the leased subnet service

• Typically you’ll see:

  • Pending right after checkout

  • Active once processed

What to save (optional)

• loa.uuid if you later want LOA-specific operations (extend/renew/view details) when you add them.

Variables used/introduced in this flow

Check and Download Invoices

This flow explains how to list invoices for a tenant and download a specific invoice file using the IPXO API.

Use this when you need to:

• display billing history

• reconcile payments

• allow users to download invoice PDFs programmatically

Prerequisites

You need:

• A valid access token ({{access_token}})

• Your tenant UUID ({{tenant_uuid}})

Flow overview

1. List invoices for the tenant

2. Select an invoice

3. Download the invoice file

1. List invoices

Retrieve all invoices for the tenant, optionally filtered by status.

What this does

• Returns invoices for the tenant

• Sorted by newest first (placed_at)

• Supports filtering by invoice status

Common invoice statuses

• paid

• unpaid

• refunded

What to save

From the selected invoice:

• uuid → {{invoice_uuid}}

2. Download invoice

Download the invoice file (PDF).

What this does

• Returns the invoice file as a binary response

• Typically a PDF

Example: save invoice to file

Variables used in this flow