post_subscription_buy

POST /subscriptions/buy

Purchase Subscription

Initiate a subscription purchase for the authenticated user's organization. For paid subscriptions, creates a Stripe checkout session for payment processing. For free subscriptions, immediately activates the subscription without payment processing. Allows subscription changes by automatically handling cancellation of existing subscriptions.

Parameters

Name

Type

Required

Description

subscriptionPeriodId

body

string

true

Unique identifier for the subscription period

TypeScript Client Library

public buySubscription = async (data: BuySubscriptionRequest): Promise<BuySubscriptionResponse> => {
  return this.makeRequest<BuySubscriptionResponse>('subscriptions/buy', 'POST', data);
};

Code Samples

curl -X POST https://backend.flashback.tech/subscriptions/buy \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "subscriptionPeriodId": "123e4567-e89b-12d3-a456-426614174000"
  }'

POST https://backend.flashback.tech/subscriptions/buy HTTP/1.1
Host: localhost:3000
Accept: application/json
Authorization: Bearer {access-token}
Content-Type: application/json

{
  "subscriptionPeriodId": "123e4567-e89b-12d3-a456-426614174000"
}

const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}',
  'Content-Type':'application/json'
};

const body = {
  subscriptionPeriodId: '123e4567-e89b-12d3-a456-426614174000'
};

fetch('https://backend.flashback.tech/subscriptions/buy',
{
  method: 'POST',
  headers: headers,
  body: JSON.stringify(body)
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}',
  'Content-Type' => 'application/json'
}

body = {
  subscriptionPeriodId: '123e4567-e89b-12d3-a456-426614174000'
}

result = RestClient.post 'https://backend.flashback.tech/subscriptions/buy',
  body.to_json, headers: headers

p JSON.parse(result)

import requests
import json

headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}',
  'Content-Type': 'application/json'
}

body = {
  'subscriptionPeriodId': '123e4567-e89b-12d3-a456-426614174000'
}

r = requests.post('https://backend.flashback.tech/subscriptions/buy', 
                  headers=headers, 
                  data=json.dumps(body))

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/json',
    'Authorization' => 'Bearer {access-token}',
    'Content-Type' => 'application/json',
);

$body = array(
    'subscriptionPeriodId' => '123e4567-e89b-12d3-a456-426614174000'
);

$client = new \GuzzleHttp\Client();

try {
    $response = $client->request('POST','https://backend.flashback.tech/subscriptions/buy', array(
        'headers' => $headers,
        'json' => $body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://backend.flashback.tech/subscriptions/buy");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/json");
con.setRequestProperty("Authorization", "Bearer {access-token}");

String body = "{\"subscriptionPeriodId\":\"123e4567-e89b-12d3-a456-426614174000\"}";

con.setDoOutput(true);
DataOutputStream wr = new DataOutputStream(con.getOutputStream());
wr.writeBytes(body);
wr.close();

int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
       "encoding/json"
)

func main() {
    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
        "Content-Type": []string{"application/json"},
    }

    body := map[string]string{
        "subscriptionPeriodId": "123e4567-e89b-12d3-a456-426614174000",
    }
    
    jsonBody, _ := json.Marshal(body)
    data := bytes.NewBuffer(jsonBody)
    req, err := http.NewRequest("POST", "https://backend.flashback.tech/subscriptions/buy", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

Example responses

200 Response (Paid Subscription)

{
  "success": true,
  "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_test_1234567890abcdef",
  "sessionId": "cs_test_1234567890abcdef",
  "isSubscriptionChange": false,
  "previousSubscription": null,
  "isFreeSubscription": false
}

200 Response (Free Subscription)

{
  "success": true,
  "checkoutUrl": null,
  "sessionId": "free_sub_1234567890abcdef_1642248600000",
  "isSubscriptionChange": false,
  "previousSubscription": null,
  "isFreeSubscription": true
}

200 Response (Subscription Change)

{
  "success": true,
  "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_test_1234567890abcdef",
  "sessionId": "cs_test_1234567890abcdef",
  "isSubscriptionChange": true,
  "previousSubscription": {
    "id": "sub_old1234567890abcdef",
    "name": "Basic Plan"
  },
  "isFreeSubscription": false
}

400 Response (No Organization)

{
  "success": false,
  "error_code": "NO_ORGANIZATION",
  "message": "User must belong to an organization"
}

400 Response (Stripe ID Missing)

{
  "success": false,
  "error_code": "STRIPE_ID_MISSING",
  "message": "Subscription period is not configured for payments"
}

400 Response (Stripe Price Invalid)

{
  "success": false,
  "error_code": "STRIPE_PRICE_INVALID",
  "message": "Invalid Stripe price configuration"
}

404 Response

{
  "success": false,
  "error_code": "USER_NOT_FOUND",
  "message": "User not found"
}

404 Response (Subscription Not Found)

{
  "success": false,
  "error_code": "SUBSCRIPTION_PERIOD_NOT_FOUND",
  "message": "Subscription period not found or not active"
}

404 Response (Subscription Not Active)

{
  "success": false,
  "error_code": "SUBSCRIPTION_NOT_ACTIVE",
  "message": "Parent subscription is not active"
}

404 Response (Organization Not Found)

{
  "success": false,
  "error_code": "ORG_NOT_FOUND",
  "message": "Organization not found"
}

403 Response (Not Authorized)

{
  "success": false,
  "error_code": "NOT_AUTHORIZED",
  "message": "User does not have permission to buy subscriptions"
}

409 Response (Already Active)

{
  "success": false,
  "error_code": "SUBSCRIPTION_ALREADY_ACTIVE",
  "message": "You already have an active Professional Plan subscription"
}

409 Response (Payment In Progress)

{
  "success": false,
  "error_code": "PAYMENT_IN_PROGRESS",
  "message": "A payment is already in progress. Please complete or cancel the current payment before starting a new one."
}

500 Response

{
  "success": false,
  "error_code": "INTERNAL_ERROR",
  "message": "Failed to process subscription purchase"
}

Responses

Status

Meaning

Description

Schema

200

Subscription purchase initiated or completed

Inline

400

Bad Request

Invalid request or configuration

Inline

403

Forbidden

User lacks permission for billing operations

Inline

404

Not Found

User, organization, or subscription not found

Inline

409

Conflict

Active subscription exists or payment in progress

Inline

500

Internal Server Error

Server error

Inline

Response Schema

Status Code 200

Name

Type

Required

Restrictions

Description

» success

boolean

false

none

Indicates if the request was successful

» checkoutUrl

string

false

none

Stripe hosted checkout URL for redirect (null for free subscriptions)

» sessionId

string

false

none

Stripe checkout session identifier or free payment ID

» isSubscriptionChange

boolean

false

none

Indicates if this is changing from an existing subscription

» previousSubscription

object

false

none

Details of the previous subscription (null if not a change)

»» id

string

false

none

Previous subscription identifier

»» name

string

false

none

Previous subscription name

» isFreeSubscription

boolean

false

none

Indicates if this is a free subscription (no payment required)

Status Code 400

Name

Type

Required

Restrictions

Description

» success

boolean

false

none

Will be false for error responses

» error_code

string

false

none

Machine-readable error code (NO_ORGANIZATION, STRIPE_ID_MISSING, STRIPE_PRICE_INVALID)

» message

string

false

none

Human-readable error message

Status Code 403

Name

Type

Required

Restrictions

Description

» success

boolean

false

none

Will be false for error responses

» error_code

string

false

none

Machine-readable error code (NOT_AUTHORIZED)

» message

string

false

none

Human-readable error message

Status Code 404

Name

Type

Required

Restrictions

Description

» success

boolean

false

none

Will be false for error responses

» error_code

string

false

none

Machine-readable error code (USER_NOT_FOUND, SUBSCRIPTION_PERIOD_NOT_FOUND, SUBSCRIPTION_NOT_ACTIVE, ORG_NOT_FOUND)

» message

string

false

none

Human-readable error message

Status Code 409

Name

Type

Required

Restrictions

Description

» success

boolean

false

none

Will be false for error responses

» error_code

string

false

none

Machine-readable error code (SUBSCRIPTION_ALREADY_ACTIVE, PAYMENT_IN_PROGRESS)

» message

string

false

none

Human-readable error message

Status Code 500

Name

Type

Required

Restrictions

Description

» success

boolean

false

none

Will be false for error responses

» error_code

string

false

none

Machine-readable error code

» message

string

false

none

Human-readable error message

Previousget__subscription_my Nextget__subscription_payments

Last updated 4 months ago

Was this helpful?

hashtagParameters

hashtagTypeScript Client Library

hashtagCode Samples

hashtagResponses

hashtagResponse Schema

Parameters

TypeScript Client Library

Code Samples

Responses

Response Schema