# Orders

> MENA Proxies API: plans and prices, buying a plan from the balance and order history. Parameters, example responses, curl, Python and Node.js code.

- URL: https://menaproxies.com/docs/api/orders/
- Last updated: 2026-10-14
- Publisher: MENA Proxies (https://menaproxies.com)

List the plans and their prices, buy a plan from the balance (new service, more traffic or a port extension) and read your past orders.

**Endpoints on this page**

- `GET /v1/catalog/products`: Products, plans and prices
- `POST /v1/orders`: Buy a plan from the balance (new service, more traffic, or port extension)
- `GET /v1/orders`: List orders
- `GET /v1/orders/{orderId}`: Get an order

Base URL `https://menaproxies.com/api/v1`. Authentication, errors and limits: see the [API overview](https://menaproxies.com/docs/api/).

## Products, plans and prices

`GET /v1/catalog/products`

Every product with its plans and prices, exactly as charged when you order.

Public: no API key needed.

**Response** `200 OK`

```json
{
  "data": [
    {
      "id": "residential",
      "name": "Residential proxies",
      "description": "Rotating and sticky residential IPs for business checks in 14 Middle East and North Africa countries, with country and city targeting and ASN targeting at no extra cost, billed per GB.",
      "unit": "GB",
      "plans": [
        {
          "id": "res-10",
          "productId": "residential",
          "name": "Team",
          "quantity": 10,
          "unit": "GB",
          "durationDays": null,
          "price": "5.94",
          "pricePerUnit": "0.59",
          "popular": false,
          "features": [
            "Regular checks in a few markets",
            "Sub-users per project",
            "Traffic never expires"
          ],
          "available": true,
          "countries": null
        }
      ]
    }
  ]
}
```

*curl*

```bash
curl -s "https://menaproxies.com/api/v1/catalog/products"
```

*Python*

```python
import os
import requests

API = "https://menaproxies.com/api/v1"

r = requests.get(f"{API}/catalog/products", timeout=30)
r.raise_for_status()
print(r.json())
```

*Node.js*

```javascript
// Node.js 18+ (built-in fetch), ES module
const API = 'https://menaproxies.com/api/v1';

const res = await fetch(`${API}/catalog/products`);
if (!res.ok) throw new Error((await res.json()).error?.message ?? `HTTP ${res.status}`);
console.log(await res.json());
```

## Buy a plan from the balance (new service, more traffic, or port extension)

`POST /v1/orders`

Always paid from the prepaid balance: the price is computed by the API (catalogue price × `quantity`), the balance is debited, the service is created or extended and the order comes back `completed` with its `fulfillment`. The proxy credentials are available at once.

- **New residential traffic**: `{ "planId": "res-10" }`.
- **New rotating 4G/5G traffic (per GB)**: `{ "planId": "mgb-10" }` (a traffic subscription with `productId: "mobile-gb"`, delivered in `fulfillment.residentialSubscriptionId`).
- **Add traffic to an existing subscription**: `{ "planId": "res-10", "options": { "subscriptionId": "res_9x2m4k" } }`: the plan must belong to the subscription's product.
- **New mobile port(s)**: `{ "planId": "mob-30d", "quantity": 1, "options": { "country": "AE" } }`, optionally with `carrier` (see the carriers of a country in [Mobile ports](https://menaproxies.com/docs/api/mobile/)). Zone plans only cover the countries of their zone (`422` on `options.country` otherwise).
- **Extend a mobile port**: `{ "planId": "mob-7d", "options": { "portId": "mob_2v8k1q" } }` adds the plan's duration to `expiresAt`.

**Balance too low → `402 insufficient_balance`**, with the missing amount and a suggested top-up in `error.details` (`missing`, `suggestedTopUp`). Nothing is debited on any error. To pay the difference, start a top-up carrying the same request in `purchase` (`POST /v1/topups`): the plan is bought as soon as the top-up is credited.

Authentication: API key in the `Authorization: Bearer API_KEY` header.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | string | No | Unique key (e.g. a UUID) to safely retry a POST. Kept 24 h. — max. 128 characters |

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `planId` | string | Yes | — |
| `quantity` | integer | No | 1–100, default `1` |
| `options` | object | No | — |

*Example: Residential*

```json
{
  "planId": "res-10"
}
```

*Example: Mobile Ports*

```json
{
  "planId": "mob-30d",
  "quantity": 1,
  "options": {
    "country": "AE",
    "carrier": "etisalat",
    "autoRenew": true
  }
}
```

*Example: Extend Port*

```json
{
  "planId": "mob-7d",
  "options": {
    "portId": "mob_2v8k1q"
  }
}
```

*Example: Mobile Traffic*

```json
{
  "planId": "mgb-10"
}
```

*Example: Zone Port*

```json
{
  "planId": "mob-30d",
  "options": {
    "country": "AE",
    "carrier": "etisalat"
  }
}
```

**Response** `201 Created`

```json
{
  "id": "ord_4f8k2m9q",
  "status": "completed",
  "productId": "residential",
  "planId": "res-10",
  "planName": "Team",
  "quantity": 1,
  "unitPrice": "5.94",
  "subtotal": "5.94",
  "discount": "0.00",
  "total": "5.94",
  "promoCode": null,
  "currency": "USD",
  "topUpId": null,
  "options": {},
  "fulfillment": {
    "residentialSubscriptionId": "res_9x2m4k",
    "mobilePortIds": []
  },
  "createdAt": "2026-10-05T14:03:11Z",
  "paidAt": "2026-10-05T14:03:11Z"
}
```

*curl*

```bash
curl -s -X POST "https://menaproxies.com/api/v1/orders" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"planId":"res-10"}'
```

*Python*

```python
import os, uuid
import requests

API = "https://menaproxies.com/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['API_KEY']}", "Idempotency-Key": str(uuid.uuid4())}

r = requests.post(f"{API}/orders", headers=HEADERS, json={"planId": "res-10"}, timeout=30)
r.raise_for_status()
print(r.json())
```

*Node.js*

```javascript
// Node.js 18+ (built-in fetch), ES module
import { randomUUID } from 'node:crypto';

const API = 'https://menaproxies.com/api/v1';

const res = await fetch(`${API}/orders`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.API_KEY}`, 'Idempotency-Key': randomUUID(), 'Content-Type': 'application/json' },
  body: JSON.stringify({ planId: 'res-10' }),
});
if (!res.ok) throw new Error((await res.json()).error?.message ?? `HTTP ${res.status}`);
console.log(await res.json());
```

## List orders

`GET /v1/orders`

Authentication: API key in the `Authorization: Bearer API_KEY` header.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `page` | query | integer | No | ≥ 1, default `1` |
| `perPage` | query | integer | No | 1–100, default `20` |
| `status` | query | `completed` · `cancelled` | No | Orders are created already paid (debited from the balance). `completed` — paid and delivered (credentials available immediately). |
| `productId` | query | string | No | Product id from the catalogue. Values for MENA Proxies: `residential` (GB), `mobile` (dedicated 4G/5G ports) and `mobile-gb` (rotating 4G/5G traffic per GB). Clients must tolerate unknown values. |

**Response** `200 OK`

```json
{
  "data": [
    {
      "id": "ord_4f8k2m9q",
      "status": "completed",
      "productId": "residential",
      "planId": "res-10",
      "planName": "Team",
      "quantity": 1,
      "unitPrice": "5.94",
      "subtotal": "5.94",
      "discount": "0.00",
      "total": "5.94",
      "promoCode": null,
      "currency": "USD",
      "topUpId": null,
      "options": {},
      "fulfillment": {
        "residentialSubscriptionId": "res_9x2m4k",
        "mobilePortIds": []
      },
      "createdAt": "2026-10-05T14:03:11Z",
      "paidAt": "2026-10-05T14:03:11Z"
    }
  ],
  "pagination": {
    "page": 1,
    "perPage": 20,
    "total": 1,
    "totalPages": 1
  }
}
```

*curl*

```bash
curl -s "https://menaproxies.com/api/v1/orders" \
  -H "Authorization: Bearer $API_KEY"
```

*Python*

```python
import os
import requests

API = "https://menaproxies.com/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['API_KEY']}"}

r = requests.get(f"{API}/orders", headers=HEADERS, timeout=30)
r.raise_for_status()
print(r.json())
```

*Node.js*

```javascript
// Node.js 18+ (built-in fetch), ES module
const API = 'https://menaproxies.com/api/v1';

const res = await fetch(`${API}/orders`, {
  headers: { Authorization: `Bearer ${process.env.API_KEY}` },
});
if (!res.ok) throw new Error((await res.json()).error?.message ?? `HTTP ${res.status}`);
console.log(await res.json());
```

## Get an order

`GET /v1/orders/{orderId}`

Authentication: API key in the `Authorization: Bearer API_KEY` header.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orderId` | path | string | Yes | — |

**Response** `200 OK`

```json
{
  "id": "ord_4f8k2m9q",
  "status": "completed",
  "productId": "residential",
  "planId": "res-10",
  "planName": "Team",
  "quantity": 1,
  "unitPrice": "5.94",
  "subtotal": "5.94",
  "discount": "0.00",
  "total": "5.94",
  "promoCode": null,
  "currency": "USD",
  "topUpId": null,
  "options": {},
  "fulfillment": {
    "residentialSubscriptionId": "res_9x2m4k",
    "mobilePortIds": []
  },
  "createdAt": "2026-10-05T14:03:11Z",
  "paidAt": "2026-10-05T14:03:11Z"
}
```

*curl*

```bash
curl -s "https://menaproxies.com/api/v1/orders/ord_4f8k2m9q" \
  -H "Authorization: Bearer $API_KEY"
```

*Python*

```python
import os
import requests

API = "https://menaproxies.com/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['API_KEY']}"}

r = requests.get(f"{API}/orders/ord_4f8k2m9q", headers=HEADERS, timeout=30)
r.raise_for_status()
print(r.json())
```

*Node.js*

```javascript
// Node.js 18+ (built-in fetch), ES module
const API = 'https://menaproxies.com/api/v1';

const res = await fetch(`${API}/orders/ord_4f8k2m9q`, {
  headers: { Authorization: `Bearer ${process.env.API_KEY}` },
});
if (!res.ok) throw new Error((await res.json()).error?.message ?? `HTTP ${res.status}`);
console.log(await res.json());
```

---

MENA Proxies: MENA Proxies is a residential proxy provider for the Middle East and North Africa, paid in crypto with no ID upload: rotating home IPs with country targeting in the UAE, Saudi Arabia, Qatar, Egypt, Morocco and 9 more countries, billed per GB.