ClaimUpdateRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/riskified/json-schema/riskified-claim-update-request-schema.json",
  "title": "ClaimUpdateRequest",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/riskified-returns-api-openapi.yml#/components/schemas/ClaimUpdateRequest",
  "type": "object",
  "properties": {
    "claim": {
      "$ref": "#/$defs/ClaimUpdate"
    }
  },
  "$defs": {
    "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"
      ]
    },
    "ClaimUpdate": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "The unique identifier for the claim."
        },
        "line_items": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/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"
      ]
    },
    "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"
      ]
    },
    "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": "#/$defs/ReturnShipping",
          "description": "An object containing information regarding the return shipment back to the merchant. Required when event_type: label_scan."
        },
        "inspection": {
          "$ref": "#/$defs/Inspection",
          "description": "An object containing information regarding item inspection. Required when event_type: inspection."
        }
      },
      "required": [
        "order_id",
        "sku",
        "event_type"
      ]
    },
    "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": "#/$defs/Address",
          "description": "The address of the drop-off location."
        }
      },
      "required": [
        "tracking_numbers"
      ]
    }
  }
}