Start a subscription

curl --request POST \
  --url https://api.salesbricks.com/api/v2/subscriptions/{subscription_id}/start \
  --header 'X-SALESBRICKS-KEY: <api-key>'

import requests

url = "https://api.salesbricks.com/api/v2/subscriptions/{subscription_id}/start"

headers = {"X-SALESBRICKS-KEY": "<api-key>"}

response = requests.post(url, headers=headers)

print(response.text)

const options = {method: 'POST', headers: {'X-SALESBRICKS-KEY': '<api-key>'}};

fetch('https://api.salesbricks.com/api/v2/subscriptions/{subscription_id}/start', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.salesbricks.com/api/v2/subscriptions/{subscription_id}/start",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "X-SALESBRICKS-KEY: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.salesbricks.com/api/v2/subscriptions/{subscription_id}/start"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("X-SALESBRICKS-KEY", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.salesbricks.com/api/v2/subscriptions/{subscription_id}/start")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-SALESBRICKS-KEY"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "ends_at": "2023-12-25",
  "sub_total": 123,
  "grand_total": 123,
  "line_items": [
    {
      "quantity": 123,
      "brick_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "is_unlimited": false,
      "brick_name": "<string>",
      "brick_code": "<string>",
      "sub_total": 123,
      "plan_id": "<string>",
      "plan_name": "<string>",
      "grand_total": "<string>",
      "grand_total_details": "<string>",
      "tiers_breakdown": [
        {
          "quantity": 0,
          "unit_price": "<string>",
          "sub_total": "<string>",
          "duration_text": "<string>"
        }
      ],
      "pre_commitment_schedule": "<string>",
      "discount": [
        {
          "rate": "<string>",
          "amount": 123,
          "renews": false
        }
      ]
    }
  ],
  "billing_schedule": [
    {
      "starts_at": "<string>",
      "ends_at": "<string>",
      "sub_total": 123,
      "grand_total": "<string>",
      "grand_total_details": "<string>"
    }
  ],
  "grand_total_details": "<unknown>",
  "subscription_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "customer": {
    "customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "legal_name": "<string>",
    "subscriptions": [
      {
        "subscription_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "status": "ACTIVE",
        "state": "ACTIVE",
        "renewal_status": "AUTO_RENEWING",
        "name": "<string>",
        "starts_at": "2023-12-25",
        "ends_at": "2023-12-25"
      }
    ],
    "external_id": "<string>",
    "address": {
      "line_1": "<string>",
      "city": "<string>",
      "zip": "<string>",
      "country": "<string>",
      "line_2": "<string>",
      "region": "<string>"
    },
    "stripe_customer_id": "<string>",
    "tax_id": "<string>"
  },
  "crm_account_id": "<string>",
  "crm_opportunity_id": "<string>",
  "renews_at": "2023-12-25",
  "status": "ACTIVE",
  "state": "ACTIVE",
  "renewal_status": "AUTO_RENEWING",
  "stage": "BUILDING",
  "transaction_method": "ORDER_FORM",
  "terminates_at": "2023-12-25",
  "termination_reason": "POOR_PRODUCT_MARKET_FIT",
  "time_zone": "<string>",
  "starts_at": "2023-12-25",
  "billing_frequency": "MONTHLY",
  "point_of_contact": {
    "person_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "first_name": "<string>",
    "last_name": "<string>",
    "email": "jsmith@example.com",
    "role": "<string>",
    "preferred_name": "<string>"
  },
  "products": [
    {
      "name": "<string>",
      "logo_image": "<string>"
    }
  ],
  "signatory_user": {
    "person_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "first_name": "<string>",
    "last_name": "<string>",
    "email": "jsmith@example.com",
    "role": "<string>",
    "preferred_name": "<string>"
  },
  "accounts_payable_emails": [
    "jsmith@example.com"
  ],
  "currency": "USD",
  "payment_terms": 123,
  "auto_renews": true,
  "renewal_total": 123,
  "renewal_contract_period": 123,
  "pauses": [
    {
      "paused_at": "2023-11-07T05:31:56Z",
      "resume_at": "2023-11-07T05:31:56Z"
    }
  ],
  "phases": [
    {
      "phase_position": 123,
      "starts_at": "2023-12-25",
      "ends_at": "2023-12-25",
      "billing_frequency": "MONTHLY",
      "payment_terms": 123,
      "sub_total": 123,
      "grand_total": 123,
      "line_items": [
        {
          "quantity": 123,
          "brick_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "is_unlimited": false,
          "brick_name": "<string>",
          "brick_code": "<string>",
          "sub_total": 123,
          "plan_id": "<string>",
          "plan_name": "<string>",
          "grand_total": "<string>",
          "grand_total_details": "<string>",
          "tiers_breakdown": [
            {
              "quantity": 0,
              "unit_price": "<string>",
              "sub_total": "<string>",
              "duration_text": "<string>"
            }
          ],
          "pre_commitment_schedule": "<string>",
          "discount": [
            {
              "rate": "<string>",
              "amount": 123,
              "renews": false
            }
          ]
        }
      ],
      "is_annual": true,
      "billing_schedule": [
        {
          "starts_at": "<string>",
          "ends_at": "<string>",
          "sub_total": 123,
          "grand_total": "<string>",
          "grand_total_details": "<string>"
        }
      ]
    }
  ],
  "metadata": "<unknown>",
  "attributed_to": {
    "user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "first_name": "<string>",
    "last_name": "<string>",
    "email": "jsmith@example.com"
  },
  "purchase_order": {
    "code": "<string>"
  }
}

{
  "error": {
    "code": "ERR_NOT_FOUND",
    "message": "<string>",
    "error_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

POST

subscriptions

{subscription_id}

start

Start a subscription

curl --request POST \
  --url https://api.salesbricks.com/api/v2/subscriptions/{subscription_id}/start \
  --header 'X-SALESBRICKS-KEY: <api-key>'

import requests

url = "https://api.salesbricks.com/api/v2/subscriptions/{subscription_id}/start"

headers = {"X-SALESBRICKS-KEY": "<api-key>"}

response = requests.post(url, headers=headers)

print(response.text)

const options = {method: 'POST', headers: {'X-SALESBRICKS-KEY': '<api-key>'}};

fetch('https://api.salesbricks.com/api/v2/subscriptions/{subscription_id}/start', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.salesbricks.com/api/v2/subscriptions/{subscription_id}/start",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "X-SALESBRICKS-KEY: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.salesbricks.com/api/v2/subscriptions/{subscription_id}/start"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("X-SALESBRICKS-KEY", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.salesbricks.com/api/v2/subscriptions/{subscription_id}/start")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-SALESBRICKS-KEY"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "ends_at": "2023-12-25",
  "sub_total": 123,
  "grand_total": 123,
  "line_items": [
    {
      "quantity": 123,
      "brick_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "is_unlimited": false,
      "brick_name": "<string>",
      "brick_code": "<string>",
      "sub_total": 123,
      "plan_id": "<string>",
      "plan_name": "<string>",
      "grand_total": "<string>",
      "grand_total_details": "<string>",
      "tiers_breakdown": [
        {
          "quantity": 0,
          "unit_price": "<string>",
          "sub_total": "<string>",
          "duration_text": "<string>"
        }
      ],
      "pre_commitment_schedule": "<string>",
      "discount": [
        {
          "rate": "<string>",
          "amount": 123,
          "renews": false
        }
      ]
    }
  ],
  "billing_schedule": [
    {
      "starts_at": "<string>",
      "ends_at": "<string>",
      "sub_total": 123,
      "grand_total": "<string>",
      "grand_total_details": "<string>"
    }
  ],
  "grand_total_details": "<unknown>",
  "subscription_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "customer": {
    "customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "legal_name": "<string>",
    "subscriptions": [
      {
        "subscription_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "status": "ACTIVE",
        "state": "ACTIVE",
        "renewal_status": "AUTO_RENEWING",
        "name": "<string>",
        "starts_at": "2023-12-25",
        "ends_at": "2023-12-25"
      }
    ],
    "external_id": "<string>",
    "address": {
      "line_1": "<string>",
      "city": "<string>",
      "zip": "<string>",
      "country": "<string>",
      "line_2": "<string>",
      "region": "<string>"
    },
    "stripe_customer_id": "<string>",
    "tax_id": "<string>"
  },
  "crm_account_id": "<string>",
  "crm_opportunity_id": "<string>",
  "renews_at": "2023-12-25",
  "status": "ACTIVE",
  "state": "ACTIVE",
  "renewal_status": "AUTO_RENEWING",
  "stage": "BUILDING",
  "transaction_method": "ORDER_FORM",
  "terminates_at": "2023-12-25",
  "termination_reason": "POOR_PRODUCT_MARKET_FIT",
  "time_zone": "<string>",
  "starts_at": "2023-12-25",
  "billing_frequency": "MONTHLY",
  "point_of_contact": {
    "person_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "first_name": "<string>",
    "last_name": "<string>",
    "email": "jsmith@example.com",
    "role": "<string>",
    "preferred_name": "<string>"
  },
  "products": [
    {
      "name": "<string>",
      "logo_image": "<string>"
    }
  ],
  "signatory_user": {
    "person_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "first_name": "<string>",
    "last_name": "<string>",
    "email": "jsmith@example.com",
    "role": "<string>",
    "preferred_name": "<string>"
  },
  "accounts_payable_emails": [
    "jsmith@example.com"
  ],
  "currency": "USD",
  "payment_terms": 123,
  "auto_renews": true,
  "renewal_total": 123,
  "renewal_contract_period": 123,
  "pauses": [
    {
      "paused_at": "2023-11-07T05:31:56Z",
      "resume_at": "2023-11-07T05:31:56Z"
    }
  ],
  "phases": [
    {
      "phase_position": 123,
      "starts_at": "2023-12-25",
      "ends_at": "2023-12-25",
      "billing_frequency": "MONTHLY",
      "payment_terms": 123,
      "sub_total": 123,
      "grand_total": 123,
      "line_items": [
        {
          "quantity": 123,
          "brick_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "is_unlimited": false,
          "brick_name": "<string>",
          "brick_code": "<string>",
          "sub_total": 123,
          "plan_id": "<string>",
          "plan_name": "<string>",
          "grand_total": "<string>",
          "grand_total_details": "<string>",
          "tiers_breakdown": [
            {
              "quantity": 0,
              "unit_price": "<string>",
              "sub_total": "<string>",
              "duration_text": "<string>"
            }
          ],
          "pre_commitment_schedule": "<string>",
          "discount": [
            {
              "rate": "<string>",
              "amount": 123,
              "renews": false
            }
          ]
        }
      ],
      "is_annual": true,
      "billing_schedule": [
        {
          "starts_at": "<string>",
          "ends_at": "<string>",
          "sub_total": 123,
          "grand_total": "<string>",
          "grand_total_details": "<string>"
        }
      ]
    }
  ],
  "metadata": "<unknown>",
  "attributed_to": {
    "user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "first_name": "<string>",
    "last_name": "<string>",
    "email": "jsmith@example.com"
  },
  "purchase_order": {
    "code": "<string>"
  }
}

{
  "error": {
    "code": "ERR_NOT_FOUND",
    "message": "<string>",
    "error_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

Authorizations

X-SALESBRICKS-KEY

string

header

required

API key for authentication

Path Parameters

subscription_id

string

required

Pattern: ^([a-zA-Z\d\-]+)$

Query Parameters

charge_immediately

enum<string>

Whether to charge the first invoice to the customer's saved payment method during this request. Defaults to yes. With no, the order starts without a charge and the invoice is paid like any other: automatically on its charge date if the customer has auto-pay on (starting a card order turns it on), otherwise by the customer.

Available options:

no,

yes

Response

Subscription detail serializer.

ends_at

string<date>

required

End date of subscription

sub_total

integer

required

Subtotal before taxes and discounts

grand_total

integer

required

Final total after taxes and discounts

line_items

object[]

required

The line items of the subscription

Show child attributes

billing_schedule

object[]

required

The billing schedule of the subscription

Show child attributes

grand_total_details

any

required

Breakdown containing total discount and tax amounts

subscription_id

string<uuid>

required

Unique identifier for the subscription

customer

object

required

Customer details

Show child attributes

crm_account_id

string | null

required

ID of the account linked in your connected CRM, if any.

crm_opportunity_id

string | null

required

ID of the opportunity linked in your connected CRM, if any.

renews_at

string<date>

required

Date of renewal

status

enum<string>

required

deprecated

Deprecated: use state and renewal_status. Combines whether the subscription is being served with its renewal situation, and can lag behind a date-driven change such as a pause starting.

ACTIVE - Active
ORDER_NEEDED - Order needed
OPEN_ORDER - Open order
SCHEDULED - Scheduled
TERMINATED - Terminated
TERMINATING - Terminating
INACTIVE - Inactive
PAUSED - Paused
SUPERSEDED - Superseded

Available options:

ACTIVE,

ORDER_NEEDED,

OPEN_ORDER,

SCHEDULED,

TERMINATED,

TERMINATING,

INACTIVE,

PAUSED,

SUPERSEDED

state

enum<string> | null

required

Whether the customer is being served today, in the subscription's time zone. A termination or pause that hasn't started yet doesn't change it; see terminates_at and pauses.

ACTIVE - Active
PAUSED - Paused
TERMINATED - Terminated
INACTIVE - Inactive

Available options:

ACTIVE,

PAUSED,

TERMINATED,

INACTIVE

renewal_status

enum<string> | null

required

What has to happen for the next contract, read from the subscription's orders and auto_renews whatever its state. OPEN_ORDER means an order is being built or awaits your signature. INACTIVE with AUTO_RENEWING is a lapsed auto-renewal. A subscription needs a renewal order now when state is ACTIVE, terminates_at is empty and this is ORDER_NEEDED or OPEN_ORDER, or when it is a lapsed auto-renewal.

AUTO_RENEWING - Auto-renewing
ORDER_NEEDED - Order needed
OPEN_ORDER - Open order
WILL_NOT_RENEW - Won't renew

Available options:

AUTO_RENEWING,

ORDER_NEEDED,

OPEN_ORDER,

WILL_NOT_RENEW

stage

enum<string>

required

Current stage of the subscription

BUILDING - Open
CLOSED - Closed Won
CLOSED_LOST - Closed Lost
CLOSED_DELETE - Closed Delete
SELLER_SIGNING - Signing
MIGRATING - Migrating

Available options:

BUILDING,

CLOSED,

CLOSED_LOST,

CLOSED_DELETE,

SELLER_SIGNING,

MIGRATING

transaction_method

enum<string>

required

The medium by which the order is agreed.

ORDER_FORM - Order form
STRIPE - Stripe

Available options:

ORDER_FORM,

STRIPE

terminates_at

string<date>

required

Date of termination

termination_reason

enum<string> | null

required

Reason code given when the subscription was terminated, if any

POOR_PRODUCT_MARKET_FIT - Poor Product-Market Fit
INSUFFICIENT_VALUE - Insufficient Perceived Value / ROI
POOR_ONBOARDING - Poor Onboarding Experience
LOW_UTILIZATION - Low Utilization
POOR_SUPPORT - Poor Customer Support and Service
PRICING_AND_CONTRACT - Pricing and Contract Issues
PRODUCT_RELIABILITY - Product Reliability, Performance, or Security Problems
COMPETITIVE_DISPLACEMENT - Competitive Displacement
ORGANIZATIONAL_CHANGES - Customer Business or Organizational Changes
LACK_OF_INNOVATION - Lack of Product Innovation and Evolution
WENT_BANKRUPT - Went Bankrupt
LOST_CHAMPION - Lost Champion
OTHER - Other

Available options:

POOR_PRODUCT_MARKET_FIT,

INSUFFICIENT_VALUE,

POOR_ONBOARDING,

LOW_UTILIZATION,

POOR_SUPPORT,

PRICING_AND_CONTRACT,

PRODUCT_RELIABILITY,

COMPETITIVE_DISPLACEMENT,

ORGANIZATIONAL_CHANGES,

LACK_OF_INNOVATION,

WENT_BANKRUPT,

LOST_CHAMPION,

OTHER

time_zone

string

required

Subscription time zone

starts_at

string<date>

required

Start date of subscription

billing_frequency

enum<string>

required

Billing frequency of the subscription

MONTHLY - Monthly
QUARTERLY - Quarterly
SEMI_ANNUALLY - Semi-annually
ANNUALLY - Annually
ALL_UPFRONT - All upfront
CUSTOM - Custom

Available options:

MONTHLY,

QUARTERLY,

SEMI_ANNUALLY,

ANNUALLY,

ALL_UPFRONT,

CUSTOM

point_of_contact

object

required

Primary contact person for the subscription

Show child attributes

products

object[]

required

read-only

Product details

Show child attributes

signatory_user

object

required

User who signed the subscription agreement

Show child attributes

accounts_payable_emails

string<email>[]

required

List of email addresses for accounts payable contacts

currency

enum<string>

required

The currency used

USD - United States Dollar
EUR - Euros
GBP - Great British Pound
AUD - Australian Dollar
CAD - Canadian Dollar
INR - Indian Rupee

Available options:

USD,

EUR,

GBP,

AUD,

CAD,

INR

payment_terms

integer

required

The payment terms for this susbcription

auto_renews

boolean

required

If the subscription will auto renew at the end of the current contract period

renewal_total

integer | null

required

The grand total, in cents of currency, the subscription is estimated to renew at, for the same order and term as renewal_contract_period. Null while a renewal, upgrade or recast is open.

renewal_contract_period

integer

required

The length, in months, of the term the subscription renews for. When no renewal term was set, the term the renewal inherits: the current term, or for an upgrade, the term of the agreement it upgrades.

pauses

object[]

required

Every pause of the subscription, past, current and upcoming, oldest first. A pause is current when paused_at is in the past and resume_at is null or in the future. Empty when the subscription has never been paused.

Show child attributes

phases

object[]

Order phases with per-phase dates, billing config, and bricks. Omitted — not empty — unless you have multi-phase orders enabled and the order has phase rows, so treat its absence as 'single phase, read the order-level fields' rather than 'no phases'.

Show child attributes

metadata

any

Optional metadata to add to the subscription.

attributed_to

object | null

The user that owns the subscription (account representative)

Show child attributes

purchase_order

object | null

Purchase order for the subscription. Reported on every invoice generated for it, unless an invoice carries its own override. Null when the subscription has no purchase order.

Show child attributes

APIs

REST API Endpoints

Usage

Webhooks

Start a subscription

Authorizations

Path Parameters

Query Parameters

Response