Starting a Subscription

The REST API lets you create and activate subscriptions programmatically — the foundation of a self-serve or product-led signup flow in your own app. Every flow shares the same first three steps: create a customer, add a contact, and create a subscription. Only the final activation step differs.

Which flow would you like to build?

Checkout

Send the customer to a Salesbricks-hosted page to pay. Best for self-serve signup.

Signature

Send the customer to execute the contract by signing an order form. Best for enterprise or sales-assisted deals.

Direct start

Activate server-side with no customer interaction. Best for existing customers and migrations.

Before you begin

You will need a Public API Token and a published plan. All examples use the production base URL https://api.salesbricks.com/api/v2.

Find the plan_id and the brick_id values you want to sell with List all plans:

cURL

curl https://api.salesbricks.com/api/v2/plans \
  -H "X-SALESBRICKS-KEY: <your-api-key>"

Send an X-SALESBRICKS-IDEMPOTENT-OPERATION-KEY header on every POST in this guide so a network retry cannot create a duplicate customer or subscription. See Idempotent Requests.

Shared steps

Create a customer

POST /customers creates the record representing the purchasing company. Only name is required.

cURL

curl -X POST https://api.salesbricks.com/api/v2/customers \
  -H "X-SALESBRICKS-KEY: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "external_id": "crm-account-001"
  }'

JSON

{
  "customer_id": "a1b2c3d4-0d44-4b50-8888-8dd25736052a",
  "name": "Acme Corp",
  "legal_name": "Acme Corp",
  "external_id": "crm-account-001",
  "address": null,
  "stripe_customer_id": null,
  "tax_id": null,
  "subscriptions": []
}

Customer names must be unique. Creating a customer with a name already in use returns 400. Set external_id to your own identifier so you can find the customer again with Search customers.

Save the customer_id.

Add a contact

POST /customers/{customer_id}/persons adds a person to the customer. This person can be used as the subscription point of contact, the signatory, or both. first_name, last_name, email, and role are all required.

cURL

curl -X POST https://api.salesbricks.com/api/v2/customers/a1b2c3d4-0d44-4b50-8888-8dd25736052a/persons \
  -H "X-SALESBRICKS-KEY: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane.smith@acmecorp.com",
    "role": "admin"
  }'

JSON

{
  "person_id": "e5f6g7h8-0d44-4b50-8888-8dd25736052a",
  "first_name": "Jane",
  "last_name": "Smith",
  "email": "jane.smith@acmecorp.com",
  "preferred_name": null,
  "role": "admin"
}

Save the person_id. The same person can act as both the point of contact and the signatory, or you can create a separate contact for each role.

Create the subscription

POST /subscriptions builds the agreement. These fields are all required: customer_id, point_of_contact_id, signatory_user_id, plan_id, bricks, starts_at, contract_length, and billing_frequency.

cURL

curl -X POST https://api.salesbricks.com/api/v2/subscriptions \
  -H "X-SALESBRICKS-KEY: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "a1b2c3d4-0d44-4b50-8888-8dd25736052a",
    "point_of_contact_id": "e5f6g7h8-0d44-4b50-8888-8dd25736052a",
    "signatory_user_id": "e5f6g7h8-0d44-4b50-8888-8dd25736052a",
    "plan_id": "p9q0r1s2-0d44-4b50-8888-8dd25736052a",
    "bricks": [
      { "brick_id": "b3c4d5e6-0d44-4b50-8888-8dd25736052a", "quantity": 10 }
    ],
    "starts_at": "2025-08-01",
    "contract_length": 12,
    "billing_frequency": "MONTHLY",
    "currency": "USD"
  }'

JSON

{
  "subscription_id": "7a8b9c0d-0d44-4b50-8888-8dd25736052a"
}

Save the subscription_id — the activation step needs it.

billing_frequency accepts MONTHLY, QUARTERLY, SEMI_ANNUALLY, ANNUALLY, or ALL_UPFRONT. contract_length is the total term in months, which is separate from how often you invoice.

Useful optional fields include currency (defaults to USD), payment_terms, auto_renews, discount_coupons, accounts_payable_emails, first_charge_date, and metadata for your own key-value data.

Preview the price first

To show a total before committing — a pricing page or an in-app plan picker — post the same body to POST /subscriptions/estimate. It returns the billing schedule and grand total without creating anything.

cURL

curl -X POST https://api.salesbricks.com/api/v2/subscriptions/estimate \
  -H "X-SALESBRICKS-KEY: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_id": "p9q0r1s2-0d44-4b50-8888-8dd25736052a",
    "bricks": [{ "brick_id": "b3c4d5e6-0d44-4b50-8888-8dd25736052a", "quantity": 10 }],
    "starts_at": "2025-08-01",
    "contract_length": 12,
    "billing_frequency": "MONTHLY"
  }'

Activate the subscription

Pick one of the three endpoints below.

Option 1 — Hosted checkout

GET /subscriptions/{subscription_id}/checkout returns a hosted checkout URL showing the subscription summary and a payment form.

cURL

curl https://api.salesbricks.com/api/v2/subscriptions/7a8b9c0d-0d44-4b50-8888-8dd25736052a/checkout \
  -H "X-SALESBRICKS-KEY: <your-api-key>"

JSON

{
  "url": "https://checkout.salesbricks.com/..."
}

Redirect the customer to this URL, or email it to them. The subscription activates once they complete payment — listen for the order.complete webhook to provision access in your app.

Option 2 — Order form signature

POST /subscriptions/{subscription_id}/sign returns a URL where the customer signs the order form. A redirect_url is required — that is where the customer lands after signing.

cURL

curl -X POST https://api.salesbricks.com/api/v2/subscriptions/7a8b9c0d-0d44-4b50-8888-8dd25736052a/sign \
  -H "X-SALESBRICKS-KEY: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "redirect_url": "https://yourapp.com/signup/complete"
  }'

JSON

{
  "url": "https://app.salesbricks.com/sign/..."
}

Option 3 — Direct start

POST /subscriptions/{subscription_id}/start activates the subscription server-side, with no checkout or signature. Use it when the customer already has a payment method on file, or when migrating subscriptions in from another system.

cURL

curl -X POST "https://api.salesbricks.com/api/v2/subscriptions/7a8b9c0d-0d44-4b50-8888-8dd25736052a/start?charge_immediately=yes" \
  -H "X-SALESBRICKS-KEY: <your-api-key>"

A 200 response returns the full subscription detail and confirms activation.

charge_immediately takes the string yes or no, not a boolean. With yes and no default payment method on the customer, the request returns 400 — either add a payment method first, or pass charge_immediately=no.

This endpoint applies to new subscriptions only. To change an existing subscription, use upgrade to add or remove add-ons, or recast to replace the current agreement.

Common errors

Status	Likely cause
`400` on `/customers`	Customer `name` is already in use.
`400` on `/subscriptions`	Missing a required field, or a quantity outside the brick’s min/max units.
`400` on `/start`	No default payment method while `charge_immediately=yes`.
`400` on `/start`	The subscription has already started.
`404`	Unknown `customer_id`, `person_id`, or `subscription_id`.

Endpoint reference

Step	Method	Endpoint
Create customer	`POST`	`/customers`
Add contact	`POST`	`/customers/{customer_id}/persons`
Estimate price	`POST`	`/subscriptions/estimate`
Create subscription	`POST`	`/subscriptions`
Checkout URL	`GET`	`/subscriptions/{subscription_id}/checkout`
Signature URL	`POST`	`/subscriptions/{subscription_id}/sign`
Direct start	`POST`	`/subscriptions/{subscription_id}/start`

​Which flow would you like to build?

Checkout

Signature

Direct start

​Before you begin

​Shared steps

​Preview the price first

​Activate the subscription

​Option 1 — Hosted checkout

​Option 2 — Order form signature

​Option 3 — Direct start

​Common errors

​Endpoint reference

Which flow would you like to build?

Before you begin

Shared steps

Preview the price first

Activate the subscription

Option 1 — Hosted checkout

Option 2 — Order form signature

Option 3 — Direct start

Common errors

Endpoint reference