Get Subscriptions

Retrieve subscription information for an account. For accounts with enterprise plans, this endpoint returns a simplified response indicating enterprise status.

Endpoint

GET https://api.recoupable.com/api/subscriptions

Parameters

Name	Type	Required	Description
accountId	string	Yes	The unique identifier of the account to query

Request Examples

cURL

curl -X GET "https://api.recoupable.com/api/subscriptions?accountId=YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json"

Response Format

The API returns different response formats based on the account type:

Standard Account Response

For accounts with regular subscriptions, the API returns the full Stripe subscription object:

{
  "status": "success",
  "subscription": {
    "id": "sub_1MowQVLkdIwHu7ixeRlqHVzs",
    "object": "subscription",
    "application": null,
    "application_fee_percent": null,
    "automatic_tax": {
      "enabled": false,
      "liability": null
    },
    "billing_cycle_anchor": 1679609767,
    "billing_thresholds": null,
    "cancel_at": null,
    "cancel_at_period_end": false,
    "canceled_at": null,
    "cancellation_details": {
      "comment": null,
      "feedback": null,
      "reason": null
    },
    "collection_method": "charge_automatically",
    "created": 1679609767,
    "currency": "usd",
    "customer": "cus_Na6dX7aXxi11N4",
    "days_until_due": null,
    "default_payment_method": null,
    "default_source": null,
    "default_tax_rates": [],
    "description": null,
    "discount": null,
    "discounts": null,
    "ended_at": null,
    "invoice_settings": {
      "issuer": {
        "type": "self"
      }
    },
    "items": {
      "object": "list",
      "data": [
        {
          "id": "si_Na6dzxczY5fwHx",
          "object": "subscription_item",
          "billing_thresholds": null,
          "created": 1679609768,
          "current_period_end": 1682288167,
          "current_period_start": 1679609767,
          "metadata": {},
          "plan": {
            "id": "price_1MowQULkdIwHu7ixraBm864M",
            "object": "plan",
            "active": true,
            "aggregate_usage": null,
            "amount": 1000,
            "amount_decimal": "1000",
            "billing_scheme": "per_unit",
            "created": 1679609766,
            "currency": "usd",
            "discounts": null,
            "interval": "month",
            "interval_count": 1,
            "livemode": false,
            "metadata": {},
            "nickname": null,
            "product": "prod_Na6dGcTsmU0I4R",
            "tiers_mode": null,
            "transform_usage": null,
            "trial_period_days": null,
            "usage_type": "licensed"
          },
          "price": {
            "id": "price_1MowQULkdIwHu7ixraBm864M",
            "object": "price",
            "active": true,
            "billing_scheme": "per_unit",
            "created": 1679609766,
            "currency": "usd",
            "custom_unit_amount": null,
            "livemode": false,
            "lookup_key": null,
            "metadata": {},
            "nickname": null,
            "product": "prod_Na6dGcTsmU0I4R",
            "recurring": {
              "aggregate_usage": null,
              "interval": "month",
              "interval_count": 1,
              "trial_period_days": null,
              "usage_type": "licensed"
            },
            "tax_behavior": "unspecified",
            "tiers_mode": null,
            "transform_quantity": null,
            "type": "recurring",
            "unit_amount": 1000,
            "unit_amount_decimal": "1000"
          },
          "quantity": 1,
          "subscription": "sub_1MowQVLkdIwHu7ixeRlqHVzs",
          "tax_rates": []
        }
      ],
      "has_more": false,
      "total_count": 1,
      "url": "/v1/subscription_items?subscription=sub_1MowQVLkdIwHu7ixeRlqHVzs"
    },
    "latest_invoice": "in_1MowQWLkdIwHu7ixuzkSPfKd",
    "livemode": false,
    "metadata": {},
    "next_pending_invoice_item_invoice": null,
    "on_behalf_of": null,
    "pause_collection": null,
    "payment_settings": {
      "payment_method_options": null,
      "payment_method_types": null,
      "save_default_payment_method": "off"
    },
    "pending_invoice_item_interval": null,
    "pending_setup_intent": null,
    "pending_update": null,
    "schedule": null,
    "start_date": 1679609767,
    "status": "active",
    "test_clock": null,
    "transfer_data": null,
    "trial_end": null,
    "trial_settings": {
      "end_behavior": {
        "missing_payment_method": "create_invoice"
      }
    },
    "trial_start": null
  }
}

Enterprise Account Response

For accounts with enterprise plans, the API returns a simplified response:

{
  "status": "success",
  "isEnterprise": true
}

Response Properties

Standard Response Object

Property	Type	Description
status	string	Status of the request ("success" or "error")
subscription	StripeSubscription	Full Stripe subscription object (see Stripe Documentation)

Enterprise Response Object

Property	Type	Description
status	string	Status of the request ("success" or "error")
isEnterprise	boolean	Indicates if the account has an enterprise plan

Stripe Subscription Reference

This endpoint returns subscription data that follows the Stripe Subscription object structure. For detailed information about all available properties and their meanings, refer to the official Stripe documentation.

Key Stripe subscription properties include:

Status values: active, canceled, incomplete, incomplete_expired, past_due, trialing, unpaid
Billing intervals: day, week, month, year
Currency codes: Three-letter ISO codes (e.g., usd, eur, gbp)

Error Handling

The API uses conventional HTTP response codes:

200: Success
400: Bad Request (missing or invalid accountId)
401: Unauthorized
404: Account not found
500: Internal Server Error

Example error response:

{
  "status": "error",
  "error": "Account not found"
}

Notes

Enterprise accounts receive a simplified response (isEnterprise: true) instead of detailed subscription data
All timestamps are returned as Unix timestamps (seconds since epoch)
The subscription object structure matches Stripe's API exactly for compatibility
For detailed subscription management operations, refer to the Stripe Subscriptions API documentation