Interface ISubscriptionsApi

Namespace

Cloudflare.NET.Subscriptions

Assembly

Cloudflare.NET.dll

Provides access to Cloudflare Subscriptions API operations.

This interface provides unified access to subscription management across account, user, and zone scopes. Subscriptions manage billing plans and add-ons for Cloudflare services.

public interface ISubscriptionsApi

Examples

// List account subscriptions
var subscriptions = await cf.Subscriptions.ListAccountSubscriptionsAsync(accountId);
foreach (var sub in subscriptions)
{
  Console.WriteLine($"{sub.RatePlan?.PublicName}: {sub.State}");
}

// Create a new subscription
var newSub = await cf.Subscriptions.CreateAccountSubscriptionAsync(accountId,
  new CreateAccountSubscriptionRequest(
    RatePlan: new RatePlanReference("rate_plan_id"),
    Frequency: SubscriptionFrequency.Monthly));

Remarks

Billing Permissions Required: Subscriptions API requires tokens with Billing Read and/or Billing Write permissions.

Cost Warning: Creating or updating subscriptions may incur charges. Use test/sandbox accounts for development.

Externally Managed Subscriptions: Some subscriptions are managed outside of Cloudflare (e.g., through partners) and cannot be modified via API.

Methods

CreateAccountSubscriptionAsync(string, CreateAccountSubscriptionRequest, CancellationToken)

Creates a new subscription for an account.

Warning: Creating subscriptions may incur billing charges. Requires Billing Write permission.

Task<Subscription> CreateAccountSubscriptionAsync(string accountId, CreateAccountSubscriptionRequest request, CancellationToken cancellationToken = default)

Parameters

accountId string

The account identifier.

request CreateAccountSubscriptionRequest

The subscription creation parameters.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<Subscription>

The created subscription.

Examples

var request = new CreateAccountSubscriptionRequest(
  RatePlan: new RatePlanReference("enterprise_plan_id"),
  Frequency: SubscriptionFrequency.Yearly);

var subscription = await cf.Subscriptions.CreateAccountSubscriptionAsync(accountId, request);
Console.WriteLine($"Created: {subscription.Id}");

Remarks

Preview: This operation has limited test coverage.

Exceptions

ArgumentException

Thrown when accountId is null or whitespace.

ArgumentNullException

Thrown when request is null.

HttpRequestException

Thrown when the API request fails (403 if no billing permission).

CloudflareApiException

Thrown when the rate plan is invalid or subscription cannot be created.

CreateZoneSubscriptionAsync(string, CreateZoneSubscriptionRequest, CancellationToken)

Creates a zone subscription (upgrades the zone plan).

Use this to upgrade a zone from Free to a paid plan (Pro, Business, Enterprise).

Warning: Creating subscriptions will incur billing charges for paid plans.

Task<Subscription> CreateZoneSubscriptionAsync(string zoneId, CreateZoneSubscriptionRequest request, CancellationToken cancellationToken = default)

Parameters

zoneId string

The zone identifier.

request CreateZoneSubscriptionRequest

The subscription creation parameters.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<Subscription>

The created subscription.

Examples

// Upgrade to Pro plan
var subscription = await cf.Subscriptions.CreateZoneSubscriptionAsync(zoneId,
  new CreateZoneSubscriptionRequest(
    RatePlan: new RatePlanReference("pro"),
    Frequency: SubscriptionFrequency.Monthly));

Remarks

Preview: This operation has limited test coverage.

Exceptions

ArgumentException

Thrown when zoneId is null or whitespace.

ArgumentNullException

Thrown when request is null.

HttpRequestException

Thrown when the API request fails (404 if zone not found, 403 if no billing permission).

CloudflareApiException

Thrown when the rate plan is invalid or subscription cannot be created.

DeleteAccountSubscriptionAsync(string, string, CancellationToken)

Deletes an account subscription.

Warning: Deleting a subscription will cancel the associated plan. This action may be irreversible.

Note: Externally managed subscriptions cannot be deleted via API.

Task DeleteAccountSubscriptionAsync(string accountId, string subscriptionId, CancellationToken cancellationToken = default)

Parameters

accountId string

The account identifier.

subscriptionId string

The subscription identifier to delete.

cancellationToken CancellationToken

A cancellation token.

Returns

Task

Examples

await cf.Subscriptions.DeleteAccountSubscriptionAsync(accountId, subscriptionId);
Console.WriteLine("Subscription cancelled");

Remarks

Preview: This operation has limited test coverage.

Exceptions

ArgumentException

Thrown when accountId or subscriptionId is null or whitespace.

HttpRequestException

Thrown when the API request fails (404 if not found, 403 if no permission).

CloudflareApiException

Thrown when the subscription is externally managed or deletion fails.

DeleteUserSubscriptionAsync(string, CancellationToken)

Deletes a user subscription.

Warning: Deleting a subscription will cancel the associated plan. This action may be irreversible.

Note: Externally managed subscriptions cannot be deleted via API.

Task<DeleteUserSubscriptionResult> DeleteUserSubscriptionAsync(string subscriptionId, CancellationToken cancellationToken = default)

Parameters

subscriptionId string

The subscription identifier to delete.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<DeleteUserSubscriptionResult>

Result containing the deleted subscription ID.

Examples

var result = await cf.Subscriptions.DeleteUserSubscriptionAsync(subscriptionId);
Console.WriteLine($"Deleted subscription: {result.SubscriptionId}");

Remarks

Preview: This operation has limited test coverage.

Exceptions

ArgumentException

Thrown when subscriptionId is null or whitespace.

HttpRequestException

Thrown when the API request fails (404 if not found, 403 if no permission).

CloudflareApiException

Thrown when the subscription is externally managed or deletion fails.

GetZoneSubscriptionAsync(string, CancellationToken)

Gets the subscription details for a zone.

Returns the current subscription including the rate plan, state, and billing details. Zones always have a subscription (at minimum, a Free plan).

Task<Subscription> GetZoneSubscriptionAsync(string zoneId, CancellationToken cancellationToken = default)

Parameters

zoneId string

The zone identifier.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<Subscription>

The zone subscription details.

Examples

var subscription = await cf.Subscriptions.GetZoneSubscriptionAsync(zoneId);
Console.WriteLine($"Current plan: {subscription.RatePlan?.PublicName}");
Console.WriteLine($"State: {subscription.State}");

Exceptions

ArgumentException

Thrown when zoneId is null or whitespace.

HttpRequestException

Thrown when the API request fails (404 if zone not found, 403 if no billing permission).

ListAccountSubscriptionsAsync(string, CancellationToken)

Lists all subscriptions for an account.

Returns all active and inactive subscriptions associated with the account. Requires Billing Read permission.

Task<IReadOnlyList<Subscription>> ListAccountSubscriptionsAsync(string accountId, CancellationToken cancellationToken = default)

Parameters

accountId string

The account identifier.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<IReadOnlyList<Subscription>>

All subscriptions for the account.

Examples

var subscriptions = await cf.Subscriptions.ListAccountSubscriptionsAsync(accountId);
foreach (var sub in subscriptions)
{
  Console.WriteLine($"{sub.RatePlan?.PublicName}: {sub.Price} {sub.Currency}");
  Console.WriteLine($"  State: {sub.State}, Frequency: {sub.Frequency}");
}

Exceptions

ArgumentException

Thrown when accountId is null or whitespace.

HttpRequestException

Thrown when the API request fails (403 if no billing permission).

ListAvailableRatePlansAsync(string, CancellationToken)

Lists all rate plans available for a zone.

Returns the plans the zone can subscribe to, including pricing information. Use this to discover valid rate plan IDs before creating or updating subscriptions.

Task<IReadOnlyList<ZoneRatePlan>> ListAvailableRatePlansAsync(string zoneId, CancellationToken cancellationToken = default)

Parameters

zoneId string

The zone identifier.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<IReadOnlyList<ZoneRatePlan>>

Available rate plans for the zone.

Examples

var plans = await cf.Subscriptions.ListAvailableRatePlansAsync(zoneId);
foreach (var plan in plans)
{
  Console.WriteLine($"{plan.Name}: {plan.Currency} {plan.Frequency}");
}

Exceptions

ArgumentException

Thrown when zoneId is null or whitespace.

HttpRequestException

Thrown when the API request fails (404 if zone not found).

ListUserSubscriptionsAsync(CancellationToken)

Lists all subscriptions for the authenticated user.

Returns all active and inactive subscriptions owned by the user. Requires Billing Read permission.

Task<IReadOnlyList<Subscription>> ListUserSubscriptionsAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

A cancellation token.

Returns

Task<IReadOnlyList<Subscription>>

All subscriptions for the authenticated user.

Examples

var subscriptions = await cf.Subscriptions.ListUserSubscriptionsAsync();
foreach (var sub in subscriptions)
{
  Console.WriteLine($"{sub.RatePlan?.PublicName}: {sub.State}");
}

Exceptions

HttpRequestException

Thrown when the API request fails (403 if no billing permission).

UpdateAccountSubscriptionAsync(string, string, UpdateAccountSubscriptionRequest, CancellationToken)

Updates an existing account subscription.

Warning: Updating subscriptions may affect billing. Requires Billing Write permission.

Note: Externally managed subscriptions cannot be updated via API.

Task<Subscription> UpdateAccountSubscriptionAsync(string accountId, string subscriptionId, UpdateAccountSubscriptionRequest request, CancellationToken cancellationToken = default)

Parameters

accountId string

The account identifier.

subscriptionId string

The subscription identifier to update.

request UpdateAccountSubscriptionRequest

The update parameters.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<Subscription>

The updated subscription.

Examples

// Change to yearly billing
var request = new UpdateAccountSubscriptionRequest(
  Frequency: SubscriptionFrequency.Yearly);

var updated = await cf.Subscriptions.UpdateAccountSubscriptionAsync(
  accountId, subscriptionId, request);

Remarks

Preview: This operation has limited test coverage.

Exceptions

ArgumentException

Thrown when accountId or subscriptionId is null or whitespace.

ArgumentNullException

Thrown when request is null.

HttpRequestException

Thrown when the API request fails (404 if not found, 403 if no permission).

CloudflareApiException

Thrown when the subscription is externally managed or update fails.

UpdateUserSubscriptionAsync(string, UpdateUserSubscriptionRequest, CancellationToken)

Updates an existing user subscription.

Warning: Updating subscriptions may affect billing. Requires Billing Write permission.

Note: Externally managed subscriptions cannot be updated via API.

Task<Subscription> UpdateUserSubscriptionAsync(string subscriptionId, UpdateUserSubscriptionRequest request, CancellationToken cancellationToken = default)

Parameters

subscriptionId string

The subscription identifier to update.

request UpdateUserSubscriptionRequest

The update parameters.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<Subscription>

The updated subscription.

Examples

// Change to yearly billing
var request = new UpdateUserSubscriptionRequest(
  Frequency: SubscriptionFrequency.Yearly);

var updated = await cf.Subscriptions.UpdateUserSubscriptionAsync(subscriptionId, request);

Remarks

Preview: This operation has limited test coverage.

Exceptions

ArgumentException

Thrown when subscriptionId is null or whitespace.

ArgumentNullException

Thrown when request is null.

HttpRequestException

Thrown when the API request fails (404 if not found, 403 if no permission).

CloudflareApiException

Thrown when the subscription is externally managed or update fails.

UpdateZoneSubscriptionAsync(string, UpdateZoneSubscriptionRequest, CancellationToken)

Updates a zone subscription.

Use this to change the plan, billing frequency, or component values. Can be used to upgrade, downgrade, or modify an existing subscription.

Warning: Updating subscriptions may affect billing.

Task<Subscription> UpdateZoneSubscriptionAsync(string zoneId, UpdateZoneSubscriptionRequest request, CancellationToken cancellationToken = default)

Parameters

zoneId string

The zone identifier.

request UpdateZoneSubscriptionRequest

The update parameters.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<Subscription>

The updated subscription.

Examples

// Downgrade to Pro from Business
var subscription = await cf.Subscriptions.UpdateZoneSubscriptionAsync(zoneId,
  new UpdateZoneSubscriptionRequest(
    RatePlan: new RatePlanReference("pro")));

Remarks

Preview: This operation has limited test coverage.

Exceptions

ArgumentException

Thrown when zoneId is null or whitespace.

ArgumentNullException

Thrown when request is null.

HttpRequestException

Thrown when the API request fails (404 if zone not found, 403 if no billing permission).

CloudflareApiException

Thrown when the rate plan is invalid or update fails.