--- title: "Create a Claim" method: POST path: "/claim_create" tags: ["Returns"] --- # Create a Claim `POST /claim_create` 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' — **(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` 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. - `event_type` 'label_scan' | 'inspection' — Where the item is in the claim/return lifecycle. Required only when triggered at return label scan or inspection. - `return_shipping` ReturnShipping - `tracking_numbers` string, required — The return shipping number, provided by the shipping company. - `scanned_at` string, date-time — The date and time (ISO 8601) that the package was scanned (picked up) by the carrier. - `label_created_at` string, date-time — The date and time (ISO 8601) that the return shipping label was created. - `arrived_at` string, date-time — The date and time (ISO 8601) that the package has arrived to the store/warehouse. - `tracking_company` string — The name of the shipping company. - `weight` number, float — The package weight in grams or ounces. - `weight_unit` 'grams' | 'ounces' — The unit of measure for the weight. - `is_verified` boolean — Indication of whether the content of the box was physically inspected/verified at the time of scan. - `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. - `inspection` Inspection - `condition` 'pristine' | 'second_quality' | 'poor' | 'fake' | 'missing' | 'valid_complaint', required — The condition of the item at time of inspection. - `external_condition` string — The condition of the item at time of inspection as recorded in the merchant's system. - `inspected_at` string, date-time, required — The date and time (ISO 8601) when the item was inspected. - `location` 'in_store' | 'warehouse' | 'third_party', required — The type of location where the item was inspected. - `location_id` string — The ID of the store/warehouse where the item was inspected. - `note` string — Free text or note added to claim as part of the inspection process. - `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/chargeback-guarantee.md) · [All operations](https://skmtc.dev/riskified/apis/chargeback-guarantee/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/riskified/chargeback-guarantee/revisions/2b7df5bce861/schema)