Riskified Returns API

openapi: 3.2.0
info:
  version: 1.0.0
  title: 'Policy Protect: Refunds Returns API'
servers:
- url: https://api-sandbox.riskified.com/policy/v2
  description: Sandbox
- url: https://api.riskified.com/policy/v2
  description: Production
tags:
- name: Returns
paths:
  /claim_update:
    post:
      summary: Update Claim
      tags:
      - Returns
      parameters:
      - $ref: '#/components/parameters/RiskifiedShopDomain'
      - $ref: '#/components/parameters/RiskifiedSignature'
      - $ref: '#/components/parameters/ContentType'
      - $ref: '#/components/parameters/Accept'
      description: The /claim_update endpoint is used to update Riskified regarding the claim - specifically in regards to the return shipment back to the merchant. This endpoint will not trigger claim analysis. Riskified's acknowledgement response to this endpoint is returned synchronously.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClaimUpdateRequest'
            examples:
              update_claim_example:
                $ref: '#/components/examples/update_claim_example'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClaimUpdateResponse'
              examples:
                update_claim_response_example:
                  $ref: '#/components/examples/update_claim_response_example'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response_messages'
              examples:
                bad_request:
                  value:
                    error:
                      messages:
                      - JSON malformed - missing 'tracking_numbers' field
                      - JSON malformed - 'return_shipping' field in wrong format
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401_response'
              examples:
                create_unauthorized_response_401:
                  $ref: '#/components/examples/create_unauthorized_response_401_example'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_with_code'
              examples:
                not_found:
                  value:
                    error:
                      statusCode: 404
                      message: Claim ABC-DEF-123 not found - unable to update
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_with_code'
              examples:
                too_many_requests:
                  value:
                    error:
                      statusCode: 429
                      message: Too many requests. Please try again later.
      operationId: postClaimUpdate
      x-operation-id-source: derived
components:
  examples:
    update_claim_response_example:
      summary: Example of a Claim Update Response
      value:
        claim:
          id: claim123
    create_unauthorized_response_401_example:
      summary: Unauthorized
      value:
        code: 401
        error:
          message: Missing HMAC configuration
          error: Unauthorized
          statusCode: 401
    update_claim_example:
      summary: Example of a Claim Update Request
      value:
        claim:
          id: '53953819'
          line_items:
          - event_type: inspection
            order_id: '450789469'
            item_id: 3AF0F17A323D4_1
            sku: 3AF0F17A323D4
            inspection:
              inspected_at: '2020-07-14T10:36:04-05:00'
              location: warehouse
              location_id: '3458972'
              condition: second_quality
          - event_type: label_scan
            order_id: '450789469'
            item_id: 3AF0F17A323D4_2
            sku: 3AF0F17A323D4
            return_shipping:
              tracking_numbers: '[REDACTED_PHONE_NUMBER_1]'
              label_created_at: '2020-07-08T19:05:40-05:00'
              scanned_at: '2020-07-09T13:20:34-05:00'
              arrived_at: '2020-07-14T14:48:16-05:00'
              tracking_company: UPS
              weight: '4030.54'
              weight_unit: grams
              is_verified: false
              address:
                address1: 55 UPS Drive
                address2: ''
                country: United States
                country_code: US
                city: Louisville
                province: Kentucky
                province_code: KY
                zip: '40202'
        note: return claim
  schemas:
    ReturnShipping:
      type: object
      properties:
        tracking_numbers:
          type: string
          description: The return shipping number, provided by the shipping company.
        scanned_at:
          type: string
          format: date-time
          description: The date and time (ISO 8601) that the package was scanned (picked up) by the carrier.
        label_created_at:
          type: string
          format: date-time
          description: The date and time (ISO 8601) that the return shipping label was created.
        arrived_at:
          type: string
          format: date-time
          description: The date and time (ISO 8601) that the package has arrived to the store/warehouse.
        tracking_company:
          type: string
          description: The name of the shipping company.
        weight:
          type: number
          format: float
          description: The package weight in grams or ounces.
        weight_unit:
          type: string
          enum:
          - grams
          - ounces
          description: The unit of measure for the weight.
        is_verified:
          type: boolean
          description: Indication of whether the content of the box was physically inspected/verified at the time of scan.
        address:
          $ref: '#/components/schemas/Address'
          description: The address of the drop-off location.
      required:
      - tracking_numbers
    ClaimUpdateResponse:
      type: object
      properties:
        claim:
          $ref: '#/components/schemas/ClaimOnlyId'
    ClaimUpdate:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the claim.
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/LineItemUpdate'
          description: An array of line item objects, each one containing information about a unit of an item in the claim.
        note:
          type: string
          description: A note attached to the claim.
      required:
      - id
      - line_items
    Address:
      type: object
      properties:
        first_name:
          type: string
          description: The first name of the person associated with the address.
        last_name:
          type: string
          description: The last name of the person associated with the address.
        address1:
          type: string
          description: The street name of the address.
        country:
          type: string
          description: The name of the country address.
        country_code:
          type: string
          description: The 2 letter country code (ISO 3166-1 alpha-2) of the country address.
        phone:
          type: string
          description: The phone number at the address.
        city:
          type: string
          description: The city of the address.
        zip:
          type: string
          description: The zip or postal code of the address.
        address2:
          type: string
          description: An optional additional field for the street address.
        company:
          type: string
          description: '**(Conditional Requirement)** Required if the address is associated to a company. The company of the person associated with the address.'
        additional_phone:
          type: string
          description: Additional phone number at the address.
        verified_phone:
          type: boolean
          description: Indicates whether the provided phone number was verified.
        province:
          type: string
          description: The name of the state or province of the address.
        province_code:
          type: string
          description: The two-letter ISO 3166-2 alpha-2 code for the state or province of the address.
        neighborhood:
          type: string
          description: The district or city division of the address. The neighborhood should be provided if used in a country’s official postal addresses. Examples of this include the Colonia in Mexico or Bairro in Brazil.
        latitude:
          type: number
          format: float
          description: The latitude coordinates of the address.
        longitude:
          type: number
          format: float
          description: The longitude coordinates of the address.
        id:
          type: string
          description: '**(Conditional Requirement)** unique ID, is required in case of multiple shipping addresses.'
      required:
      - first_name
      - last_name
      - address1
      - country
      - country_code
      - phone
      - city
      - zip
      - province
    error_with_code:
      type: object
      properties:
        statusCode:
          type: string
          description: Error code
        message:
          type: string
          description: Error message
    ClaimUpdateRequest:
      type: object
      properties:
        claim:
          $ref: '#/components/schemas/ClaimUpdate'
    LineItemUpdate:
      type: object
      properties:
        order_id:
          type: string
          description: The unique identifier for the order which is associated with the claim.
        sku:
          type: string
          description: The sku of the item in the fulfillment.
        item_id:
          type: string
          description: The unique identifier of the individual line item object in the claim/order.
        requested_action:
          type: string
          enum:
          - store_credit
          - refund
          - reshipment
          - exchange
          - physical_gift_card
          - none
          description: '**(Conditional Requirement)** The action requested by the customer. The field is required to be provided either in /claim_create or in /claim_update.'
        return_deadline:
          type: string
          format: date-time
          description: The date and time (ISO 8601) of the return deadline for the individual product.
        return_requested:
          type: boolean
          description: States whether the item is expected to be returned back to the merchant.
        event_type:
          type: string
          description: Where the item is in the claim/return lifecycle.
          enum:
          - label_scan
          - inspection
        return_shipping:
          $ref: '#/components/schemas/ReturnShipping'
          description: 'An object containing information regarding the return shipment back to the merchant. Required when event_type: label_scan.'
        inspection:
          $ref: '#/components/schemas/Inspection'
          description: 'An object containing information regarding item inspection. Required when event_type: inspection.'
      required:
      - order_id
      - sku
      - event_type
    ClaimOnlyId:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the claim.
    Inspection:
      type: object
      properties:
        condition:
          type: string
          enum:
          - pristine
          - second_quality
          - poor
          - fake
          - missing
          - valid_complaint
          description: The condition of the item at time of inspection.
        external_condition:
          type: string
          description: The condition of the item at time of inspection as recorded in the merchant's system.
        inspected_at:
          type: string
          format: date-time
          description: The date and time (ISO 8601) when the item was inspected.
        location:
          type: string
          enum:
          - in_store
          - warehouse
          - third_party
          description: The type of location where the item was inspected.
        location_id:
          type: string
          description: The ID of the store/warehouse where the item was inspected.
        note:
          type: string
          description: Free text or note added to claim as part of the inspection process.
      required:
      - condition
      - location
      - inspected_at
    error_response_messages:
      type: object
      properties:
        messages:
          type: array
          items:
            type: string
    401_response:
      type: object
      properties:
        code:
          type: string
          example: '401'
        error:
          type: object
          properties:
            message:
              type: string
              example: Missing HMAC configuration
            error:
              type: string
              example: Unauthorized
            statusCode:
              type: string
              example: 401
  parameters:
    Accept:
      name: accept
      in: header
      required: true
      schema:
        type: string
        enum:
        - application/vnd.riskified.com; version=2
      description: 'Specify the version of the API to target. For example, to target the latest version of the API, use the following: `application/vnd.riskified.com; version=2`'
    RiskifiedShopDomain:
      name: x-riskified-shop-domain
      in: header
      required: true
      schema:
        type: string
        example: merchant.example.com
      description: The merchant shop domain registered with Riskified.
    RiskifiedSignature:
      name: x-riskified-hmac-sha256
      in: header
      required: true
      schema:
        type: string
        example: b1946ac92492d2347c6235b4d2611184
      description: 'Verification hash for the Request.

        Generated by performing an SHA256 encryption on the request''s POST body and calculating the HMAC hash of the result using your Riskified authentication token.

        Please use UTF8 encoding.'
    ContentType:
      name: content_type
      in: header
      required: true
      schema:
        type: string
        enum:
        - application/json
      description: 'As payloads are sent to Riskified in JSON format, value should be: `application/json`'
x-samples-languages:
- json
- shell
- javascript
- python
- node
x- explorer-enabled: false
x-provenance:
  method: searched
  source: https://developers.riskified.com/reference
  harvested: '2026-10-14'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://developers.riskified.com/reference/refunds-claim_create.md
  - https://developers.riskified.com/reference/refunds-claim_decision.md
  - https://developers.riskified.com/reference/returns-claim_create.md
  - https://developers.riskified.com/reference/returns-claim_decision.md
  - https://developers.riskified.com/reference/returns-claim_update.md
  merge:
    pages: 5
    deduped: 48
    conflicts_kept_first: 4