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

# Products & services catalog

> Browse services, products, and plans before making a purchase

## Overview

The catalog endpoints let you discover what's available on the Dancity platform before initiating any purchase. Always fetch catalog data dynamically — identifiers (plan IDs, product names) can change over time.

The catalog has three levels:

| Level | Endpoint | What it returns |
| - | - | - |
| **Services** | `GET /api/v1/services` | Top-level service categories (e.g., Airtime, Data, Cable TV) |
| **Products** | `GET /api/v1/products` | Specific providers within a service (e.g., MTN, DSTV) |
| **Plans** | `GET /api/v1/plans/data`, `.../cable`, `.../internet` | Individual purchase options with prices |

## Authentication

All catalog endpoints use your **merchant API key** only.

```http theme={null}
Authorization: Bearer dcy_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

***

## Get services

```
GET /api/v1/services
```

Returns all service categories.

```bash cURL theme={null}
curl -sS "https://api.dancity.app/api/v1/services" \
  -H "Authorization: Bearer $DANCITY_API_KEY"
```

```javascript Node.js theme={null}
const res = await fetch(
  "https://api.dancity.app/api/v1/services",
  { headers: { Authorization: `Bearer ${process.env.DANCITY_API_KEY}` } }
);
const data = await res.json();
```

```python Python theme={null}
import requests, os

res = requests.get(
    "https://api.dancity.app/api/v1/services",
    headers={"Authorization": f"Bearer {os.environ['DANCITY_API_KEY']}"},
)
print(res.json())
```

***

## Get products

```
GET /api/v1/products
```

Returns products (providers/operators) within a service. Filter by service name to get only the products you need.

| Query param | Type | Description |
| - | - | - |
| `service` | string | Service name from `GET /api/v1/services` (e.g. Airtime, Data) |

```bash cURL theme={null}
# All airtime products
curl -sS "https://api.dancity.app/api/v1/products?service=AIRTIME" \
  -H "Authorization: Bearer $DANCITY_API_KEY"
```

```javascript Node.js theme={null}
const res = await fetch(
  "https://api.dancity.app/api/v1/products?service=AIRTIME",
  { headers: { Authorization: `Bearer ${process.env.DANCITY_API_KEY}` } }
);
const { data } = await res.json();
// data = [{ name: "MTN Airtime", ... }, { name: "Airtel Airtime", ... }]
```

```python Python theme={null}
import requests, os

res = requests.get(
    "https://api.dancity.app/api/v1/products",
    params={"service": "AIRTIME"},
    headers={"Authorization": f"Bearer {os.environ['DANCITY_API_KEY']}"},
)
```

***

## Get data plans

```
GET /api/v1/plans/data
```

Returns data plans for purchase. Each plan includes a **`planId`** — pass that value as `plan` in `POST /api/v1/data/buy`.

| Field | Description |
| - | - |
| `_id` | Internal Mongo id |
| `product` | Product name (e.g. `MTN GIFTING`) |
| `plan` | Data size (e.g. `40MB`, `1GB`) |
| `price` | Price in NGN |
| `validity` | Validity period (e.g. `1 Day`, `30 days`) |
| `planId` | **Send this to buy** — e.g. `40GB_MTN_GIFTING_1Day` |

| Query param | Type | Description |
| - | - | - |
| `product` | string | Product name from `GET /api/v1/products` (e.g. `MTN GIFTING`, `GLO GIFTING`). Spaces, underscores, and hyphens all work: `MTN GIFTING`, `MTN_GIFTING`, `MTN-GIFTING`. |

```bash cURL theme={null}
curl -sS "https://api.dancity.app/api/v1/plans/data?product=MTN%20GIFTING" \
  -H "Authorization: Bearer $DANCITY_API_KEY"
```

```javascript Node.js theme={null}
const res = await fetch(
  "https://api.dancity.app/api/v1/plans/data?product=MTN%20GIFTING",
  { headers: { Authorization: `Bearer ${process.env.DANCITY_API_KEY}` } }
);
const { data } = await res.json();
// data = [{ _id: "...", product: "MTN GIFTING", plan: "40MB", planId: "40MB_MTN_GIFTING_1Day", ... }]
```

```python Python theme={null}
import requests, os

res = requests.get(
    "https://api.dancity.app/api/v1/plans/data",
    params={"product": "MTN GIFTING"},
    headers={"Authorization": f"Bearer {os.environ['DANCITY_API_KEY']}"},
)
```

***

## Get cable plans

```
GET /api/v1/plans/cable
```

Returns cable TV subscription plans. Each item includes a **`planId`** — pass that as `cableplan` in `POST /api/v1/cable/buy`.

| Field | Description |
| - | - |
| `_id` | Internal Mongo id |
| `product` | Cable provider (e.g. `GOTV`, `DSTV`) |
| `plan` | Package name (e.g. `GOtv Supa Plus - monthly N16,800`) |
| `price` | Price in NGN |
| `planId` | **Send this to buy** — e.g. `GOtv_Supa_monthly_N11_400` |

**How `planId` is built:** slugified package name. If the package already includes the brand (e.g. `GOtv Supa`), the product is **not** repeated — `GOtv_Supa_monthly_N11_400`. For packages without the brand, the product is appended: `Nova_monthly_Startimes`.

Examples:

* `GOtv Supa Plus - monthly N16,800` + `GOTV` → `GOtv_Supa_Plus_monthly_N16_800`
* `GOtv Max` + `GOTV` → `GOtv_Max`

| Query param | Type | Description |
| - | - | - |
| `product` | string | Product name from `GET /api/v1/products` (e.g. DSTV, GOTV, Startimes). |

```bash cURL theme={null}
curl -sS "https://api.dancity.app/api/v1/plans/cable?product=GOTV" \
  -H "Authorization: Bearer $DANCITY_API_KEY"
```

```javascript Node.js theme={null}
const res = await fetch(
  "https://api.dancity.app/api/v1/plans/cable?product=GOTV",
  { headers: { Authorization: `Bearer ${process.env.DANCITY_API_KEY}` } }
);
const { data } = await res.json();
// data = [{ _id: "...", product: "GOTV", plan: "GOtv Supa Plus...", price: 16800 }, ...]
```

```python Python theme={null}
import requests, os

res = requests.get(
    "https://api.dancity.app/api/v1/plans/cable",
    params={"product": "GOTV"},
    headers={"Authorization": f"Bearer {os.environ['DANCITY_API_KEY']}"},
)
```

***

## Recommended catalog caching strategy

Catalog data (services, products, plans) doesn't change frequently, but prices and availability can. We recommend:

* Cache catalog responses for **15–60 minutes** in production
* Re-fetch on cache miss or user-initiated refresh
* Never hard-code plan IDs — always resolve them from the catalog at runtime

> [!TIP]
>
> Use the `product` name returned from `/products` as the `product` field in buy requests (e.g. `"MTN Airtime"`, `"MTN-Airtime"`, or `"MTN_Airtime"`). Use the plan `_id` as the `plan` field for data/internet purchases.

## Next steps

* [Buy airtime or data](https://docs.dancity.app/guides/airtime-data.md)
* [Buy cable TV subscription](https://docs.dancity.app/guides/cable-tv.md)
* [Buy internet bundle](https://docs.dancity.app/guides/internet.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.