> ## 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. # Start a subscription > Starts a subscription for the specified ID. This endpoint is used to initiate a subscription and trigger the subscription lifecycle. It returns the subscription details after the start process. ## OpenAPI ````yaml https://api.salesbricks.com/api/v2/openapi.yaml post /subscriptions/{subscription_id}/start 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}/start: post: tags: - Subscriptions summary: Start a subscription description: >- Starts a subscription for the specified ID. This endpoint is used to initiate a subscription and trigger the subscription lifecycle. It returns the subscription details after the start process. operationId: startSubscription parameters: - in: query name: charge_immediately schema: type: string enum: - 'no' - 'yes' description: Whether to attempt an immediate charge. - 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 - [subscription.inactive](/api-reference/webhooks/subscription/inactive.md) - [Subscription Inactive Payload](/api-reference/webhooks/subscription/payload.md) - [Getting Started](/quickstart-guide/getting-started.md)