From 220c2fc76ef0aa6978d5e9fdc769b1280ef4eff1 Mon Sep 17 00:00:00 2001
From: Sarah Riehl <sarah.riehl@bigcommerce.com>
Date: Sun, 4 Feb 2024 19:03:53 -0600
Subject: [PATCH] ISSUE-83: [update] Orders V2, change shipping_provider to
 anyOf (#84)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

<!-- Ticket number or summary of work -->
# ISSUE-83
* #83

## What changed?
<!-- Provide a bulleted list in the present tense -->
* change shipping_provider to anyOf to accommodate custom providers and
support autogeneration
* add examples

## Release notes draft
<!-- Provide an entry for the release notes using simple, conversational
language. Don't be too technical. Explain how the change will benefit
the merchant and link to the feature.

Examples:
* The newly-released [X feature] is now available to use. Now, you’ll be
able to [perform Y action].
* We're happy to announce [X feature], which can help you [perform Y
action].
* [X feature] helps you to create [Y response] using the [Z query
parameter]. Now, you can deliver [ex, localized shopping experiences for
your customers].
* Fixed a bug in the [X endpoint]. Now the [Y field] will appear when
you click [Z option]. -->
* We've updated the shipping_provider property throughout the Orders V2
spec to allow arbitrary strings. This better indicates support for new
and custom shipping providers, and improves API client autogeneration.

## Anything else?
<!-- Add related PRs, salient notes, additional ticket numbers, etc. -->
* #83

ping FYI @bc-andreadao @theromulans
---
 reference/orders.v2.oas2.yml | 114 ++++++++++++++++++++++-------------
 1 file changed, 73 insertions(+), 41 deletions(-)

diff --git a/reference/orders.v2.oas2.yml b/reference/orders.v2.oas2.yml
index a08f2a9d2..f5563736a 100644
--- a/reference/orders.v2.oas2.yml
+++ b/reference/orders.v2.oas2.yml
@@ -631,7 +631,19 @@ paths:
 
         3. Supply a custom `tracking_link`: By providing a value for the `tracking_link` property, you can use your own tracking link within the BigCommerce control panel and in customer-facing emails. The API response will return your supplied tracking link as part of the `tracking_link` property in the response. In situations when there isn't a `generated_tracking_link`, the property in the API response will remain empty. 
         
-        Acceptable values for `shipping_provider` include an empty string (`""`), `auspost`, `carrier_{your_carrier_id}` (only used if the carrier is a [third-party Shipping Provider](/docs/integrations/shipping)), `canadapost`, `endicia`, `usps`, `fedex`, `royalmail`, `ups`, `upsready`, `upsonline`, or `shipperhq`.
+        Acceptable values for `shipping_provider` include the following, and this list may be updated at any time: 
+         - `""`, an empty string
+         - `auspost`
+         - `canadapost
+         - `endicia`
+         - `usps`
+         - `fedex`
+         - `royalmail`
+         - `ups`
+         - `upsready`
+         - `upsonline`
+         - `shipperhq`
+         - `carrier_{your_carrier_id}`, when the carrier is a [third-party Shipping Provider](/docs/integrations/shipping) 
         
         Acceptable values for `tracking_carrier` include an empty string (`""`) or one of the valid [tracking-carrier values](https://github.com/bigcommerce/dev-docs/blob/master/assets/csv/tracking_carrier_values.csv).
       summary: Create Order Shipment
@@ -3162,26 +3174,32 @@ components:
           example: Ship by Weight
           type: string
         shipping_provider:
-          type: string
-          description: Enum of the BigCommerce shipping-carrier integration/module.
-          enum:
-            - auspost
-            - canadapost
-            - carrier_{your_carrier_id} (only used if the carrier is a [third-party Shipping Provider](/docs/integrations/shipping))
-            - endicia
-            - usps
-            - fedex
-            - ups
-            - upsready
-            - upsonline
-            - shipperhq
-            - ''
+          anyOf:
+            - type: string
+              description: An enum identifying one of several core shipping providers.
+              enum:
+                - auspost
+                - canadapost
+                - endicia
+                - usps
+                - fedex
+                - ups
+                - upsready
+                - upsonline
+                - shipperhq
+                - royalmail
+                - ''
+              example: shipperhq
+            - type: string
+              description: A string identifying the shipping provider. Some shipping providers may not be listed in the preceding enum list. In addition, if the carrier is a [third-party Shipping Provider](/docs/integrations/shipping), the string takes the form `carrier_{your_carrier_id}`.
+              example: carrier_1234567
         tracking_carrier:
           type: string
           title: Tracking Carrier
           description: |-
             Tracking carrier for the shipment.
             Acceptable values for `tracking_carrier` include an empty string (`""`) or one of the valid [tracking-carrier values](https://github.com/bigcommerce/dev-docs/blob/master/assets/csv/tracking_carrier_values.csv).
+          example: ""
         tracking_link:
           type: string
           description: The custom tracking link supplied on POST or PUT shipments. For the auto-generated tracking link see the `generated_tracking_link` property.
@@ -3562,25 +3580,32 @@ components:
           example: Ship by Weight
           type: string
         shipping_provider:
-          type: string
-          description: Enum of the BigCommerce shipping-carrier integration/module.
-          enum:
-            - auspost
-            - canadapost
-            - carrier_{your_carrier_id} (only used if the carrier is a [third-party Shipping Provider](/docs/integrations/shipping))
-            - endicia
-            - usps
-            - fedex
-            - ups
-            - upsready
-            - upsonline
-            - shipperhq
+          anyOf:
+            - type: string
+              description: An enum identifying one of several core shipping providers.
+              enum:
+                - auspost
+                - canadapost
+                - endicia
+                - usps
+                - fedex
+                - ups
+                - upsready
+                - upsonline
+                - shipperhq
+                - royalmail
+                - ''
+              example: shipperhq
+            - type: string
+              description: A string identifying the shipping provider. Some shipping providers may not be listed in the preceding enum list. In addition, if the carrier is a [third-party Shipping Provider](/docs/integrations/shipping), the string takes the form `carrier_{your_carrier_id}`.
+              example: carrier_1234567
         tracking_carrier:
           type: string
           title: Tracking Carrier
           description: |-
             Tracking carrier for the shipment.
             Acceptable values for `tracking_carrier` include an empty string (`""`) or one of the valid [tracking-carrier values](https://github.com/bigcommerce/dev-docs/blob/master/assets/csv/tracking_carrier_values.csv).
+          example: ""
         comments:
           type: string
           description: Comments the shipper wishes to add.
@@ -3617,25 +3642,32 @@ components:
           example: Ship by Weight
           type: string
         shipping_provider:
-          type: string
-          description: Enum of the BigCommerce shipping-carrier integration/module.
-          enum:
-            - auspost
-            - canadapost
-            - carrier_{your_carrier_id} (only used if the carrier is a [third-party Shipping Provider](/docs/integrations/shipping))
-            - endicia
-            - usps
-            - fedex
-            - ups
-            - upsready
-            - upsonline
-            - shipperhq
+          anyOf:
+            - type: string
+              description: An enum identifying one of several core shipping providers.
+              enum:
+                - auspost
+                - canadapost
+                - endicia
+                - usps
+                - fedex
+                - ups
+                - upsready
+                - upsonline
+                - shipperhq
+                - royalmail
+                - ''
+              example: shipperhq
+            - type: string
+              description: A string identifying the shipping provider. Some shipping providers may not be listed in the preceding enum list. In addition, if the carrier is a [third-party Shipping Provider](/docs/integrations/shipping), the string takes the form `carrier_{your_carrier_id}`.
+              example: carrier_1234567
         tracking_carrier:
           type: string
           title: Tracking Carrier
           description: |-
             Tracking carrier for the shipment.
             Acceptable values for `tracking_carrier` include an empty string (`""`) or one of the valid [tracking-carrier values](https://github.com/bigcommerce/dev-docs/blob/master/assets/csv/tracking_carrier_values.csv).
+          example: ""
         tracking_link:
           type: string
           description: The custom tracking link supplied on POST or PUT shipments. For the auto-generated tracking link see the `generated_tracking_link` property.