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

# Create order

> Place a proxy order as an authenticated user.

Places a new proxy order. The proxies are provisioned immediately after a successful payment.

Use `"payment_method": "wallet"` to deduct from your wallet balance instantly, or `"payment_method": "cryptocloud"` to pay with crypto and receive a redirect URL.

<Tip>
  Send an `idempotency_key` to make this request safe to retry. See [Idempotency](/overview/idempotency).
</Tip>

## Request body

<ParamField body="offer_id" type="integer" required>
  ID of the proxy offer from the catalog.
</ParamField>

<ParamField body="payment_method" type="string" required>
  `wallet` or `cryptocloud`.
</ParamField>

<ParamField body="proxy_type" type="string" default="residential">
  Proxy type: `datacenter`, `residential`, or `mobile`.
</ParamField>

<ParamField body="ip_version" type="string" default="IPv4">
  `IPv4` or `IPv6`.
</ParamField>

<ParamField body="protocol" type="string" default="HTTP">
  `HTTP`, `HTTPS`, or `SOCKS5`.
</ParamField>

<ParamField body="country" type="string" default="US">
  ISO 3166-1 alpha-2 country code.
</ParamField>

<ParamField body="city" type="string">
  Optional city for geo-targeting.
</ParamField>

<ParamField body="isp" type="string">
  Optional ISP filter.
</ParamField>

<ParamField body="quantity" type="integer" default="1">
  Number of proxies.
</ParamField>

<ParamField body="period_days" type="integer" default="30">
  Rental period in days. For offers that require a `tarification_index`, must
  match the chosen option's `period_days` exactly.
</ParamField>

<ParamField body="tarification_index" type="integer">
  Index into the offer's `options` array. Required for mobile rotating
  offers, which sell only pre-registered tariff triples; pass the index of
  the option the user picked. Ignored for other offers and rejected with
  `422` if supplied for them.
</ParamField>

<ParamField body="bandwidth_gb" type="integer">
  Optional traffic limit in GB. Leave unset for unlimited (where supported).
</ParamField>

<ParamField body="auto_renew" type="boolean" default="false">
  Automatically renew when the period ends.
</ParamField>

<ParamField body="notes" type="string">
  Optional private notes for your reference.
</ParamField>

<ParamField body="idempotency_key" type="string">
  UUID for idempotent request handling.
</ParamField>

## Response

<ResponseField name="id" type="string">Order UUID.</ResponseField>

<ResponseField name="status" type="string">
  Order status. One of: `pending`, `pending_payment`, `active`, `failed`, `cancelled`, `expired`.
</ResponseField>

<ResponseField name="total_usd" type="number">Total charged in USD.</ResponseField>

<ResponseField name="payment_info" type="object">
  <Expandable title="PaymentInfo">
    <ResponseField name="payment_method" type="string">`wallet` or `cryptocloud`.</ResponseField>
    <ResponseField name="payment_intent_id" type="string">Present for cryptocloud payments.</ResponseField>
    <ResponseField name="payment_url" type="string">Redirect URL for crypto payment. Present for cryptocloud.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="proxy_access" type="array">
  Populated once the order is `active`. Each item:

  <Expandable title="ProxyAccess">
    <ResponseField name="id" type="string">Provider proxy ID.</ResponseField>
    <ResponseField name="host" type="string">Proxy hostname or IP.</ResponseField>
    <ResponseField name="port" type="integer">Proxy port.</ResponseField>
    <ResponseField name="username" type="string">Authentication username.</ResponseField>
    <ResponseField name="password" type="string">Authentication password.</ResponseField>
    <ResponseField name="protocol" type="string">Connection protocol.</ResponseField>
    <ResponseField name="status" type="string">Proxy status.</ResponseField>
    <ResponseField name="expires_at" type="string">ISO 8601 expiry timestamp.</ResponseField>
    <ResponseField name="whitelisted_ips" type="array">List of allowed source IPs.</ResponseField>
    <ResponseField name="bandwidth_total_gb" type="number">Total traffic limit in GB.</ResponseField>
    <ResponseField name="bandwidth_used_gb" type="number">Traffic already used in GB.</ResponseField>
  </Expandable>
</ResponseField>

## Example — wallet payment

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.proxyjam.com/public/v1/orders \
    -H "X-API-Key: pj_AbCdEf..." \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
    -d '{
      "offer_id": 42,
      "payment_method": "wallet",
      "proxy_type": "residential",
      "ip_version": "IPv4",
      "protocol": "HTTP",
      "country": "US",
      "quantity": 2,
      "period_days": 30
    }'
  ```

  ```python Python theme={null}
  from proxyjam import ProxyJamClient

  with ProxyJamClient(api_key="pj_live_...") as proxyjam:
      orders = proxyjam.orders.create(
          offer_id=42,
          quantity=2,
          period_days=30,
          payment_method="wallet",
          idempotency_key="550e8400-e29b-41d4-a716-446655440000",
      )
      order = orders[0]
      print(order.id, order.status, order.proxy_host, order.proxy_port)
  ```

  ```json Response theme={null}
  {
    "id": "order-uuid-here",
    "user_id": "user-uuid",
    "offer_id": 42,
    "status": "active",
    "total_usd": 7.0,
    "proxy_type": "residential",
    "ip_version": "IPv4",
    "protocol": "HTTP",
    "country": "US",
    "city": null,
    "isp": null,
    "quantity": 2,
    "period_days": 30,
    "bandwidth_gb": null,
    "auto_renew": false,
    "notes": null,
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-15T10:00:05Z",
    "payment_info": {
      "payment_method": "wallet",
      "payment_intent_id": null,
      "payment_url": null
    },
    "proxy_access": [
      {
        "id": "1836367",
        "host": "proxy.ProxyJam.com",
        "port": 10001,
        "username": "usr_abc",
        "password": "<proxy-password>",
        "protocol": "HTTP",
        "status": "active",
        "expires_at": "2024-02-14T10:00:00Z",
        "whitelisted_ips": [],
        "bandwidth_total_gb": 1.0,
        "bandwidth_used_gb": 0.0
      }
    ]
  }
  ```
</CodeGroup>