Create Checkout

curl --request POST \
  --url https://api.byteful.com/1.0/public/user/checkout/create \
  --header 'Content-Type: <content-type>' \
  --header 'X-API-Private-Key: <api-key>' \
  --header 'X-API-Public-Key: <api-key>' \
  --data '
{
  "cycle_interval": "month",
  "cycle_interval_count": 1,
  "product_code": "isp_us",
  "promotional_code": "PROMOCODEHERE",
  "quantity": 5
}
'

import requests

url = "https://api.byteful.com/1.0/public/user/checkout/create"

payload = {
    "cycle_interval": "month",
    "cycle_interval_count": 1,
    "product_code": "isp_us",
    "promotional_code": "PROMOCODEHERE",
    "quantity": 5
}
headers = {
    "Content-Type": "<content-type>",
    "X-API-Private-Key": "<api-key>",
    "X-API-Public-Key": "<api-key>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Content-Type': '<content-type>',
    'X-API-Private-Key': '<api-key>',
    'X-API-Public-Key': '<api-key>'
  },
  body: JSON.stringify({
    cycle_interval: 'month',
    cycle_interval_count: 1,
    product_code: 'isp_us',
    promotional_code: 'PROMOCODEHERE',
    quantity: 5
  })
};

fetch('https://api.byteful.com/1.0/public/user/checkout/create', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.byteful.com/1.0/public/user/checkout/create",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'cycle_interval' => 'month',
    'cycle_interval_count' => 1,
    'product_code' => 'isp_us',
    'promotional_code' => 'PROMOCODEHERE',
    'quantity' => 5
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: <content-type>",
    "X-API-Private-Key: <api-key>",
    "X-API-Public-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.byteful.com/1.0/public/user/checkout/create"

	payload := strings.NewReader("{\n  \"cycle_interval\": \"month\",\n  \"cycle_interval_count\": 1,\n  \"product_code\": \"isp_us\",\n  \"promotional_code\": \"PROMOCODEHERE\",\n  \"quantity\": 5\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "<content-type>")
	req.Header.Add("X-API-Private-Key", "<api-key>")
	req.Header.Add("X-API-Public-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.byteful.com/1.0/public/user/checkout/create")
  .header("Content-Type", "<content-type>")
  .header("X-API-Private-Key", "<api-key>")
  .header("X-API-Public-Key", "<api-key>")
  .body("{\n  \"cycle_interval\": \"month\",\n  \"cycle_interval_count\": 1,\n  \"product_code\": \"isp_us\",\n  \"promotional_code\": \"PROMOCODEHERE\",\n  \"quantity\": 5\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.byteful.com/1.0/public/user/checkout/create")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = '<content-type>'
request["X-API-Private-Key"] = '<api-key>'
request["X-API-Public-Key"] = '<api-key>'
request.body = "{\n  \"cycle_interval\": \"month\",\n  \"cycle_interval_count\": 1,\n  \"product_code\": \"isp_us\",\n  \"promotional_code\": \"PROMOCODEHERE\",\n  \"quantity\": 5\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "created": [
      "API-1234-5678"
    ],
    "invoice_is_paid": true,
    "invoice_url": "https://invoice.stripe.com/i/acct_1H7dAB2BUlqim5l/test_123",
    "mobile_ledger_created": [],
    "proxies": [
      {
        "asn_id": 7018,
        "asn_name": "AT&T Enterprises, LLC",
        "city_example_postcode": "75202",
        "city_id": 75202,
        "city_latitude": 32.7767,
        "city_longitude": -96.797,
        "city_name": "Dallas",
        "city_timezone": "America/Chicago",
        "country_id": "us",
        "country_name": "United States",
        "customer_id": 1976,
        "default_proxy_user_password": "apple1984",
        "default_proxy_user_username": "stevejobs",
        "ip_address_id_v4": "107.225.73.142",
        "ip_address_id_v6": "2600:1000:b12a:6351:8523:997e:93c4:f124",
        "proxy_http_port": 8080,
        "proxy_id": "7a018d34-76c2-4c23-b14d-f7b9a7054e25",
        "proxy_ip_address": "107.225.73.142",
        "proxy_ip_address_v6": "2600:1000:b12a:6351:8523:997e:93c4:f124",
        "proxy_last_update_datetime": "2023-11-07T05:31:56Z",
        "proxy_protocol": "ipv4",
        "proxy_socks5_port": 1080,
        "proxy_status": "in_use",
        "proxy_type": "isp",
        "service_id": "API-1234-5678",
        "service_line_item_id": "550e8400-e29b-41d4-a716-446655440000",
        "subdivision_id": "us-tx",
        "subdivision_name": "Texas",
        "subnet_id": "107.225.72.0/22",
        "subnet_id_v6": "2600:1000::/28"
      }
    ],
    "proxy_edited": [
      "7a018d34-76c2-4c23-b14d-f7b9a7054e25"
    ],
    "residential_ledger_created": [],
    "service": {
      "country_id": "us",
      "open_invoice_id": "null",
      "payment_method_id": "null",
      "service_creation_datetime": "2023-11-07T05:31:56Z",
      "service_cycle": "1:month",
      "service_dispatch_datetime": "2023-11-07T05:31:56Z",
      "service_earliest_cancellation_datetime": "2023-11-07T05:31:56Z",
      "service_expiry_datetime": "2023-11-07T05:31:56Z",
      "service_id": "API-1234-5678",
      "service_image": "https://files.stripe.com/links/MDB8YWNjdF8xSDdkOEFCMkJVbHFpbTVsfGZsX2xpdmVfZFZ6TTZjUG01Q0NuR1IzSTZsVzNjVVFX00kUPPfQE9",
      "service_is_automatic_collection": true,
      "service_is_pending_cancellation": false,
      "service_is_reconfigurable": true,
      "service_last_update_datetime": "2023-11-07T05:31:56Z",
      "service_line_items": [
        {
          "country_id": "us",
          "service_id": "API-1234-5678",
          "service_line_item_creation_datetime": "2023-11-07T05:31:56Z",
          "service_line_item_dispatch_datetime": "2023-11-07T05:31:56Z",
          "service_line_item_fulfillment_filter": {
            "asn_id": 7018
          },
          "service_line_item_id": "550e8400-e29b-41d4-a716-446655440000",
          "service_line_item_last_update_datetime": "2023-11-07T05:31:56Z",
          "service_line_item_quantity": 10,
          "service_line_item_status": "active"
        }
      ],
      "service_metadata": {},
      "service_name": "AT&T ISP Proxies [US]",
      "service_promotional_code": "PROMOCODEHERE",
      "service_protocol": "ipv4",
      "service_quantity": 5,
      "service_status": "active",
      "service_subscription_id": "sub_1QxSHmB2BUlqim5lTUH8HvKa",
      "service_subscription_is_paused": false,
      "service_total": 450,
      "service_type": "isp",
      "subscription_schedule_id": "null"
    },
    "service_id": "API-1234-5678"
  },
  "message": "Successfully created checkout and paid with credit. Your service will be provisioned shortly."
}

Checkout

Create Checkout

This endpoint creates a checkout for the authenticated user based on the provided data. It supports promotional codes and can handle both one-time and recurring payments. The product can be configured in one of two mutually exclusive forms:

Legacy flat form: a product_code directly, or the traditional combination of product_type, country_id, and product_protocol, with a top-level quantity.
Multi-location form: a single line_items entry carrying its own product type, billing cycle, quantity, and per-location service_fulfillment_filter.

Important considerations

If product_code is provided alongside product_type/country_id/product_protocol, their values must match the actual product attributes.
API checkouts are settled with your existing credit balance; a cart your credit cannot fully cover is rejected with 422. The returned invoice is already paid and invoice_url points at its hosted page.

Example: multi-location checkout (line_items form)

{
  "line_items": [
    {
      "product_type": "isp",
      "item_quantity": 5,
      "cycle_interval": "month",
      "cycle_interval_count": 1,
      "service_fulfillment_filter": [
        {"country_id": "us", "quantity": 2},
        {"country_id": "gb", "quantity": 2}
      ]
    }
  ],
  "promotional_code": "PROMOCODEHERE"
}

POST

public

user

checkout

create

Create Checkout

curl --request POST \
  --url https://api.byteful.com/1.0/public/user/checkout/create \
  --header 'Content-Type: <content-type>' \
  --header 'X-API-Private-Key: <api-key>' \
  --header 'X-API-Public-Key: <api-key>' \
  --data '
{
  "cycle_interval": "month",
  "cycle_interval_count": 1,
  "product_code": "isp_us",
  "promotional_code": "PROMOCODEHERE",
  "quantity": 5
}
'

import requests

url = "https://api.byteful.com/1.0/public/user/checkout/create"

payload = {
    "cycle_interval": "month",
    "cycle_interval_count": 1,
    "product_code": "isp_us",
    "promotional_code": "PROMOCODEHERE",
    "quantity": 5
}
headers = {
    "Content-Type": "<content-type>",
    "X-API-Private-Key": "<api-key>",
    "X-API-Public-Key": "<api-key>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Content-Type': '<content-type>',
    'X-API-Private-Key': '<api-key>',
    'X-API-Public-Key': '<api-key>'
  },
  body: JSON.stringify({
    cycle_interval: 'month',
    cycle_interval_count: 1,
    product_code: 'isp_us',
    promotional_code: 'PROMOCODEHERE',
    quantity: 5
  })
};

fetch('https://api.byteful.com/1.0/public/user/checkout/create', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.byteful.com/1.0/public/user/checkout/create",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'cycle_interval' => 'month',
    'cycle_interval_count' => 1,
    'product_code' => 'isp_us',
    'promotional_code' => 'PROMOCODEHERE',
    'quantity' => 5
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: <content-type>",
    "X-API-Private-Key: <api-key>",
    "X-API-Public-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.byteful.com/1.0/public/user/checkout/create"

	payload := strings.NewReader("{\n  \"cycle_interval\": \"month\",\n  \"cycle_interval_count\": 1,\n  \"product_code\": \"isp_us\",\n  \"promotional_code\": \"PROMOCODEHERE\",\n  \"quantity\": 5\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "<content-type>")
	req.Header.Add("X-API-Private-Key", "<api-key>")
	req.Header.Add("X-API-Public-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.byteful.com/1.0/public/user/checkout/create")
  .header("Content-Type", "<content-type>")
  .header("X-API-Private-Key", "<api-key>")
  .header("X-API-Public-Key", "<api-key>")
  .body("{\n  \"cycle_interval\": \"month\",\n  \"cycle_interval_count\": 1,\n  \"product_code\": \"isp_us\",\n  \"promotional_code\": \"PROMOCODEHERE\",\n  \"quantity\": 5\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.byteful.com/1.0/public/user/checkout/create")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = '<content-type>'
request["X-API-Private-Key"] = '<api-key>'
request["X-API-Public-Key"] = '<api-key>'
request.body = "{\n  \"cycle_interval\": \"month\",\n  \"cycle_interval_count\": 1,\n  \"product_code\": \"isp_us\",\n  \"promotional_code\": \"PROMOCODEHERE\",\n  \"quantity\": 5\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "created": [
      "API-1234-5678"
    ],
    "invoice_is_paid": true,
    "invoice_url": "https://invoice.stripe.com/i/acct_1H7dAB2BUlqim5l/test_123",
    "mobile_ledger_created": [],
    "proxies": [
      {
        "asn_id": 7018,
        "asn_name": "AT&T Enterprises, LLC",
        "city_example_postcode": "75202",
        "city_id": 75202,
        "city_latitude": 32.7767,
        "city_longitude": -96.797,
        "city_name": "Dallas",
        "city_timezone": "America/Chicago",
        "country_id": "us",
        "country_name": "United States",
        "customer_id": 1976,
        "default_proxy_user_password": "apple1984",
        "default_proxy_user_username": "stevejobs",
        "ip_address_id_v4": "107.225.73.142",
        "ip_address_id_v6": "2600:1000:b12a:6351:8523:997e:93c4:f124",
        "proxy_http_port": 8080,
        "proxy_id": "7a018d34-76c2-4c23-b14d-f7b9a7054e25",
        "proxy_ip_address": "107.225.73.142",
        "proxy_ip_address_v6": "2600:1000:b12a:6351:8523:997e:93c4:f124",
        "proxy_last_update_datetime": "2023-11-07T05:31:56Z",
        "proxy_protocol": "ipv4",
        "proxy_socks5_port": 1080,
        "proxy_status": "in_use",
        "proxy_type": "isp",
        "service_id": "API-1234-5678",
        "service_line_item_id": "550e8400-e29b-41d4-a716-446655440000",
        "subdivision_id": "us-tx",
        "subdivision_name": "Texas",
        "subnet_id": "107.225.72.0/22",
        "subnet_id_v6": "2600:1000::/28"
      }
    ],
    "proxy_edited": [
      "7a018d34-76c2-4c23-b14d-f7b9a7054e25"
    ],
    "residential_ledger_created": [],
    "service": {
      "country_id": "us",
      "open_invoice_id": "null",
      "payment_method_id": "null",
      "service_creation_datetime": "2023-11-07T05:31:56Z",
      "service_cycle": "1:month",
      "service_dispatch_datetime": "2023-11-07T05:31:56Z",
      "service_earliest_cancellation_datetime": "2023-11-07T05:31:56Z",
      "service_expiry_datetime": "2023-11-07T05:31:56Z",
      "service_id": "API-1234-5678",
      "service_image": "https://files.stripe.com/links/MDB8YWNjdF8xSDdkOEFCMkJVbHFpbTVsfGZsX2xpdmVfZFZ6TTZjUG01Q0NuR1IzSTZsVzNjVVFX00kUPPfQE9",
      "service_is_automatic_collection": true,
      "service_is_pending_cancellation": false,
      "service_is_reconfigurable": true,
      "service_last_update_datetime": "2023-11-07T05:31:56Z",
      "service_line_items": [
        {
          "country_id": "us",
          "service_id": "API-1234-5678",
          "service_line_item_creation_datetime": "2023-11-07T05:31:56Z",
          "service_line_item_dispatch_datetime": "2023-11-07T05:31:56Z",
          "service_line_item_fulfillment_filter": {
            "asn_id": 7018
          },
          "service_line_item_id": "550e8400-e29b-41d4-a716-446655440000",
          "service_line_item_last_update_datetime": "2023-11-07T05:31:56Z",
          "service_line_item_quantity": 10,
          "service_line_item_status": "active"
        }
      ],
      "service_metadata": {},
      "service_name": "AT&T ISP Proxies [US]",
      "service_promotional_code": "PROMOCODEHERE",
      "service_protocol": "ipv4",
      "service_quantity": 5,
      "service_status": "active",
      "service_subscription_id": "sub_1QxSHmB2BUlqim5lTUH8HvKa",
      "service_subscription_is_paused": false,
      "service_total": 450,
      "service_type": "isp",
      "subscription_schedule_id": "null"
    },
    "service_id": "API-1234-5678"
  },
  "message": "Successfully created checkout and paid with credit. Your service will be provisioned shortly."
}

Authorizations

X-API-Private-Key

string

header

required

Private API key for user-level authentication.

X-API-Public-Key

string

header

required

Public API key for user-level authentication.

Headers

Content-Type

string

default:application/json

required

Content type for the request body as application/json.

Body

application/json

The data needed to create the checkout.

country_id

string

An ISO country code used for region-specific datacenter or ISP products.

cycle_interval

enum<string>

default:month

The billing interval for recurring purchases.

Available options:

year,

month,

week,

day

cycle_interval_count

integer

The number of intervals for a recurring cycle (e.g. 1 month, 2 months, etc.).

line_items

object[]

Multi-location form: a list containing exactly one line item that carries its own product type, billing cycle, quantity, and optional per-location filter. Mutually exclusive with the top-level product_code, product_type, country_id, product_protocol, cycle_interval, cycle_interval_count, quantity, and service_fulfillment_filter fields (promotional_code remains top-level).

Show child attributes

product_code

string

A direct product code (e.g. "datacenter_us"). If this is provided, you do not need product_type, country_id, or product_protocol.

product_protocol

enum<string>

default:ipv4

The protocol of the product.

Available options:

ipv4,

ipv6,

dual

product_type

enum<string>

The type of product to purchase (if product_code is not used).

Available options:

datacenter,

isp,

residential,

mobile

promotional_code

string

A promotional code to apply a discount to the checkout.

quantity

integer

The quantity of the product to purchase. Required for the legacy flat form (the line_items form uses item_quantity instead).

service_fulfillment_filter

object

Legacy single-object filter applied to the whole service (e.g. {"asn_id": 7018}), pinned to the product's country. For multi-location allocation use line_items instead. asn_id requires an account permission; insufficient stock matching the filter rejects with 422.

Response

201 - application/json

Successfully created a checkout. Depending on the remaining invoice amount, it may already be paid by credit, or you may need to complete payment at the returned invoice URL.

data

object

Show child attributes

message

string

Success message.

Example:

"Successfully created checkout and paid with credit. Your service will be provisioned shortly."

Customer

Proxy

Proxy User

Proxy User ACL

Residential

Residential Availability

Residential Ledger

Mobile

Mobile Availability

Mobile Ledger

Service

Service Adjustment

Checkout

Analytics

Product

ASN

Continent

Country

Subdivision

City

Zip Code

Proxy Tester

Create Checkout

Authorizations

Headers

Body

Response