API Reference > Endpoints > Deprecated Endpoints > Order (Deprecated)

Order (Deprecated)

This endpoint is deprecated. Send order details in a Checkout Request.

POST api.ravelin.com/v2/order

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).

order object

required

The order describing the goods or services the customer wants to, or has attempted to buy.

Show definition

orderId string

required

A unique identifier for this order.

creationTime integer

important

The time that the order was submitted by the customer. Used in reporting.

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

app object

important

The mobile or web app that this order was submitted on. Used for segmenting business analytics and creating app-specific risk profiles.

Show definition

status

important

The stage of order in the purchase and delivery flow. Used in reporting.

One of the following:

Pending: The order is yet to be submitted for payment and processing, and you are yet to decide whether you will accept the order.

Show definition

Accepted: The customer has submitted the order and you intend to fulfill it. This stage is useful if you provide the goods and services before taking payment. If you take payment immediately, you can consider the order fulfilled.

Show definition

Failed: Something went wrong, and the order can no longer be fulfilled.

Show definition

Cancelled: The order has been cancelled.

Show definition

Fulfilled: The goods have been provided to the customer and payment has been successfully taken.

Show definition

Refunded: The order has been refunded.

Show definition

price integer

important

The total price for this order, including delivery and taxes, in the currency's basic units. This price should always equal the sum of each items', tickets', and rooms' price times quantity.

currency string

important

The currency of the price for this order as an ISO 4217 currency code.

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

country string

important

The country the order should be attributed to for reporting and risk bucketing. Should reflect the country segmentation that you use for your reporting internally, whether that's by billing or shipping address, for example.

market string

important

The country-group market the customer belongs to. E.g. 'southamerica', 'europe', 'emea'. Used for reporting and risk bucketing.

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

marketCity string

important

The city that the customer belongs to. Used for reporting and risk bucketing.

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

category string

optional

The highest level category that applies to this order as a whole, e.g. the type of service provided. See item.category to describe individual order items.

to object

important

The delivery or drop-off location of the order. For taxis, can be the requested drop-off location to begin, and updated to the actual drop-off location once known.

Show definition

from object

optional

The pick-up location of the order. For taxis, can be the requested pick-up location to begin, and updated to the actual pick-up location once known.

Show definition

items array

important

The line items of the order, describing what the customer is purchasing. Including, but not limited to, products, services, journeys, tips, taxes, and delivery fees.

Show definition

quantity integer

required

Number of copies of this item that are present in the basket (set to 0 to remove).

sku string

optional

A merchant specific identifier for an item or a service.

name string

optional

The name of the product or service that is being purchased.

price integer

important

The total price for a single one of these items, in the currency's basic units.

currency string

optional

The currency of the price for this order item as an ISO 4217 currency code. Defaults to order currency.

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

brand string

optional

The name of the brand that the item is from.

upc string

optional

The name of the Universal Item Code.

category string

optional

The highest level category that this item is sold in.

subcategory string

optional

A category that this item is sold in.

executionTime integer

optional

The scheduled time for the service described by this item.

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

eventTicket object

optional

If the item being purchased is a ticket for an event, associate the ticket and event information here.

Show definition

ticket object

required

The ticket information for this event.

Show definition

event object

required

The event the ticket is granting access to. This could be a access to an event, an attraction, or any other activity the customer is purchasing a ticket to attend.

Show definition

eventId string

required

A unique identifier for this event.

category string

required

The category that best described the type of event.

One of: adventure, attraction, conference, convention, culinary, business, family, festival, health, live show, music, party, social, sport, or other.

venue object

required

The location the event will take place.

Show definition

name string

optional

The name of the event.

description string

optional

A short description of the event.

startTime

optional

Timestamp at which event is scheduled to start. If the event is ongoing/recurring, you can use the ticket time here.

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

endTime

optional

Timestamp at which event is scheduled to end. If the event is ongoing/recurring, you can use the ticket time here.

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

guest object

optional

The individual who will be attending the event.

Show definition

travelTicket

optional

If the item being purchased is a ticket for travel, associate the journey information here.

Show definition

ticketId string

required

A unique identifier for the ticket

description string

optional

A human-readable text description of what the ticket provides

passenger object

optional

The person travelling with this ticket.

Show definition

routes array

optional

The list of routes that this ticket grants the holder travel on.

Show definition

direction string

optional

The direction of travel along this route, e.g. 'outward' or 'return'.

journeyId string

optional

This is an optional unique id to tie routes together. For example, You can tie a outbound and return route together with this. This way you can have multiple return tickets in one order and routes can be logically grouped together. This must be GLOBALLY UNIQUE

legs array

optional

This is the list of travel legs taken by the passengers. It may contain any number of legs but must start at the first departure and end up at the final destination

Show definition

legId string

required

The ID of the current leg. For flight tickets, flight number (e.g. 'BA101'). For bus tickets, bus number (e.g: 'A7')

departurePortCode string

optional

Departure port code for the current leg. For flights: the 3 letter IATA airport code.

departurePort object

optional

The location of the departure port for the current leg. For flights: the location of the airport.

Show definition

departureCity string

optional

The name of the city of departure for the current leg.

departureCountryCode string

optional

The ISO 3166 country code (2- or 3-letter) for the departure country of the current leg.

departureTime integer

optional

The departure time for the current leg.

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

arrivalPortCode string

optional

Arrival port code for the current leg. For flights: the 3 letter IATA airport code.

arrivalPort object

optional

The location of the arrival port for the current leg. For flights: the location of the airport.

Show definition

arrivalCity string

optional

The name of the city of arrival for the current leg.

arrivalCountryCode string

optional

The ISO 3166 country code (2- or 3-letter) for the arrival country of the current leg.

arrivalTime integer

optional

The arrival time for the current leg.

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

carrierName string

optional

The name of the carrier/company conducting the current leg.

carrierCode string

optional

A publicly agreed code describing the carrier/company conducting the current leg. For Flights, this is the IATA 2 letter carrier code.

transportationType string

optional

The type of transportation.

One of: plane, train, bus, or ship.

seatReservation boolean

optional

Whether there are seat reservations on this leg.

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.

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.

travelInsurance boolean

optional

If the passenger purchased travel insurance.

ticketClass string

optional

The class of travel this ticket grants access to.

One of: business, economy, first, or standard.

ticketType string

optional

The type of ticket this belongs to. This includes round trip, multi city, open return, etc

validUntilTime integer

optional

The time that this ticket can be used until.

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

fulfilmentMethod string

optional

The method in which a customer obtains their tickets. E-mail, pickup at station, physical mail, etc

loyaltyCardId string

optional

The identifier for a loyalty card used on this order. If no loyalty card is used just omit this field

discountCardId string

optional

The identifier for a loyalty card used on this order. If no loyalty card is used just omit this field

accommodation object

optional

If the item being purchased represents accommodation being booked, associate the trip information here.

Show definition

refundable boolean

required

Whether this booking is refundable or not.

payOnArrival boolean

required

Whether the payment is taken at the hotel during check-in.

guest object

optional

The individual the booking is registered under (i.e the individual who will be checking in to the hotel). Either the current customer or another individual who the customer is booking the room on behalf of.

Show definition

freeCancellationUntilTime integer

optional

Timestamp at which any free cancellation period ends (unix time). Ignore if there is no free cancellation period.

paymentDueBeforeTime integer

optional

Timestamp at which payment is due. Ignore if payment is taken immediately at booking.

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

hotel object

optional

Information on the hotel that the room is located in.

Show definition

room object

optional

Information on room being booked.

Show definition

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.

note string

optional

Descriptive text relating to the contents or nature of the order being completed.

email string

optional

Contact e-mail for this order.

telephone string

optional

Contact phone number for this order. Best in E.164 format with an international dialing code.

telephoneCountry string

optional

Contact phone number's country

sellerId string

optional

deprecated

The unique identifier of the seller/counterparty in the transaction, if not your business. E.g. The restaurant, driver ID, etc.

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.

executionTime integer

optional

deprecated

Deprecated in favour of items.executionTime. Execution or pick-up time of the order.

suppliers array

optional

Suppliers (e.g. restaurants, couriers or drivers) involved in this order.

Show definition

eventType string

optional

An eventType should identify what event in your system triggered this API call.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-_]*$

customerId string

optional

The ID of the customer whose order is being submitted or updated.

tempCustomerId string

optional

A temporary ID for a customer when the real account ID has yet to be minted. This must eventually be sent in conjunction with a real customer ID to migrate the data into the full customer account.

device object

optional

The device used by the customer to trigger this update.

Show definition

deviceId string

required

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

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

optional

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

important

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

important

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

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

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

POST /v2/order HTTP/1.1
Authorization: token ...
Content-Type: application/json

{
  "timestamp": 1512828988826,
  "customerId": "abc-123-ZYZ",
  "tempCustomerId": "abc-123-XYZ",
  "order": {
    "orderId": "abcde12345-ZXY",
    "creationTime": 1512828988826,
    "app": {
      "name": "Our App Lite",
      "platform": "web",
      "domain": "us.brand.com"
    },
    "status": {
      "stage": "pending",
      "actor": "merchant"
    },
    "price": 10000,
    "currency": "GBP",
    "country": "GBR",
    "market": "emea",
    "marketCity": "london",
    "category": "delivery",
    "to": {
      "country": "GBR",
      "postalCode": "E1 1AA",
      "latitude": 51.503252,
      "longitude": -0.127899,
      "addresseeName": "John Smith",
      "street1": "123 fake st.",
      "street2": "floor 4, flat 48",
      "neighbourhood": "Hackney",
      "zone": "1",
      "city": "London",
      "region": "California",
      "poBoxNumber": "1234"
    },
    "from": {
      "country": "GBR",
      "postalCode": "E1 1AA",
      "latitude": 51.503252,
      "longitude": -0.127899,
      "addresseeName": "John Smith",
      "street1": "123 fake st.",
      "street2": "floor 4, flat 48",
      "neighbourhood": "Hackney",
      "zone": "1",
      "city": "London",
      "region": "California",
      "poBoxNumber": "1234"
    },
    "items": [
      {
        "sku": "delivery",
        "quantity": 1,
        "name": "Delivery Fee",
        "price": 10000,
        "currency": "GBP",
        "category": "delivery",
        "executionTime": 1512828988826,
        "eventTicket": {
          "ticket": {
            "ticketId": "ticket_123",
            "ticketType": "Adult Single Day Pass",
            "validFromTime": 1480330580,
            "validUntilTime": 1480340580
          },
          "event": {
            "eventId": "event_123",
            "name": "The Fitzwilliam Museum.",
            "description": "Fitzwilliam Museum, Exhibition of Old Things",
            "startTime": 1480340580,
            "endTime": 1480340580,
            "category": "music",
            "venue": {
              "name": "Royal Albert Hall",
              "location": {
                "country": "GBR",
                "postalCode": "E1 1AA",
                "latitude": 51.503252,
                "longitude": -0.127899,
                "addresseeName": "John Smith",
                "street1": "123 fake st.",
                "street2": "floor 4, flat 48",
                "neighbourhood": "Hackney",
                "zone": "1",
                "city": "London",
                "region": "California",
                "poBoxNumber": "1234"
              }
            }
          },
          "guest": {
            "familyName": "Smith",
            "givenName": "John",
            "name": "John Smith"
          }
        }
      }
    ],
    "email": "jsmith@example.com",
    "telephone": "+441234558887",
    "telephoneCountry": "GBR",
    "sellerId": "abcde12345-ZXY",
    "executionTime": 1512828988826,
    "suppliers": [
      {
        "supplierId": "abc-123-ZYZ",
        "status": {
          "stage": "fulfilled",
          "timestamp": 1512828988826,
          "reason": "Could not find passenger"
        },
        "fee": 250,
        "debt": 1000,
        "tip": 200,
        "currency": "GBP",
        "type": "courier"
      }
    ]
  },
  "device": {
    "deviceId": "65fc5ac0-2ba3-4a3b-aa5e-f5a77b845260",
    "ipAddress": "81.152.92.84",
    "language": "en-US",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36",
    "model": "Pixel XL",
    "os": "android",
    "type": "phone",
    "manufacturer": "google",
    "location": {
      "country": "GBR",
      "postalCode": "E1 1AA",
      "latitude": 51.503252,
      "longitude": -0.127899,
      "addresseeName": "John Smith",
      "street1": "123 fake st.",
      "street2": "floor 4, flat 48",
      "neighbourhood": "Hackney",
      "zone": "1",
      "city": "London",
      "region": "California",
      "poBoxNumber": "1234"
    }
  }
}

Response

Parameter	Type	Description
customerId	string	Identifier for this customer, as supplied by the client
action	string	Action to take for this customer, according to Ravelin. One of `ALLOW`, `REVIEW`, `PREVENT`
score	int	Ravelin score for this customer as an integer. Debugging purposes only
source	string	Source of the score, e.g. `RAVELIN` or `MANUAL_REVIEW`
scoreId	string	Unique identifier for this score
comment	string	In the case of manual review, this is the comment left by the reviewer on this particular review action. E.g.: `"Definitely not a fraudster, I know him personally"`, or `"I know this person from another account, infamous fraudster"`
warnings	array of warnings	Ravelin can return warnings on API responses when malformed or absent data may negative impact fraud-detection, but where we would rather return a best-effort score instead of out-right rejecting the API request.

Feedback

Was this page helpful?