> ## Documentation Index > Fetch the complete documentation index at: https://docs.salesbricks.com/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve a subscription > Returns the current subscription details for the specified ID, including plan name, lifecycle dates, billing information, point of contact, and line items. Use this endpoint to show subscription lifecycle info in user dashboards (e.g., start/end dates, contract renewal dates) and track active plan details. ## OpenAPI ````yaml https://api.salesbricks.com/api/v2/openapi.yaml get /subscriptions/{subscription_id} openapi: 3.0.3 info: title: Salesbricks REST API version: 2.0.0 description: API reference for external integrations servers: - url: https://api.salesbricks.com/api/v2 description: Production - url: https://api.staging.salesbricks.com/api/v2 description: Staging security: - ApiKeyAuth: [] tags: - name: Subscriptions description: >- Operations related to subscription management, including creation, updates, and retrieving subscription details. Subscriptions can be upgraded to add / remove add-ons by using the POST /subscriptions/{subscription_id}/upgrade endpoint and can be recasted for replacing the current agreement using the POST /subscriptions/{subscription_id}/recast endpoint - name: Customers description: >- Operations related to customer management, including creation, updates, and managing customer person objects. - name: Invoices description: Operations related to subscription's invoicing details. - name: Plans description: >- Operations related to listing and getting plan details including bricks in the plan. - name: Payment Methods description: Operations related to subscription's payment method. paths: /subscriptions/{subscription_id}: get: tags: - Subscriptions summary: Retrieve a subscription description: >- Returns the current subscription details for the specified ID, including plan name, lifecycle dates, billing information, point of contact, and line items. Use this endpoint to show subscription lifecycle info in user dashboards (e.g., start/end dates, contract renewal dates) and track active plan details. operationId: retrieveSubscription parameters: - in: path name: subscription_id schema: type: string pattern: ^([a-zA-Z\d\-]+)$ required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/SubscriptionDetail' description: '' '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: '' components: schemas: SubscriptionDetail: type: object description: Subscription detail serializer. properties: ends_at: type: string format: date description: End date of subscription sub_total: type: integer description: Subtotal before taxes and discounts grand_total: type: integer description: Final total after taxes and discounts line_items: type: array items: $ref: '#/components/schemas/LineItem' description: The line items of the subscription billing_schedule: type: array items: $ref: '#/components/schemas/BillingPeriodItem' description: The billing schedule of the subscription grand_total_details: description: Breakdown containing total discount and tax amounts subscription_id: type: string format: uuid description: Unique identifier for the subscription customer: allOf: - $ref: '#/components/schemas/CustomerOutput' readOnly: true description: Customer details metadata: description: Optional metadata to add to the subscription. renews_at: type: string format: date description: Date of renewal status: enum: - ACTIVE - ORDER_NEEDED - OPEN_ORDER - SCHEDULED - TERMINATED - TERMINATING - INACTIVE - PAUSED - SUPERSEDED type: string x-spec-enum-id: f557ac38d7b2529c description: |- Current status of the subscription * `ACTIVE` - Active * `ORDER_NEEDED` - Order needed * `OPEN_ORDER` - Open order * `SCHEDULED` - Scheduled * `TERMINATED` - Terminated * `TERMINATING` - Terminating * `INACTIVE` - Inactive * `PAUSED` - Paused * `SUPERSEDED` - Superseded stage: enum: - BUILDING - CLOSED - CLOSED_LOST - CLOSED_DELETE - SELLER_SIGNING - MIGRATING type: string x-spec-enum-id: e1125ad9e735326c description: |- Current stage of the subscription * `BUILDING` - Open * `CLOSED` - Closed Won * `CLOSED_LOST` - Closed Lost * `CLOSED_DELETE` - Closed Delete * `SELLER_SIGNING` - Signing * `MIGRATING` - Migrating transaction_method: enum: - ORDER_FORM - STRIPE type: string x-spec-enum-id: c68094511bb51423 description: |- The medium by which the order is agreed. * `ORDER_FORM` - Order form * `STRIPE` - Stripe terminates_at: type: string format: date description: Date of termination time_zone: type: string description: Subscription time zone starts_at: type: string format: date description: Start date of subscription billing_frequency: enum: - MONTHLY - QUARTERLY - SEMI_ANNUALLY - ANNUALLY - ALL_UPFRONT - CUSTOM type: string x-spec-enum-id: 5f29351b16a5547f description: |- Billing frequency of the subscription * `MONTHLY` - Monthly * `QUARTERLY` - Quarterly * `SEMI_ANNUALLY` - Semi-annually * `ANNUALLY` - Annually * `ALL_UPFRONT` - All upfront * `CUSTOM` - Custom point_of_contact: allOf: - $ref: '#/components/schemas/PersonOutput' description: Primary contact person for the subscription products: type: array items: $ref: '#/components/schemas/ProductDetail' readOnly: true description: Product details signatory_user: allOf: - $ref: '#/components/schemas/PersonOutput' description: User who signed the subscription agreement attributed_to: allOf: - $ref: '#/components/schemas/UserOutput' nullable: true description: The user that owns the subscription (account representative) accounts_payable_emails: type: array items: type: string format: email description: List of email addresses for accounts payable contacts currency: enum: - USD - EUR - GBP - AUD - CAD - INR type: string x-spec-enum-id: fde863feba7c4cf4 description: |- The currency used * `USD` - United States Dollar * `EUR` - Euros * `GBP` - Great British Pound * `AUD` - Australian Dollar * `CAD` - Canadian Dollar * `INR` - Indian Rupee payment_terms: type: integer description: The payment terms for this susbcription auto_renews: type: boolean description: >- If the subscription will auto renew at the end of the current contract period required: - accounts_payable_emails - auto_renews - billing_frequency - billing_schedule - currency - customer - ends_at - grand_total - grand_total_details - line_items - payment_terms - point_of_contact - products - renews_at - signatory_user - stage - starts_at - status - sub_total - subscription_id - terminates_at - time_zone - transaction_method ErrorResponse: type: object description: >- Standardizes API error responses with a consistent structure containing error code and message. properties: error: $ref: '#/components/schemas/Error' required: - error LineItem: type: object description: Line item serializer for a subscription estimate properties: quantity: oneOf: - type: integer - type: number format: double readOnly: true description: The quantity of the brick brick_id: type: string format: uuid description: The brick id brick_name: type: string description: The name of the brick sub_total: type: integer description: Subtotal for the line item before taxes and discounts plan_id: type: string readOnly: true description: ID of the plan this line item belongs to plan_name: type: string description: Name of the plan this line item belongs to grand_total: type: string readOnly: true description: Final total for the line item after taxes and discounts grand_total_details: type: string readOnly: true description: Breakdown containing total discount amounts for the line item tiers_breakdown: type: array items: $ref: '#/components/schemas/TierBreakdown' readOnly: true description: Tiers breakdown for the line item pre_commitment_schedule: type: string readOnly: true nullable: true description: The pre-commitment schedule for usage-based line items discount: type: array items: $ref: '#/components/schemas/LineItemDiscount' readOnly: true description: >- Per-brick discount(s) in the same shape accepted on input, so they can be read off a subscription and carried forward explicitly on upgrade, recast, or renewal. Empty when the line item has no discount. required: - brick_id - brick_name - discount - grand_total - grand_total_details - plan_id - plan_name - pre_commitment_schedule - quantity - sub_total - tiers_breakdown BillingPeriodItem: type: object description: Billing schedule for a subscription properties: starts_at: type: string readOnly: true description: Start date of the billing period ends_at: type: string readOnly: true description: End date of the billing period sub_total: type: integer description: Subtotal for the billing period before taxes and discounts grand_total: type: string readOnly: true description: Final total for the billing period after taxes and discounts grand_total_details: type: string readOnly: true description: Breakdown containing total discount for the billing period required: - ends_at - grand_total - grand_total_details - starts_at - sub_total CustomerOutput: type: object description: >- Customer output serializer; we can represent the customer model differently depending on the request so we need a custom serializer for the output. properties: customer_id: type: string format: uuid name: type: string legal_name: type: string readOnly: true external_id: type: string nullable: true maxLength: 255 address: allOf: - $ref: '#/components/schemas/AddressInput' description: The address of the customer stripe_customer_id: type: string nullable: true description: The companies stripe customer_id maxLength: 255 tax_id: type: string nullable: true description: Tax identification number (e.g., EIN, VAT number) subscriptions: type: array items: $ref: '#/components/schemas/SubscriptionSummary' readOnly: true description: List of subscriptions associated with this customer required: - customer_id - legal_name - name - subscriptions PersonOutput: type: object description: Person output serializer for creating a new person. properties: person_id: type: string format: uuid description: The ID of the person first_name: type: string description: The first name of the person last_name: type: string description: The last name of the person email: type: string format: email description: The email of the person preferred_name: type: string nullable: true maxLength: 255 role: type: string readOnly: true description: The role of the person required: - email - first_name - last_name - person_id - role ProductDetail: type: object description: Product detail serializer. properties: name: type: string description: Name of the product logo_image: type: string readOnly: true description: URL to the product logo image, falls back to seller logo if not set required: - logo_image - name UserOutput: type: object description: >- User output serializer for seller-side users (e.g. the subscription owner). properties: user_id: type: string format: uuid readOnly: true description: The ID of the user first_name: type: string description: The first name of the user last_name: type: string description: The last name of the user email: type: string format: email description: The email of the user required: - email - first_name - last_name - user_id Error: type: object description: >- Represents individual error details with a standardized code and descriptive message. properties: code: enum: - ERR_NOT_FOUND - ERR_BAD_REQUEST - ERR_SERVER_ERROR type: string x-spec-enum-id: dc5a5d6feae1b697 description: >- Error code indicating the type of error: NOT_FOUND for missing resources, BAD_REQUEST for invalid input, SERVER_ERROR for internal server issues * `ERR_NOT_FOUND` - ERR_NOT_FOUND * `ERR_BAD_REQUEST` - ERR_BAD_REQUEST * `ERR_SERVER_ERROR` - ERR_SERVER_ERROR message: type: string error_id: type: string format: uuid description: >- Correlation handle for SERVER_ERROR responses — quote this when contacting support; it joins to the structured server log line for the failure. Not present on 4xx responses. required: - code - message TierBreakdown: type: object description: Tier breakdown serializer for line item tiers properties: quantity: type: number format: double maximum: 100000000000000 minimum: -100000000000000 exclusiveMaximum: true exclusiveMinimum: true description: Number of units in this tier unit_price: type: string format: decimal pattern: ^-?\d{0,14}(?:\.\d{0,6})?$ description: Unit price for this tier sub_total: type: string format: decimal pattern: ^-?\d{0,18}(?:\.\d{0,2})?$ description: Subtotal for this tier duration_text: type: string description: Duration text for frontend display required: - duration_text - quantity - sub_total - unit_price LineItemDiscount: type: object description: Discount serializer for a subscription estimate line item properties: rate: type: string format: decimal pattern: ^-?\d{0,14}(?:\.\d{0,6})?$ description: >- The discount rate as a percentage with up to six decimal places (e.g. 10 = 10%, 62.6758 = 62.6758%). Mutually exclusive with `amount`. amount: type: integer description: >- A fixed discount amount in cents (e.g. 1000 = $10.00). One-time only — `renews` must be false when `amount` is set. Mutually exclusive with `rate`. The amount is applied as-is and is not clamped to the line item total, so it should not exceed the brick's price. renews: type: boolean default: false description: >- If the discount is carried over at renewal. Must be false when `amount` is set, as fixed discounts are one-time only. AddressInput: type: object description: >- Address input serializer to not confuse it with Address model serializer. properties: line_1: type: string description: The first line of the address input line_2: type: string nullable: true description: The second line of the address input city: type: string description: The city of the address input region: type: string description: 'The region (ISO 3166: 2 character code) of the address input' zip: type: string description: The zip code of the address input country: type: string description: 'The country (ISO 3166: 2 character code) of the address input' required: - city - country - line_1 - zip SubscriptionSummary: type: object description: |- Lightweight subscription serializer for embedding in customer responses. Contains only the essential subscription fields. properties: subscription_id: type: string format: uuid description: Unique identifier for the subscription status: enum: - ACTIVE - ORDER_NEEDED - OPEN_ORDER - SCHEDULED - TERMINATED - TERMINATING - INACTIVE - PAUSED - SUPERSEDED type: string x-spec-enum-id: f557ac38d7b2529c description: |- Current status of the subscription * `ACTIVE` - Active * `ORDER_NEEDED` - Order needed * `OPEN_ORDER` - Open order * `SCHEDULED` - Scheduled * `TERMINATED` - Terminated * `TERMINATING` - Terminating * `INACTIVE` - Inactive * `PAUSED` - Paused * `SUPERSEDED` - Superseded name: type: string nullable: true description: Name of the subscription starts_at: type: string format: date nullable: true description: Start date of the subscription ends_at: type: string format: date nullable: true description: End date of the subscription required: - ends_at - name - starts_at - status - subscription_id securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-SALESBRICKS-KEY description: API key for authentication ```` ## Related topics - [Overview](/api-reference/getting-started/overview.md) - [subscription.inactive](/api-reference/webhooks/subscription/inactive.md) - [Subscription Inactive Payload](/api-reference/webhooks/subscription/payload.md)