Update Store (v1)

Method + Path

PATCH /v1/workspace/:workspaceId/storefront/store

Actual backend path: /v1/workspace/:workspaceId/storefront/store

Description

Update the storefront store configuration. All fields are optional - only provided fields will be updated.

Authentication

Required - JWT token in Authorization header

Required Permissions:

• storefront.update

Headers

Header	Type	Required	Description
Authorization	string	Yes	Bearer token: Bearer <token>
Content-Type	string	Yes	application/json

Path Parameters

Parameter	Type	Required	Description
workspaceId	string	Yes	Workspace identifier

Request Body

{
  "name": "Updated Store Name",
  "slug": "updated-slug",
  "description": "Updated description"
}

Body Parameters

Parameter	Type	Required	Description
name	string	No	Store name (1-120 characters if provided)
slug	string	No	URL-friendly slug (1-120 characters if provided)
description	string	No	Store description (maximum 2000 characters, can be null)
inventoryUnits	array	No	Inventory units for the store. Each item: { id: string, name: string, sortOrder: number }. Default unit ids (liter, gram, kilo, piece) must remain; custom units can be added or removed.
storewideDiscount	object | null	No	Store-wide percentage discount applied to cart subtotal. When set, object: { isActive: boolean, type: "percentage", value: number (0-100), startsAt?: string (ISO date), endsAt?: string (ISO date) }. Set to null to clear. If startsAt/endsAt are provided, the discount is only active within that date range.
postCheckoutWhatsAppPhone	string | null	No	International WhatsApp number for the business in E.164 format, starting with + (e.g. +970591234567). When set, customers who complete an order on the public storefront are redirected to WhatsApp with a prefilled message (order id and name). Use null or empty string to disable. Total digits after + must be between 7 and 15.
productReviewsAutoPublish	boolean	No	When true, new customer product reviews (rating + optional comment) are published on the public storefront immediately. When false (default), reviews start as pending until a user with store.products.manage approves them in the dashboard. Personas: Workspace Owner, Staff with store management permission (store.manage).
appearance	object	No	Partial storefront appearance. At least one nested field is required when appearance is sent. Supported fields include headerTitle, cartLabel, language, currency, colors (partial color map), footerCopyrightText, and social URL fields (socialInstagram, socialFacebook, socialSnapchat, socialTelegram, socialWhatsApp).
appearance.cartLabel	string | null	No	Custom label for the shopping cart on the public storefront (e.g. Arabic wording chosen by the store). Max 40 characters after trim. Use null or empty string to clear and use default i18n (“السلة” / “Cart” by language). Personas: Workspace Owner, Staff with storefront.update.
appearance.footerCopyrightText	string | null	No	Optional line shown on the public storefront above the Placio credit (e.g. “جميع الحقوق محفوظة”). Max 200 characters after trim. Personas: Workspace Owner, Staff with storefront.update.
appearance.socialInstagram	string | null	No	Optional https:// URL for Instagram; shown as an icon above the copyright line on the public storefront. Personas: Workspace Owner, Staff with storefront.update.
appearance.socialFacebook	string | null	No	Optional https:// URL for Facebook. Same display rules as Instagram.
appearance.socialSnapchat	string | null	No	Optional https:// URL for Snapchat. Same display rules as Instagram.
appearance.socialTelegram	string | null	No	Optional https:// URL for Telegram. Same display rules as Instagram.
appearance.socialWhatsApp	string | null	No	Optional https:// URL for WhatsApp (e.g. https://wa.me/...). Same display rules as Instagram.

Response (200)

{
  "store": {
    "id": "507f1f77bcf86cd799439011",
    "name": "Updated Store Name",
    "slug": "updated-slug",
    "description": "Updated description",
    "storewideDiscount": null,
    "updatedAt": "2024-01-15T11:00:00Z"
  }
}

When storewideDiscount is configured, the response includes it, e.g.:

"storewideDiscount": {
  "isActive": true,
  "type": "percentage",
  "value": 10,
  "startsAt": "2024-06-01T00:00:00.000Z",
  "endsAt": "2024-06-30T23:59:59.999Z"
}

The same field is returned in the public store response (GET /v1/public/storefront/stores/:slug) so the storefront can display the discount in the cart.

postCheckoutWhatsAppPhone is also returned on the public store payload when configured (otherwise null) so storefront-web can open WhatsApp after checkout.

Common Errors

• 400 Bad Request: Invalid request body
• 401 Unauthorized: Missing or invalid authentication token
• 403 Forbidden: Insufficient permissions (requires storefront.update)
• 404 Not Found: Store or workspace not found
• 409 Conflict: Slug already taken
• 422 Unprocessable Entity: Validation errors
• 500 Internal Server Error: Server error