Skip to main content
POST
Create a subscription

Authorizations

​
X-SALESBRICKS-KEY
string
header
required

API key for authentication

Body

Subscription update input serializer that comes from previously posted subscription estimate.

This payload has two forms — see anyOf:

  • Single-phase — omit phases; the order-level starts_at, contract_length, billing_frequency and bricks define the one phase and are required.
  • Multi-phase — send phases; the phases own the timeline, billing frequency and bricks, and the order-level equivalents become optional (omitted, they are derived from the phases).

The fields are declared optional because OpenAPI 3.0 cannot make one field's required depend on another. Sending neither form is a 400.

Every phase needs a plan, so the multi-phase form splits in two: send an order-level plan_id (the plan for any phase that names none), or give every phase its own plan_id. A multi-phase payload naming no plan at all is a 400.

​
starts_at
string<date>
required

The start date of the subscription. Required unless phases is provided, in which case phase 0's start date is used.

​
contract_length
integer
required

The length of the contract in months. Required unless phases is provided, in which case it is the sum of the phase lengths.

Required range: x >= 1
​
billing_frequency
enum<string>
required

The billing frequency. Required unless phases is provided, in which case each phase declares its own billing_frequency.

  • MONTHLY - Monthly
  • QUARTERLY - Quarterly
  • SEMI_ANNUALLY - Semi-annually
  • ANNUALLY - Annually
  • ALL_UPFRONT - All upfront
Available options:
MONTHLY,
QUARTERLY,
SEMI_ANNUALLY,
ANNUALLY,
ALL_UPFRONT
​
plan_id
string<uuid>
required

The ID of the plan. Required unless every phase declares its own plan_id — it is the plan for any phase that does not.

​
bricks
object[]
required

The bricks included in the subscription. Required unless phases is provided, in which case every brick comes from the phases.

​
point_of_contact_id
string<uuid>
required

The ID of the point of contact (Person) object

​
signatory_user_id
string<uuid>
required

The ID of the signatory user (Person) object

​
customer_id
string<uuid>
required

The ID of the customer

​
crm_account_id
string

Optional ID of the account (company in HubSpot) in your connected CRM to link the subscription to; a 400 is returned if your CRM has no such account. Linking syncs the subscription to the CRM, may update its owner from the CRM, and fills a blank customer address or point of contact from the CRM account. Omit for no change; pass an empty string to unlink the account and its opportunity.

Maximum string length: 255
​
crm_opportunity_id
string

Optional ID of the opportunity (deal in HubSpot) in your connected CRM to link the subscription to. Requires a linked CRM account, and must not be linked to another subscription. Omit for no change; pass an empty string to unlink it.

Maximum string length: 255
​
currency
enum<string>
default:USD

Optional currency to be used for the subscription. Defaults to USD.

  • 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
​
discount_coupons
string[]

Discount coupon codes to apply to the subscription. Currently only supports one discount coupon - only the first one in the list will be applied.

​
phases
object[] | null

Optional list of phases for multi-phase orders. When provided, ALL phases come from this array (first element = phase 0, second = phase 1, etc.) and starts_at, contract_length, billing_frequency and bricks become optional — omit them and they are derived from the phases. plan_id is still required, and every brick in every phase must belong to it. When absent, the order-level fields define a single phase.

​
auto_renews
boolean

Whether the subscription auto-renews. Defaults to true.

​
accounts_payable_emails
string<email>[]

List of email addresses for accounts payable contacts

​
payment_terms
integer

The number of days from an invoice being generated that the buyer is expected to pay in

Required range: 0 <= x <= 999
​
renewal_contract_period
integer | null

The contract period for renewals in months. If null, inherits from initial contract period.

Required range: x >= 1
​
renewal_uplifted_rate
string<decimal> | null

The percentage rate to uplift renewal pricing. If null, no uplift is applied.

Pattern: ^-?\d{0,3}(?:\.\d{0,2})?$
​
transaction_method
enum<string>

The medium by which the order is agreed.

  • ORDER_FORM - Order form
  • STRIPE - Stripe
Available options:
ORDER_FORM,
STRIPE
​
metadata
any | null

Optional metadata to add to the subscription. Sending an empty map will delete all keys. Keys prefixed with _ are private and will be ignored.

​
custom_order_form_html
string

The custom order form html to use with <html><body>...</body></html> formatting

​
accepted_payment_methods_config
object | null

Configuration for accepted payment methods during checkout and paywall

​
first_charge_date
enum<string>

When the first invoice should be charged. If not provided, defaults to your first_charge_date setting, or CHECKOUT_DATE if you have no setting.

  • CONTRACT_START_DATE - Contract Start Date
  • CHECKOUT_DATE - Checkout Date
Available options:
CONTRACT_START_DATE,
CHECKOUT_DATE
​
purchase_order
object | null

Purchase order for the subscription. Applies to every invoice generated for it, unless an invoice carries its own override. Omit or pass null for no change; pass an empty object or an empty code to clear.

​
legal_entity_id
string<uuid> | null

Optional ID of the legal entity that issues this subscription. Falls back to your default legal entity when omitted.

Response

Common subscription response serializer that includes the ID of the subscription from the result of a subscription related operation.

​
subscription_id
string<uuid>
required

ID of the subscription