# Get Subscription

> Get a single subscription by its ID. Results are limited to only show subscriptions authorized by the X-API-Key and X-Publishable-Key.

Source: https://help.boltapp.com/api-reference/endpoints/subscriptions/getsubscription

`GET /v1/subscriptions/{subscription_id}`

## OpenAPI definition

This endpoint as it appears in the OpenAPI document, with every schema it references included.

```json
{
  "openapi": "3.2.0",
  "info": {
    "version": "1.0.1",
    "title": "Bolt API Reference",
    "description": "Postman Collection:\n\n[![](https://run.pstmn.io/button.svg)](https://god.gw.postman.com/run-collection/9136127-55d2bde1-a248-473f-95b5-64cfd02fb445?action=collection%2Ffork&collection-url=entityId%3D9136127-55d2bde1-a248-473f-95b5-64cfd02fb445%26entityType%3Dcollection%26workspaceId%3D78beee89-4238-4c5f-bd1f-7e98978744b4#?env%5BBolt%20Sandbox%20Environment%5D=W3sia2V5IjoiYXBpX2Jhc2VfdXJsIiwidmFsdWUiOiJodHRwczovL2FwaS1zYW5kYm94LmJvbHQuY29tIiwidHlwZSI6ImRlZmF1bHQiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6InRrX2Jhc2UiLCJ2YWx1ZSI6Imh0dHBzOi8vc2FuZGJveC5ib2x0dGsuY29tIiwidHlwZSI6ImRlZmF1bHQiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImFwaV9rZXkiLCJ2YWx1ZSI6IjxyZXBsYWNlIHdpdGggeW91ciBCb2x0IFNhbmRib3ggQVBJIGtleT4iLCJ0eXBlIjoic2VjcmV0IiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJwdWJsaXNoYWJsZV9rZXkiLCJ2YWx1ZSI6IjxyZXBsYWNlIHdpdGggeW91ciBCb2x0IFNhbmRib3ggcHVibGlzaGFibGUga2V5PiIsInR5cGUiOiJkZWZhdWx0IiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJkaXZpc2lvbl9pZCIsInZhbHVlIjoiPHJlcGxhY2Ugd2l0aCB5b3VyIEJvbHQgU2FuZGJveCBwdWJsaWMgZGl2aXNpb24gSUQ+IiwidHlwZSI6ImRlZmF1bHQiLCJlbmFibGVkIjp0cnVlfV0=)\n\n## About\n A comprehensive Bolt API reference for interacting with Transactions, Orders, Product Catalog, Configuration, Testing, and much more.\n\n Note: You must also reference the [Merchant Callback API](/api-merchant) when building a managed checkout custom cart integration\n"
  },
  "servers": [
    {
      "url": "https://api.boltapp.com",
      "description": "The Production URL (Live Data)."
    },
    {
      "url": "https://api-sandbox.boltapp.com",
      "description": "The Sandbox URL (Test Data)."
    },
    {
      "url": "https://api-staging.boltapp.com",
      "description": "The Staging URL (Staged Data)."
    }
  ],
  "security": [
    {
      "X-API-Key": []
    },
    {
      "OAuth": [
        "bolt.account.manage",
        "bolt.account.view"
      ]
    }
  ],
  "paths": {
    "/v1/subscriptions/{subscription_id}": {
      "get": {
        "description": "Get a single subscription by its ID. Results are limited to only show subscriptions authorized by the X-API-Key and X-Publishable-Key.",
        "operationId": "getSubscription",
        "parameters": [
          {
            "$ref": "#/components/parameters/subscription_v2_id_path"
          },
          {
            "$ref": "#/components/parameters/x_publishable_key_required"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/subscription_v2"
                }
              }
            },
            "description": "Success"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/errors_bolt_api_response"
                }
              }
            },
            "description": "BAD REQUEST. Request is malformed or invalid values are detected."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/errors_bolt_api_response"
                }
              }
            },
            "description": "UNAUTHORIZED. Missing or invalid X-API-Key or X-Publishable-Key."
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/errors_bolt_api_response"
                }
              }
            },
            "description": "NOT FOUND. Unable to find a subscription with this ID for this merchant division."
          }
        },
        "security": [
          {
            "X-API-Key": []
          }
        ],
        "summary": "Get Subscription",
        "tags": [
          "Subscriptions"
        ]
      }
    }
  },
  "components": {
    "parameters": {
      "subscription_v2_id_path": {
        "description": "The unique ID for the subscription.",
        "in": "path",
        "name": "subscription_id",
        "required": true,
        "schema": {
          "$ref": "#/components/schemas/subscription_v2_id"
        }
      },
      "x_publishable_key_required": {
        "description": "The publicly viewable identifier used to identify a merchant division. This key is found in the Developer > API section of the Bolt Merchant Dashboard.",
        "in": "header",
        "name": "X-Publishable-Key",
        "required": true,
        "schema": {
          "type": "string"
        }
      }
    },
    "schemas": {
      "subscription_v2_id": {
        "description": "The unique ID for a Bolt subscription.",
        "title": "Subscription ID",
        "type": "string",
        "examples": [
          "sub_1a2b3c4d5e"
        ]
      },
      "subscription_v2": {
        "description": "A Bolt subscription.",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/subscription_v2_id"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          },
          "merchant_name": {
            "description": "The name of the merchant this subscription belongs to.",
            "type": "string",
            "examples": [
              "Bolt Swag Store"
            ]
          },
          "email": {
            "description": "The email address of the shopper who owns this subscription. Nullable.",
            "type": [
              "string",
              "null"
            ],
            "examples": [
              "shopper@example.com"
            ]
          },
          "status_details": {
            "$ref": "#/components/schemas/subscription_v2_status_details"
          },
          "payment_method": {
            "$ref": "#/components/schemas/subscription_v2_payment_method"
          },
          "next_renewal_date": {
            "description": "The date of the next scheduled renewal, if any.",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "next_payment_retry_date": {
            "description": "The date of the next scheduled payment retry, if the subscription currently has a failed payment.",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "canceled_date": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "paused_date": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "plan": {
            "$ref": "#/components/schemas/subscription_v2_plan"
          },
          "product_names": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "total_amount": {
            "$ref": "#/components/schemas/amounts"
          },
          "metadata": {
            "additionalProperties": {
              "type": "string"
            },
            "description": "Merchant-defined custom metadata.",
            "type": "object"
          }
        },
        "required": [
          "id",
          "created_at",
          "updated_at",
          "merchant_name",
          "email",
          "status_details",
          "plan",
          "product_names",
          "total_amount",
          "metadata"
        ],
        "title": "Subscription",
        "type": "object"
      },
      "subscription_v2_status_details": {
        "description": "Details about the subscription's current status.",
        "properties": {
          "type": {
            "$ref": "#/components/schemas/subscription_v2_status"
          },
          "reason": {
            "description": "Additional context for the current status, when available.",
            "type": "string",
            "examples": [
              "payment_failed"
            ]
          }
        },
        "required": [
          "type"
        ],
        "title": "Subscription Status Details",
        "type": "object"
      },
      "subscription_v2_status": {
        "description": "The current status of the subscription.",
        "enum": [
          "active",
          "paused",
          "canceled",
          "payment_failed"
        ],
        "title": "Subscription Status",
        "type": "string",
        "examples": [
          "active"
        ]
      },
      "subscription_v2_payment_method": {
        "description": "The card currently used to pay for this subscription.",
        "properties": {
          "card_last_4": {
            "description": "The last 4 digits of the card number.",
            "type": "string",
            "examples": [
              "4242"
            ]
          },
          "card_network": {
            "description": "The card network (e.g. Visa, Mastercard).",
            "type": "string",
            "examples": [
              "visa"
            ]
          }
        },
        "required": [
          "card_last_4",
          "card_network"
        ],
        "title": "Subscription Payment Method",
        "type": "object"
      },
      "subscription_v2_plan": {
        "description": "The billing plan the subscription is enrolled in.",
        "properties": {
          "id": {
            "description": "The unique ID for the subscription plan.",
            "type": "string",
            "examples": [
              "plan_9f8e7d6c5b"
            ]
          },
          "name": {
            "description": "The display name of the plan.",
            "type": "string",
            "examples": [
              "Monthly"
            ]
          },
          "sku": {
            "description": "The merchant-defined SKU for the plan.",
            "type": "string",
            "examples": [
              "SUB-MONTHLY-001"
            ]
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          },
          "frequency": {
            "description": "The number of `frequency_unit`s between each billing cycle.",
            "type": "integer",
            "examples": [
              1
            ]
          },
          "frequency_unit": {
            "description": "The unit of time between billing cycles.",
            "enum": [
              "day",
              "week",
              "month",
              "year"
            ],
            "type": "string",
            "examples": [
              "month"
            ]
          },
          "product_id": {
            "description": "The unique ID of the subscription product this plan belongs to.",
            "type": "string",
            "examples": [
              "prod_3c2b1a0f9e"
            ]
          },
          "checkout_link": {
            "description": "A hosted checkout link for this plan, when available.",
            "type": "string",
            "examples": [
              "https://subscribe.boltapp.com/plans/plan_9f8e7d6c5b"
            ]
          },
          "initial_period": {
            "$ref": "#/components/schemas/subscription_v2_initial_period"
          }
        },
        "required": [
          "id",
          "name",
          "sku",
          "created_at",
          "updated_at",
          "frequency",
          "frequency_unit",
          "product_id"
        ],
        "title": "Subscription Plan",
        "type": "object"
      },
      "subscription_v2_initial_period": {
        "description": "An initial billing period, such as a trial or introductory offer, that differs from the plan's regular frequency.",
        "properties": {
          "frequency": {
            "description": "The number of `frequency_unit`s in the initial period.",
            "type": "integer",
            "examples": [
              14
            ]
          },
          "frequency_unit": {
            "description": "The unit of time for the initial period's frequency.",
            "enum": [
              "day",
              "week",
              "month",
              "year"
            ],
            "type": "string",
            "examples": [
              "day"
            ]
          }
        },
        "required": [
          "frequency",
          "frequency_unit"
        ],
        "title": "Subscription Initial Period",
        "type": "object"
      },
      "amounts": {
        "description": "The amount. **Nullable** for Transactions Details.",
        "properties": {
          "amount": {
            "$ref": "#/components/schemas/amount"
          },
          "currency": {
            "$ref": "#/components/schemas/currency_iso"
          },
          "currency_symbol": {
            "$ref": "#/components/schemas/currency_symbol"
          }
        },
        "required": [
          "amount",
          "currency",
          "currency_symbol"
        ],
        "type": "object"
      },
      "amount": {
        "description": "The amount in cents. **Nullable** for Transactions Details.",
        "type": "integer",
        "examples": [
          754
        ]
      },
      "currency_iso": {
        "description": "The 3-digit ISO code for the currency. **Nullable** for Transactions Details.",
        "type": "string",
        "examples": [
          "USD"
        ]
      },
      "currency_symbol": {
        "description": "The currency symbol used for the amount. **Nullable** for Transactions Details.",
        "type": "string",
        "examples": [
          "$"
        ]
      },
      "errors_bolt_api_response": {
        "properties": {
          "errors": {
            "$ref": "#/components/schemas/errors_bolt_api"
          },
          "result": {
            "$ref": "#/components/schemas/request_result"
          }
        },
        "type": "object"
      },
      "errors_bolt_api": {
        "items": {
          "$ref": "#/components/schemas/error_bolt_api"
        },
        "type": "array"
      },
      "error_bolt_api": {
        "properties": {
          "code": {
            "$ref": "#/components/schemas/code"
          },
          "message": {
            "$ref": "#/components/schemas/message"
          }
        },
        "type": "object",
        "description": "Error object containing custom error information"
      },
      "code": {
        "description": "Custom-defined Bolt error code. This can be used to programmatically react to specific errors.",
        "format": "int64",
        "type": "integer",
        "examples": [
          2001005
        ]
      },
      "message": {
        "description": "Human-readable description of the error for developers. Should not be shown to users and is not localized.",
        "type": "string",
        "examples": [
          "The input is missing a required parameter."
        ]
      },
      "request_result": {
        "description": "Custom-defined Bolt result object.",
        "properties": {
          "success": {
            "$ref": "#/components/schemas/request_failed"
          }
        },
        "type": "object"
      },
      "request_failed": {
        "type": "boolean",
        "description": "Indicates that the request failed. This value is always false.",
        "examples": [
          false
        ]
      }
    },
    "securitySchemes": {
      "OAuth": {
        "description": "Bolt utilizes the OAuth flow that developers can use to attain access to Bolt Account data via APIs.\nFor all APIs that require authorization, please provide your `access_token` returned from `/v1/oauth/token` via the basic auth bearer header `Authorization: bearer ${TOKEN}`.\n[Read more about the OAuth token endpoint.](/api-bolt/#tag/OAuth)\n",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://api.boltapp.com/v1/oauth/authorize",
            "refreshUrl": "https://api.boltapp.com/v1/oauth/token",
            "scopes": {
              "bolt.account.manage": "This scope grants permissions to perform read/edit/delete actions on Bolt Account data",
              "bolt.account.view": "This scope grants permissions to perform read only actions on Bolt Account data",
              "openid": "This scope grants permissions that enable Bolt SSO by granting an id token JWT that stores account data. Not used in v1/account endpoints"
            },
            "tokenUrl": "https://api.boltapp.com/v1/oauth/token"
          }
        },
        "type": "oauth2"
      },
      "X-API-Key": {
        "description": "Admins and Developers can obtain their Bolt API key from the Bolt Merchant Dashboard.",
        "in": "header",
        "name": "X-API-Key",
        "type": "apiKey"
      }
    }
  }
}
```