Add specification for UpcomingInvoice (#1748)

* Add specification for UpcomingInvoice

* Remove sensitive data from StorefrontUpcomingInvoice

* Storefront upcoming invoice fixes

* CR fixes

* CR fixes

---------

Co-authored-by: Alexander Shkarpetin <alexander.shkarpetin@rebilly.com>

openapi/components/schemas/StorefrontUpcomingInvoice.yaml

@@ -0,0 +1,113 @@
+type: object
+readOnly: true
+properties:
+  id:
+    description: ID of the upcoming invoice, which is persisted in the future renewal invoice.
+    type: string
+    readOnly: true
+    maxLength: 50
+    example: in_0YVF9605RKC62BP14NE2R7V2XT
+  websiteId:
+    $ref: ./WebsiteId.yaml
+  subscriptionId:
+    description: ID of the related subscription order.
+    type: string
+    readOnly: true
+    maxLength: 50
+    example: ord_01GYJPRKHBD6ZYHH897QCJMBS4
+  currency:
+    $ref: ./CurrencyCode.yaml
+  items:
+    type: array
+    description: Upcoming invoice items array.
+    items:
+      $ref: ./UpcomingInvoiceItem.yaml
+  amount:
+    description: Amount of the invoice.
+    type: number
+    format: double
+    readOnly: true
+  amountDue:
+    description: Amount that is due on the invoice.
+    type: number
+    format: double
+    readOnly: true
+  subtotalAmount:
+    description: Subtotal amount of the invoice.
+    type: number
+    format: double
+    readOnly: true
+  discountAmount:
+    description: Discount amount that is applied to the invoice.
+    type: number
+    format: double
+    readOnly: true
+  shipping:
+    $ref: ./Shipping.yaml
+  tax:
+    $ref: ./Taxes.yaml
+  billingAddress:
+    description: Billing address of the invoice.
+    $ref: ./ContactObject.yaml
+  deliveryAddress:
+    description: Delivery address of the invoice.
+    $ref: ./ContactObject.yaml
+  poNumber:
+    description: Purchase order number that is displayed on the invoice.
+    type:
+      - 'string'
+      - 'null'
+    example: PO123456
+  notes:
+    description: Notes for the customer that are displayed on the invoice.
+    type: string
+  discounts:
+    type: array
+    description: Discounts applied.
+    readOnly: true
+    items:
+      type: object
+      readOnly: true
+      properties:
+        couponId:
+          type: string
+          description: ID of the coupon.
+          maxLength: 50
+          example: cpn_0YVCNKF81GD778N4YNVGDJK558
+        redemptionId:
+          description: ID of the redemption.
+          $ref: ./ResourceId.yaml
+        amount:
+          description: Total amount discounted by this coupon.
+          type: number
+          format: double
+        description:
+          type: string
+          description: Description of the discount.
+        context:
+          $ref: ./DiscountContext.yaml
+  dueTime:
+    description: Date and time when the invoice is due for payment.
+    type: string
+    format: date-time
+  issuedTime:
+    description: Date and time when the invoice is issued.
+    $ref: ./ServerTimestamp.yaml
+  createdTime:
+    $ref: ./CreatedTime.yaml
+  updatedTime:
+    $ref: ./UpdatedTime.yaml
+  _links:
+    type: array
+    description: Related links.
+    items:
+      type: object
+      properties:
+        href:
+          description: Link URL.
+          type: string
+        rel:
+          description: Type of link.
+          type: string
+          enum:
+            - self

openapi/openapi.yaml

@@ -1327,6 +1327,8 @@ paths:
     $ref: paths/storefront/invoices.yaml
   '/storefront/invoices/{id}':
     $ref: paths/storefront/invoices@{id}.yaml
+  '/storefront/orders/{id}/upcoming-invoice':
+    $ref: paths/storefront/orders@{id}@upcoming-invoice.yaml
   '/storefront/kyc-documents':
     $ref: paths/storefront/kyc-documents.yaml
   '/storefront/kyc-documents/{id}':

openapi/paths/storefront/orders@{id}@upcoming-invoice.yaml

@@ -0,0 +1,31 @@
+parameters:
+  - $ref: ../../components/parameters/resourceId.yaml
+get:
+  x-products:
+    - Storefront
+  tags:
+    - Storefront orders
+  summary: Retrieve an upcoming subscription order invoice
+  operationId: StorefrontGetOrderUpcomingInvoice
+  x-sdk-operation-name: getUpcomingInvoice
+  security:
+    - CustomerJWT: []
+  description: |-
+    Retrieves an upcoming invoice for a specified subscription order.
+
+    An upcoming invoice is an invoice that has not been issued.
+    It functions as a preview of the next invoice for the order.
+    For more information, see [Invoices](https://www.rebilly.com/docs/dev-docs/invoices/).
+  responses:
+    200:
+      description: Upcoming invoice retrieved.
+      content:
+        application/json:
+          schema:
+            $ref: ../../components/schemas/StorefrontUpcomingInvoice.yaml
+    401:
+      $ref: ../../components/responses/Unauthorized.yaml
+    403:
+      $ref: ../../components/responses/Forbidden.yaml
+    404:
+      $ref: ../../components/responses/NotFound.yaml