# Storefront · Subscriptions

Part of AppEngine API Documentation. Full index: https://appengine.appmint.io/documentation.md
## GET /storefront/subscriptions/get/{author}/{subscriptionid}

**Get a customer's subscriptions**

`operationId: StorefrontController_getSubscriptions`

Returns the subscriptions belonging to a customer. Supply `subscriptionid` to fetch one; omit the segment to list them all.

Pass `enrich=true` to resolve the linked plan and product records inline instead of returning bare references.

#### Signature

```http
GET /storefront/subscriptions/get/{author}/{subscriptionid} (author: string, subscriptionid: string, enrich?: boolean) -> The customer's subscriptions
```

#### Access

Public — no credentials required.

#### Errors

Plus the standard platform errors: `429`, `500`.

#### See also

- `POST /storefront/update-subscription`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `author` | path | string | yes | Customer email or username. |
| `subscriptionid` | path | string | yes | Subscription number. Omit to list every subscription for the customer. |
| `enrich` | query | boolean | — | Resolve linked plan and product records inline. |

### Responses

| Status | Meaning |
| --- | --- |
| `200` | The customer's subscriptions |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## POST /storefront/stripe/subscription-session

**Create a Stripe subscription session**

`operationId: StorefrontController_stripeSubscriptionSession`

Creates a hosted Stripe Checkout session in subscription mode and returns the redirect URL. Use this to start a recurring plan; use `stripe/checkout-session` for one-off purchases.

#### Signature

```http
POST /storefront/stripe/subscription-session (body) -> The subscription session, including the redirect URL
```

#### Access

Public — no credentials required.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| `400` | GATEWAY_ERROR | The payment gateway rejected the request. | Stripe returned an error — an invalid amount, a missing configuration, or a declined card. | The gateway message is passed through. Fix the reported problem and retry; do not retry an unchanged declined request. |

Plus the standard platform errors: `429`, `500`.

#### See also

- `GET /storefront/subscriptions/get/{author}/{subscriptionid}`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |
| `x-client-host` | header | string | — | Client host, used to build the return URLs. |
| `x-client-protocol` | header | string | — | Protocol for the return URLs. |

### Request body

Subscription session details.

```json
{
  "plan": "pro-monthly",
  "email": "ada@example.com"
}
```

### Responses

| Status | Meaning |
| --- | --- |
| `201` | The subscription session, including the redirect URL |
| `400` | The payment gateway rejected the request. — Stripe returned an error — an invalid amount, a missing configuration, or a declined card. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |

## POST /storefront/update-subscription

**Update a subscription**

`operationId: StorefrontController_subscriptionUpdate`

Changes a subscription — plan, quantity, or cancellation. The change is applied both locally and at the payment gateway, so billing follows the new terms.

#### Signature

```http
POST /storefront/update-subscription (body) -> The updated subscription
```

#### Access

Public — no credentials required.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| `404` | SUBSCRIPTION_NOT_FOUND | Subscription not found | `subscriptionId` does not resolve in the org. | List the customer's subscriptions to find the right identifier. |
| `400` | GATEWAY_ERROR | The payment gateway rejected the request. | Stripe returned an error — an invalid amount, a missing configuration, or a declined card. | The gateway message is passed through. Fix the reported problem and retry; do not retry an unchanged declined request. |

Plus the standard platform errors: `429`, `500`.

#### See also

- `GET /storefront/subscriptions/get/{author}/{subscriptionid}`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgid` | header | string | yes | Organization (tenant) identifier. Every request is scoped to this org; data from other orgs is never visible. Issued with your API credentials. |

### Request body

The subscription and the change to apply.

```json
{
  "subscriptionId": "SUB-4821",
  "plan": "pro-annual"
}
```

### Responses

| Status | Meaning |
| --- | --- |
| `201` | The updated subscription |
| `400` | The payment gateway rejected the request. — Stripe returned an error — an invalid amount, a missing configuration, or a declined card. |
| `404` | Subscription not found — `subscriptionId` does not resolve in the org. |
| `429` | Too Many Requests — More than 100,000 requests from one IP within 5 minutes (configurable per deployment). CORS preflights and requests from inside the platform cluster are not counted. The limiter answers before the error filter, so the body is `{ statusCode, error, message }` with no `path`, `method` or `timeStamp`; the `RateLimit-*` response headers say when the window resets. |
| `500` | An unexpected error occurred. Our team has been notified. — An unhandled server-side failure. |