Add Storefront change-items endpoint (#1769)

* Add Storefront change-items endpoint

* Remove usage limits

* Adjust subscription terms

* Add preview field

* Apply suggestions from code review

Co-authored-by: Chris  <[email protected]>

* Adjust status code

---------

Co-authored-by: Lucas de Oliveira <[email protected]>
Co-authored-by: Chris <[email protected]>

Author: 3 people

openapi/components/requestBodies/storefront/PostSubscriptionItemsChange.yaml

@@ -0,0 +1,38 @@
+type: object
+description: Change customer subscription items.
+properties:
+  effectiveTime:
+    type: string
+    description: Effective time when changes are applied.
+    default: now
+    enum:
+      - now
+      - next-service-period
+    x-enumDescriptions:
+      now: Apply changes immediately.
+      next-service-period: Apply changes at the beginning of next service period.
+  items:
+    type: array
+    description: Details of items in the subscription.
+    minItems: 1
+    items:
+      type: object
+      required:
+        - planId
+      properties:
+        planId:
+          type: string
+          description: ID of the plan.
+          maxLength: 50
+          example: plan_0YV7DENSVGDBW9S71XZNNYYQ0X
+        quantity:
+          description: Number of units of the product on the given plan.
+          type: integer
+          minimum: 0
+  preview:
+    description: |-
+      Specifies if the quote must be previewed before it is created.
+      Subscriptions cannot be changed in the preview.
+    type: boolean
+    default: false
+    example: true

openapi/openapi.yaml

@@ -1359,6 +1359,8 @@ paths:
     $ref: paths/storefront/orders@{id}@cancellation.yaml
   '/storefront/orders/{id}/pause':
     $ref: paths/storefront/orders@{id}@pause.yaml
+  '/storefront/subscriptions/{id}/change-items':
+    $ref: paths/storefront/subscriptions@{id}@change-items.yaml
   '/storefront/payment':
     $ref: paths/storefront/payment.yaml
   '/storefront/payment-instruments':

openapi/paths/storefront/subscriptions@{id}@change-items.yaml

@@ -0,0 +1,41 @@
+parameters:
+  - $ref: ../../components/parameters/resourceId.yaml
+post:
+  x-badge: Experimental
+  x-products:
+    - Storefront
+  tags:
+    - Storefront orders
+  summary: Change subscription items
+  operationId: StorefrontPostSubscriptionItemsChange
+  x-sdk-operation-name: changeItems
+  security:
+    - CustomerJWT: []
+  description: |-
+    Creates a quote for requested changes to items and quantities.
+    This operation applies the requested changes to the subscription when the quote is accepted.
+  requestBody:
+    content:
+      application/json:
+        schema:
+          $ref: ../../components/requestBodies/storefront/PostSubscriptionItemsChange.yaml
+    description: Change items request.
+    required: true
+  responses:
+    '201':
+      description: Quote for requested changes to items and quantities is created and issued.
+      headers:
+        Location:
+          $ref: ../../components/headers/Location.yaml
+      content:
+        application/json:
+          schema:
+            $ref: ../../components/schemas/StorefrontQuoteChangeOrder.yaml
+    '401':
+      $ref: ../../components/responses/Unauthorized.yaml
+    '403':
+      $ref: ../../components/responses/Forbidden.yaml
+    '404':
+      $ref: ../../components/responses/NotFound.yaml
+    '422':
+      $ref: ../../components/responses/ValidationError.yaml