Managing Subscriptions through API

Subscriptions through API provide developers with detailed guide on how to handle subscription-related operations using API endpoints. This includes updating, retrieving, & cancelling subscriptions.

Managing subscriptions is a key feature of the Fungies.io platform, allowing businesses to offer recurring billing and subscription-based services to their users. The subscription endpoints enable developers to retrieve, manage, and cancel subscriptions, providing full control over the subscription lifecycle. These endpoints are particularly useful for handling subscription statuses, updating customer details, and processing cancellations.

To access these endpoints, authentication via API keys is required, you can go through the "Getting Started with the API" guide in which you will learn how you can generate the API-key and write-API-key.

After generating the API key and write-API key you can immediately start making requests to the Fungies Subscriptions API endpoints.

GET /subscriptions/list (List All Subscriptions)

The /subscriptions/list endpoint is used to retrieve a list of all subscriptions from the Fungies.io platform. It allows developers to access details of every subscription within the system, providing an overview of active, cancelled, or all subscriptions.

Note: This endpoint requires an API key for authentication.

This is a GET API endpoint that accepts the following parameters:

• status: Specifies the current status of the subscriptions. Possible values include-

  active: Lists all active subscriptions. canceled: Lists all cancelled subscriptions. all: Lists both active and cancelled subscriptions.

• cursor: The cursor parameter is used for pagination. It points to a specific position in a list of results, allowing you to retrieve the next set of data starting from this position.

• take: The take parameter defines the number of items to return in a single request. It controls how many records are fetched from the database or API at once. For example, the setting take=10 would retrieve 10 records per request.

Successful Response:

When the request is successful, you will receive a response like this:

{
  "status": "<string>",
  "data": {
    "subscriptions": [
      {
        "id": "<string>",
        "currentPeriodEnd": "2023-11-07T05:31:56Z",
        "currentPeriodStart": "2023-11-07T05:31:56Z",
        "cancelAtPeriodEnd": true,
        "createdAt": "2023-11-07T05:31:56Z",
        "status": "active",
        "interval": "day",
        "canceledAt": "2023-11-07T05:31:56Z",
        "cancellationDetails": {
          "comment": "<string>",
          "feedback": "<string>",
          "reason": "<string>"
        },
        "user": {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "email": "[e-mail]",
          "createdAt": "2023-11-07T05:31:56Z",
          "details": {
            "avatar": "<string>"
          },
          "settings": {
            "newsletter": true
          },
          "username": "<string>"
        },
        "cart": {
          "id": "<string>",
          "status": "ACTIVE",
          "itemsInCart": 0,
          "totalValue": 0,
          "subtotal": 0,
          "totalValueWithTax": 0,
          "totalTax": 0,
          "createdAt": "2023-11-07T05:31:56Z"
        }
      }
    ],
    "count": 0
  }
}

Error Response:

If the request fails, you will receive an error response like this:

{
  "status": "error",
  "error": {
    "message": "Sample error message"
  }
}

GET /subscriptions/{subscriptionId} (Get Subscription by ID)

The /subscriptions/{subscriptionId} endpoint is used to retrieve details of a specific subscription by its unique ID. This allows developers to access subscription information for a particular user.

Note: This endpoint requires an API key for authentication.

This is a GET API endpoint that accepts a single parameter to filter the results:

• subscriptionId: The unique ID of the subscription you want to retrieve.

Successful Response:

When the request is successful, you will receive a response like this:

{
  "status": "<string>",
  "data": {
    "id": "<string>",
    "currentPeriodEnd": "2023-11-07T05:31:56Z",
    "currentPeriodStart": "2023-11-07T05:31:56Z",
    "cancelAtPeriodEnd": true,
    "createdAt": "2023-11-07T05:31:56Z",
    "status": "active",
    "interval": "day",
    "canceledAt": "2023-11-07T05:31:56Z",
    "cancellationDetails": {
      "comment": "<string>",
      "feedback": "<string>",
      "reason": "<string>"
    },
    "user": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "email": "[e-mail]",
      "createdAt": "2023-11-07T05:31:56Z",
      "details": {
        "avatar": "<string>"
      },
      "settings": {
        "newsletter": true
      },
      "username": "<string>"
    },
    "cart": {
      "id": "<string>",
      "status": "ACTIVE",
      "itemsInCart": 0,
      "totalValue": 0,
      "subtotal": 0,
      "totalValueWithTax": 0,
      "totalTax": 0,
      "createdAt": "2023-11-07T05:31:56Z"
    }
  }
}

Error Response:

If the request fails, you will receive an error response like this:

{
  "status": "error",
  "error": {
    "message": "Sample error message"
  }
}

PATCH /subscriptions/{subscriptionId}/cancel (Cancel Subscription)

The /subscriptions/{subscriptionId}/cancel endpoint is used to cancel a specific subscription by its ID. It allows developers to cancel a user's subscription and offers options for how the cancellation should be handled, such as immediate cancellation or at the end of the billing period.

Note: This endpoint requires an API key and write-API key (both) for authentication at the same time.

This is a PATCH API endpoint that requires the following in the request body:

• Id: The ID used as the unique identifier of the specific subscription.

• cancelOption: The cancelOption determines how the subscription should be cancelled. It allows you to specify whether the cancellation should take effect immediately or at the end of the current billing cycle. Available options- immediately: When set, the action (such as cancellation or modification of the subscription) will take effect immediately upon execution. endPeriod: When set, the action will be deferred until the end of the current billing period. This allows the subscription to continue through the remainder of the paid period before changes like cancellation or downgrades are applied.

• refundOption: The refundOption defines how refunds should be handled when a subscription is cancelled. It provides options for whether and how much to refund the user based on the timing of the cancellation. Available options: noRefund: When set, this parameter ensures that no refund is issued upon cancellation of the subscription, regardless of any remaining time in the billing cycle. lastPayment: When set, the system will retain the last payment made for the subscription without issuing a refund or making any adjustments. prorate: When set, this parameter enables prorated adjustments based on the remaining time in the subscription period. For example, if a user upgrades or downgrades their subscription in the middle of a billing cycle, the system will calculate a prorated charge or credit to reflect the partial use of the original plan.

Successful Response:

When the request is successful, you will receive a response like this:

{
  "status": "<string>",
  "data": {
    "success": true
  }
}

Error Response:

If the request fails, you will receive an error response like this:

{
  "status": "error",
  "error": {
    "message": "Sample error message"
  }
}