# Payments

The payment endpoints let you manage subscriptions via Stripe: list plans, create checkout sessions, process subscriptions, update or cancel plans, and access the customer portal.

## Endpoints

| Method | Path                             | Description                         |
| ------ | -------------------------------- | ----------------------------------- |
| GET    | `/payment/subscription-plans`    | List available subscription plans   |
| POST   | `/payment/subscription-checkout` | Create checkout session             |
| POST   | `/payment/subscription-process`  | Process subscription after checkout |
| POST   | `/payment/subscription-update`   | Update subscription                 |
| POST   | `/payment/subscription-cancel`   | Cancel subscription                 |
| GET    | `/payment/customer-info`         | Get Stripe customer info            |
| POST   | `/payment/customer-portal`       | Create customer portal session      |

***

## List Subscription Plans

Returns available subscription plans for an organization.

**Method:** GET\
**Path:** `/payment/subscription-plans`

### Query Parameters

| Parameter        | Type   | Required | Description     |
| ---------------- | ------ | -------- | --------------- |
| `organizationId` | string | Yes      | Organization ID |

### Response Body

Returns an array of subscription plan objects with pricing, features, and product details.

### Example

```bash
curl -X GET "https://api.app.bullseye.so/api/v1/payment/subscription-plans?organizationId=org_abc123" \
  -H "X-API-Key: bsk_live_your_api_key_here" \
  -H "Content-Type: application/json"
```

***

## Create Checkout Session

Creates a Stripe Checkout session for subscribing to a plan. Returns a URL to redirect the user to complete payment.

**Method:** POST\
**Path:** `/payment/subscription-checkout`

### Request Body

JSON object with `organizationId`, `priceId`, `productId`, and optionally `successUrl`, `cancelUrl`.

### Response Body

Returns an object with a `url` field for the checkout session.

### Example

```bash
curl -X POST "https://api.app.bullseye.so/api/v1/payment/subscription-checkout" \
  -H "X-API-Key: bsk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"organizationId": "org_abc123", "priceId": "price_xxx", "productId": "prod_xxx"}'
```

***

## Process Subscription

Processes a subscription after the user completes Stripe Checkout. Typically called by a webhook or redirect handler.

**Method:** POST\
**Path:** `/payment/subscription-process`

### Query Parameters

| Parameter | Type   | Required | Description                                |
| --------- | ------ | -------- | ------------------------------------------ |
| `secret`  | string | Yes      | Secret or session identifier from checkout |

### Response Body

Returns confirmation of the processed subscription.

### Example

```bash
curl -X POST "https://api.app.bullseye.so/api/v1/payment/subscription-process?secret=session_xxx" \
  -H "X-API-Key: bsk_live_your_api_key_here" \
  -H "Content-Type: application/json"
```

***

## Update Subscription

Updates the subscription plan for an organization (e.g., upgrade or downgrade).

**Method:** POST\
**Path:** `/payment/subscription-update`

### Request Body

| Field            | Type   | Required | Description           |
| ---------------- | ------ | -------- | --------------------- |
| `organizationId` | string | Yes      | Organization ID       |
| `priceId`        | string | Yes      | New Stripe price ID   |
| `productId`      | string | Yes      | New Stripe product ID |

### Response Body

Returns confirmation of the update.

### Example

```bash
curl -X POST "https://api.app.bullseye.so/api/v1/payment/subscription-update" \
  -H "X-API-Key: bsk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"organizationId": "org_abc123", "priceId": "price_xxx", "productId": "prod_xxx"}'
```

***

## Cancel Subscription

Cancels the subscription for an organization.

**Method:** POST\
**Path:** `/payment/subscription-cancel`

### Request Body

| Field            | Type   | Required | Description     |
| ---------------- | ------ | -------- | --------------- |
| `organizationId` | string | Yes      | Organization ID |

### Response Body

Returns an empty object on success.

### Example

```bash
curl -X POST "https://api.app.bullseye.so/api/v1/payment/subscription-cancel" \
  -H "X-API-Key: bsk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"organizationId": "org_abc123"}'
```

***

## Get Customer Info

Retrieves Stripe customer information for an organization, including subscription status, payment method, and billing details.

**Method:** GET\
**Path:** `/payment/customer-info`

### Query Parameters

| Parameter        | Type   | Required | Description     |
| ---------------- | ------ | -------- | --------------- |
| `organizationId` | string | Yes      | Organization ID |

### Response Body

Returns customer details such as `customerId`, `email`, `address`, `defaultCardLast4`, `activeProductId`, and subscription status.

### Example

```bash
curl -X GET "https://api.app.bullseye.so/api/v1/payment/customer-info?organizationId=org_abc123" \
  -H "X-API-Key: bsk_live_your_api_key_here" \
  -H "Content-Type: application/json"
```

***

## Create Customer Portal Session

Creates a Stripe Customer Portal session. Returns a URL where the user can manage their subscription, payment methods, and invoices.

**Method:** POST\
**Path:** `/payment/customer-portal`

### Request Body

| Field            | Type   | Required | Description     |
| ---------------- | ------ | -------- | --------------- |
| `organizationId` | string | Yes      | Organization ID |

### Response Body

Returns an object with a `url` field for the portal session.

### Example

```bash
curl -X POST "https://api.app.bullseye.so/api/v1/payment/customer-portal" \
  -H "X-API-Key: bsk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"organizationId": "org_abc123"}'
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bullseye.so/api-reference/payments.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.