Channable Returns API

openapi: 3.2.0
info:
  title: Channable order connection Returns API
  description: '# Introduction


    Welcome to the Channable API __v1__.'
  version: v1
  x-logo:
    url: https://www.channable.com/_next/image?url=https%3A%2F%2Fmedia.graphassets.com%2FcntRnbAcSrCmS1wLTWrb&w=256&q=75
tags:
- name: Returns
paths:
  /v1/companies/{company_id}/projects/{project_id}/returns:
    get:
      tags:
      - Returns
      summary: All Returns
      description: 'This endpoint retrieves all returns for a given project, sorted from most recent to oldest.

        Optionally, you can pass query parameters to customize the query and response content.


        **Example usage**


        Suppose the following scenario for a given project of yours:

        - The project contains the returns `o1`, `o2`, `o3`, and `o4` (from oldest to most recent)

        - `o1` and `o4` are searchable by the term `t`

        - `o3` is searchable by the term `tE`


        | Request parameters | Response

        | ------------- | -----------

        | _none_ | `{"returns": [o4, o3, o2, o1], "total": 4}`

        | `?limit=2` | `{"returns": [o4, o3], "total": 2}`

        | `?offset=4` | `{"returns": [], "total": 0}`

        | `?offset=1` | `{"returns": [o3, o2, o1], "total": 3}`

        | `?offset=1&limit=1` | `{"returns": [o3], "total": 1}`

        | `?offset=1&limit=2` | `{"returns": [o3, o2], "total": 2}`

        | `?search=t` | `{"returns": [o4, o1], "total": 2}`

        | `?search=tE` | `{"returns": [o3], "total": 1}`

        | `?start_date=2018-01-01` | `{"returns": [o4, o3, o2], "total": 3}`

        | `?start_date=2018-01-01&end_date=2018-02-28` | `{"returns": [o3, o2], "total": 2}`

        | `?last_modified_after=2018-02-29` | `{"returns": [o4], "total": 1}`'
      operationId: all_returns_companies__company_id__projects__project_id__returns_get
      parameters:
      - name: company_id
        in: path
        required: true
        schema:
          type: integer
          title: Company Id
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - name: download
        in: query
        required: false
        schema:
          type: boolean
          description: If true, a file download will be served
          default: false
          title: Download
        description: If true, a file download will be served
      - name: errors
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Errors
      - name: search
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            minLength: 1
          - type: 'null'
          description: Any text based search query
          title: Search
        description: Any text based search query
      - name: start_date
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: string
            format: date-time
          - type: 'null'
          title: Start Date
      - name: end_date
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: string
            format: date-time
          - type: 'null'
          title: End Date
      - name: retrieved_at_start
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: string
            format: date-time
          - type: 'null'
          title: Retrieved At Start
      - name: retrieved_at_end
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: string
            format: date-time
          - type: 'null'
          title: Retrieved At End
      - name: last_modified_after
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: string
            format: date-time
          - type: 'null'
          title: Last Modified After
      - name: last_modified_before
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: string
            format: date-time
          - type: 'null'
          title: Last Modified Before
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Max number of results in a single page.
          default: 100
          title: Limit
        description: Max number of results in a single page.
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Filter results starting from this offset.
          default: 0
          title: Offset
        description: Filter results starting from this offset.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecentReturns'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/companies/{company_id}/projects/{project_id}/anonymous_returns:
    get:
      tags:
      - Returns
      summary: Anonymized All Returns
      description: 'This endpoint is identical to `/returns`, but the returned return data has all personal

        identifiable information (PII) removed.


        See the docs of `/returns` for more info on how to query this endpoint.'
      operationId: anonymized_all_returns_companies__company_id__projects__project_id__anonymous_returns_get
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - name: search
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            minLength: 1
          - type: 'null'
          description: Any text based search query
          title: Search
        description: Any text based search query
      - name: start_date
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: string
            format: date-time
          - type: 'null'
          title: Start Date
      - name: end_date
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: string
            format: date-time
          - type: 'null'
          title: End Date
      - name: last_modified_after
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: string
            format: date-time
          - type: 'null'
          title: Last Modified After
      - name: last_modified_before
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: string
            format: date-time
          - type: 'null'
          title: Last Modified Before
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Max number of results in a single page.
          default: 100
          title: Limit
        description: Max number of results in a single page.
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Filter results starting from this offset.
          default: 0
          title: Offset
        description: Filter results starting from this offset.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnonymizedRecentReturns'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/companies/{company_id}/projects/{project_id}/returns/{return_id}:
    get:
      tags:
      - Returns
      summary: Single Return
      description: This endpoint retrieves a given return based on its id.
      operationId: single_return_companies__company_id__projects__project_id__returns__return_id__get
      parameters:
      - name: company_id
        in: path
        required: true
        schema:
          type: integer
          title: Company Id
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - name: return_id
        in: path
        required: true
        schema:
          type: integer
          title: Return Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleEfferentReturn'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/companies/{company_id}/projects/{project_id}/returns/test:
    post:
      tags:
      - Returns
      summary: Create Test Return
      description: This endpoint allows you to create one or more test returns within Channable.
      operationId: create_test_return_companies__company_id__projects__project_id__returns_test_post
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TestReturnBody'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestReturnResponse'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChannableErrorResponse'
          description: Bad Request
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChannableErrorResponse'
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChannableErrorResponse'
          description: Conflict
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/companies/{company_id}/projects/{project_id}/returns/{return_id}/status:
    post:
      tags:
      - Returns
      summary: Update Return Status
      description: 'This endpoint allows you to update a return status. We will then propagate the update to

        the involved marketplace.


        Depending of the return status the end customer does or does not get their money back.'
      operationId: update_return_status_companies__company_id__projects__project_id__returns__return_id__status_post
      parameters:
      - name: return_id
        in: path
        required: true
        schema:
          type: integer
          title: Return Id
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - name: company_id
        in: path
        required: true
        schema:
          type: integer
          title: Company Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChannableReturnsPayload'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateReturnStatusResponse'
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChannableErrorResponse'
          description: Conflict
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ChannableReturnsStatus:
      type: string
      enum:
      - new
      - accepted
      - rejected
      - repaired
      - keeps
      - exchanged
      - cancelled
      - manual
      - processing
      title: ChannableReturnsStatus
      description: 'A container for channable return status.


        Based on the enum values of `status` column in the returns table.'
    ResponseModel:
      properties:
        status:
          $ref: '#/components/schemas/ResponseModelStatus'
          title: Response Status
        message:
          type: string
          title: Message
        response:
          type: string
          title: Response
          default: ''
        id:
          anyOf:
          - type: string
          - type: 'null'
          title: Id
        data:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Data
          description: Data relevant to the specific response. This may vary by endpoint
      type: object
      required:
      - status
      - message
      title: ResponseModel
      description: A container for response model.
    TestReturnResponse:
      properties:
        status:
          type: string
          const: success
          title: Response Status
          default: success
        message:
          type: string
          title: Message
        data:
          anyOf:
          - items:
              $ref: '#/components/schemas/ResponseModel'
            type: array
          - type: 'null'
          title: Data
      type: object
      required:
      - message
      title: TestReturnResponse
    ResponseModelStatus:
      type: string
      enum:
      - success
      - error
      - warning
      - debug
      title: ResponseModelStatus
    AnonymizedRecentReturns:
      properties:
        total:
          type: integer
          title: Total
        error_count:
          type: integer
          title: Error Count
        returns:
          items:
            $ref: '#/components/schemas/AnonymizedEfferentReturn'
          type: array
          title: Anonymized Returns
      type: object
      required:
      - total
      - error_count
      - returns
      title: AnonymizedRecentReturns
    ChannableReturnsDataMeta:
      properties:
        channel_order_id:
          type: string
          title: Channel Order Id
        channel_order_id_internal:
          anyOf:
          - type: string
          - type: 'null'
          title: Channel Order Id Internal
        platform_order_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Platform Order Id
          description: The same id as the 'platform_id' in the original order. For Channable api order connections 'platform_id' is the Channable order id
        is_demo_return:
          type: boolean
          title: Is Demo Return
          default: false
        is_test_return:
          type: boolean
          title: Is Test Return
          default: false
        channel_return_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Channel Return Id
      type: object
      required:
      - channel_order_id
      title: ChannableReturnsDataMeta
    UpdateReturnStatusResponse:
      properties:
        status:
          type: string
          const: success
          title: Response Status
          default: success
        message:
          type: string
          title: Message
      type: object
      required:
      - message
      title: UpdateReturnStatusResponse
    AnonymizedEfferentReturnDataAddress:
      properties:
        city:
          anyOf:
          - type: string
          - type: 'null'
          title: City
        country_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Country Code
        company:
          anyOf:
          - type: string
          - type: 'null'
          title: Company
        region_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Region Code
      type: object
      title: AnonymizedEfferentReturnDataAddress
    AnonymizedEfferentReturnDataCustomer:
      properties:
        gender:
          type: string
          title: Gender
      type: object
      required:
      - gender
      title: AnonymizedEfferentReturnDataCustomer
    AnonymizedEfferentReturnDataItem:
      properties:
        id:
          anyOf:
          - type: string
          - type: 'null'
          title: Id
        gtin:
          anyOf:
          - type: string
          - type: 'null'
          title: Gtin
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        quantity:
          type: integer
          title: Quantity
        reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Reason
        delivery_period:
          anyOf:
          - type: string
          - type: 'null'
          title: Delivery Period
      type: object
      required:
      - quantity
      title: AnonymizedEfferentReturnDataItem
    EfferentReturn:
      properties:
        id:
          type: integer
          title: Id
        project_id:
          type: integer
          title: Project Id
        created:
          type: string
          format: date-time
          title: Created
        modified:
          type: string
          format: date-time
          title: Modified
        retrieved_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Retrieved At
        error:
          type: boolean
          title: Error
        platform_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Platform Id
        platform_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Platform Name
        channel_id:
          type: string
          title: Channel Id
        channel_name:
          type: string
          title: Channel Name
        log:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Log
        status:
          $ref: '#/components/schemas/ChannableReturnsStatus'
          title: Return Status
        data:
          additionalProperties: true
          type: object
          title: Data
        obfuscated:
          type: boolean
          title: Obfuscated
      type: object
      required:
      - id
      - project_id
      - created
      - modified
      - error
      - channel_id
      - channel_name
      - log
      - status
      - data
      - obfuscated
      title: EfferentReturn
    AnonymizedEfferentReturn:
      properties:
        id:
          type: integer
          title: Id
        project_id:
          type: integer
          title: Project Id
        created:
          type: string
          format: date-time
          title: Created
        modified:
          type: string
          format: date-time
          title: Modified
        retrieved_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Retrieved At
        error:
          type: boolean
          title: Error
        platform_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Platform Id
        platform_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Platform Name
        channel_id:
          type: string
          title: Channel Id
        channel_name:
          type: string
          title: Channel Name
        log:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Log
        status:
          $ref: '#/components/schemas/ChannableReturnsStatus'
          title: Return Status
        data:
          $ref: '#/components/schemas/AnonymizedEfferentReturnData'
          title: Anonymized Return Data
      type: object
      required:
      - id
      - project_id
      - created
      - modified
      - error
      - channel_id
      - channel_name
      - log
      - status
      - data
      title: AnonymizedEfferentReturn
      description: 'A return representation from any channel to any platform,

        but with all PII filtered out of the data.'
    ChannableApiReturnsStatus:
      type: string
      enum:
      - accepted
      - rejected
      - repaired
      - keeps
      - exchanged
      - cancelled
      title: ChannableApiReturnsStatus
      description: 'A container for channable api return status.

        This is similar to realtime2.models.returns.ChannableReturnsStatus but is missing a few

        statuses (new, manual, and processing).'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ChannableReturnsPayload:
      properties:
        status:
          $ref: '#/components/schemas/ChannableApiReturnsStatus'
      type: object
      required:
      - status
      title: ChannableReturnsPayload
      description: Model for data obtained from the Channable API return status update
    TestReturnBody:
      properties:
        order_id:
          type: integer
          title: Order Id
          description: The unique id of a Channable order object.
      type: object
      required:
      - order_id
      title: TestReturnBody
    AnonymizedEfferentReturnData:
      properties:
        item:
          $ref: '#/components/schemas/AnonymizedEfferentReturnDataItem'
          title: Anonymized Item
        address:
          $ref: '#/components/schemas/AnonymizedEfferentReturnDataAddress'
          title: Anonymized Address
        customer:
          $ref: '#/components/schemas/AnonymizedEfferentReturnDataCustomer'
          title: Anonymized Customer
        meta:
          anyOf:
          - $ref: '#/components/schemas/ChannableReturnsDataMeta'
          - type: 'null'
          title: Return Meta Data
      type: object
      required:
      - item
      - address
      - customer
      title: AnonymizedEfferentReturnData
    SingleEfferentReturn:
      properties:
        return:
          $ref: '#/components/schemas/EfferentReturn'
          title: Return
      type: object
      required:
      - return
      title: SingleEfferentReturn
      example:
        return:
          channel_id: '31234567'
          channel_name: bol
          created: '2017-02-09T12:39:48+00:00'
          data:
            address:
              address1: streetname 1
              address_supplement: ''
              city: cityname
              company: ''
              country_code: NL
              email: noreply@example.com
              first_name: Firstname
              house_number: '1'
              house_number_ext: ''
              last_name: Lastname
              region_code: ''
              street: streetname
              zip_code: 1234 AB
            customer:
              email: noreply@example.com
              first_name: Firstname
              gender: female
              last_name: Lastname
            item:
              comment: Some extra info
              delivery_period: ''
              gtin: '1234567890123'
              id: 123456-some-item
              quantity: 1
              reason: Not as pictured
              title: Product Title
            meta:
              channel_order_id: 123456-some-order
              channel_order_id_internal: ''
              channel_return_id: 123456-some-return
              platform_order_id: ABC9839833
          error: false
          id: 1
          log: []
          modified: '2017-02-09T12:39:48+00:00'
          obfuscated: false
          platform_id: '123456'
          platform_name: lightspeed
          project_id: 1
          retrieved_at: '2017-02-09T12:39:48+00:00'
          status: new
    ChannableErrorResponse:
      properties:
        status:
          type: string
          const: error
          title: Status
          default: error
        message:
          type: string
          title: Message
          description: A description about the given error
      type: object
      required:
      - message
      title: ChannableErrorResponse
      description: The standard Channable error response
    RecentReturns:
      properties:
        total:
          type: integer
          title: Total
        error_count:
          type: integer
          title: Error Count
        returns:
          items:
            $ref: '#/components/schemas/EfferentReturn'
          type: array
          title: Returns
      type: object
      required:
      - total
      - error_count
      - returns
      title: RecentReturns
      example:
        error_count: 0
        returns:
        - channel_id: '31234567'
          channel_name: bol
          created: '2017-02-09T12:39:48+00:00'
          data:
            address:
              address1: streetname 1
              address_supplement: ''
              city: cityname
              company: ''
              country_code: NL
              email: noreply@example.com
              first_name: Firstname
              house_number: '1'
              house_number_ext: ''
              last_name: Lastname
              region_code: ''
              street: streetname
              zip_code: 1234 AB
            customer:
              email: noreply@example.com
              first_name: Firstname
              gender: female
              last_name: Lastname
            item:
              comment: Some extra info
              delivery_period: ''
              gtin: '1234567890123'
              id: 123456-some-item
              quantity: 1
              reason: Not as pictured
              title: Product Title
            meta:
              channel_order_id: 123456-some-order
              channel_order_id_internal: ''
              channel_return_id: 123456-some-return
              platform_order_id: ABC9839833
          error: false
          id: 1
          log: []
          modified: '2017-02-09T12:39:48+00:00'
          obfuscated: false
          platform_id: '123456'
          platform_name: lightspeed
          project_id: 1
          retrieved_at: '2017-02-09T12:39:48+00:00'
          status: new
        total: 1
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError