Table of Contents

Class SubscriptionsApi

Namespace
Cloudflare.NET.Subscriptions
Assembly
Cloudflare.NET.dll

Implementation of ISubscriptionsApi for Cloudflare Subscriptions.

Provides operations for managing subscriptions at account, user, and zone levels. Subscriptions control billing plans and add-ons for Cloudflare services. 

public class SubscriptionsApi : ApiResource, ISubscriptionsApi
Inheritance
SubscriptionsApi
Implements
Inherited Members

Remarks

Billing Permissions Required: All operations require appropriate Billing permissions.

Cost Warning: Creating or updating subscriptions may incur charges.

Constructors

SubscriptionsApi(HttpClient, ILoggerFactory)

Initializes a new instance of the SubscriptionsApi class.

public SubscriptionsApi(HttpClient httpClient, ILoggerFactory loggerFactory)

Parameters

httpClient HttpClient

The HttpClient for making requests.

loggerFactory ILoggerFactory

The factory to create loggers for this resource.

Methods

CreateAccountSubscriptionAsync(string, CreateAccountSubscriptionRequest, CancellationToken)

Creates a new subscription for an account.

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

public 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. 

public 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. 

public 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. 

public 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). 

public 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. 

public 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. 

public 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. 

public 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. 

public 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. 

public 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. 

public 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.

Edit this page