> ## Documentation Index
> Fetch the complete documentation index at: https://docs.salesbricks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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?

<CardGroup cols={3}>
  <Card title="Checkout" icon="credit-card">
    Send the customer to a Salesbricks-hosted page to pay. Best for self-serve signup.
  </Card>

  <Card title="Signature" icon="signature">
    Send the customer to execute the contract by signing an order form. Best for enterprise or sales-assisted deals.
  </Card>

  <Card title="Direct start" icon="bolt">
    Activate server-side with no customer interaction. Best for existing customers and migrations.
  </Card>
</CardGroup>

## Before you begin

<Info>
  You will need a [Public API Token](/api-reference/getting-started/authentication) and a
  **published plan**. All examples use the production base URL `https://api.salesbricks.com/api/v2`.
</Info>

Find the `plan_id` and the `brick_id` values you want to sell with [List all plans](/api-reference/plans/list-all-plans):

```bash cURL theme={null}
curl https://api.salesbricks.com/api/v2/plans \
  -H "X-SALESBRICKS-KEY: <your-api-key>"
```

<Tip>
  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](/api-reference/getting-started/idempotent-requests).
</Tip>

## Shared steps

<Steps>
  <Step title="Create a customer">
    `POST /customers` creates the record representing the purchasing company. Only `name` is required.

    ```bash cURL theme={null}
    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 JSON theme={null}
    {
      "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": []
    }
    ```

    <Warning>
      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](/api-reference/customers/search-customers).
    </Warning>

    Save the `customer_id`.
  </Step>

  <Step title="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.

    ```bash cURL theme={null}
    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 JSON theme={null}
    {
      "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.
  </Step>

  <Step title="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`.

    ```bash cURL theme={null}
    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 JSON theme={null}
    {
      "subscription_id": "7a8b9c0d-0d44-4b50-8888-8dd25736052a"
    }
    ```

    Save the `subscription_id` — the activation step needs it.

    <Note>
      `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.
    </Note>

    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.
  </Step>
</Steps>

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

```bash cURL theme={null}
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.

```bash cURL theme={null}
curl https://api.salesbricks.com/api/v2/subscriptions/7a8b9c0d-0d44-4b50-8888-8dd25736052a/checkout \
  -H "X-SALESBRICKS-KEY: <your-api-key>"
```

```json JSON theme={null}
{
  "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](/api-reference/webhooks/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.

```bash cURL theme={null}
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 JSON theme={null}
{
  "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.

```bash cURL theme={null}
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.

<Warning>
  `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`.
</Warning>

<Note>
  This endpoint applies to new subscriptions only. To change an existing subscription, use
  [upgrade](/api-reference/subscription-upgrades/create-a-subscription-upgrade) to add or remove
  add-ons, or [recast](/api-reference/subscription-recasts/create-a-subscription-recast) to replace
  the current agreement.
</Note>

## 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`    |


## Related topics

- [GraphQL API (Legacy)](/api-reference/getting-started/graphql.md)
- [REST API Overview](/api-reference/getting-started/overview.md)
- [BrIQ AI Assistant](/documentation/briq.md)