Merchants > API Reference > Endpoints > Customer Label

Customer Label

The Customer Label endpoint allows you to review customers across multiple fraud categories, including Payment Fraud and Refund Abuse. This endpoint replaces the legacy v2/label endpoint, which has been deprecated.

See our Payment Fraud or Refund Abuse guides for more information on how to use manual reviews to prevent fraud.

Field Status Definitions

Required Required fields must be sent. If the data is not sent Ravelin will return an error.

Important Important fields are crucial for performance where that data is relevant for your business.

Optional Optional fields are additional data points that can be shared with Ravelin.
These fields are unlikely to impact performance but may be visible in the Ravelin dashboard.

Jump to Response

POST api.ravelin.com/v2/customer/:customerid:/labels

Show all

category string optional

The fraud category associated with this label.

One of: PAYMENT_FRAUD, or REFUND_ABUSE.

review string optional

The specific label to apply, based on the category selected.

• For PAYMENT_FRAUD category, one of:

FRAUDSTER,
GENUINE,
POTENTIALLY_FRAUDSTER,
POTENTIALLY_GENUINE,
UNREVIEWED.

Note: The "potential" labels (POTENTIALLY_FRAUDSTER and POTENTIALLY_GENUINE) are only available if Ravelin has enabled them for your account.

• For REFUND_ABUSE category one of:

REFUND_ABUSE,
NOT_REFUND_ABUSE,
UNREVIEWED.

reviewer object optional

The individual who is reviewing the customer.

Their details will appear in the audit log on the Ravelin dashboard so you are able to see who did this review.

Show definition

name string optional

The name of the individual who has reviewed the customer.

email string optional

The email address of the individual who has reviewed the customer.

comment string optional

The reason for reviewing the customer with this label.

This will appear in the audit log on the dashboard so you are able to see why this customer was reviewed.

POST https://api.ravelin.com/v2/customer/:customerid:/labels HTTP/1.1
Authorization: token ...
Content-Type: application/json

{
  "category": "REFUND_ABUSE",
  "review": "UNREVIEWED",
  "reviewer": {
    "name": "Bilbo Baggins",
    "email": "bilbo.b@shiremail.com"
  },
  "comment": "We spoke to this customer on the phone and determined they are not a fraudster."
}

Response

Example response:

Show all

timestamp string

The response's timestamp in the YYYY-MM-DDTHH:MM:SS.Z format.

category string

The fraud category associated with this label.

One of: paymentFraud, or refundAbuse.

author object

The individual who reviewed the customer.

Show definition

name string

The name of the individual who has reviewed the customer.

email string

The email address of the individual who has reviewed the customer.

review string

The specific label to applied to the customer.

reviewBand string

The color band associate with this label.

reviewText string

The reason for reviewing the customer with this label.

entityId string

The id of the customer reviewed.

entityType string

The type of the entity reviewed.

{
  "timestamp": "2025-01-27T16:43:58.164260202Z",
  "category": "refundAbuse",
  "author": {
    "name": "Bilbo Baggins",
    "email": "bilbo.b@shiremail.com"
  },
  "review": "FRAUDSTER",
  "reviewBand": "RED",
  "reviewText": "We spoke to this customer on the phone and determined they are a fraudster.",
  "entityId": "abc-123-321-cba",
  "entityType": "customer"
}

Feedback

Was this page helpful?