@redotech/redo-api-schema 2.2.416 → 2.2.423

package/lib/openapi.d.ts

@@ -76,6 +76,11 @@ export interface paths {
     /**
      * Update Return Status
      * @description Update return status.
+     *
+     * Certain status transitions trigger additional side effects to maintain data consistency:
+     *
+     * - Setting status to **complete** will also mark all return items as complete.
+     * - Setting status to **open** from **complete** or **rejected** will reopen the return, resetting all processed/rejected items back to open, clearing pending processing info, resetting the expiration date, and marking the return as reopened. **Note:** Reopening a processed return does not reverse any refunds, exchanges, or other actions that were performed during processing.
      */
     put: operations["Return status update"];
   };
@@ -185,6 +190,11 @@ export interface paths {
      * @description List returns, sorted by most recent to least recent.
      */
     get: operations["Returns list"];
+    /**
+     * Create Return
+     * @description Create a return for specific order line items.
+     */
+    post: operations["Return create"];
     parameters: {
       path: {
         storeId: components["parameters"]["store-id.param"];
@@ -340,6 +350,83 @@ export interface components {
        */
       price: components["schemas"]["money.schema"];
     };
+    /** @description Create return request body. */
+    "create-return-request.schema": {
+      /** @description Return information payload. */
+      data: {
+        /** @description External order ID from the ecommerce platform. */
+        externalOrderId: string;
+        /** @description Items being returned. */
+        items: ({
+            /**
+             * @description How the customer should be compensated for this item.
+             * @enum {string}
+             */
+            compensation: "refund" | "store_credit";
+            /** @description External line item ID from the order. */
+            lineItemId: string;
+            /** @description Customer-facing notes for this item. */
+            notes?: string;
+            /** @description Number of units to return. */
+            quantity: number;
+            /** @description Customer-facing return reason. */
+            reason: string;
+            /** @description Machine-readable reason code. */
+            reasonCode?: string;
+          })[];
+        /** @description Optional return label and tracking details. */
+        label?: {
+          /** @description Carrier name. */
+          carrier?: string;
+          /** @description Commercial or form label URL. */
+          formLabelUrl?: string;
+          /** @description Provider shipment identifier to reference. */
+          originalShipmentId?: string;
+          /** @description Postage label URL. */
+          postageLabelUrl?: string;
+          /** @description Carrier tracking number. */
+          trackingNumber: string;
+          /** @description Public tracking URL. */
+          trackingUrl?: string;
+        };
+        /** @description Internal merchant-side notes. */
+        notes?: string;
+        /** @description Ecommerce platform provider. */
+        provider: string;
+        /** @description Address the customer is shipping from. */
+        shippingAddress: {
+          city: string;
+          /** @description ISO 3166-1 alpha-2 country code. */
+          country: string;
+          line1: string;
+          line2?: string;
+          postalCode: string;
+          state: string;
+        };
+      };
+      /** @description Options controlling side effects of the return creation. */
+      options?: {
+        /**
+         * @description Whether to create RMAs with external integrations (e.g. ShipBob). Defaults to false.
+         * @default false
+         */
+        createExternalRMAs?: boolean;
+      };
+    };
+    /** @description Create return response body. */
+    "create-return-response.schema": {
+      externalRMAResponses: {
+          /** @description Provider error code when external RMA creation fails. */
+          errorCode?: string;
+          /** @description Provider error message when external RMA creation fails. */
+          errorMessage?: string;
+          /** @description Name of the external integration provider. */
+          integrationProvider: string;
+          /** @description Whether external RMA creation succeeded. */
+          success: boolean;
+        }[];
+      return: components["schemas"]["return-read.schema"];
+    };
     /**
      * Custom Event Request
      * @description Custom event to trigger flows with merchant-defined event names and properties.
@@ -1519,6 +1606,8 @@ export interface components {
   };
   responses: never;
   parameters: {
+    /** @description Optional idempotency key for safely retrying create requests. */
+    "idempotency-key.param"?: string;
     /** @description Invoice ID */
     "invoice-id.param": string;
     /**
@@ -1794,6 +1883,11 @@ export interface operations {
   /**
    * Update Return Status
    * @description Update return status.
+   *
+   * Certain status transitions trigger additional side effects to maintain data consistency:
+   *
+   * - Setting status to **complete** will also mark all return items as complete.
+   * - Setting status to **open** from **complete** or **rejected** will reopen the return, resetting all processed/rejected items back to open, clearing pending processing info, resetting the expiration date, and marking the return as reopened. **Note:** Reopening a processed return does not reverse any refunds, exchanges, or other actions that were performed during processing.
    */
   "Return status update": {
     parameters: {
@@ -2282,6 +2376,63 @@ export interface operations {
       };
     };
   };
+  /**
+   * Create Return
+   * @description Create a return for specific order line items.
+   */
+  "Return create": {
+    parameters: {
+      header?: {
+        "Idempotency-Key"?: components["parameters"]["idempotency-key.param"];
+      };
+      path: {
+        storeId: components["parameters"]["store-id.param"];
+      };
+    };
+    requestBody: {
+      content: {
+        "application/json": components["schemas"]["create-return-request.schema"];
+      };
+    };
+    responses: {
+      /** @description Success (idempotent replay; existing return returned) */
+      200: {
+        content: {
+          "application/json": components["schemas"]["create-return-response.schema"];
+        };
+      };
+      /** @description Created */
+      201: {
+        content: {
+          "application/json": components["schemas"]["create-return-response.schema"];
+        };
+      };
+      /** @description Invalid request body */
+      400: {
+        content: {
+          "application/json": components["schemas"]["error.schema"];
+        };
+      };
+      /** @description Order not found */
+      404: {
+        content: {
+          "application/json": components["schemas"]["error.schema"];
+        };
+      };
+      /** @description Conflict */
+      409: {
+        content: {
+          "application/json": components["schemas"]["error.schema"];
+        };
+      };
+      /** @description Error */
+      default: {
+        content: {
+          "application/problem+json": components["schemas"]["error.schema"];
+        };
+      };
+    };
+  };
   /**
    * Receive Storefront Events
    * @description Processes events from storefronts using Shopify pixel event schema

package/lib/openapi.yaml

@@ -830,7 +830,13 @@ paths:
       tags:
         - Returns
     put:
-      description: Update return status.
+      description: |
+        Update return status.
+
+        Certain status transitions trigger additional side effects to maintain data consistency:
+
+        - Setting status to **complete** will also mark all return items as complete.
+        - Setting status to **open** from **complete** or **rejected** will reopen the return, resetting all processed/rejected items back to open, clearing pending processing info, resetting the expiration date, and marking the return as reopened. **Note:** Reopening a processed return does not reverse any refunds, exchanges, or other actions that were performed during processing.
       operationId: Return status update
       parameters:
         - $ref: '#/components/parameters/return-id.param'
@@ -906,6 +912,59 @@ paths:
       summary: List Returns
       tags:
         - Returns
+    post:
+      description: Create a return for specific order line items.
+      operationId: Return create
+      parameters:
+        - $ref: '#/components/parameters/idempotency-key.param'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/create-return-request.schema'
+        required: true
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/create-return-response.schema'
+          description: Success (idempotent replay; existing return returned)
+        '201':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/create-return-response.schema'
+          description: Created
+        '400':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/error.schema'
+          description: Invalid request body
+        '404':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/error.schema'
+          description: Order not found
+        '409':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/error.schema'
+          description: Conflict
+        default:
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/error.schema'
+          description: Error
+      security:
+        - Bearer: []
+      summary: Create Return
+      tags:
+        - Returns
     parameters:
       - $ref: '#/components/parameters/store-id.param'
     summary: Returns
@@ -1239,6 +1298,13 @@ components:
       name: status
       schema:
         $ref: '#/components/schemas/return-status.schema'
+    idempotency-key.param:
+      description: Optional idempotency key for safely retrying create requests.
+      in: header
+      name: Idempotency-Key
+      required: false
+      schema:
+        type: string
     webhook-id.param:
       description: Webhook ID
       in: path
@@ -2748,6 +2814,150 @@ components:
       example: open
       title: Return status
       type: string
+    create-return-request.schema:
+      type: object
+      description: Create return request body.
+      properties:
+        data:
+          type: object
+          description: Return information payload.
+          properties:
+            provider:
+              type: string
+              description: Ecommerce platform provider.
+              examples:
+                - shopify
+            externalOrderId:
+              type: string
+              description: External order ID from the ecommerce platform.
+            items:
+              type: array
+              minItems: 1
+              description: Items being returned.
+              items:
+                type: object
+                properties:
+                  lineItemId:
+                    type: string
+                    description: External line item ID from the order.
+                  quantity:
+                    type: integer
+                    minimum: 1
+                    description: Number of units to return.
+                  reason:
+                    type: string
+                    description: Customer-facing return reason.
+                  reasonCode:
+                    type: string
+                    description: Machine-readable reason code.
+                  compensation:
+                    type: string
+                    enum:
+                      - refund
+                      - store_credit
+                    description: How the customer should be compensated for this item.
+                  notes:
+                    type: string
+                    description: Customer-facing notes for this item.
+                required:
+                  - lineItemId
+                  - quantity
+                  - reason
+                  - compensation
+            shippingAddress:
+              type: object
+              description: Address the customer is shipping from.
+              properties:
+                line1:
+                  type: string
+                line2:
+                  type: string
+                city:
+                  type: string
+                state:
+                  type: string
+                postalCode:
+                  type: string
+                country:
+                  type: string
+                  description: ISO 3166-1 alpha-2 country code.
+              required:
+                - line1
+                - city
+                - state
+                - postalCode
+                - country
+            label:
+              type: object
+              description: Optional return label and tracking details.
+              properties:
+                trackingNumber:
+                  type: string
+                  description: Carrier tracking number.
+                carrier:
+                  type: string
+                  description: Carrier name.
+                trackingUrl:
+                  type: string
+                  description: Public tracking URL.
+                postageLabelUrl:
+                  type: string
+                  description: Postage label URL.
+                formLabelUrl:
+                  type: string
+                  description: Commercial or form label URL.
+                originalShipmentId:
+                  type: string
+                  description: Provider shipment identifier to reference.
+              required:
+                - trackingNumber
+            notes:
+              type: string
+              description: Internal merchant-side notes.
+          required:
+            - provider
+            - externalOrderId
+            - items
+            - shippingAddress
+        options:
+          type: object
+          description: Options controlling side effects of the return creation.
+          properties:
+            createExternalRMAs:
+              type: boolean
+              description: Whether to create RMAs with external integrations (e.g. ShipBob). Defaults to false.
+              default: false
+      required:
+        - data
+    create-return-response.schema:
+      type: object
+      description: Create return response body.
+      properties:
+        return:
+          $ref: '#/components/schemas/return-read.schema'
+        externalRMAResponses:
+          type: array
+          items:
+            type: object
+            properties:
+              integrationProvider:
+                type: string
+                description: Name of the external integration provider.
+              success:
+                type: boolean
+                description: Whether external RMA creation succeeded.
+              errorCode:
+                type: string
+                description: Provider error code when external RMA creation fails.
+              errorMessage:
+                type: string
+                description: Provider error message when external RMA creation fails.
+            required:
+              - integrationProvider
+              - success
+      required:
+        - return
+        - externalRMAResponses
     storefront-event.schema:
       additionalProperties: true
       description: Shopify pixel event for storefront tracking.

package/package.json

@@ -31,5 +31,5 @@
       ]
     }
   },
-  "version": "2.2.416"
+  "version": "2.2.423"
 }