@shipengine/connect-fulfillment-provider-api 0.4.0 → 0.5.0

package/spec.yaml

@@ -32,6 +32,7 @@ paths:
                 auth:
                   $ref: '#/components/schemas/Auth'
         description: Contains form data for connecting to the app
+      description: Verify credentials are valid for a new connection to a fulfillment provider
   /delegate_fulfillment:
     post:
       summary: Delegate Fulfillment
@@ -46,7 +47,7 @@ paths:
                 properties:
                   fulfillment_provider_order_id:
                     type: string
-      description: ''
+      description: Delegate a sales order to a fulfillment provider.  The fulfillment provider will attempt to fulfill the shipment of all line items.  Returns the identifier used by the fulfillment provider for subsequent status updates for the order and it's fulfillments.  Often this is the same as the order_id.
       requestBody:
         content:
           application/json:
@@ -305,9 +306,9 @@ paths:
           in: header
           name: tenant-id
     parameters: []
-  /get_fulfillment:
+  /get_fulfillments:
     post:
-      summary: Get Fulfillment
+      summary: Get Fulfillments
       operationId: post-fulfillment-status
       responses:
         '200':
@@ -317,18 +318,121 @@ paths:
               schema:
                 type: object
                 properties:
-                  fulfillment:
-                    $ref: '#/components/schemas/SalesOrderStatusChange'
+                  fulfillment_provider_order_id:
+                    type: string
+                  status:
+                    type: string
+                  fulfillments:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/SalesOrderFulfillment'
+                  shipments:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/ShipmentNotification'
                   polling:
                     type: object
                     properties:
                       is_final_update_state:
                         type: boolean
-                        enum:
-                          - once
-                          - changes_since
                       max_age_seconds:
                         type: number
+                required:
+                  - fulfillment_provider_order_id
+              examples:
+                example-1:
+                  value:
+                    fulfillment_provider_order_id: string
+                    status: string
+                    fulfillments:
+                      - status: Processing
+                        reason: string
+                        explanation: string
+                        line_items:
+                          - line_item_id: string
+                            sku: string
+                            quantity: 0
+                    shipments:
+                      - carrier_code: string
+                        carrier_service_code: string
+                        currency: 'USD,EUR,NZD'
+                        ext_location_id: string
+                        fulfillment_cost: 0
+                        insurance_cost: 0
+                        integration_context: {}
+                        items:
+                          - description: string
+                            line_item_id: string
+                            product_id: string
+                            quantity: 0
+                            sku: string
+                        notes:
+                          - text: string
+                            type: BackOrderMessage
+                        notification_id: string
+                        notify_buyer: true
+                        order_id: string
+                        order_number: string
+                        return_address:
+                          address_line_1: string
+                          address_line_2: string
+                          address_line_3: string
+                          city: string
+                          company: string
+                          country_code: 'US,MX,CA'
+                          is_verified: true
+                          name: string
+                          first_name: string
+                          last_name: string
+                          phone: string
+                          pickup_location:
+                            carrier_id: string
+                            relay_id: string
+                          postal_code: string
+                          residential_indicator: R
+                          state_province: string
+                        ship_date: '2021-03-31T18:21:14.858Z'
+                        ship_from:
+                          address_line_1: string
+                          address_line_2: string
+                          address_line_3: string
+                          city: string
+                          company: string
+                          country_code: 'US,MX,CA'
+                          is_verified: true
+                          name: string
+                          first_name: string
+                          last_name: string
+                          phone: string
+                          pickup_location:
+                            carrier_id: string
+                            relay_id: string
+                          postal_code: string
+                          residential_indicator: R
+                          state_province: string
+                        ship_to:
+                          address_line_1: string
+                          address_line_2: string
+                          address_line_3: string
+                          city: string
+                          company: string
+                          country_code: 'US,MX,CA'
+                          is_verified: true
+                          name: string
+                          first_name: string
+                          last_name: string
+                          phone: string
+                          pickup_location:
+                            carrier_id: string
+                            relay_id: string
+                          postal_code: string
+                          residential_indicator: R
+                          state_province: string
+                        tracking_number: string
+                        tracking_url: string
+                    polling:
+                      is_final_update_state: true
+                      max_age_seconds: 0
       requestBody:
         content:
           application/json:
@@ -343,25 +447,13 @@ paths:
                 - auth
                 - fulfillment_provider_order_id
       description: |-
-        Receives an single fulfillment provider order id that was returned from the /delegate_fulfillment resource.
-        It should return matching fulfillment quantity updates for all line items of the original fulfillment delegations.
-        It should return quantities for rejected, cancelled, and shipped per line item.
-        Rejected means the fulfillment provider cannot fulfill that item.
-        Cancelled means the client has requested an item not be fulfilled and the fulfillment provider was able to stop fulfillment.
-        Shipped means the item has left for delivery.
-
-        The original fulfillment will be marked shipped when all line items are either rejected/cancelled/shipped and at least one is shipped.
+        Returns a list of fulfillments that the fulfillment provider has decided to use to fulfill an order.  It may return only a root level status, which indicates a single status for all line items on an order.  It may also return a list of fulfillments, their status, and the line items included in that fulfillment.  Fulfillments may or may not match a list of shipments, this is completely up to the fulfillment provider.
 
-        This resource is requested after the first time /fulfillment/status returns a polling method of "Batch".
-        The polling interval is once every 30 minutes.
-        The maximum number of ids per request is 50.
-        When there are more than 50 ids to request they are sequentially sent in batches of 50.
+        To communicate that the results for an order will no longer change the polling fields is_final_update_state should be set to true.  
 
-        Polling can be controlled by returning the polling.max_age_seconds or polling.per_request_limit property.
-        The polling.max_age_seconds property overrides the 30 minute interval.
-        The polling.per_request_limit property overrides the 50 ids sent per request.
+        The polling fields max_age_seconds refers to the expected cachable time of this result.
 
-        Individual fulfillments can be removed from the batch polling method by returning "once" or "cursor" in the polling.method property.
+        To instead return a list of changes on a periodic basis, refer to the /get_recent_changes path instead.
       parameters:
         - schema:
             type: string
@@ -400,6 +492,7 @@ paths:
                 - auth
                 - fulfillment_provider_order_id
                 - reason
+      description: Request the cancellation of a requested fulfillment send using the /delegate_fulfillment path.  This will likely only start the cancellation process.  Status updates via /get_fulfillments and /get_recent_changes will return the cancellation status when it is completed.
     parameters: []
   /get_rates:
     post:
@@ -476,7 +569,7 @@ paths:
   /get_recent_changes:
     parameters: []
     post:
-      summary: Get Fulfillments With Changes
+      summary: Get Recent Changes
       operationId: post-fulfillment-get-recent-changes
       responses:
         '200':
@@ -489,24 +582,15 @@ paths:
                   changes:
                     type: array
                     items:
-                      $ref: '#/components/schemas/SalesOrderStatusChange'
+                      $ref: '#/components/schemas/SalesOrderFulfillment'
                   next_request:
                     type: string
-        '':
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  changes:
-                    type: string
-                  next_request:
-                    type:
-                      - object
-                      - string
       description: |-
-        Receives a timestamp and returns a list of line item changes since then.
-        It may also return order level status changes that should be applied to all line items on the order as a whole.
+        Receives a timestamp of the last time requested changes was made, automatically buffered to include duplicate results to prevent skipping time.
+
+        Returns a list of changes. These changes include fulfillments that the fulfillment provider has decided to use to fulfill an order.  It may return only an order level status, which indicates a single status for all line items on an order.  It may also return a list of fulfillments, their status, and the line items included in that fulfillment.  Fulfillments may or may not match a list of shipments, this is completely up to the fulfillment provider.
+
+        To instead return status on single orders at a time , refer to the /get_fulfillments path instead.
       requestBody:
         content:
           application/json:
@@ -521,6 +605,7 @@ paths:
                     - string
                 since:
                   type: string
+            examples: {}
       parameters:
         - schema:
             type: string
@@ -528,7 +613,7 @@ paths:
           name: tenant-id
   /get_inventory:
     post:
-      summary: Get Paged Inventory
+      summary: Get Inventory
       operationId: post-get-inventory
       responses:
         '200':
@@ -555,6 +640,16 @@ paths:
                     type:
                       - string
                       - object
+              examples:
+                example-1:
+                  value:
+                    inventory:
+                      sku: string
+                      warehouse_id: string
+                      available_quantity: string
+                      committed_quantity: string
+                      on_hand_quantity: string
+                    next_request: string
       requestBody:
         content:
           application/json:
@@ -569,6 +664,7 @@ paths:
                     - string
               required:
                 - auth
+      description: Return the inventory that a fulfillment provider currently has for this merchant.  Pagination is supplied via the next_request field.  Pagination requests will be made until next_request is set to null.  This is an optional path only for fulfillment providers who support inventory and are added as inventory provider integrations.
     parameters: []
 components:
   schemas:
@@ -1367,29 +1463,6 @@ components:
                   type: string
       required:
         - rates
-    LineItemQuantityStatus:
-      title: LineItemQuantityStatus
-      type: object
-      properties:
-        line_item_id:
-          type: string
-        sku:
-          type: string
-        quantity:
-          type: number
-        shipped_quantity:
-          type: number
-        cancelled_quantity:
-          $ref: '#/components/schemas/QuantityWithReason'
-        rejected_quantity:
-          $ref: '#/components/schemas/QuantityWithReason'
-        unknown_quantity:
-          $ref: '#/components/schemas/QuantityWithReason'
-      required:
-        - line_item_id
-        - sku
-        - quantity
-      description: Sales order line item quantity fulfillment statuses
     Note:
       title: Note
       type: object
@@ -1756,31 +1829,29 @@ components:
       required:
         - description
         - quantity
-    SalesOrderStatus:
+    SalesOrderFulfillmentStatus:
       type: string
-      title: SalesOrderStatus
+      title: SalesOrderFulfillmentStatus
       enum:
         - Processing
         - Cancelled
         - Rejected
-        - Unknown
-        - PartiallyShipped
         - Shipped
-    SalesOrderStatusChange:
-      title: SalesOrderStatusChange
+    SalesOrderFulfillment:
+      title: SalesOrderFulfillment
       type: object
       description: Represents a status change update for a sales order
       properties:
-        order_id:
-          type: string
         status:
-          $ref: '#/components/schemas/SalesOrderStatus'
-        items:
-          $ref: '#/components/schemas/LineItemQuantityStatus'
-        shipments:
+          $ref: '#/components/schemas/SalesOrderFulfillmentStatus'
+        reason:
+          type: string
+        explanation:
+          type: string
+        line_items:
           type: array
           items:
-            $ref: '#/components/schemas/ShipmentNotification'
+            $ref: '#/components/schemas/FulfillmentLineItem'
     ShipmentNotification:
       title: ShipmentNotification
       type: object
@@ -2078,4 +2149,38 @@ components:
         - weight_in_grams
         - source_weight
         - source_weight_unit
+    FulfillmentLineItem:
+      title: FulfillmentLineItem
+      x-stoplight:
+        id: 0wglkamy8lqi5
+      type: object
+      properties:
+        line_item_id:
+          type: string
+        sku:
+          type: string
+        quantity:
+          type: number
+      required:
+        - quantity
+    SalesOrderFulfillments:
+      title: SalesOrderFulfillments
+      x-stoplight:
+        id: 0mccgdffw5fq2
+      type: object
+      properties:
+        fulfillment_provider_order_id:
+          type: string
+        status:
+          $ref: '#/components/schemas/SalesOrderFulfillmentStatus'
+        fulfillments:
+          type: array
+          items:
+            $ref: '#/components/schemas/SalesOrderFulfillment'
+        shipments:
+          type: array
+          items:
+            $ref: '#/components/schemas/ShipmentNotification'
+      required:
+        - fulfillment_provider_order_id
   requestBodies: {}