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

# 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)**
```json
{
  "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"
}
```




## OpenAPI

````yaml post /public/user/checkout/create
openapi: 3.0.1
info:
  title: Byteful Public User API
  description: Public API used for third-party usage.
  termsOfService: https://byteful.com
  contact:
    url: https://byteful.com
    email: developer@byteful.com
  version: '1.0'
  x-logo:
    altText: Byteful
    backgroundColor: '#6354eb'
    url: >-
      https://pbs.twimg.com/profile_banners/1038803520605118464/1729783007/1500x500
servers:
  - url: https://api.byteful.com/1.0/
security: []
paths:
  /public/user/checkout/create:
    post:
      tags:
        - Checkout
      summary: Create Checkout
      description: >
        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)**

        ```json

        {
          "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"
        }

        ```
      parameters:
        - name: Content-Type
          in: header
          description: Content type for the request body as application/json.
          required: true
          schema:
            type: string
            default: application/json
      requestBody:
        description: The data needed to create the checkout.
        content:
          application/json:
            schema:
              type: object
              properties:
                country_id:
                  type: string
                  description: >-
                    An ISO country code used for region-specific datacenter or
                    ISP products.
                cycle_interval:
                  type: string
                  description: The billing interval for recurring purchases.
                  default: month
                  enum:
                    - year
                    - month
                    - week
                    - day
                cycle_interval_count:
                  type: integer
                  description: >-
                    The number of intervals for a recurring cycle (e.g. 1 month,
                    2 months, etc.).
                line_items:
                  type: array
                  description: >
                    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).
                  items:
                    required:
                      - item_quantity
                      - product_type
                    type: object
                    properties:
                      cycle_interval:
                        type: string
                        example: month
                        default: month
                        enum:
                          - year
                          - month
                          - week
                          - day
                      cycle_interval_count:
                        type: integer
                        example: 1
                      item_quantity:
                        type: integer
                        description: The quantity of the product to purchase.
                        example: 5
                      product_type:
                        type: string
                        example: isp
                        enum:
                          - datacenter
                          - isp
                          - residential
                          - mobile
                      service_fulfillment_filter:
                        type: array
                        description: >
                          Per-IP products (isp / datacenter) only. Entries are
                          {country_id, quantity, [asn_id]};

                          quantities are positive and may sum to less than
                          item_quantity — the remainder is

                          fulfilled from random locations. A country may repeat
                          only when refinements differ

                          (identical entries must be merged). Refinements beyond
                          country_id/quantity (e.g.

                          asn_id) require an account permission, and the
                          JSON-encoded filter is capped at 450

                          characters. Countries not offered for the product, and
                          stock shortages (including

                          refined pools), reject with 422.
                        items:
                          type: object
                          properties:
                            asn_id:
                              type: integer
                              example: 7018
                            country_id:
                              type: string
                              example: gb
                            quantity:
                              type: integer
                              example: 3
                product_code:
                  type: string
                  description: >-
                    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:
                  type: string
                  description: The protocol of the product.
                  default: ipv4
                  enum:
                    - ipv4
                    - ipv6
                    - dual
                product_type:
                  type: string
                  description: >-
                    The type of product to purchase (if `product_code` is not
                    used).
                  enum:
                    - datacenter
                    - isp
                    - residential
                    - mobile
                promotional_code:
                  type: string
                  description: A promotional code to apply a discount to the checkout.
                quantity:
                  type: integer
                  description: >-
                    The quantity of the product to purchase. Required for the
                    legacy flat form (the line_items form uses item_quantity
                    instead).
                service_fulfillment_filter:
                  type: object
                  properties: {}
                  description: >
                    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.
              example:
                cycle_interval: month
                cycle_interval_count: 1
                product_code: isp_us
                promotional_code: PROMOCODEHERE
                quantity: 5
        required: true
      responses:
        '201':
          description: >-
            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.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      created:
                        type: array
                        description: >-
                          A list of service IDs created during checkout (usually
                          contains only one).
                        example:
                          - API-1234-5678
                        items:
                          type: string
                      invoice_is_paid:
                        type: boolean
                        description: Indicates whether the invoice is already paid.
                        example: true
                      invoice_url:
                        type: string
                        description: >-
                          Hosted Stripe URL of the paid invoice (null if payment
                          is still pending).
                        example: >-
                          https://invoice.stripe.com/i/acct_1H7dAB2BUlqim5l/test_123
                      mobile_ledger_created:
                        type: array
                        description: >-
                          A list of mobile ledger entries created (may be
                          empty).
                        example: []
                        items:
                          type: string
                      proxies:
                        type: array
                        description: >-
                          A list of proxy objects tied to the newly created
                          service.
                        items:
                          type: object
                          properties:
                            asn_id:
                              type: integer
                              example: 7018
                            asn_name:
                              type: string
                              example: AT&T Enterprises, LLC
                            city_example_postcode:
                              type: string
                              example: '75202'
                            city_id:
                              type: integer
                              example: 75202
                            city_latitude:
                              type: number
                              format: float
                              example: 32.7767
                            city_longitude:
                              type: number
                              format: float
                              example: -96.797
                            city_name:
                              type: string
                              example: Dallas
                            city_timezone:
                              type: string
                              example: America/Chicago
                            country_id:
                              type: string
                              example: us
                            country_name:
                              type: string
                              example: United States
                            customer_id:
                              type: integer
                              example: 1976
                            default_proxy_user_password:
                              type: string
                              example: apple1984
                            default_proxy_user_username:
                              type: string
                              example: stevejobs
                            ip_address_id_v4:
                              type: string
                              example: 107.225.73.142
                            ip_address_id_v6:
                              type: string
                              description: IPv6 address if dual protocol is used
                              example: 2600:1000:b12a:6351:8523:997e:93c4:f124
                            proxy_http_port:
                              type: integer
                              example: 8080
                            proxy_id:
                              type: string
                              example: 7a018d34-76c2-4c23-b14d-f7b9a7054e25
                            proxy_ip_address:
                              type: string
                              example: 107.225.73.142
                            proxy_ip_address_v6:
                              type: string
                              description: IPv6 address if dual protocol is used
                              example: 2600:1000:b12a:6351:8523:997e:93c4:f124
                            proxy_last_update_datetime:
                              type: string
                              format: date-time
                            proxy_protocol:
                              type: string
                              example: ipv4
                            proxy_socks5_port:
                              type: integer
                              example: 1080
                            proxy_status:
                              type: string
                              example: in_use
                            proxy_type:
                              type: string
                              example: isp
                            service_id:
                              type: string
                              example: API-1234-5678
                            service_line_item_id:
                              type: string
                              description: The service line item this proxy fulfills.
                              example: 550e8400-e29b-41d4-a716-446655440000
                            subdivision_id:
                              type: string
                              example: us-tx
                            subdivision_name:
                              type: string
                              example: Texas
                            subnet_id:
                              type: string
                              example: 107.225.72.0/22
                            subnet_id_v6:
                              type: string
                              description: IPv6 subnet if dual protocol is used
                              example: 2600:1000::/28
                      proxy_edited:
                        type: array
                        description: >-
                          A list of proxies edited or updated in the process
                          (may be empty).
                        example:
                          - 7a018d34-76c2-4c23-b14d-f7b9a7054e25
                        items:
                          type: string
                      residential_ledger_created:
                        type: array
                        description: >-
                          A list of residential ledger entries created (may be
                          empty).
                        example: []
                        items:
                          type: string
                      service:
                        type: object
                        properties:
                          country_id:
                            type: string
                            example: us
                          open_invoice_id:
                            type: string
                            example: 'null'
                          payment_method_id:
                            type: string
                            example: 'null'
                          service_creation_datetime:
                            type: string
                            format: date-time
                          service_cycle:
                            type: string
                            example: 1:month
                          service_dispatch_datetime:
                            type: string
                            format: date-time
                          service_earliest_cancellation_datetime:
                            type: string
                            format: date-time
                          service_expiry_datetime:
                            type: string
                            format: date-time
                          service_id:
                            type: string
                            example: API-1234-5678
                          service_image:
                            type: string
                            example: >-
                              https://files.stripe.com/links/MDB8YWNjdF8xSDdkOEFCMkJVbHFpbTVsfGZsX2xpdmVfZFZ6TTZjUG01Q0NuR1IzSTZsVzNjVVFX00kUPPfQE9
                          service_is_automatic_collection:
                            type: boolean
                            example: true
                          service_is_pending_cancellation:
                            type: boolean
                            example: false
                          service_is_reconfigurable:
                            type: boolean
                            example: true
                          service_last_update_datetime:
                            type: string
                            format: date-time
                          service_line_items:
                            type: array
                            description: >-
                              The service's live per-location line items
                              (canceled lines excluded).
                            items:
                              $ref: '#/components/schemas/ServiceLineItem'
                          service_metadata:
                            type: object
                            properties: {}
                            example: {}
                          service_name:
                            type: string
                            example: AT&T ISP Proxies [US]
                          service_promotional_code:
                            type: string
                            example: PROMOCODEHERE
                          service_protocol:
                            type: string
                            example: ipv4
                          service_quantity:
                            type: integer
                            example: 5
                          service_status:
                            type: string
                            example: active
                          service_subscription_id:
                            type: string
                            example: sub_1QxSHmB2BUlqim5lTUH8HvKa
                          service_subscription_is_paused:
                            type: boolean
                            example: false
                          service_total:
                            type: integer
                            example: 450
                          service_type:
                            type: string
                            example: isp
                          subscription_schedule_id:
                            type: string
                            example: 'null'
                        description: >-
                          Detailed information about the provisioned service
                          (null if not yet provisioned).
                      service_id:
                        type: string
                        description: The ID of the newly created service.
                        example: API-1234-5678
                  message:
                    type: string
                    description: Success message.
                    example: >-
                      Successfully created checkout and paid with credit. Your
                      service will be provisioned shortly.
      security:
        - APIPrivateKey: []
          APIPublicKey: []
components:
  schemas:
    ServiceLineItem:
      type: object
      properties:
        country_id:
          type: string
          example: us
        service_id:
          type: string
          example: API-1234-5678
        service_line_item_creation_datetime:
          type: string
          format: date-time
        service_line_item_dispatch_datetime:
          type: string
          format: date-time
        service_line_item_fulfillment_filter:
          type: object
          properties: {}
          example:
            asn_id: 7018
        service_line_item_id:
          type: string
          example: 550e8400-e29b-41d4-a716-446655440000
        service_line_item_last_update_datetime:
          type: string
          format: date-time
        service_line_item_quantity:
          type: integer
          example: 10
        service_line_item_status:
          type: string
          example: active
  securitySchemes:
    APIPrivateKey:
      type: apiKey
      description: ' Private API key for user-level authentication.'
      name: X-API-Private-Key
      in: header
    APIPublicKey:
      type: apiKey
      description: ' Public API key for user-level authentication.'
      name: X-API-Public-Key
      in: header

````