---
title: "Get an eSIM offer"
method: GET
path: "/v1/esim/offers/{offer_id}"
tags: ["esim-offers"]
---

# Get an eSIM offer

`GET /v1/esim/offers/{offer_id}`

## Request

- Base URL: `https://us1.platform.bird.com`
- URL: `https://us1.platform.bird.com/v1/esim/offers/{offer_id}`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `bird_session`

Returns one eSIM offer with its pricing and embedded coverage zone.

## Path parameters

- `offer_id` string, required

## Headers

- `X-Workspace-Id` string
- `X-Organization-Id` string

## Response `200`

The offer.

- EsimOffer: A purchasable offer from the curated catalog: the commercial terms for prepaid data in one coverage zone, priced as your workspace is billed. The coverage itself lives on the referenced zone, shared by every offer selling the same footprint.
  - `id` string, required
  - `name` string, required: Display name of the offer.
  - `revision` integer, required: Increments whenever the offer's terms change. Orders lock the revision they were quoted at.
  - `zone_id` string, required
  - `zone` EsimZone, required: A group of countries covered by an offer. Use `countries` to check a destination rather than inferring coverage from the zone name. Purchased packages retain their coverage details from the time of purchase.
    - `id` string, required
    - `name` string, required: Human-readable zone name.
    - `revision` integer, required: Increments whenever the country list changes.
    - `type` 'local' | 'regional' | 'global', required: Zone breadth: a single country, a multi-country region, or worldwide.
    - `countries` CountryCode[], required: Countries covered by the zone, as ISO 3166-1 alpha-2 codes.
    - `created_at` string, date-time, required
  - `speed` 'full' | 'reduced', required: Speed class. full: data flows at full network speed until the allowance is used; reduced: speed is limited, typically after the full-speed allowance. Full-speed and reduced-speed packages cannot be combined on one eSIM.
  - `stackable` boolean, required: Whether packages from this offer can be held alongside packages from other zones on the same eSIM, subject to the eSIM's package_limit.
  - `phone` EsimOfferPhone, required: Phone service included with the plan. Every eSIM sold from the offer gets its own phone number; each flag states one direction of service on that number. A false flag means the plan does not include that service.
    - `included` 'always' | 'on_request', required: How the plan provides a phone number. - `always`: a phone number is included with each eSIM purchased from the offer. - `on_request`: reserved for offers with an optional phone number; currently unavailable.
    - `voice_inbound` boolean, required: The eSIM can receive calls on its phone number.
    - `voice_outbound` boolean, required: The eSIM can place calls.
    - `sms_inbound` boolean, required: The eSIM can receive text messages on its phone number.
    - `sms_outbound` boolean, required: The eSIM can send text messages.
  - `pricing` EsimOfferBundlePricing, required: Fixed-allowance terms: a data allowance with a validity period, charged once per provisioned package.
    - `type` 'bundle', required: Pricing type.
    - `data` EsimOfferData, required: Data allowance of a bundle.
      - `amount_bytes` integer, required: Total data allowance in bytes.
      - `throttled_after_bytes` integer, nullable: Data amount in bytes after which speed is reduced instead of cut off. Null when the allowance is a hard cap.
    - `validity` EsimOfferValidity, required: How long a package from this offer stays usable. one_time offers run once for the given period after activation; recurring offers renew for a further period each time it lapses. Match on type and treat an unrecognized value as an offer your integration cannot order.
      - `type` 'one_time' | 'recurring', required: How the validity period behaves. one_time runs once and expires; recurring renews for a further period each time it lapses.
      - `unit` 'day' | 'month', required: Unit of the validity period.
      - `value` integer, required: Number of units per period.
      - `minimum_periods` integer, nullable: For recurring offers, the minimum number of periods committed. Null when there is no minimum, and for one_time offers.
    - `price` Money, required
      - `amount` string, required: Decimal amount as a string, in major currency units.
      - `currency_code` string, required: ISO 4217 three-letter currency code.
  - `product` string, required: URL-safe identifier for a billing product. Lowercase letters and digits, separated by underscores. Must start with a letter.
  - `status` 'draft' | 'active' | 'retired', required: Availability of an offer. - `draft`: being curated; never returned on the customer surface and not purchasable. - `active`: purchasable. - `retired`: no longer purchasable; packages already sold are unaffected.
  - `created_at` string, date-time, required

## Other responses

- `400`: Bad request
- `401`: Authentication required
- `403`: Insufficient permissions
- `404`: Resource not found
- `422`: The request has invalid field values, violates a business rule, or carries a query parameter the endpoint does not declare. Field validation errors use `type: validation_error` and include the affected fields in `details`. Business-rule errors identify the failed rule in `type`.
- `429`: Rate limit exceeded
- `500`: Internal server error

---

[API](https://skmtc.dev/messagebird/apis/bird-api.md) · [All operations](https://skmtc.dev/messagebird/apis/bird-api/llms.txt) · [OpenAPI document](https://skmtc.dev/messagebird/apis/bird-api/revisions/6dfce1179799?raw)