Order Risks

The Order risk assessment is used to indicate to a merchant the fraud checks that have been done on an order.

What can you do with Order Risks?

The Shopify API lets you do the following with the Order Risks resource. More detailed versions of these general actions may be available:

Order Risks Properties

cause_cancel
{ "cause_cancel" : true }

Use this flag when a fraud check is accompanied with a call to the Orders API to cancel the order. This will indicate to the merchant that this risk was severe enough to force cancellation of the order.

Note: Setting this parameter does not cancel the order. This must be done by the Orders API.

display
{ "display" : true }

States whether or not the risk is displayed. Valid values are "true" or "false".

id
{ "id" : 284138680 }

A unique numeric identifier for the order risk.

order_id
{ "order_id" : 450789469 }

The id of the order the order risk belongs to

message
{ "message" : "This order came from an anonymous proxy." }

A message that should be displayed to the merchant to indicate the results of the fraud check.

recommendation
{ "recommendation" : "cancel" }

The recommended action given to the merchant. Valid values are:

  • cancel: This order should be cancelled by the merchant.
  • investigate: This order might be fraudulent and needs further investigation.
  • accept: This check found no indication of fraud.

score
{ "score" : 1.0 }

A number between 0 and 1 indicating percentage likelihood of being fraud.

source
{ "source" : "external" }

This indicates the source of the risk assessment.

Endpoints

POST /admin/orders/450789469/risks.json

Create a new Order Risk for an Order

Add a fraud risk for Proxy detection

POST /admin/orders/#{id}/risks.json
{
  "risk": {
    "message": "This order came from an anonymous proxy",
    "recommendation": "cancel",
    "score": 1.0,
    "source": "External",
    "cause_cancel": true,
    "display": true
  }
}
View Response
HTTP/1.1 201 Created
{
  "risk": {
    "id": 1066215049,
    "order_id": 450789469,
    "checkout_id": 901414060,
    "source": "External",
    "score": "1.0",
    "recommendation": "cancel",
    "display": true,
    "cause_cancel": true,
    "message": "This order came from an anonymous proxy",
    "merchant_message": "This order came from an anonymous proxy"
  }
}
GET /admin/orders/450789469/risks.json

Get a list of all Order Risks

Get all Order Risks for an Order

GET /admin/orders/#{id}/risks.json
View Response
HTTP/1.1 200 OK
{
  "risks": [
    {
      "id": 284138680,
      "order_id": 450789469,
      "checkout_id": null,
      "source": "External",
      "score": "1.0",
      "recommendation": "cancel",
      "display": true,
      "cause_cancel": true,
      "message": "This order was placed from a proxy IP",
      "merchant_message": "This order was placed from a proxy IP"
    },
    {
      "id": 1066215048,
      "order_id": 450789469,
      "checkout_id": 901414060,
      "source": "External",
      "score": "1.0",
      "recommendation": "cancel",
      "display": true,
      "cause_cancel": true,
      "message": "This order came from an anonymous proxy",
      "merchant_message": "This order came from an anonymous proxy"
    }
  ]
}
GET /admin/orders/450789469/risks/284138680.json

Get a single Order Risk by its ID

Get a single Order Risk

GET /admin/orders/#{id}/risks/#{id}.json
View Response
HTTP/1.1 200 OK
{
  "risk": {
    "id": 284138680,
    "order_id": 450789469,
    "checkout_id": null,
    "source": "External",
    "score": "1.0",
    "recommendation": "cancel",
    "display": true,
    "cause_cancel": true,
    "message": "This order was placed from a proxy IP",
    "merchant_message": "This order was placed from a proxy IP"
  }
}
PUT /admin/orders/450789469/risks/284138680.json

Update an Order Risk entry

Update an existing risk detail line on an order

PUT /admin/orders/#{id}/risks/#{id}.json
{
  "risk": {
    "id": 284138680,
    "message": "After further review, this is a legitimate order",
    "recommendation": "accept",
    "source": "External",
    "cause_cancel": false,
    "score": 0.0
  }
}
View Response
HTTP/1.1 200 OK
{
  "risk": {
    "id": 284138680,
    "order_id": 450789469,
    "checkout_id": null,
    "source": "External",
    "score": "0.0",
    "recommendation": "accept",
    "display": true,
    "cause_cancel": false,
    "message": "After further review, this is a legitimate order",
    "merchant_message": "After further review, this is a legitimate order"
  }
}
DELETE /admin/orders/450789469/risks/284138680.json

Delete an Order Risk Entry. Consider updating a previous order risk with display set to false rather than deleting an entry

Delete an erroneous risk entry

DELETE /admin/orders/#{id}/risks/#{id}.json
View Response
HTTP/1.1 200 OK
{}