Skip to main content
POST
/
subscriptions
Create a subscription
curl --request POST \
  --url https://api.salesbricks.com/api/v2/subscriptions \
  --header 'Content-Type: application/json' \
  --header 'X-SALESBRICKS-KEY: <api-key>' \
  --data '
{
  "starts_at": "2023-12-25",
  "contract_length": 2,
  "plan_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "bricks": [
    {
      "brick_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "quantity": 123,
      "discount": [
        {
          "rate": "<string>",
          "amount": 123,
          "renews": false
        }
      ]
    }
  ],
  "point_of_contact_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "signatory_user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "currency": "USD",
  "discount_coupons": [
    "<string>"
  ],
  "auto_renews": true,
  "accounts_payable_emails": [
    "jsmith@example.com"
  ],
  "payment_terms": 499,
  "renewal_contract_period": 2,
  "renewal_uplifted_rate": "<string>",
  "metadata": "<unknown>",
  "custom_order_form_html": "<string>",
  "accepted_payment_methods_config": {
    "paywall_credit_card": true,
    "paywall_check": true,
    "paywall_ach": true,
    "paywall_wire": true,
    "checkout_credit_card": true,
    "checkout_ach": true,
    "checkout_order_form": true,
    "minimum_order_form_tcv": 0,
    "paywall_force_autopay": false
  },
  "legal_entity_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'
{
  "subscription_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

Authorizations

​
X-SALESBRICKS-KEY
string
header
required

API key for authentication

Body

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

​
starts_at
string<date>
required

The start date of the subscription.

​
contract_length
integer
required

The length of the contract in months.

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

The billing frequency

  • 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
​
plan_id
string<uuid>
required

The ID of the plan.

​
bricks
object[]
required

The bricks included in the subscription.

​
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

​
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.

​
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

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 seller's first_charge_date setting, or CHECKOUT_DATE if seller has no setting.

  • CONTRACT_START_DATE - Contract Start Date
  • CHECKOUT_DATE - Checkout Date
Available options:
CONTRACT_START_DATE,
CHECKOUT_DATE
​
legal_entity_id
string<uuid> | null

Optional ID of the legal entity that issues this subscription. Falls back to the seller's 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