---
title: "Cancel recurring eSIM renewal"
method: POST
path: "/v1/esim/subscriptions/{subscription_id}/cancel"
tags: ["esims"]
---

# Cancel recurring eSIM renewal

`POST /v1/esim/subscriptions/{subscription_id}/cancel`

## Request

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

Stops future package renewal at the current paid boundary. A period already committed remains payable. The installed profile and separately purchased packages are preserved.

## Headers

- `X-Workspace-Id` string
- `Idempotency-Key` string
- `X-Organization-Id` string

## Response `200`

The requested resource.

- union: Recurring service for an assigned eSIM or a pending initial purchase. Paid periods and delivered connectivity have separate states. Ending recurrence preserves the profile and separately purchased packages.
  - object
    - `delivery_mode` 'exact_period' | 'recurring_top_up', required: Relationship between the paid period and package delivery. - `exact_period`: the package covers the accepted paid interval. - `recurring_top_up`: each funded period purchases a standard package. Activation, expiry, and accumulation follow that package’s terms.
    - `id` string, required
    - `esim_id` string, nullable, required: The provisioned eSIM, or null while the initial purchase is pending.
    - `initial_order_id` string, required
    - `subscriber_id` string, required
    - `offer_id` string, required
    - `status` 'pending' | 'active' | 'needs_attention' | 'ended', required: Delivery state of the recurring service. Check payment and renewal fields separately. - `pending`: enrollment or the initial purchase is still being processed. - `active`: the service has delivered a package and remains active. - `needs_attention`: delivery or a related credit remains unresolved. Check period history and the associated order before purchasing a replacement. - `ended`: recurrence has ended. Previously delivered packages keep their own validity.
    - `billing_status` string, nullable, required: The financial subscription state, or null while acceptance is pending.
    - `current_period_start` string, date-time, nullable, required: The authoritative billing period boundary, or null while acceptance is pending.
    - `current_period_end` string, date-time, nullable, required: The authoritative billing period boundary, or null while acceptance is pending.
    - `cancel_at_period_end` boolean, required: Whether future renewal is stopped at the current paid boundary.
    - `latest_order_id` string, required
    - `created_at` string, date-time, required: When the recurring service was requested.
    - `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.
    - `model` 'calendar_month' | 'fixed_days', required: Billing cadence for recurring packages. - `calendar_month`: periods follow calendar months from the billing anchor. - `fixed_days`: each period lasts the stated number of 24-hour days.
    - `interval_count` integer, nullable, required: Number of calendar months or fixed 24-hour days in each accepted period. Null before acceptance.
    - `next_renewal_at` string, date-time, nullable, required: Next scheduled renewal boundary. Null when enrollment is pending or future renewals have stopped.
    - `cancellation_effective_at` string, date-time, nullable, required: When canceled recurrence ends: the paid boundary for scheduled cancellation, or the recorded cancellation time for an immediate stop. Null when renewal has not been stopped or no period was accepted. Paid packages remain available under their own validity.
    - `stop_reason` 'canceled' | 'funding_unavailable' | 'price_changed' | 'delivery_failed' | 'delivery_unresolved', required: Reason future package renewal stopped. - `canceled`: cancellation was requested. - `funding_unavailable`: the next period could not be funded. - `price_changed`: the published price changed and requires new acceptance. - `delivery_failed`: a paid package could not be delivered. - `delivery_unresolved`: the previous period’s delivery remains unresolved. Check period history for delivery and credit outcomes before starting another subscription.
  - object
    - `delivery_mode` 'exact_period' | 'recurring_top_up', required: Relationship between the paid period and package delivery. - `exact_period`: the package covers the accepted paid interval. - `recurring_top_up`: each funded period purchases a standard package. Activation, expiry, and accumulation follow that package’s terms.
    - `id` string, required
    - `esim_id` string, required
    - `initial_order_id` string, nullable, required: The initial purchase order, or null when recurrence was enrolled on an existing eSIM.
    - `subscriber_id` string, required
    - `offer_id` string, required
    - `status` 'pending' | 'active' | 'needs_attention' | 'ended', required: Delivery state of the recurring service. Check payment and renewal fields separately. - `pending`: enrollment or the initial purchase is still being processed. - `active`: the service has delivered a package and remains active. - `needs_attention`: delivery or a related credit remains unresolved. Check period history and the associated order before purchasing a replacement. - `ended`: recurrence has ended. Previously delivered packages keep their own validity.
    - `billing_status` string, nullable, required: The financial subscription state, or null while acceptance is pending.
    - `current_period_start` string, date-time, nullable, required: The authoritative billing period boundary, or null while acceptance is pending.
    - `current_period_end` string, date-time, nullable, required: The authoritative billing period boundary, or null while acceptance is pending.
    - `cancel_at_period_end` boolean, required: Whether future renewal is stopped at the current paid boundary.
    - `latest_order_id` string, required
    - `created_at` string, date-time, required: When the recurring service was requested.
    - `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.
    - `model` 'calendar_month' | 'fixed_days', required: Billing cadence for recurring packages. - `calendar_month`: periods follow calendar months from the billing anchor. - `fixed_days`: each period lasts the stated number of 24-hour days.
    - `interval_count` integer, nullable, required: Number of calendar months or fixed 24-hour days in each accepted period. Null before acceptance.
    - `next_renewal_at` string, date-time, nullable, required: Next scheduled renewal boundary. Null when enrollment is pending or future renewals have stopped.
    - `cancellation_effective_at` string, date-time, nullable, required: When canceled recurrence ends: the paid boundary for scheduled cancellation, or the recorded cancellation time for an immediate stop. Null when renewal has not been stopped or no period was accepted. Paid packages remain available under their own validity.
    - `stop_reason` 'canceled' | 'funding_unavailable' | 'price_changed' | 'delivery_failed' | 'delivery_unresolved', required: Reason future package renewal stopped. - `canceled`: cancellation was requested. - `funding_unavailable`: the next period could not be funded. - `price_changed`: the published price changed and requires new acceptance. - `delivery_failed`: a paid package could not be delivered. - `delivery_unresolved`: the previous period’s delivery remains unresolved. Check period history for delivery and credit outcomes before starting another subscription.

## Other responses

- `400`: Bad request
- `401`: Authentication required
- `403`: Insufficient permissions
- `404`: Resource not found
- `409`: Resource conflict
- `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
- `503`: The service is temporarily unavailable. If `Retry-After` is present, wait for that delay before retrying; otherwise, retry with exponential backoff. Reuse the same idempotency key and request when retrying a mutation.

---

[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)