From a55991fe23da65a099ebf20d6935bfcf5096946c Mon Sep 17 00:00:00 2001
From: bc-msung <marcus.sung@bigcommerce.com>
Date: Mon, 24 Feb 2025 11:33:08 +1100
Subject: [PATCH] chore(shipping): SHIPPING-3338 Publish documentation for v3
 channel based out of zone delivery message

---
 reference/shipping.v3.yml | 161 +++++++++++++++++++++++++++++++++++++-
 1 file changed, 158 insertions(+), 3 deletions(-)

diff --git a/reference/shipping.v3.yml b/reference/shipping.v3.yml
index 615176e50..7ac77b3de 100644
--- a/reference/shipping.v3.yml
+++ b/reference/shipping.v3.yml
@@ -164,7 +164,7 @@ paths:
                     type: object
                     properties: {}
       description: |-
-        Get shipping settings.
+        Returns the global-level shipping settings.
       tags:
         - Shipping Settings
       summary: Get Shipping Settings
@@ -185,9 +185,53 @@ paths:
                   meta:
                     type: object
                     properties: {}
+        '400':
+          description: Bad Request. Input is invalid.
+          content:
+            application/json:
+              schema:
+                description: ''
+                type: object
+                properties:
+                  status:
+                    type: number
+                  title:
+                    type: string
+                    minLength: 1
+                  type:
+                    type: string
+                    minLength: 1
+                  detail:
+                    type: string
+                    minLength: 1
+              example:
+                status: 400
+                title: Input is invalid
+                type: 'https://developer.bigcommerce.com/api-docs/getting-started/api-status-codes'
+                detail: Syntax error
+        '422':
+          description: The request body does not meet the specification.
+          content:
+            application/json:
+              schema:
+                description: ''
+                type: object
+                properties:
+                  status:
+                    type: number
+                  title:
+                    type: string
+                    minLength: 1
+                  type:
+                    type: string
+                    minLength: 1
+              example:
+                status: 422
+                title: Input is invalid
+                type: 'https://developer.bigcommerce.com/api-docs/getting-started/api-status-codes'
       summary: Update Shipping Settings
       description: |-
-        Updates shipping settings.
+        Updates the global-level shipping settings.
       tags:
         - Shipping Settings
       requestBody:
@@ -195,6 +239,107 @@ paths:
           application/json:
             schema:
               $ref: '#/components/schemas/shippingSettings'
+  '/shipping/settings/channels/{channel_id}':
+    parameters:
+      - $ref: '#/components/parameters/Accept'
+      - name: channel_id
+        in: path
+        schema:
+          type: string
+        description: Channel ID
+        required: true
+
+    get:
+      operationId: getChannelShippingSettings
+      responses:
+        '200':
+          description: ''
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    $ref: '#/components/schemas/channelShippingSettings'
+                  meta:
+                    type: object
+                    properties: {}
+      description: |-
+        Returns shipping settings for a specific channel.
+      tags:
+        - Shipping Settings
+      summary: Get Shipping Settings per Channel
+    put:
+      operationId: updateChannelShippingSettings
+      parameters:
+        - $ref: '#/components/parameters/ContentType'
+      responses:
+        '200':
+          description: ''
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    $ref: '#/components/schemas/channelShippingSettings'
+                  meta:
+                    type: object
+                    properties: {}
+        '400':
+          description: Bad Request. Input is invalid.
+          content:
+            application/json:
+              schema:
+                description: ''
+                type: object
+                properties:
+                  status:
+                    type: number
+                  title:
+                    type: string
+                    minLength: 1
+                  type:
+                    type: string
+                    minLength: 1
+                  detail:
+                    type: string
+                    minLength: 1
+              example:
+                status: 400
+                title: Input is invalid
+                type: 'https://developer.bigcommerce.com/api-docs/getting-started/api-status-codes'
+                detail: Syntax error
+        '422':
+          description: The request body does not meet the specification.
+          content:
+            application/json:
+              schema:
+                description: ''
+                type: object
+                properties:
+                  status:
+                    type: number
+                  title:
+                    type: string
+                    minLength: 1
+                  type:
+                    type: string
+                    minLength: 1
+              example:
+                status: 422
+                title: Input is invalid
+                type: 'https://developer.bigcommerce.com/api-docs/getting-started/api-status-codes'
+      summary: Update Shipping Settings per Channel
+      description: |-
+        Updates shipping settings for a specific channel.
+      tags:
+        - Shipping Settings
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/channelShippingSettings'
 components:
   parameters:
     store_hash:
@@ -420,7 +565,17 @@ components:
                 - DISPLAY_ALL_COUNTRIES
                 - DISPLAY_ONLY_SHIPPABLE_COUNTRIES
               example: DISPLAY_ALL_COUNTRIES
-            out_of_zone_delivery_message:
+            out_of_delivery_zone_message:
+              description: Message shown to the shopper during checkout when their order does not meet the merchant's shipping criteria.
+              type: string
+              example: Unfortunately, one or more items in your cart can't be shipped to your location. Please choose a different delivery address.
+    channelShippingSettings:
+      type: object
+      properties:
+        checkout:
+          type: object
+          properties:
+            out_of_delivery_zone_message:
               description: Message shown to the shopper during checkout when their order does not meet the merchant's shipping criteria.
               type: string
               example: Unfortunately, one or more items in your cart can't be shipped to your location. Please choose a different delivery address.