Create a subscription

Creates a new subscription for a customer.

POST /subscriptions

Create a subscription

cURL

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>"
  ],
  "phases": [
    {
      "phase_position": 1,
      "bricks": [
        {
          "brick_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "quantity": 123,
          "discount": [
            {
              "rate": "<string>",
              "amount": 123,
              "renews": false
            }
          ]
        }
      ],
      "starts_at": "2023-12-25",
      "contract_length": 2,
      "plan_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "payment_terms": 499,
      "discount_coupons": [
        "<string>"
      ]
    }
  ],
  "auto_renews": true,
  "accounts_payable_emails": [
    "[e-mail]"
  ],
  "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"
}
'

200

{
  "subscription_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

Authorizations

X-SALESBRICKS-KEY · string · header · required

API key for authentication

Body

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

SubscriptionInputSinglePhase

SubscriptionInputMultiPhasePerPhasePlans

SubscriptionInputMultiPhase

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.

Show child attributes

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.

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.

Show child attributes

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

Show child attributes

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

200

application/json

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