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.

shipping object optional

Shipping details of the order.

Show definition

accountType string optional

The type of account which the customer had when they placed the order. See also customer.accountType:

GUEST - The customer placed the order without registering for an account.
REGISTERED - The customer placed the order after registering for an account.

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 https://api.ravelin.com/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"
          }
        }
      }
    ],
    "shipping": {
      "daysToDispatch": 3,
      "carrier": "DHL"
    },
    "accountType": "REGISTERED",
    "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?