Whiplash Merchandising consumer_returns API

openapi: 3.1.0
info:
  version: '2.0'
  title: Rydership bundle_items consumer_returns API
  description: 'The Rydership V2 API is open by invite only. Fill out request form <a href="https://help.whiplash.com/hc/en-us/requests/new?ticket_form_id=360001303092"> here</a>.

    <br>

    <a href="api.v2.html">V2 documentation</a>

    <br>

    <a href="api.v2-1.html">V2.1 documentation</a>

    '
  contact:
    name: Rydership Development Team
    email: tech@whiplash.com
    url: https://www.getwhiplash.com
  x-logo:
    url: https://wl-s3-assets.s3.amazonaws.com/rydership/RyderShip-horizontal-safe-padding.svg
    backgroundColor: '#FFFFFF'
    altText: RyderShip
servers:
- url: ''
  description: Base Path
tags:
- name: consumer_returns
  description: A ConsumerReturn represents goods coming back from an end consumer. It is a special form of Shipnotice, and is processed in much the same way.
paths:
  /api/v2/consumer_returns:
    get:
      operationId: GetApiV2ConsumerReturns
      tags:
      - consumer_returns
      summary: List all consumer returns
      description: Get all consumer returns
      parameters:
      - name: search
        in: query
        required: false
        schema:
          type: string
          description: 'JSON search string like {"attribute_eq": "Term"}'
      - name: fields
        in: query
        required: false
        schema:
          type: string
          description: Comma-separated list of fields to include in the response
      - name: sort
        in: query
        required: false
        schema:
          type: string
          description: 'A list of sort options (ex: name asc,created_at desc)'
      - name: page
        in: query
        required: false
        schema:
          type: integer
          format: int32
          description: Page of results to fetch
      - name: per_page
        in: query
        required: false
        schema:
          type: integer
          format: int32
          description: Number of results to return per page
      - name: page_total
        in: query
        required: false
        schema:
          type: boolean
          description: Include total count of results
      - name: page_links
        in: query
        required: false
        schema:
          type: boolean
          description: Include prev/next links in response headers
      responses:
        '200':
          description: Get all consumer returns
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ApiV2EntitiesConsumerReturn'
              examples:
                api.v2.consumer_return.all:
                  $ref: '#/components/examples/api.v2.consumer_return.all'
        '401':
          description: unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSharedEntitiesApiError'
        '403':
          description: forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSharedEntitiesApiError'
    post:
      operationId: PostApiV2ConsumerReturns
      tags:
      - consumer_returns
      summary: Create a consumer return
      description: Create a consumer return
      parameters: []
      responses:
        '201':
          description: Create a consumer return
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiV2EntitiesConsumerReturn'
              examples:
                api.v2.consumer_return.in_transit:
                  $ref: '#/components/examples/api.v2.consumer_return.in_transit'
        '401':
          description: unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSharedEntitiesApiError'
        '403':
          description: forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSharedEntitiesApiError'
        '409':
          description: conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSharedEntitiesApiError'
        '422':
          description: unprocessable_entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSharedEntitiesApiError'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV2ConsumerReturnsRequest'
  /api/v2/consumer_returns/bulk:
    post:
      operationId: PostApiV2ConsumerReturnsBulk
      tags:
      - consumer_returns
      summary: Create consumer_returns in bulk
      description: Create consumer_returns in bulk
      parameters: []
      responses:
        '201':
          description: Create consumer_returns in bulk
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ApiV2EntitiesResult'
              examples: null
        '401':
          description: unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSharedEntitiesApiError'
        '403':
          description: forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSharedEntitiesApiError'
        '409':
          description: conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSharedEntitiesApiError'
        '422':
          description: unprocessable_entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSharedEntitiesApiError'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV2ConsumerReturnsBulkRequest'
  /api/v2/consumer_returns/count:
    get:
      operationId: GetApiV2ConsumerReturnsCount
      tags:
      - consumer_returns
      summary: Count consumer returns
      description: Returns count of consumer returns
      parameters:
      - name: search
        in: query
        required: false
        schema:
          type: string
          description: 'JSON search string like {"attribute_eq": "Term"}'
      responses:
        '200':
          description: Returns count of consumer returns
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiV2EntitiesCount'
              examples: null
        '401':
          description: unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSharedEntitiesApiError'
        '403':
          description: forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSharedEntitiesApiError'
  /api/v2/consumer_returns/{id}:
    get:
      operationId: GetApiV2ConsumerReturnsId
      tags:
      - consumer_returns
      summary: Retrieve a consumer return
      description: Get a consumer return
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Get a consumer return
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiV2EntitiesConsumerReturn'
              examples:
                api.v2.consumer_return.in_transit:
                  $ref: '#/components/examples/api.v2.consumer_return.in_transit'
        '401':
          description: unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSharedEntitiesApiError'
        '403':
          description: forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSharedEntitiesApiError'
    put:
      operationId: PutApiV2ConsumerReturnsId
      tags:
      - consumer_returns
      summary: Update a consumer return
      description: Update a consumer return
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Update a consumer return
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiV2EntitiesConsumerReturn'
              examples:
                api.v2.consumer_return.in_transit:
                  $ref: '#/components/examples/api.v2.consumer_return.in_transit'
        '401':
          description: unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSharedEntitiesApiError'
        '403':
          description: forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSharedEntitiesApiError'
        '422':
          description: unprocessable_entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSharedEntitiesApiError'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutApiV2ConsumerReturnsIdRequest'
    delete:
      operationId: DeleteApiV2ConsumerReturnsId
      tags:
      - consumer_returns
      summary: Destroy a consumer return
      description: Destroy a consumer return
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '204':
          description: Successfully deleted
        '401':
          description: unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSharedEntitiesApiError'
        '403':
          description: forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSharedEntitiesApiError'
        '422':
          description: unprocessable_entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSharedEntitiesApiError'
  /api/v2/consumer_returns/{id}/meta_fields:
    get:
      operationId: GetApiV2ConsumerReturnsIdMetaFields
      tags:
      - consumer_returns
      summary: List meta fields
      description: Get the meta fields for a(n) ConsumerReturn
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      - name: associations
        in: query
        required: false
        schema:
          type: array
          description: Include meta fields for associations
          items:
            type: string
      responses:
        '200':
          description: Get the meta fields for a(n) ConsumerReturn
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSharedEntitiesMetaFields'
              examples: null
        '401':
          description: unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSharedEntitiesApiError'
        '403':
          description: forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSharedEntitiesApiError'
    put:
      operationId: PutApiV2ConsumerReturnsIdMetaFields
      tags:
      - consumer_returns
      summary: Set meta fields
      description: Update ConsumerReturn meta fields
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '204':
          description: Successfully updated
        '401':
          description: unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSharedEntitiesApiError'
        '403':
          description: forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSharedEntitiesApiError'
        '422':
          description: unprocessable_entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSharedEntitiesApiError'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutApiV2ConsumerReturnsIdMetaFieldsRequest'
components:
  schemas:
    ApiV2EntitiesReturnItem:
      type: object
      title: V2
      properties:
        id:
          type: integer
          format: int32
          description: the return item id
        item_id:
          type: integer
          format: int32
          description: the return item item id
        name:
          type: string
          description: item title/description
        sku:
          type: string
          description: item SKU
        price:
          type: string
          description: price paid for the returning item
        quantity:
          type: integer
          format: int32
          description: the number of returning items
        quantity_good:
          type: integer
          format: int32
          description: how many of this item arrived in acceptable condition
        quantity_damaged:
          type: integer
          format: int32
          description: how many of this item arrived in damaged condition
        description:
          type: string
          description: description of the item
        extended_description:
          type: string
          description: an extended description of the item
        return_action:
          type: string
          description: 'action to perform on item return '
        order_item_id:
          type: integer
          format: int32
          description: returning order order item id
        return_item_originator_id:
          type: integer
          format: int32
          description: the item originator id for the returning item
        originator_id:
          type: integer
          format: int32
          description: the order item originator id for the returning item
        lot_ids:
          type: array
          items:
            type: integer
            format: int32
        lot_numbers:
          type: array
          items:
            type: integer
            format: int32
      additionalProperties: false
    ApiV2EntitiesWholesaleItem:
      type: object
      title: V2
      properties:
        id:
          type: integer
          format: int32
          description: the wholesale item id
        order_item_id:
          type: integer
          format: int32
          description: the associated order item id
        line_no:
          type:
          - string
          - 'null'
          description: the line number
        item_alias:
          type:
          - string
          - 'null'
          description: the item alias
        item_color:
          type:
          - string
          - 'null'
          description: the item color
        item_size:
          type:
          - string
          - 'null'
          description: the item size
        vendor_part_number:
          type:
          - string
          - 'null'
          description: the vendor part number
        buyer_part_number:
          type:
          - string
          - 'null'
          description: the buyer part number
        consumer_package_code:
          type:
          - string
          - 'null'
          description: the consumer package code
        outer_pack_value:
          type:
          - string
          - 'null'
          description: the outer pack value
        inner_pack_value:
          type:
          - string
          - 'null'
          description: the inner pack value
        size_description:
          type:
          - string
          - 'null'
          description: the size description
        color_description:
          type:
          - string
          - 'null'
          description: the color description
        upc:
          type:
          - string
          - 'null'
          description: the UPC
        description:
          type:
          - string
          - 'null'
          description: the description
        style:
          type:
          - string
          - 'null'
          description: the style
        ean:
          type:
          - string
          - 'null'
          description: the EAN
        alternate_item_number:
          type:
          - string
          - 'null'
          description: the alternate item number
        alternate_barcode:
          type:
          - string
          - 'null'
          description: the alternate barcode
        alternate_sku:
          type:
          - string
          - 'null'
          description: the alternate SKU
        lot:
          type:
          - string
          - 'null'
          description: the lot
        ih_category:
          type:
          - string
          - 'null'
          description: the IH category
        created_at:
          type: string
          format: date-time
          description: the wholesale item creation date and time
        updated_at:
          type: string
          format: date-time
          description: the wholesale item last update date and time
      additionalProperties: false
    ApiSharedEntitiesMetaFields:
      type: object
      title: Shared
      properties:
        fields:
          type: object
          description: Hash of key/value pairs
        association_fields:
          type: object
          description: Included meta fields for associations
      additionalProperties: false
    PutApiV2ConsumerReturnsIdMetaFieldsRequest:
      type: object
      properties:
        fields:
          type: object
          description: Hash of key/value pairs
        association_fields:
          type: object
          description: Included meta fields for associations
    ApiV2EntitiesConsumerReturn:
      type: object
      title: V2
      properties:
        id:
          type: integer
          format: int32
          description: the consumer return id
        order_id:
          type:
          - integer
          - 'null'
          format: int32
          description: The whiplash id of the order from which an item is being returned
        customer_id:
          type:
          - integer
          - 'null'
          format: int32
          description: the consumer return customer id
        warehouse_id:
          type: integer
          format: int32
          description: the consumer return warehouse id
        sender:
          type:
          - string
          - 'null'
          description: the consumer return sender
        eta:
          type:
          - string
          - 'null'
          format: date-time
          description: the consumer return estimated arrival date
        status:
          type:
          - integer
          - 'null'
          format: int32
          description: status of the consumer return
        status_name:
          type: string
          description: the shipnotice status name
        received_by:
          type:
          - string
          - 'null'
          description: the name of the person who received the consumer return
        notes_by_whiplash:
          type:
          - string
          - 'null'
          description: notes by whiplash
        notes_by_customer:
          type:
          - string
          - 'null'
          description: notes by customer
        total_boxes:
          type:
          - integer
          - 'null'
          format: int32
          description: total number of boxes in the consumer return
        created_at:
          type:
          - string
          - 'null'
          format: date-time
          description: the consumer return creation date and time
        updated_at:
          type:
          - string
          - 'null'
          format: date-time
          description: the consumer return last update date and time
        arrived_at:
          type: string
          format: date-time
          description: the consumer return arrival date and time
        skip_images:
          type:
          - boolean
          - 'null'
          description: allow skipping of images for this consumer return?
        easypostable_id:
          type:
          - string
          - 'null'
          description: the ID of the easypost shipment or tracker
        easypostable_type:
          type:
          - string
          - 'null'
          description: the type of the easypost object (shipment or tracker)
        shipping_label_url:
          type:
          - string
          - 'null'
          description: url of the shipping label
        ship_actual_cost:
          type:
          - string
          - 'null'
          description: the consumer return actual cost of shipping
        shipping_method_text:
          type:
          - string
          - 'null'
          description: the method of shipping for the consumer return
        carrier:
          type: string
          description: shipping carrier
        tracking:
          type:
          - string
          - 'null'
          description: the tracking number of the consumer return
        type:
          type:
          - string
          - 'null'
          description: consumer return type (Shipnotice, ConsumerReturn)
        postage_billed:
          type:
          - boolean
          - 'null'
          description: was postage billed?
        handling_billed:
          type:
          - boolean
          - 'null'
          description: was handling billed?
        ship_3rdparty_cost:
          type:
          - string
          - 'null'
          description: 3rd party cost for the consumer return
        requires_label:
          type:
          - boolean
          - 'null'
          description: does this consumer return require a label?
        completed_at:
          type:
          - string
          - 'null'
          format: date-time
          description: the consumer return completion date and time
        ship_actual_currency:
          type:
          - string
          - 'null'
          description: currency used for this consumer return
        delivered_at:
          type:
          - string
          - 'null'
          format: date-time
          description: date when was the consumer return delivered
        due_at:
          type:
          - string
          - 'null'
          format: date-time
          description: date when the consumer return is due to be delivered
        reference:
          type:
          - string
          - 'null'
          description: purchase order number or other human readable token to another system
        exchange_order_id:
          type:
          - integer
          - 'null'
          format: int32
          description: the id of the exhange order
        originator:
          $ref: '#/components/schemas/ApiV2EntitiesOriginator'
        return_items:
          type: array
          items:
            $ref: '#/components/schemas/ApiV2EntitiesReturnItem'
        exchange_order:
          $ref: '#/components/schemas/ApiV2EntitiesOrder'
        order:
          $ref: '#/components/schemas/ApiV2EntitiesOrder'
        customer:
          $ref: '#/components/schemas/ApiV2EntitiesCustomerShallow'
        warehouse:
          $ref: '#/components/schemas/ApiV2EntitiesWarehouseShallow'
      additionalProperties: false
    ApiV2EntitiesOrder:
      type: object
      title: V2
      properties:
        id:
          type: integer
          format: int32
          description: the order id
        customer_id:
          type: integer
          format: int32
          description: the order customer id
        order_batch_id:
          type:
          - integer
          - 'null'
          format: int32
          description: the order batch id
        quote_id:
          type:
          - integer
          - 'null'
          format: int32
          description: the order quote id
        warehouse_id:
          type:
          - integer
          - 'null'
          format: int32
          description: the order warehouse id
        return_warehouse_id:
          type:
          - integer
          - 'null'
          format: int32
          description: the order return warehouse id
        shipping_method_id:
          type:
          - integer
          - 'null'
          format: int32
          description: the order shipping method id
        estimated_shipping_method_id:
          type:
          - integer
          - 'null'
          format: int32
          description: the estimated order shipping method id, if set to cheapest rate
        humanize_id:
          type: string
          description: the order humanized id
        status:
          type: integer
          format: int32
          description: 'the order status: 30 (Shipped Externally), 35 (Quote), 40 (Cancelled), 45 (Closed by Originator), 50 (Unpaid), 75 (Pending Return), 77 (Return Verified), 80 (Pre-Order), 90 (Paused), 95 (Insufficient Inventory), 100 (Processing), 120 (Printed), 140 (Pending Pick Confirmation), 150 (Picked), 155 (Prepacking in Progress), 160 (Packed), 200 (Label Scheduled for Purchase), 250 (Label Purchased), 300 (Shipped), 325 (Picked Up), 350 (Delivered), 375 (Return Expired), 380 (Replacement Cancelled), 400 (Returned Undeliverable), 410 (Replacement Requested), 430 (Exchanged), 450 (Refund Requested)'
          enum:
          - 30
          - 35
          - 40
          - 45
          - 50
          - 75
          - 77
          - 80
          - 90
          - 95
          - 100
          - 120
          - 140
          - 150
          - 155
          - 160
          - 200
          - 250
          - 300
          - 325
          - 350
          - 375
          - 380
          - 400
          - 410
          - 430
          - 450
          x-enum-varnames:
            ShippedExternally: 30
            Quote: 35
            Cancelled: 40
            ClosedByOriginator: 45
            Unpaid: 50
            PendingReturn: 75
            ReturnVerified: 77
            PreOrder: 80
            Paused: 90
            InsufficientInventory: 95
            Processing: 100
            Printed: 120
            PendingPickConfirmation: 140
            Picked: 150
            PrepackingInProgress: 155
            Packed: 160
            LabelScheduledForPurchase: 200
            LabelPurchased: 250
            Shipped: 300
            PickedUp: 325
            Delivered: 350
            ReturnExpired: 375
            ReplacementCancelled: 380
            ReturnedUndeliverable: 400
            ReplacementRequested: 410
            Exchanged: 430
            RefundRequested: 450
        status_name:
          type: string
          description: the order status name
        previous_status:
          type:
          - integer
          - 'null'
          format: int32
          description: the previous order status
        order_orig:
          type:
          - string
          - 'null'
          description: "the order original id (from the shop that sent whiplash the order)\n          Note: contains the global-e order id for any global-e order."
        package_label_reference:
          type:
          - string
          - 'null'
          description: "User-defined reference for shipping labels on packages.\n          Note: this field has a limit of 35 chars."
        level1_token:
          type:
          - string
          - 'null'
          description: the order level 1 token
        level2_token:
          type:
          - string
          - 'null'
          description: the order level 2 token
        workable_at:
          type:
          - string
          - 'null'
          format: date-time
          description: the date and time the order is workable
        skip_street_date:
          type:
          - boolean
          - 'null'
          description: skip street date for this order?
        due_at:
          type:
          - string
          - 'null'
          format: date-time
          description: the order due at date and time
        created_at:
          type:
          - string
          - 'null'
          format: date-time
          description: the order creation date and time
        updated_at:
          type:
          - string
          - 'null'
          format: date-time
          description: the order last update date and time
        meta_data:
          type:
          - string
          - 'null'
          description: meta data for this order as stringified JSON
        customer_provided_label_carrier:
          type:
          - string
          - 'null'
          description: the carrier on the customer provided label (for tracking purposes)
        purchase_order:
          type:
          - string
          - 'null'
          description: the purchase order this order
        order_type:
          type:
          - string
          - 'null'
          description: the order type
          enum:
          - retail
          - wholesale
          - direct_to_consumer
          - dropship
          - transfer
          - value_added_service
        batch_priority:
          type:
          - boolean
          - 'null'
          description: the order batch priority
        email:
          type:
          - string
          - 'null'
          description: the order shipping email
        address_verified:
          type:
          - boolean
          - 'null'
          description: is the order shipping address verified?
        items_updateable:
          type: boolean
          description: are the items in the order updateable
        skip_address_verification:
          type:
          - boolean
          - 'null'
          description: skip order shipping address verification?
        address_message:
          type:
          - string
          - 'null'
          description: the order address message
        scac:
          type:
          - string
          - 'null'
          description: the orders Standard Carrier Alpha Code number
        tms_id:
          type:
          - string
          - 'null'
          description: The Transport Management System ID for the order, if applicable
        tms_required:
          type:
          - boolean
          - 'null'
          description: Does the order require a Transport Management System ID
        shop_warehouse_ids:
          type: array
          items:
            type: integer
            format: int32
        shop_shipping_method_currency:
          type:
          - string
          - 'null'
          description: the order shop shipping method currency
        shop_created_at:
          type:
          - string
          - 'null'
          format: date-time
          description: the order shop creation date and time
        shop_updated_at:
          type:
          - string
          - 'null'
          format: date-time
          description: the order shop last update date and time
        shop_shipping_method_text:
          type:
          - string
          - 'null'
          description: "the order shop shipping method text\n          ge_standard = order uses global-e standard shipping method\n          ge_express = order uses global-e express shipping method"
        shop_shipping_method_price:
          type:
          - string
          - 'null'
          description: the order shop shipping method price
        billing_company:
          type:
          - string
          - 'null'
          description: the order billing company
        billing_address_1:
          type:
          - string
          - 'null'
          description: the order billing street address 1
        billing_address_2:
          type:
          - string
          - 'null'
          description: the order billing street address 2
        billing_address_3:
          type:
          - string
          - 'null'
          description: the order billing st

# --- truncated at 32 KB (169 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/whiplash-merchandising/refs/heads/main/openapi/whiplash-merchandising-consumer-returns-api-openapi.yml