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

# Update Store

> Update an existing store's name, status, or configuration settings

Update an existing store's name, status, or configuration settings. Only fields included in the request body are updated; omitted fields remain unchanged.

```
POST /v1/actions/store/update-store
```

**Authentication:** API Key (owner or admin role required)

<Note>
  This endpoint does not manage webhook configuration. If a `webhookSettings` field is sent in the request body it is silently ignored and the response includes a top-level `warnings` array; other fields update normally and the call returns 200. Use [`add-webhook`](/api-reference/endpoints/webhooks/add-webhook), [`update-webhook`](/api-reference/endpoints/webhooks/update-webhook), and [`remove-webhook`](/api-reference/endpoints/webhooks/remove-webhook) to configure webhooks, and GraphQL `Store.storeWebhooks` to list them.
</Note>

## Request Body

| Field                  | Type             | Required | Description                                            |
| ---------------------- | ---------------- | -------- | ------------------------------------------------------ |
| `id`                   | string           | Yes      | Store ID (Short ID format `STO_xxx`)                   |
| `name`                 | string           | No       | Updated store name (1-48 characters)                   |
| `status`               | string           | No       | `active`, `inactive`, or `suspended`                   |
| `logo`                 | string \| null   | No       | Store logo URL (set to `null` to remove)               |
| `supportEmail`         | `string \| null` | No       | Store support email address (set to `null` to remove)  |
| `website`              | `string \| null` | No       | Store website URL (set to `null` to remove)            |
| `notificationSettings` | object \| null   | No       | Notification preferences (set to `null` to remove)     |
| `checkoutSettings`     | object \| null   | No       | Checkout theme configuration (set to `null` to remove) |

## Notification Settings

Two categories with different write permissions:

**Merchant-writable** (✅ accepted via this endpoint):

| Field                          | Type    | Default | Description                                                            |
| ------------------------------ | ------- | ------- | ---------------------------------------------------------------------- |
| `notifyNewOrders`              | boolean | `true`  | Notify merchant of new orders                                          |
| `notifyNewSubscriptions`       | boolean | `true`  | Notify merchant of new subscriptions                                   |
| `notifySubscriptionCanceled`   | boolean | `true`  | Notify merchant when a subscriber cancels (still within access period) |
| `notifySubscriptionEnded`      | boolean | `true`  | Notify merchant when a subscription ends                               |
| `notifySubscriptionPastDue`    | boolean | `true`  | Notify merchant when a subscription enters past-due (payment failure)  |
| `notifySubscriptionRenewed`    | boolean | `true`  | Notify merchant when a subscription successfully renews                |
| `notifySubscriptionUncanceled` | boolean | `true`  | Notify merchant when a previously canceled subscription is reactivated |
| `notifySubscriptionUpdated`    | boolean | `true`  | Notify merchant when a subscription plan changes (forward-compat)      |
| `notifyChargeback`             | boolean | `true`  | Notify merchant when a chargeback is filed (forward-compat)            |

**Platform-managed** (🔒 read-only via merchant API; managed by PANCAKE platform):

| Field                           | Type    | Default | Description                                                |
| ------------------------------- | ------- | ------- | ---------------------------------------------------------- |
| `emailOrderConfirmation`        | boolean | `true`  | Send email on order confirmation                           |
| `emailSubscriptionConfirmation` | boolean | `true`  | Send email on subscription creation                        |
| `emailSubscriptionCycled`       | boolean | `true`  | Send email on subscription renewal                         |
| `emailSubscriptionCanceled`     | boolean | `true`  | Send email on subscription cancellation                    |
| `emailSubscriptionRevoked`      | boolean | `true`  | Send email on subscription revocation                      |
| `emailSubscriptionPastDue`      | boolean | `true`  | Send email on subscription past due                        |
| `emailTrialStarted`             | boolean | `true`  | Send email when a free trial is started                    |
| `emailTrialEnding`              | boolean | `true`  | Send email reminder before a trial ends                    |
| `emailUpcomingCharge`           | boolean | `true`  | Send email reminder before an upcoming subscription charge |

<Note>
  If your `notificationSettings` payload includes any platform-managed field (`email*`, or the legacy `notifyPayoutCompleted` / `notifyPayoutFailed` keys — payout result emails are always delivered and have no toggle), the server silently drops it and returns a `200` response with a `warnings[]` entry listing the dropped keys. To toggle a customer email, contact PANCAKE platform support.
</Note>

## Checkout Settings

| Field             | Type    | Description                      |
| ----------------- | ------- | -------------------------------- |
| `defaultDarkMode` | boolean | Whether to default to dark mode  |
| `light`           | object  | Light theme settings (see below) |
| `dark`            | object  | Dark theme settings (see below)  |

**Checkout Theme Settings** (applies to both `light` and `dark`):

| Field                     | Type           | Description                |
| ------------------------- | -------------- | -------------------------- |
| `checkoutLogo`            | string \| null | Logo URL for checkout page |
| `checkoutColorPrimary`    | string         | Primary color (hex)        |
| `checkoutColorBackground` | string         | Background color (hex)     |
| `checkoutColorCard`       | string         | Card/panel color (hex)     |
| `checkoutColorText`       | string         | Text color (hex)           |
| `checkoutBorderRadius`    | string         | Border radius (CSS value)  |

## Partial Update Semantics

Both settings objects support partial updates. Each sub-field follows these semantics:

| Value                 | Behavior            | Example                                                              |
| --------------------- | ------------------- | -------------------------------------------------------------------- |
| Omitted (not in JSON) | Keep existing value | Only pass `notifyNewOrders`; other notification flags stay unchanged |
| `null`                | Clear the field     | `"checkoutLogo": null` removes the checkout logo                     |
| Actual value          | Create or update    | `"checkoutColorPrimary": "#FF6600"` sets a new primary color         |

Setting the entire object to `null` (e.g., `"notificationSettings": null`) clears all fields in that settings group.

## Example Request

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

  const client = new WaffoPancake({
    merchantId: process.env.WAFFO_MERCHANT_ID!,
    privateKey: process.env.WAFFO_PRIVATE_KEY!,
  });

  const { store } = await client.stores.update({
    id: "STO_2aUyqjCzEIiEcYMKj7TZtw",
    name: "Updated Store Name",

    notificationSettings: {
      notifyNewOrders: true,
      notifyNewSubscriptions: false,
    },
  });
  ```

  ```typescript TypeScript (fetch) theme={"system"}
  // Uses callApi() helper from authentication.mdx
  const result = await callApi("POST", "/v1/actions/store/update-store", {
    id: "STO_2aUyqjCzEIiEcYMKj7TZtw",
    name: "Updated Store Name",

    notificationSettings: {
      notifyNewSubscriptions: false,
    },
  });
  console.log(result.data.store.name); // => "Updated Store Name"
  ```

  ```java Java theme={"system"}
  // Uses callApi() helper from authentication.mdx
  String body = """
      {
        "id": "STO_2aUyqjCzEIiEcYMKj7TZtw",
        "name": "Updated Store Name",

        "notificationSettings": {
          "notifyNewSubscriptions": false
        }
      }""";

  String response = callApi("POST", "/v1/actions/store/update-store", body);
  System.out.println(response);
  ```

  ```python Python theme={"system"}
  # Uses call_api() helper from authentication.mdx
  result = call_api("POST", "/v1/actions/store/update-store", {
      "id": "STO_2aUyqjCzEIiEcYMKj7TZtw",
      "name": "Updated Store Name",

      "notificationSettings": {
          "notifyNewSubscriptions": False,
      },
  })
  store = result["data"]["store"]
  print(store["name"])  # => "Updated Store Name"
  ```

  ```go Go theme={"system"}
  // Uses callAPI() helper from authentication.mdx
  body := map[string]interface{}{
      "id":   "STO_2aUyqjCzEIiEcYMKj7TZtw",
      "name": "Updated Store Name",

      "notificationSettings": map[string]interface{}{
          "notifyNewSubscriptions": false,
      },
  }
  result, err := callAPI("POST", "/v1/actions/store/update-store", body)
  if err != nil {
      log.Fatal(err)
  }
  fmt.Println(string(result))
  ```

  ```rust Rust theme={"system"}
  // Uses call_api() helper from authentication.mdx
  let body = serde_json::json!({
      "id": "STO_2aUyqjCzEIiEcYMKj7TZtw",
      "name": "Updated Store Name",

      "notificationSettings": {
          "notifyNewSubscriptions": false
      }
  });
  let result = call_api("POST", "/v1/actions/store/update-store", &body).await?;
  println!("{}", result);
  ```

  ```c C theme={"system"}
  /* Uses call_api() helper from authentication.mdx */
  const char *body =
      "{\"id\":\"STO_2aUyqjCzEIiEcYMKj7TZtw\","
      "\"name\":\"Updated Store Name\","
      "\"notificationSettings\":{\"notifyNewSubscriptions\":false}}";
  char *response = call_api("POST", "/v1/actions/store/update-store", body);
  printf("%s\n", response);
  free(response);
  ```

  ```cpp C++ theme={"system"}
  // Uses callApi() helper from authentication.mdx
  std::string body = R"({
    "id": "STO_2aUyqjCzEIiEcYMKj7TZtw",
    "name": "Updated Store Name",
    "notificationSettings": {
      "notifyNewSubscriptions": false
    }
  })";
  std::string response = callApi("POST", "/v1/actions/store/update-store", body);
  std::cout << response << std::endl;
  ```

  ```bash cURL theme={"system"}
  MERCHANT_ID="MER_2aUyqjCzEIiEcYMKj7TZtw"
  TIMESTAMP=$(date +%s)
  BODY='{"id":"STO_2aUyqjCzEIiEcYMKj7TZtw","name":"Updated Store Name","notificationSettings":{"notifyNewSubscriptions":false}}'
  BODY_HASH=$(echo -n "$BODY" | openssl dgst -sha256 -binary | base64 -w 0)
  CANONICAL_REQUEST="POST
  /v1/actions/store/update-store
  $TIMESTAMP
  $BODY_HASH"

  SIGNATURE=$(echo -n "$CANONICAL_REQUEST" | openssl dgst -sha256 -sign private_key.pem | base64 -w 0)

  curl -X POST "https://api.waffo.ai/v1/actions/store/update-store" \
    -H "Content-Type: application/json" \
    -H "X-Merchant-Id: $MERCHANT_ID" \
    -H "X-Timestamp: $TIMESTAMP" \
    -H "X-Signature: $SIGNATURE" \
    -d "$BODY"
  ```

  ```bash wget theme={"system"}
  MERCHANT_ID="MER_2aUyqjCzEIiEcYMKj7TZtw"
  TIMESTAMP=$(date +%s)
  BODY='{"id":"STO_2aUyqjCzEIiEcYMKj7TZtw","name":"Updated Store Name","notificationSettings":{"notifyNewSubscriptions":false}}'
  BODY_HASH=$(echo -n "$BODY" | openssl dgst -sha256 -binary | base64 -w 0)
  CANONICAL_REQUEST="POST
  /v1/actions/store/update-store
  $TIMESTAMP
  $BODY_HASH"

  SIGNATURE=$(echo -n "$CANONICAL_REQUEST" | openssl dgst -sha256 -sign private_key.pem | base64 -w 0)

  wget -qO- "https://api.waffo.ai/v1/actions/store/update-store" \
    --header="Content-Type: application/json" \
    --header="X-Merchant-Id: $MERCHANT_ID" \
    --header="X-Timestamp: $TIMESTAMP" \
    --header="X-Signature: $SIGNATURE" \
    --post-data="$BODY"
  ```
</CodeGroup>

## Success Response (200)

```json theme={"system"}
{
  "data": {
    "store": {
      "id": "STO_2aUyqjCzEIiEcYMKj7TZtw",
      "name": "Updated Store Name",
      "status": "active",
      "logo": null,
      "slug": "my-digital-store-a1b2c3",
      "prodEnabled": false,
      "notificationSettings": {
        "emailOrderConfirmation": true,
        "emailSubscriptionConfirmation": true,
        "emailSubscriptionCycled": true,
        "emailSubscriptionCanceled": true,
        "emailSubscriptionRevoked": true,
        "emailSubscriptionPastDue": true,
        "emailTrialStarted": true,
        "emailTrialEnding": true,
        "emailUpcomingCharge": true,
        "notifyNewOrders": true,
        "notifyNewSubscriptions": false,
        "notifySubscriptionCanceled": true,
        "notifySubscriptionEnded": true,
        "notifySubscriptionPastDue": true,
        "notifySubscriptionRenewed": true,
        "notifySubscriptionUncanceled": true,
        "notifySubscriptionUpdated": true,
        "notifyChargeback": true
      },
      "checkoutSettings": {
        "defaultDarkMode": false,
        "light": {
          "checkoutLogo": null,
          "checkoutColorPrimary": "#000000",
          "checkoutColorBackground": "#FFFFFF",
          "checkoutColorCard": "#F5F5F5",
          "checkoutColorText": "#1A1A1A",
          "checkoutBorderRadius": "8px"
        },
        "dark": {
          "checkoutLogo": null,
          "checkoutColorPrimary": "#FFFFFF",
          "checkoutColorBackground": "#1A1A1A",
          "checkoutColorCard": "#2A2A2A",
          "checkoutColorText": "#F5F5F5",
          "checkoutBorderRadius": "8px"
        }
      },
      "deletedAt": null,
      "createdAt": "2026-01-15T10:30:00.000Z",
      "updatedAt": "2026-01-15T11:00:00.000Z"
    }
  }
}
```

## Response Fields

Same as [Create Store response fields](/api-reference/endpoints/stores/create-store#response-fields).

## webhookSettings Compatibility Warning

If a `webhookSettings` field is sent in the request body, it is silently ignored and the response includes a top-level `warnings` array. The `data.store` object is unaffected.

```json theme={"system"}
{
  "data": { "store": { "...": "..." } },
  "warnings": [
    {
      "message": "webhookSettings is no longer accepted on update-store; the field was ignored.",
      "layer": "store",
      "aiHint": "AI assistant: 'webhookSettings' is permanently removed (BREAKING 2026-05). Do not retry with this field. SDK users: upgrade to @waffo/pancake-ts >= 0.6.0 and call client.webhooks.add / update / remove instead of client.stores.update({ webhookSettings }). Direct API users: POST /api/actions/store/add-webhook to create a webhook, /update-webhook to modify, /remove-webhook to delete. Query the webhook list via GraphQL Store.storeWebhooks field, not via this endpoint."
    }
  ]
}
```

## 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 merchantId in request context`                 | API Key did not resolve to a merchant context      | **Do not retry.** Check your API Key configuration. |
| 400    | `Missing required field: id`                            | `id` is absent from the body                       | Fix the input and resubmit.                         |
| 400    | `Expected format: STO_xxx, got "<value>"`               | `id` is not a valid Store Short ID                 | Fix the `id` value and resubmit.                    |
| 400    | `Store name cannot be empty or contain only whitespace` | `name` is empty after `trim()`                     | Fix the `name` and resubmit.                        |
| 400    | `Store name cannot exceed 48 characters`                | `name` is longer than 48 characters                | Shorten the `name` and resubmit.                    |
| 400    | `Invalid status, must be active, inactive or suspended` | `status` value is not one of the allowed enums     | Use `active`, `inactive`, or `suspended`.           |
| 400    | `Invalid logo: must be a string or null`                | `logo` is not a string and not `null`              | Pass a string URL or `null` to clear.               |
| 403    | `Not authorized to update this store`                   | Caller's role on this store is not `owner`/`admin` | **Do not retry.** Use an authorized merchant.       |
| 404    | `Store not found`                                       | Store ID does not exist for this merchant          | **Do not retry.** Verify the `id`.                  |