Merchants > API Reference > Endpoints > Voucher (v3)

Voucher (v3)

To request a recommendation at this endpoint use the Voucher Assessment checkpoint. Ravelin will return a recommendation of ALLOW or PREVENT.

Promo abuse recommendations need to be enabled on your account before they can be used. Please speak to your account manager about enabling promo abuse recommendations.

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/v3/voucher?score=voucherAssessment

Use this endpoint when a customer enters a voucher or promo code and before you apply the code.

Show all

timestamp integer required

The time at which this data payload was valid. When sending events in realtime, this will usually be 'now'. This is used to merge data that arrives out-of-order.

A Unix timestamp preferably as an integer count of milliseconds since 1970-01-01T00:00 UTC (nanoseconds are also accepted).

customer object required

The customer applying the voucher or promo code. Always sent as an object, even when only the ID is known.

Show definition

customerId string required

The unique identifier of the customer. If your system allows guest checkouts then we recommend making this the customer's lower-cased email address.

Minimum length: 1

Maximum length: 300

registrationTime integer important

The time that the customer registered. If this value is unknown, you can set it to the time the request is sent. Ravelin will retain the earliest value you have sent for this customer ID.

A Unix timestamp preferably as an integer count of milliseconds since 1970-01-01T00:00 UTC (nanoseconds are also accepted).

email string important

The email address of the customer.

Maximum length: 320

emailVerifiedTime integer important

The time at which the customer verified their email, usually by following a link back to your website from an email you sent to their address.

A Unix timestamp preferably as an integer count of milliseconds since 1970-01-01T00:00 UTC (nanoseconds are also accepted).

name string important

The full name of the customer. If you have the name split into parts, consider familyName and givenName instead.

familyName string important

The surname/last name of the customer. If you do not have the name split into parts, consider name instead.

givenName string important

The first/given names of the customer. If you do not have the name split into parts, consider name instead.

telephone string important

The telephone number of the customer. Best in E.164 format with an international dialing code.

telephoneVerifiedTime integer important

The time at which the customer verified their telephone number, usually by confirming a code from an SMS you sent to the number.

A Unix timestamp preferably as an integer count of milliseconds since 1970-01-01T00:00 UTC (nanoseconds are also accepted).

telephoneCountry string optional

The country the telephone number directs to. Note that the country is not an adequate replacement for the international dialing code in the Dominican Republic or Puerto Rico where multiple dialing codes are used.

An ISO 3166-1 Alpha 3 or Alpha 2 country code.

Minimum length: 2

Maximum length: 3

tags object optional

The tags to set or unset. Use the tag ID followed by true or false, depending on whether you want to set or unset the tag.

location object optional

Show definition

country string important

An ISO 3166-1 Alpha 3 or Alpha 2 country code.

Minimum length: 2

Maximum length: 3

postalCode string important

The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.

latitude number important

The latitude of the location.

longitude number important

The longitude of the location.

addresseeName string optional

The name of the person that will accept delivery of goods to this address.

street1 string optional

The street address of the location.

street2 string optional

The street address of the location.

neighbourhood string optional

The neighbourhood of the location.

zone string optional

The zone of the location.

city string optional

The city/village/town

region string optional

The state/county of the location.

poBoxNumber string optional

The PO box number related to the location.

custom object optional

Custom data that is relevant to your domain. This can be any json object. Please include any details that you think are relevant to fraud that our schema does not capture.

geohash string optional

deprecated

The geohash of the location.

custom object optional

Custom data that is relevant to your domain. This can be any json object. Please include any details that you think are relevant to fraud that our schema does not capture.

accountType string important

The type of account which the customer currently has.

See also order.accountType.

One of:

GUEST - The customer has not yet registered for an account, but may have placed an order.
REGISTERED - The customer has registered for an account.

username string optional

deprecated

The username the customer would log in with.

gender string optional

deprecated

The gender of the customer.

balance object optional

deprecated

The wallet contents of the customer, in the form of an object whose keys are currencies and values the amount held in that currency, in the currency's basic units.

banned boolean optional

deprecated

Whether the customer is banned in your systems.

country string optional

deprecated

The home country for this customer. Doesn't change when the customer is briefly abroad.

Minimum length: 2

Maximum length: 3

market string optional

deprecated

The logical region in which this customer exists.

Pattern: ^[0-9a-z-]*$

marketCity string optional

deprecated

The logical city in which this customer exists.

Pattern: ^[0-9a-z-]*$

passwordBcrypted string optional

deprecated

The bcypted form of the password for this customer. By its nature, the bcrypt operation is slow. Consider using passwordHashed if this is too slow for you.

passwordHashed string optional

deprecated

The SHA256 form of the password for this customer. This must be base64 encoded.

password string optional

deprecated

The plaintext password for the customer. We never store the raw password but for security we recommend using one of the hashing options instead of the plaintext option.

passwordChanged boolean optional

deprecated

Set to true on events where the password has been changed, false or omit otherwise.

voucher object required

The single code being assessed in this call. One code in, one recommendation out.

Show definition

voucherCode string required

A unique identifier for the voucher, usually the code the customer enters.

Minimum length: 1

valueType string optional

How the discount is expressed. Defaults to FIXED.

FIXED: The voucher deducts a fixed monetary amount (use value and currency).
PERCENTAGE: The voucher deducts a share of the order total (use percentage). Note: When valueType is PERCENTAGE, the percentage field is required.

One of: FIXED, or PERCENTAGE.

value integer optional

Fixed-value vouchers only. The monetary value in minor units of currency.

currency string optional

Fixed-value vouchers only. ISO 4217 currency code.

Pattern: ^[a-zA-Z]{3}$

percentage integer optional

Percentage vouchers only. The discount percentage (1-100).

maxDiscountValue integer optional

Percentage vouchers only. Cap on the discount, in minor units of currency.

voucherType string optional

The type of voucher:

GENERAL: Broadly distributed promotional code (campaigns, seasonal offers).
REFERRAL: Code generated by an existing customer for referrals.
REACTIVATION: Code targeted at lapsed customers.
STAFF: Employee or internal discount code.

One of: GENERAL, REFERRAL, REACTIVATION, or STAFF.

referrerId string optional

The customerId of the customer who created this voucher. Links a REFERRAL voucher back to its referrer. Required, together with voucherType REFERRAL, when the request is sent without the score query parameter.

referralValue integer optional

The amount the voucher owner receives when the voucher is used.

creationTime integer optional

Unix timestamp (ms) when the voucher was created.

expiry integer optional

Unix timestamp (ms) when the voucher can no longer be redeemed.

custom object optional

Custom data that is relevant to your domain. This can be any json object. Please include any details that you think are relevant to fraud that our schema does not capture.

device object important

Standard Ravelin device object. Device/IP/session reuse across accounts is a core collusion signal, available at code-entry time regardless of cart or order state. Mutually exclusive with deviceId.

Show definition

deviceId string required

The ID of the device used by the customer to trigger this update.

Minimum length: 1

Maximum length: 300

ipAddress string important

The IP address of the device connecting to your services. Used in fraud and account-takeover detection.

When extracting this IP address, consider X-Forwarded-For.

language string important

The ISO 639 code of your customer's device's preferred language, or the IET Language Tag (BCP 47) values from the browser's Accept-Language header.

userAgent string important

The browser user-agent string, if the device represents a web browser - window.navigator.userAgent.

model string optional

The model/identifier name of the device if the device represents a native app. See here for iOS models: https://www.theiphonewiki.com/wiki/Models and here for Google Play supported models: http://storage.googleapis.com/play_public/supported_devices.csv.

os string optional

The operating system that the device is running.

type string optional

The type of device.

One of: computer, phone, or tablet.

manufacturer string optional

The maker of the device.

location object optional

The geolocated position of the device.

Show definition

country string important

An ISO 3166-1 Alpha 3 or Alpha 2 country code.

Minimum length: 2

Maximum length: 3

postalCode string important

The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.

latitude number important

The latitude of the location.

longitude number important

The longitude of the location.

addresseeName string optional

The name of the person that will accept delivery of goods to this address.

street1 string optional

The street address of the location.

street2 string optional

The street address of the location.

neighbourhood string optional

The neighbourhood of the location.

zone string optional

The zone of the location.

city string optional

The city/village/town

region string optional

The state/county of the location.

poBoxNumber string optional

The PO box number related to the location.

custom object optional

Custom data that is relevant to your domain. This can be any json object. Please include any details that you think are relevant to fraud that our schema does not capture.

geohash string optional

deprecated

The geohash of the location.

custom object optional

Custom data that is relevant to your domain. This can be any json object. Please include any details that you think are relevant to fraud that our schema does not capture.

browser string optional

deprecated

The name of the web browser being used, if applicable. Prefer userAgent.

javascriptEnabled boolean optional

deprecated

Whether Javascript is enabled on the web browser.

cookiesEnabled boolean optional

deprecated

Whether cookies are enabled on the web browser.

screenResolution string optional

deprecated

The resolution of the screen on the device in the format XxY

deviceId string optional

Reference to a previously-sent device. Mutually exclusive with device.

Minimum length: 1

Maximum length: 300

orderId string optional

Send when an order or basket identifier already exists on the merchant side.

Minimum length: 1

POST https://api.ravelin.com/v3/voucher?score=voucherAssessment HTTP/1.1
Authorization: token ...
Content-Type: application/json

{
  "timestamp": 1512828988826,
  "customer": {
    "customerId": "customer-123",
    "email": "jsmith123@example.com"
  },
  "voucher": {
    "voucherCode": "20OFF",
    "valueType": "PERCENTAGE",
    "percentage": 20,
    "maxDiscountValue": 1500,
    "currency": "GBP",
    "voucherType": "GENERAL"
  },
  "device": {
    "deviceId": "device-123",
    "ipAddress": "81.152.92.84"
  },
  "orderId": "order-987"
}

Response

action string	Ravelin's recommendation for whether to apply the voucher. One of: `ALLOW` or `PREVENT`.
rules object	Details of the client rules triggered by this assessment.
rules.triggered array	The client rules triggered by this assessment.
rules.triggered[].ruleId integer	The ID of the rule which triggered.
rules.triggered[].ruleVersion integer	The version of the rule which triggered.
rules.triggered[].action string	The recommendation produced by the rule.
rules.triggered[].triggered boolean	Whether the rule triggered. This is always `true`.
rules.triggered[].state string	Whether the rule was in live or test mode. One of: `active` or `passive`.
warnings array	Warnings when the request data may negatively impact abuse detection.
warnings[].class string	The identifier for this warning.
warnings[].help string	A link to more information about this warning.
warnings[].msg string	Why the warning was issued.

{
  "action": "ALLOW",
  "rules": {
    "triggered": [
      {
        "ruleId": 1,
        "ruleVersion": 1,
        "action": "ALLOW",
        "triggered": true,
        "state": "active"
      }
    ]
  }
}

Feedback

Was this page helpful?