> ## Documentation Index > Fetch the complete documentation index at: https://docs.spenza.com/llms.txt > Use this file to discover all available pages before exploring further. # List plans > List the plans your account may purchase. `search` requires `searchType` to be set (otherwise the search matches nothing rather than erroring loudly). Omitting `category` restricts results to `MSP_PLAN` and `RESELLER_PLAN`; supplying it narrows to exactly that one category. Each plan optionally includes `tieredPricing` (only present when the plan's `planType` is `PAY_AS_YOU_GO`) and/or `volumeTierPricing` (only present when volume-tiered pricing is enabled for the plan). ## OpenAPI ````yaml /openapi.yaml get /api/v1.1/plans openapi: 3.1.0 info: title: Spenza Partner API version: 3.0.0 summary: >- Partner API for SIMs, eSIMs, plans, billing, users, groups and numbers — v1.1 surface. description: > The **Spenza Partner API** lets you manage SIMs, eSIMs, plans, subscriptions, billing, users, phone numbers, teams and device/SIM/user groups programmatically. All endpoints follow one consistent standard: - **Auth** — exchange your API `key` + `secret` for a bearer token, then send `Authorization: Bearer ` on every request. - **Envelopes** — success responses are `{ success, data, meta? }`; errors are `{ success: false, error: { code, message, details? } }`. - **Pagination** — list endpoints accept `page` (1-indexed) and `pageSize` (max 100); totals are returned in `meta`. - **Idempotency** — many write endpoints honor an optional `Idempotency-Key` request header so a retried call replays the original result instead of repeating the side effect. - **Async operations** — a handful of endpoints (eSIM provisioning, port-in, the `/api/v3/...` purchase variants, top-up) return `202` (`201` for top-up) with a `transactionId` + `statusEndpoint` instead of the finished resource. Poll `GET /api/v3/transactions/{transactionId}` (no auth required) until the transaction reaches a terminal status. One resource — **port-in submission** — is a documented exception: it lives at `POST /api/v3/port-in`, requires an Admin-tier account role rather than just a valid bearer token, and is **not** on the standard envelope (see that operation's description for its exact response shape). contact: name: Spenza API Support email: support@spenza.com url: https://spenza.com license: name: Proprietary url: https://spenza.com/terms x-logo: url: https://spenza.com/logo.png altText: Spenza servers: - url: https://api.spenza.com description: Production security: - bearerAuth: [] tags: - name: Authentication description: Exchange API credentials for a bearer token. - name: SIMs description: List, inspect, assign and manage SIMs. - name: Subscriptions description: Plan subscriptions attached to SIMs. - name: Plans & Catalog description: Purchasable plans and SIM products. - name: eSIM description: Provision eSIMs and fetch activation QR / install status. - name: Billing description: Invoices, credit balance and top-ups. - name: Users description: End users (employees) on your account that SIMs/devices are assigned to. - name: Orders & Transactions description: Order history and financial transactions. - name: Numbers & Port-in description: Check port-in eligibility and port existing numbers into Spenza. - name: Messaging description: Send outbound SMS from a provisioned number. - name: Webhooks description: Register endpoints for operator SMS/voice events and inspect deliveries. - name: Notifications description: In-account notifications and delivery preferences. - name: Device Groups description: Organize devices into named groups with spend/data limits. - name: SIM Groups description: Organize SIMs into named groups with spend/data limits. - name: User Groups description: Organize users (departments) into named groups with spend/data limits. - name: Devices description: The device catalog (phones/tablets) and their assignment to users. - name: Team Members description: Admins who manage your Spenza account (distinct from Users/end-users). - name: Async Status description: Universal status poll for any asynchronous (v3) operation. paths: /api/v1.1/plans: get: tags: - Plans & Catalog summary: List plans description: | List the plans your account may purchase. `search` requires `searchType` to be set (otherwise the search matches nothing rather than erroring loudly). Omitting `category` restricts results to `MSP_PLAN` and `RESELLER_PLAN`; supplying it narrows to exactly that one category. Each plan optionally includes `tieredPricing` (only present when the plan's `planType` is `PAY_AS_YOU_GO`) and/or `volumeTierPricing` (only present when volume-tiered pricing is enabled for the plan). operationId: listPlans parameters: - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PageSize' - name: search in: query schema: type: string - name: searchType in: query schema: type: string enum: - productName - productId - name: category in: query schema: type: string enum: - SPENZA_PLAN - MSP_PLAN - RESELLER_PLAN - ENDUSER_PLAN - SIM - SaaS responses: '200': description: A page of plans. content: application/json: example: success: true data: - productId: AT0001 productName: AT&T 5GB description: Unlimited talk & text + 5GB data price: 49.99 currency: usd validityDays: 30 data: value: 5 unit: GB voiceMinutes: 1000 smsCount: 500 operator: AT&T network: AT&T isEsim: false planType: FLAT_RATE recurring: true - productId: PAYG001 productName: Pay-As-You-Go Data description: Pay-as-you-go data, voice & SMS price: 0 currency: usd validityDays: 30 data: value: null unit: null voiceMinutes: 0 smsCount: 0 operator: AT&T network: AT&T isEsim: false planType: PAY_AS_YOU_GO recurring: false tieredPricing: dataTiers: - from: 0 to: 1 unit: GB price: 5 - from: 1 to: null unit: GB price: 4 voiceTiers: - from: 0 to: 100 unit: min price: 0.02 smsTiers: - from: 0 to: 100 unit: sms price: 0.01 volumeTierPricing: tiers: - minQuantity: 1 maxQuantity: 9 pricePerUnit: 49.99 - minQuantity: 10 maxQuantity: null pricePerUnit: 44.99 meta: page: 1 pageSize: 25 total: 8 totalPages: 1 '400': description: >- `search` was supplied without `searchType` (`MISSING_FIELDS`). Any other malformed query param — `page`/`pageSize` not coercible to an integer, an invalid `category`, or a malformed `searchType` value — returns the generic validation error instead. Note a malformed `searchType` value produces the *identical message text* as the `search`-without-`searchType` case above, but under `VALIDATION_ERROR` rather than `MISSING_FIELDS` — the two can only be told apart by `error.code`, not by message. content: application/json: examples: searchWithoutType: value: success: false error: code: MISSING_FIELDS message: Please search by either plan name or plan ID. validation: value: success: false error: code: VALIDATION_ERROR message: One or more fields failed validation. details: validationErrors: - page must not be less than 1 components: parameters: Page: name: page in: query description: 1-indexed page number. required: false schema: type: integer minimum: 1 default: 1 PageSize: name: pageSize in: query description: Items per page. required: false schema: type: integer minimum: 1 maximum: 100 default: 25 securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: Bearer token obtained from `POST /api/v1.1/auth/token`. ````