Whiplash Merchandising consumer_returns API

openapi: 3.2.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:
    ApiV2EntitiesResult:
      type: object
      title: V2
      properties:
        result:
          type: string
          description: the request result
      additionalProperties: false
    PutApiV2ConsumerReturnsIdRequest:
      type: object
      properties:
        sender:
          type: string
          description: the consumer return sender
        eta:
          type: string
          format: date-time
          description: the consumer return estimated arrival date
        tracking:
          type: string
          description: the tracking number of the consumer return
        notes_by_customer:
          type: string
          description: notes by customer
        shipping_label_url:
          type: string
          description: url of the shipping label
        total_boxes:
          type: integer
          format: int32
          description: total number of boxes in the consumer return
        shipping_method_text:
          type: string
          description: the method of shipping for the consumer return
        carrier:
          type: string
          description: shipping carrier
        requires_label:
          type: boolean
          description: does this consumer return require a label?
        ship_3rdparty_cost:
          type: string
          description: 3rd party cost for the consumer return
        reference:
          type: string
          description: purchase order number or other human readable token to another system
    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
    ApiV2EntitiesPackage:
      type: object
      title: V2
      properties:
        id:
          type: integer
          format: int32
          description: the package id
        order_id:
          type:
          - integer
          - 'null'
          format: int32
          description: the package order id
        shipped_on:
          type:
          - string
          - 'null'
          format: date-time
          description: the package shipped on date and time
        ship_actual_cost:
          type:
          - string
          - 'null'
          description: the package shipping cost
        actual_weight:
          type:
          - string
          - 'null'
          description: the package weight (in ounces)
        actual_width:
          type:
          - string
          - 'null'
          description: the package width (in inches)
        actual_height:
          type:
          - string
          - 'null'
          description: the package height (in inches)
        actual_length:
          type:
          - string
          - 'null'
          description: the package length (in inches)
        actual_dimensional_weight:
          type:
          - string
          - 'null'
          description: the package dimensional weight (in ounces)
        tracking:
          type:
          - string
          - 'null'
          description: the package tracking number
        tracking_link:
          type: string
          description: the package tracking link
        order_item_ids:
          type: array
          items:
            type: integer
            format: int32
        created_at:
          type:
          - string
          - 'null'
          format: date-time
          description: the package creation date and time
        updated_at:
          type:
          - string
          - 'null'
          format: date-time
          description: the package last update date and time
        ucc128:
          type:
          - string
          - 'null'
          description: the UCC128 carton label for the package
        barcode_sscc18:
          type:
          - string
          - 'null'
          description: the SSCC18 package identifier
        ship_actual_currency:
          type:
          - string
          - 'null'
          description: currency used for this package
        manifest_id:
          type:
          - integer
          - 'null'
          format: int32
          description: the package manifest id
        batch_id:
          type:
          - integer
          - 'null'
          format: int32
          description: the package batch id (staff only)
        shipping_label_url:
          type:
          - string
          - 'null'
          description: the package shipping label url (staff only)
        shipment_id:
          type:
          - string
          - 'null'
          description: the package easypost shipment id (staff only)
        scan_form_url:
          type:
          - string
          - 'null'
          description: the package scan form url (staff only)
        shipment_created_at:
          type:
          - string
          - 'null'
          format: date-time
          description: the package easypost shipment creation date and time (staff only)
        shipment_updated_at:
          type:
          - string
          - 'null'
          format: date-time
          description: the package easypost shipment last update date and time (staff only)
        contents_label_printed_at:
          type:
          - string
          - 'null'
          format: date-time
          description: when the contents label was last printed (staff only)
        shipping_label_printed_at:
          type:
          - string
          - 'null'
          format: date-time
          description: when the shipping label was last printed (staff only)
        scanned_to_pallet_at:
          type:
          - string
          - 'null'
          format: date-time
          description: when the package was scanned to a pallet (staff only)
        pallet_id:
          type:
          - integer
          - 'null'
          format: int32
          description: the pallet id this package is on (staff only)
      additionalProperties: false
    ApiSharedEntitiesApiError:
      type: object
      title: Shared
      properties:
        message:
          type: string
          description: error message
      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 street address 3
        billing_city:
          type:
          - string
          - 'null'
          description: the order billing city
        billing_state:
          type:
          - string
          - 'null'
          description: the order billing state
        billing_zip:
          type:
          - string
          - 'null'
          description: the order billing zip
        billing_country:
          type:
          - string
          - 'null'
          description: the order billing country
        billing_phone:
          type:
          - string
          - 'null'
          description: the order billing phone number
        billed:
          type:
          - boolean
          - 'null'
          description: has the order been billed?
        do_not_bill:
          type: boolean
          description: do not bill for the order? (staff only)
        billing_name:
          type:
          - string
          - 'null'
          description: the order billing name
        first_name:
          type:
          - string
          - 'null'
          description: the first name of the person the order is being shipped to
        last_name:
          type:
          - string
          - 'null'
          description: the last name of the person the order is being shipped to
        full_name:
          type:
          - string
          - 'null'
          description: the full name of the person the order is being shipped to
        shipping_name:
          type:
          - string
          - 'null'
          description: the order shipping name
        shipping_company:
          type:
          - string
          - 'null'
          description: the order shipping company
        shipping_address_1:
          type:
          - string
          - 'null'
          description: the order shipping street address 1
        shipping_address_2:
          type:
          - string
          - 'null'
          description: the order shipping street address 2
        shipping_city:
          type:
          - string
          - 'null'
          description: the order shipping city
        shipping_state:
          type:
       

# --- 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