Sign in
Subscriptions

Retrieve a Subscription

Retrieves a Subscription by its ID

get/subscriptions/{id}

Path parameters

idstring required

Response

OK

createdAtstring date-time required

The date and time when the entity was created.

updatedAtstring date-time nullable required

The date and time when the entity was last updated.

metadataobject nullable

Metadata used by merchants to store additional information about the entity.

idstring required

The ID of the subscription

status'active' | 'cancelled' required

The status of the subscription

isRecoveringboolean required

Whether the subscription is recovering from a failed payment

autoBillingEnabledboolean required

Whether the subscription is going to be billed automatically

autoBillingDisabledAtstring date-time nullable required

The date when auto billing was disabled

autoBillingDisabledReason'recurring_payment_errored' | 'subscription_cancelled' | 'latest_invoice_retrying' | 'null' nullable required

The reason why auto billing was disabled

startDatestring date-time required

The start date of the subscription

endDatestring date-time nullable required

The end date of the subscription, if it has ended

cancelAtPeriodEndboolean required

Whether the subscription should be cancelled when current billing cycle ends

cancelAtCyclenumber nullable required

The cycle at whose end the subscription is scheduled to be cancelled, or absent when no cancellation is scheduled. Equals currentCycle once cancelAtPeriodEnd is true

currentCyclenumber required

The current cycle of the subscription, starting from 1

currentPeriodStartstring date-time required

The start date of the current billing period

currentPeriodEndstring date-time required

The end date of the current billing period

setupInvoicestring required

The ID of the invoice that set up the subscription

setupLineItemstring nullable required

The ID of the line item that set up the subscription

Example response

{
  "createdAt": "2024-02-18T12:00:00Z",
  "updatedAt": "2024-02-21T12:15:00Z",
  "metadata": {
    "key1": "value1",
    "key2": "value2"
  },
  "id": "sub_2QC7PqoUeOxQEWscJJt6B3PkvyL",
  "status": "active",
  "autoBillingEnabled": true,
  "autoBillingDisabledReason": "subscription_cancelled",
  "cancelAtPeriodEnd": true,
  "cancelAtCycle": 2,
  "currentCycle": 1,
  "billingSettings": {
    "captureDelay": 3
  },
  "upcomingInvoice": {
    "amount": 1500,
    "currency": "usd",
    "periodStart": "2023-01-01T00:00:00Z",
    "periodEnd": "2023-01-31T23:59:59Z",
    "statementDescriptor": "SUBSCRIPTION",
    "comment": "Invoice for subscription 123, period January 2023"
  },
  "customer": {
    "createdAt": "2024-02-18T12:00:00Z",
    "updatedAt": "2024-02-21T12:15:00Z",
    "metadata": {
      "key1": "value1",
      "key2": "value2"
    },
    "id": "cus_2QC7PqoUeOxQEWscJJt6B3PkvyL",
    "email": "user@gmail.com",
    "name": "John Doe",
    "phoneNumber": "+1234567890",
    "dateOfBirth": "2020-01-01",
    "gender": "male",
    "restrictReason": "Customer restricted due to suspicious activity",
    "isRestricted": true
  },
  "price": {
    "createdAt": "2024-02-18T12:00:00Z",
    "updatedAt": "2024-02-21T12:15:00Z",
    "metadata": {
      "key1": "value1",
      "key2": "value2"
    },
    "id": "price_2R4e2xDqbww8ewmkIYWE1A6Zcfp",
    "type": "recurring",
    "active": true,
    "name": "My Digital Subscription",
    "amount": 1500,
    "quantity": 1,
    "currency": "usd",
    "product": {
      "createdAt": "2024-02-18T12:00:00Z",
      "updatedAt": "2024-02-21T12:15:00Z",
      "metadata": {
        "key1": "value1",
        "key2": "value2"
      },
      "id": "prod_2QC7PqoUeOxQEWscJJt6B3PkvyL",
      "active": true,
      "name": "My product",
      "description": "Best selling product",
      "statementDescriptor": "Face Yoga subscription",
      "category": "digital",
      "sku": "FY-YOGA-MAT-01"
    },
    "billingSchedule": {
      "createdAt": "2024-02-18T12:00:00Z",
      "updatedAt": "2024-02-21T12:15:00Z",
      "metadata": {
        "key1": "value1",
        "key2": "value2"
      },
      "id": "bsch_2QC7PqoUeOxQEWscJJt6B3PkvyL",
      "currency": "usd",
      "cycleDefinitions": [
        {
          "createdAt": "2024-02-18T12:00:00Z",
          "updatedAt": "2024-02-21T12:15:00Z",
          "metadata": {
            "key1": "value1",
            "key2": "value2"
          },
          "position": 1,
          "amount": 1500,
          "currency": "usd"
        }
      ]
    },
    "recurringSchedule": {
      "intervalUnit": "month",
      "intervalCount": 1,
      "trial": {
        "intervalUnit": "day",
        "intervalCount": 7,
        "amount": 199
      }
    }
  },
  "invoices": [
    {
      "createdAt": "2024-02-18T12:00:00Z",
      "updatedAt": "2024-02-21T12:15:00Z",
      "metadata": {
        "key1": "value1",
        "key2": "value2"
      },
      "status": "open",
      "voidedReason": "Grace period expired",
      "comment": "This is a comment for the invoice",
      "amount": 999,
      "currency": "usd",
      "type": "setup",
      "number": "2W12-1004",
      "customer": {
        "createdAt": "2024-02-18T12:00:00Z",
        "updatedAt": "2024-02-21T12:15:00Z",
        "metadata": {
          "key1": "value1",
          "key2": "value2"
        },
        "id": "cus_2QC7PqoUeOxQEWscJJt6B3PkvyL",
        "email": "user@gmail.com",
        "name": "John Doe",
        "phoneNumber": "+1234567890",
        "dateOfBirth": "2020-01-01",
        "gender": "male",
        "restrictReason": "Customer restricted due to suspicious activity",
        "isRestricted": true
      }
    }
  ]
}

Changes

No recorded changes to this endpoint across all 1 revision of this API.