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

# Change Subscription Product

> Swap the product on an existing subscription order (Coming Soon)

Swap the product attached to an active subscription order.

```
POST /v1/actions/subscription-order/change-product
```

**Authentication:** Session Token — see [Customer Endpoints](/api-reference/endpoints/auth/customer-endpoints) (customer role)

<Warning>
  **Coming Soon** — This endpoint is not yet implemented and currently returns `501 Not Implemented`. The request signature below is provisional and may change before GA. While not implemented, the route remains locked: calling it will not mutate any subscription state.
</Warning>

## Request Body

| Field             | Type   | Required | Description                                               |
| ----------------- | ------ | -------- | --------------------------------------------------------- |
| `orderId`         | string | Yes      | Current subscription order ID (Short ID format `ORD_xxx`) |
| `targetProductId` | string | Yes      | Target product ID (Short ID format `PROD_xxx`)            |

## Example Request

<CodeGroup>
  ```typescript TypeScript (SDK) theme={"system"}
  import { WaffoPancake } from "@waffo/pancake-ts";

  const client = new WaffoPancake({
    sessionToken: window.WAFFO_SESSION_TOKEN, // injected by the merchant's portal
    environment: "prod",
  });

  const result = await client.orders.changeSubscriptionProduct({
    orderId: "ORD_2aUyqjCzEIiEcYMKj7TZtw",
    targetProductId: "PROD_36ZqlJPatGOsjz7AtYqAwj",
  });
  ```

  ```typescript TypeScript (Manual) theme={"system"}
  const result = await fetch("https://api.waffo.ai/v1/actions/subscription-order/change-product", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${SESSION_TOKEN}`,
      "Content-Type": "application/json",
      "X-Environment": "prod",
    },
    body: JSON.stringify({
      orderId: "ORD_2aUyqjCzEIiEcYMKj7TZtw",
      targetProductId: "PROD_36ZqlJPatGOsjz7AtYqAwj",
    }),
  }).then(r => r.json());
  ```

  ```bash cURL theme={"system"}
  curl -X POST "https://api.waffo.ai/v1/actions/subscription-order/change-product" \
    -H "Authorization: Bearer $SESSION_TOKEN" \
    -H "Content-Type: application/json" \
    -H "X-Environment: prod" \
    -d '{"orderId":"ORD_2aUyqjCzEIiEcYMKj7TZtw","targetProductId":"PROD_36ZqlJPatGOsjz7AtYqAwj"}'
  ```

  ```bash wget theme={"system"}
  wget -qO- \
    --header="Authorization: Bearer $SESSION_TOKEN" \
    --header="Content-Type: application/json" \
    --header="X-Environment: prod" \
    --post-data='{"orderId":"ORD_2aUyqjCzEIiEcYMKj7TZtw","targetProductId":"PROD_36ZqlJPatGOsjz7AtYqAwj"}' \
    "https://api.waffo.ai/v1/actions/subscription-order/change-product"
  ```
</CodeGroup>

## Current Response (501)

```json theme={"system"}
{
  "data": null,
  "errors": [
    {
      "message": "Not implemented",
      "layer": "order"
    }
  ]
}
```

### Response Fields (planned)

| Field     | Type   | Description                           |
| --------- | ------ | ------------------------------------- |
| `orderId` | string | Subscription order ID (Short ID)      |
| `status`  | string | Order status after the product change |

## Errors

> **Retry policy:** Never retry 4xx — fix the request and resubmit. Retry 5xx with exponential backoff (start 5s, max 3 attempts).

| Status | `errors[0].message`                       | What it means                                  | Recommended handling                                      |
| ------ | ----------------------------------------- | ---------------------------------------------- | --------------------------------------------------------- |
| 400    | `Missing required field: orderId`         | `orderId` was not provided in the body         | Fix the request body, then resubmit                       |
| 400    | `Missing required field: targetProductId` | `targetProductId` was not provided in the body | Fix the request body, then resubmit                       |
| 400    | `Expected format: ORD_xxx, got "..."`     | `orderId` Short ID could not be decoded        | Fix the `orderId` format, then resubmit                   |
| 401    | `Authentication failed`                   | Session token invalid, expired, or malformed   | Re-mint the session token via Issue Session Token         |
| 403    | `Order does not belong to user`           | Ownership check failed                         | Verify the caller owns the order                          |
| 404    | `Order not found`                         | Order does not exist                           | Verify the order ID                                       |
| 501    | `Not implemented`                         | Endpoint is not yet available                  | Wait for GA — do not retry                                |
| 500    | `Internal server error`                   | Unexpected server-side failure                 | Retry with exponential backoff (start 5s, max 3 attempts) |