Canal returns API

openapi: 3.0.3
info:
  title: Rokt Catalog csv returns API
  version: 1.0.1
  description: Integrate with Rokt Catalog
servers:
- url: https://api.shopcanal.com/platform
  description: Rokt Catalog Storefront Public API
tags:
- name: returns
paths:
  /returns/:
    get:
      operationId: returns_list
      description: '

        Retrieve a paginated list of return requests associated with the authenticated store, reflecting its role.


        - **If called by a Storefront:** Returns `ReturnRequest` records initiated *by* this Storefront for orders placed on their platform.


        - **If called by a Supplier:** Returns `ReturnRequest` records received *from* connected Storefronts for orders the Supplier fulfilled.


        **Filtering:** You can filter the list by `status` using a query parameter (e.g., `?status=OPEN` or `?status=CLOSED`).


        **Response (`ReturnSerializer`, paginated):** Includes details for each return request: `id`, `name`, `rma`, associated `order_id`, `status` (''OPEN'' or ''CLOSED''), `return_line_items` (with quantities, reasons), `reverse_deliveries` (tracking info), and timestamps.


        Pagination is cursor-based (`PlatformPagination`). Ordering is available on `created_at` and `updated_at`, defaulting to `-created_at`.


        '
      parameters:
      - name: ordering
        required: false
        in: query
        description: Which field to use when ordering the results.
        schema:
          type: string
      - name: cursor
        required: false
        in: query
        description: The pagination cursor value.
        schema:
          type: string
      - in: query
        name: status
        schema:
          type: string
          enum:
          - closed
          - open
        description: Filter returns by status
      tags:
      - returns
      security:
      - platformAppId: []
        platformAppToken: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedReturnList'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: ''
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: ''
    post:
      operationId: returns_create
      description: "\n**[Storefront Only]** Initiate a return process for items purchased in a Rokt Catalog-facilitated order.\n\n**Request Body (`ReturnCreateSerializer`):**\n\n- `order_id` (UUID, required): The Catalog ID of the original Storefront order containing the items to be returned.\n\n- `name` (string, required): A unique identifier for this return request (e.g., your system's RMA number).\n\n- `rma` (string, optional): An alternative return merchandise authorization identifier.\n\n- `return_line_items` (list, required): A list of objects, each specifying:\n\n  - `line_item_id` (UUID, required): The Catalog ID of the *Storefront's* line item record to be returned.\n\n  - `quantity` (integer, required): The quantity of this line item being returned.\n\n  - `return_reason` (string, optional): A code or description for the return reason.\n\n  - `customer_note` (string, optional): Any notes provided by the customer.\n\n- `reverse_deliveries` (list, optional): Allows providing initial return shipping tracking information (see `ReverseDeliveryCreateSerializer`) within the same request.\n\n**Process:**\n\n1. **Validation:** Checks if the order and line items exist, belong to the Storefront, and if the requested return quantities are valid (e.g., not exceeding fulfilled quantity). Acquires a lock on the order.\n\n2. **Create Storefront Return Request:** Creates the primary return request record associated with the Storefront's order in Rokt Catalog.\n\n3. **Create Initial Tracking (Optional):** If `reverse_deliveries` are provided, creates associated return tracking records.\n\n4. **Dispatch to Suppliers (Async):** Triggers an **asynchronous** task to create corresponding return request records for each relevant Supplier involved in the returned line items. These Supplier return requests are linked back to the Storefront's request.\n\n**Error Handling:** Returns `400 Bad Request` for validation errors (e.g., invalid quantity, bad IDs). Returns `500 Internal Server Error` for unexpected issues.\n\n**Response:** On success, returns `201 Created` with the details of the newly created **Storefront** return request (`ReturnSerializer`).\n\n"
      tags:
      - returns
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReturnCreate'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ReturnCreate'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ReturnCreate'
        required: true
      security:
      - platformAppId: []
        platformAppToken: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Return'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: ''
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: ''
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: ''
  /returns/{id}/:
    get:
      operationId: returns_retrieve
      parameters:
      - in: path
        name: id
        schema:
          type: string
        required: true
      tags:
      - returns
      security:
      - platformAppId: []
        platformAppToken: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Return'
          description: ''
  /returns/{id}/close/:
    post:
      operationId: returns_close_create
      description: '

        **[Supplier Only]** Mark a return request that your Supplier account received from a Storefront as ''CLOSED''.


        Identify the return request by its Rokt Catalog `ID` (UUID) provided in the URL path.


        **Use Case:** This endpoint should typically be called by the Supplier once they have received the physical returned items from the customer/Storefront and completed their internal processing (inspection, restocking, etc.).


        **Action:** Sets the `status` field of the **Supplier''s** return request record in Catalog to `CLOSED`.


        **Important Limitation:** This action **only** updates the status of the Supplier''s return record. It **does not** automatically update the status of the original Storefront''s return request, nor does it trigger any notifications or refunds. Subsequent actions, such as initiating a refund using the `/refunds/` endpoint, might be required based on the agreed return policy and workflow.


        **Permissions:** Requires the request to be authenticated as the Supplier associated with the return request. Attempting to close a return belonging to another shop results in `403 Forbidden`.


        A successful update returns `200 OK` with the updated details of the **Supplier''s** return request (`ReturnSerializer`), showing the status as ''CLOSED''.


        '
      parameters:
      - in: path
        name: id
        schema:
          type: string
        required: true
      tags:
      - returns
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Return'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Return'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Return'
        required: true
      security:
      - platformAppId: []
        platformAppToken: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Return'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: ''
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: ''
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: ''
  /returns/{id}/update_tracking/:
    post:
      operationId: returns_update_tracking_create
      description: '

        **[Storefront Only]** Add or update the tracking information for the shipment returning items back to the Supplier(s). Identify the specific return request using its Rokt Catalog `ID` (UUID) in the URL path.


        **Request Body (`ReverseDeliveryCreateSerializer`):**


        - `carrier_name` (string, optional): Name of the shipping carrier (e.g., ''USPS'', ''FedEx'').


        - `tracking_number` (string, optional): The tracking number for the return shipment.


        - `tracking_url` (string, optional): A direct URL to track the shipment.


        - `shipping_label_file_url` (string, optional): URL to a downloadable shipping label file (e.g., PDF).


        - `shipping_label_created_at` (datetime string, optional): Timestamp when the label was created.


        **Process:**


        1. **Validation:** Checks if the return request exists and belongs to the Storefront.


        2. **Create Storefront Return Tracking:** Creates a return tracking record containing the provided tracking/label info and associates it with the Storefront''s return request.


        3. **Sync to Suppliers (Sync):** This **synchronously** attempts to add the same return tracking information to the corresponding return request records on the Supplier side(s).


        **Response:** Returns `200 OK` with the updated details of the **Storefront''s** return request (`ReturnSerializer`), now including the added return tracking information.


        '
      parameters:
      - in: path
        name: id
        schema:
          type: string
        required: true
      - name: ordering
        required: false
        in: query
        description: Which field to use when ordering the results.
        schema:
          type: string
      - name: cursor
        required: false
        in: query
        description: The pagination cursor value.
        schema:
          type: string
      tags:
      - returns
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReverseDeliveryCreate'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ReverseDeliveryCreate'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ReverseDeliveryCreate'
      security:
      - platformAppId: []
        platformAppToken: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedReturnList'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: ''
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: ''
components:
  schemas:
    ReverseDelivery:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        carrier_name:
          type: string
          nullable: true
          maxLength: 100
        tracking_number:
          type: string
          nullable: true
          maxLength: 100
        tracking_url:
          type: string
          format: uri
          nullable: true
          maxLength: 200
        shipping_label_file_url:
          type: string
          format: uri
          nullable: true
          maxLength: 1279
      required:
      - id
    ReturnLineItem:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        line_item_id:
          type: string
          format: uuid
        quantity:
          type: integer
          maximum: 2147483647
          minimum: -2147483648
        customer_note:
          type: string
          nullable: true
          maxLength: 300
        return_reason:
          $ref: '#/components/schemas/ReturnReasonEnum'
        return_reason_note:
          type: string
          nullable: true
          maxLength: 255
      required:
      - id
      - line_item_id
      - quantity
    ReturnReasonEnum:
      enum:
      - color
      - defective
      - not_as_described
      - other
      - size_too_large
      - size_too_small
      - style
      - unknown
      - unwanted
      - wrong_item
      type: string
      description: '* `color` - color

        * `defective` - defective

        * `not_as_described` - not_as_described

        * `other` - other

        * `size_too_large` - size_too_large

        * `size_too_small` - size_too_small

        * `style` - style

        * `unknown` - unknown

        * `unwanted` - unwanted

        * `wrong_item` - wrong_item'
    CreateReturnLineItem:
      type: object
      properties:
        line_item_id:
          type: string
          format: uuid
        quantity:
          type: integer
        customer_note:
          type: string
          nullable: true
        return_reason:
          $ref: '#/components/schemas/ReturnReasonEnum'
      required:
      - line_item_id
      - quantity
      - return_reason
    ReverseDeliveryCreate:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        carrier_name:
          type: string
          nullable: true
          maxLength: 100
        tracking_number:
          type: string
          nullable: true
          maxLength: 100
        tracking_url:
          type: string
          format: uri
          nullable: true
          maxLength: 200
        shipping_label_file_url:
          type: string
          format: uri
          nullable: true
          maxLength: 1279
      required:
      - id
    Return:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        order:
          type: string
          format: uuid
        return_line_items:
          type: array
          items:
            $ref: '#/components/schemas/ReturnLineItem'
        status:
          $ref: '#/components/schemas/Status602Enum'
        name:
          type: string
          nullable: true
          maxLength: 501
        total_return_line_items:
          type: integer
          maximum: 32767
          minimum: -32768
          description: The sum of all return line item quantities for the return.
        created_at:
          type: string
          format: date-time
          readOnly: true
        updated_at:
          type: string
          format: date-time
          readOnly: true
        tracking:
          type: array
          items:
            $ref: '#/components/schemas/ReverseDelivery'
        rma:
          type: string
          nullable: true
          description: '"Return merchandise authorization" -- used as reference number for SK to SUP comms'
          maxLength: 501
      required:
      - created_at
      - id
      - order
      - return_line_items
      - total_return_line_items
      - tracking
      - updated_at
    PaginatedReturnList:
      type: object
      required:
      - results
      properties:
        next:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?cursor=cD00ODY%3D"
        previous:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?cursor=cj0xJnA9NDg3
        results:
          type: array
          items:
            $ref: '#/components/schemas/Return'
    Error:
      type: object
      properties:
        message:
          type: string
        detail: {}
    Status602Enum:
      enum:
      - canceled
      - closed
      - declined
      - open
      - requested
      type: string
      description: '* `canceled` - canceled

        * `closed` - closed

        * `declined` - declined

        * `open` - open

        * `requested` - requested'
    ReturnCreate:
      type: object
      properties:
        order_id:
          type: string
          format: uuid
        return_line_items:
          type: array
          items:
            $ref: '#/components/schemas/CreateReturnLineItem'
        tracking:
          $ref: '#/components/schemas/ReverseDeliveryCreate'
        name:
          type: string
          nullable: true
        status:
          allOf:
          - $ref: '#/components/schemas/Status602Enum'
          readOnly: true
          default: open
        rma:
          type: string
      required:
      - order_id
      - return_line_items
      - status
      - tracking
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
    platformAppId:
      type: apiKey
      in: header
      name: X-CANAL-APP-ID
    platformAppToken:
      type: apiKey
      in: header
      name: X-CANAL-APP-TOKEN