--- title: "Create a Claim" method: POST path: "/claim_create" tags: ["Refunds"] --- # Create a Claim `POST /claim_create` ## Request - Base URL: `https://api-sandbox.riskified.com/policy/v2` - URL: `https://api-sandbox.riskified.com/policy/v2/claim_create` - Auth: none declared. Required headers: `x-riskified-shop-domain`, `x-riskified-hmac-sha256`, `content_type`, `accept` The /claim_create endpoint is used to request that Riskified analyze a claim for abuse after the customer has submitted details on the claim. Riskified's decision is returned synchronously in the response to the /claim_create request. ## Headers - `x-riskified-shop-domain` string, required - `x-riskified-hmac-sha256` string, required - `content_type` 'application/json', required - `accept` 'application/vnd.riskified.com; version=2', required ## Request body - ClaimCreateRequest - `claim` ClaimCreate - `id` string, required: The unique identifier for the claim. - `created_at` string, date-time, required: The date and time (ISO 8601) when the claim was created. - `line_items` LineItemCreate[], required: An array of line item objects, each one containing information about a unit of an item in the claim. - `order_id` string, required: The unique identifier for the order which is associated with the claim. - `claim_amount` number, float, required: The amount that the customer is claiming for the specific line item. Note: this should be in the same currency as the original order sent to Riskified. - `sku` string, required: The sku of the item in the fulfillment. - `item_id` string: The unique identifier of the individual line item object in the claim/order. - `claim_reason` 'not_received' | 'missing_item' | 'wrong_item' | 'damaged' | 'customer_preference' | 'other' | 'valid_complaint', required: The reason a refund/return is being claimed. - `orig_claim_reason` string, required: The original claim reason of the merchant. - `requested_action` 'store_credit' | 'refund' | 'reshipment' | 'exchange' | 'physical_gift_card' | 'none', required: The action requested by the customer. - `return_deadline` string, date-time: The date and time (ISO 8601) of the return deadline for the individual product. - `return_requested` boolean: States whether the item is expected to be returned back to the merchant. - `customer_note` string: A note added by the customer when opening a claim. - `fulfillment` Fulfillment - `fulfillment_id` string, required: The unique identifier of the original shipment from the merchant to the customer. This should line up with /fulfill (if implemented). - `status` 'did_not_ship' | 'in_transit' | 'delivered' | 'back_to_sender' | 'voided': The fulfillment status at the time the claim was submitted. - `delivered_at` string, date-time: The date and time (ISO8601) that the order was delivered - `tracking_company` string: The name of the shipping company. Possible values are: usps, ups, fedex, dhl_express, dhl_ecommerce, canada post. If company is not listed, insert the name. - `tracking_numbers` string: A list of shipping numbers, provided by the shipping company. - `tracking_urls` string: The URLs to track the fulfillment. - `proof_of_delivery` boolean: Indication of if any proof of delivery is obtained (signature, image, etc) - `proof_of_delivery_type` 'image' | 'signature': The type of proof of delivery obtained. - `source` 'email' | 'chat' | 'phone' | 'desktop_web' | 'mobile_web' | 'web' | 'mobile_app' | 'in_store': The channel that the claim originated from. - `customer` Customer - `is_logged_in` boolean: An indication of whether the customer is logged into their account at the time of claim submission. - `email` string: The email address of the customer who's submitting the claim, if different from the order. - `id` string: The id of the customer who's submitting the claim, if different from the order. - `first_name` string: The first name of the customer who's submitting the claim, if different from the order. - `last_name` string: The last name of the customer who's submitting the claim, if different from the order. - `phone` string: The phone number of the customer who's submitting the claim, if different from the order. - `address` Address - `first_name` string, required: The first name of the person associated with the address. - `last_name` string, required: The last name of the person associated with the address. - `address1` string, required: The street name of the address. - `country` string, required: The name of the country address. - `country_code` string, required: The 2 letter country code (ISO 3166-1 alpha-2) of the country address. - `phone` string, required: The phone number at the address. - `city` string, required: The city of the address. - `zip` string, required: The zip or postal code of the address. - `address2` string: An optional additional field for the street address. - `company` string: **(Conditional Requirement)** Required if the address is associated to a company. The company of the person associated with the address. - `additional_phone` string: Additional phone number at the address. - `verified_phone` boolean: Indicates whether the provided phone number was verified. - `province` string, required: The name of the state or province of the address. - `province_code` string: The two-letter ISO 3166-2 alpha-2 code for the state or province of the address. - `neighborhood` string: 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` number, float: The latitude coordinates of the address. - `longitude` number, float: The longitude coordinates of the address. - `id` string: **(Conditional Requirement)** unique ID, is required in case of multiple shipping addresses. - `handling_fee` number, float: Sum of any fees (i.e., handling or restocking fee, etc.) that is applicable to the claim. - `cart_token` string: The session id that this claim was created on, this value should match the session id value that is passed in the Beacon JavaScript. - `device_id` string: The mobile device identifier. Use if claim is submitted via native app platform. - `browser_ip` string: The customer's browser IP address at the time of claim submission. - `note` string: A note attached to the claim. ## Response `200` Success - union - ClaimCreateResponseApprove: Approved Claim Response - `claim` object - `id` string: The unique identifier for the claim. - `decision` 'approve': Textual status describing the result of Riskified’s claim analysis. **Always 'approve' for approved claims.** - `decision_reason` string: Additional context on Riskified’s decision. This can be customizable based on merchant needs. Some example values are: - `approved in accordance to policy` - `Risky First Claim` - `Likely Abusive` - `Flagrant Abuse` - `followed_action` string: Any secondary actions that Riskified recommends in response to the claim. This can be customizable based on merchant needs. Some example values are: - `warning_1` - `warning_2` - `handling_fee` - `warnings` string[]: A string of text that highlights any issues seen in the API call. **It’s expected this will be null for the majority of analyzed claims.** Some issues that can be highlighted in this field may include, but not limited to: - `order not found` - the order listed in the API call cannot be found in Riskified’s system - `duplicate to claim` - the claim submitted is a duplicate of a previously submitted claim - `claim filtered from analysis` - claim not analyzed due to exclusion filters in place in Riskified’s system - `order is older than 180 days` - the original order was placed more than 180 days before the claim was submitted, and therefore, the claim is not subject to analysis. - ClaimCreateResponseReview: Review Required Claim Response - `claim` object - `id` string: The unique identifier for the claim. - `decision` 'review': Textual status describing the result of Riskified’s claim analysis. **Always 'review' for claims requiring manual review.** - `decision_reason` string: Additional context on Riskified’s decision. This can be customizable based on merchant needs. Some example values are: - `approved in accordance to policy` - `Risky First Claim` - `Likely Abusive` - `Flagrant Abuse` - `followed_action` string: Any secondary actions that Riskified recommends in response to the claim. This can be customizable based on merchant needs. Some example values are: - `warning_1` - `warning_2` - `handling_fee` - `warnings` string[]: A string of text that highlights any issues seen in the API call. **It’s expected this will be null for the majority of analyzed claims.** Some issues that can be highlighted in this field may include, but not limited to: - `order not found` - the order listed in the API call cannot be found in Riskified’s system - `duplicate to claim` - the claim submitted is a duplicate of a previously submitted claim - `claim filtered from analysis` - claim not analyzed due to exclusion filters in place in Riskified’s system - `order is older than 180 days` - the original order was placed more than 180 days before the claim was submitted, and therefore, the claim is not subject to analysis. - ClaimCreateResponseDecline: Decline Claim Response - `claim` object - `id` string: The unique identifier for the claim. - `decision` 'decline': Textual status describing the result of Riskified’s claim analysis. **Always 'decline' if Riskified recommends declining the claim.** - `decision_reason` string: Additional context on Riskified’s decision. This can be customizable based on merchant needs. Some example values are: - `Risky First Claim` - `Likely Abusive` - `Flagrant Abuse` - `followed_action` string: Any secondary actions that Riskified recommends in response to the claim. This can be customizable based on merchant needs. Some example values are: - `warning_1` - `warning_2` - `handling_fee` - `warnings` string[]: A string of text that highlights any issues seen in the API call. **It’s expected this will be null for the majority of analyzed claims.** Some issues that can be highlighted in this field may include, but not limited to: - `order not found` - the order listed in the API call cannot be found in Riskified’s system - `duplicate to claim` - the claim submitted is a duplicate of a previously submitted claim - `claim filtered from analysis` - claim not analyzed due to exclusion filters in place in Riskified’s system - `order is older than 180 days` - the original order was placed more than 180 days before the claim was submitted, and therefore, the claim is not subject to analysis. - ClaimCreateResponseExcluded: Decline Claim Response - `claim` object - `id` string: The unique identifier for the claim. - `decision` 'excluded': Textual status describing the result of Riskified’s claim analysis. **Always 'excluded' if Riskified excluded the claim from both analysis and statistics due to filters, etc.** - `decision_reason` string: Additional context on Riskified’s decision. This can be customizable based on merchant needs. Some example values are: - `order not found` - `duplicate` - `filtered` - `followed_action` string: Any secondary actions that Riskified recommends in response to the claim. This can be customizable based on merchant needs. Some example values are: - `warning_1` - `warning_2` - `handling_fee` - `warnings` string[]: A string of text that highlights any issues seen in the API call. **It’s expected this will be null for the majority of analyzed claims.** Some issues that can be highlighted in this field may include, but not limited to: - `order not found` - the order listed in the API call cannot be found in Riskified’s system - `duplicate to claim` - the claim submitted is a duplicate of a previously submitted claim - `claim filtered from analysis` - claim not analyzed due to exclusion filters in place in Riskified’s system - `order is older than 180 days` - the original order was placed more than 180 days before the claim was submitted, and therefore, the claim is not subject to analysis. - ClaimCreateResponseCaptured: Captured Claim Response. Riskified excluded the claim from analysis, but will ingest for statistics - `claim` object - `id` string: The unique identifier for the claim. - `decision` 'captured': Textual status describing the result of Riskified’s claim analysis. **Always 'captured' for captured claims.** - `decision_reason` string: Additional context on Riskified’s decision. This can be customizable based on merchant needs. Some example values are: - `approved in accordance to policy` - `Risky First Claim` - `Likely Abusive` - ~Flagrant Abuse` - `followed_action` string: Any secondary actions that Riskified recommends in response to the claim. This can be customizable based on merchant needs. Some example values are: - `warning_1` - `warning_2` - `handling_fee` - `warnings` string[]: A string of text that highlights any issues seen in the API call. **It’s expected this will be null for the majority of analyzed claims.** Some issues that can be highlighted in this field may include, but not limited to: - `order not found` - the order listed in the API call cannot be found in Riskified’s system - `duplicate to claim` - the claim submitted is a duplicate of a previously submitted claim - `claim filtered from analysis` - claim not analyzed due to exclusion filters in place in Riskified’s system - `order is older than 180 days` - the original order was placed more than 180 days before the claim was submitted, and therefore, the claim is not subject to analysis. ## Other responses - `400`: Bad request - `401`: Unauthorized - `429`: Too many requests - `503`: Service Unavailable --- [API](https://skmtc.dev/riskified/apis/policy-protect-refunds-returns.md) - [All operations](https://skmtc.dev/riskified/apis/policy-protect-refunds-returns/llms.txt) - [OpenAPI document](https://skmtc.dev/riskified/apis/policy-protect-refunds-returns/revisions/1b2c88304179?raw)