Regulated orders

sfgoods AmazonSPAPI

# What are regulated orders?

Amazon classifies some products as regulated to comply with local regulations and to support providing a broader selection of regulated items to customers. Because orders that contain regulated items must be validated by skilled professionals before shipment, customers are required to provide additional information or upload prescriptions when they complete the purchase. Examples of regulated items include pet pharmacy, eye contact lenses, and prescription glasses.

The getOrderRegulatedInfo and updateVerificationStatus operations in the Orders API can help you programmatically integrate this validation process into your applications.

Terminology

Regulated product. A product sold on Amazon that requires supplying additional information at purchase time to comply with local regulations.
Regulated information. Additional information entered by the customer when purchasing a regulated product.
Regulated order. A customer order containing a regulated product and associated regulated information.
Restricted Data Token (RDT). A short-lived access token that authorizes calls to restricted operations. An RDT remains valid for one hour.
Verification status. The status of a regulated order, indicating whether it has been approved or rejected by a skilled professional.

# Tutorial: Find out if an order contains regulated information

This tutorial shows you how to determine if an order is a regulated order. Once identified, further regulated information and status about the order can be retrieved (see Tutorial: How to retrieve an order's regulated information).

Prerequisites

To complete this tutorial, you will need:

Authorization from the seller for whom you are making calls. See the Selling Partner API Developer Guide for more information.
Approval for the Direct-to-Consumer Delivery (Restricted) role in your developer profile.
The Direct-to-Consumer Delivery (Restricted) role selected in the App registration page for your application.

# Step 1. Find out if an order contains regulated information

Call the getOrder operation, passing the following query parameter:

Parameter	Description	Required
orderId	An Amazon-defined order identifier, in 3-7-7 format. Type: string	Yes

Request example:

GET https://sellingpartnerapi-eu.amazon.com/orders/v0/orders/205-1725759-9209952/

Response

A successful response includes the payload object, which contains the information for an order. Included is a HasRegulatedItems boolean property. When true, the order has regulated items which may require additional approval steps before being fulfilled.

See Order (opens new window) in the API reference for details about the possible objects and properties in an order.

Response example (for an order that contains regulated information):

{
  "payload": {
    "BuyerInfo": {},
    "AmazonOrderId": "026-1520163-6049104",
    "EarliestShipDate": "2022-03-10T00:00:00Z",
    "SalesChannel": "Amazon.co.uk",
    "AutomatedShippingSettings": {
      "HasAutomatedShippingSettings": false
    },
    "OrderStatus": "Canceled",
    "NumberOfItemsShipped": 0,
    "OrderType": "StandardOrder",
    "IsPremiumOrder": false,
    "IsPrime": false,
    "FulfillmentChannel": "MFN",
    "NumberOfItemsUnshipped": 0,
    "HasRegulatedItems": true,
    "IsReplacementOrder": false,
    "IsSoldByAB": false,
    "LatestShipDate": "2022-03-10T23:59:59Z",
    "ShipServiceLevel": "Std UK Dom_1",
    "IsISPU": false,
    "MarketplaceId": "A1F83G8C2ARO7P",
    "PurchaseDate": "2022-03-09T22:03:02Z",
    "IsAccessPointOrder": false,
    "IsBusinessOrder": false,
    "OrderTotal": {
      "CurrencyCode": "GBP",
      "Amount": "20.00"
    },
    "PaymentMethodDetails": [
      "Standard"
    ],
    "IsGlobalExpressEnabled": false,
    "LastUpdateDate": "2022-03-14T22:05:14Z",
    "ShipmentServiceLevelCategory": "Standard"
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

Response example (for an order that does NOT contain regulated information):

{
  "payload": {
    "BuyerInfo": {},
    "AmazonOrderId": "026-1520163-6049104",
    "EarliestShipDate": "2022-03-10T00:00:00Z",
    "SalesChannel": "Amazon.co.uk",
    "AutomatedShippingSettings": {
      "HasAutomatedShippingSettings": false
    },
    "OrderStatus": "Canceled",
    "NumberOfItemsShipped": 0,
    "OrderType": "StandardOrder",
    "IsPremiumOrder": false,
    "IsPrime": false,
    "FulfillmentChannel": "MFN",
    "NumberOfItemsUnshipped": 0,
    "HasRegulatedItems": false,
    "IsReplacementOrder": false,
    "IsSoldByAB": false,
    "LatestShipDate": "2022-03-10T23:59:59Z",
    "ShipServiceLevel": "Std UK Dom_1",
    "IsISPU": false,
    "MarketplaceId": "A1F83G8C2ARO7P",
    "PurchaseDate": "2022-03-09T22:03:02Z",
    "IsAccessPointOrder": false,
    "IsBusinessOrder": false,
    "OrderTotal": {
      "CurrencyCode": "GBP",
      "Amount": "20.00"
    },
    "PaymentMethodDetails": [
      "Standard"
    ],
    "IsGlobalExpressEnabled": false,
    "LastUpdateDate": "2022-03-14T22:05:14Z",
    "ShipmentServiceLevelCategory": "Standard"
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

# Tutorial: How to recognize which orders in a list contain regulated information

This tutorial shows you how to recognize which orders in a list contain regulated information. Once identified, further regulated information and status about each order can be retrieved (see Tutorial: How to retrieve an order's regulated information).

Prerequisites

To complete this tutorial, you will need:

Authorization from the seller for whom you are making calls. See the Selling Partner API Developer Guide for more information.
Approval for the Direct-to-Consumer Delivery (Restricted) role in your developer profile.
The Direct-to-Consumer Delivery (Restricted) role selected in the App registration page for your application.

# Step 1. Recognize which orders from a list contain regulated information

Call the getOrders operation, passing the parameters you want to use to filter the result.

Request example:

GET https://sellingpartnerapi-eu.amazon.com/orders/v0/orders?MarketplaceIds=A1F83G8C2ARO7P&CreatedAfter=1985-04-12T23:20:50.52Z

Response

A successful response includes a payload object, which contains an Orders array of one or more orders, and optionally additional properties (see OrderList for information about the additional properties). Each order in the array includes a HasRegulatedItems boolean property. When true, the order contains regulated items which may require additional approval steps before being fulfilled.

See Order (opens new window) in the API reference for details about the possible objects and properties in an order.

Response example:
In this example, the first order in the Orders array has regulated items, and the second order in the Orders array does not have regulated items.

{
  "payload": {
    "Orders": [
      {
        "BuyerInfo": {},
        "AmazonOrderId": "026-1520163-6049104",
        "EarliestShipDate": "2022-03-10T00:00:00Z",
        "SalesChannel": "Amazon.co.uk",
        "AutomatedShippingSettings": {
          "HasAutomatedShippingSettings": false
        },
        "OrderStatus": "Canceled",
        "NumberOfItemsShipped": 0,
        "OrderType": "StandardOrder",
        "IsPremiumOrder": false,
        "IsPrime": false,
        "FulfillmentChannel": "MFN",
        "NumberOfItemsUnshipped": 0,
        "HasRegulatedItems": true,
        "IsReplacementOrder": false,
        "IsSoldByAB": false,
        "LatestShipDate": "2022-03-10T23:59:59Z",
        "ShipServiceLevel": "Std UK Dom_1",
        "IsISPU": false,
        "MarketplaceId": "A1F83G8C2ARO7P",
        "PurchaseDate": "2022-03-09T22:03:02Z",
        "IsAccessPointOrder": false,
        "IsBusinessOrder": false,
        "OrderTotal": {
          "CurrencyCode": "GBP",
          "Amount": "20.00"
        },
        "PaymentMethodDetails": [
          "Standard"
        ],
        "IsGlobalExpressEnabled": false,
        "LastUpdateDate": "2022-03-14T22:05:14Z",
        "ShipmentServiceLevelCategory": "Standard"
      }, 
      {
        "BuyerInfo": {},
        "AmazonOrderId": "203-1028129-8694751",
        "EarliestShipDate": "2022-03-17T00:00:00Z",
        "SalesChannel": "Amazon.co.uk",
        "AutomatedShippingSettings": {
          "HasAutomatedShippingSettings": false
        },
        "OrderStatus": "Canceled",
        "NumberOfItemsShipped": 0,
        "OrderType": "StandardOrder",
        "IsPremiumOrder": false,
        "IsPrime": false,
        "FulfillmentChannel": "MFN",
        "NumberOfItemsUnshipped": 0,
        "HasRegulatedItems": false,
        "IsReplacementOrder": "false",
        "IsSoldByAB": false,
        "LatestShipDate": "2022-03-17T23:59:59Z",
        "ShipServiceLevel": "Std UK Dom_1",
        "IsISPU": false,
        "MarketplaceId": "A1F83G8C2ARO7P",
        "PurchaseDate": "2022-03-15T16:45:35Z",
        "IsAccessPointOrder": false,
        "IsBusinessOrder": false,
        "OrderTotal": {
          "CurrencyCode": "GBP",
          "Amount": "20.00"
        },
        "PaymentMethodDetails": [
          "Standard"
        ],
        "IsGlobalExpressEnabled": false,
        "LastUpdateDate": "2022-03-29T01:55:37Z",
        "ShipmentServiceLevelCategory": "Standard"
      }
    ],
    "CreatedBefore": "2022-04-22T07:23:40Z"
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79

# Tutorial: How to retrieve an order's regulated information

This tutorial shows you how to retrieve the regulated information associated with an order.

Prerequisites

To complete this tutorial, you will need:

Authorization from the seller for whom you are making calls. See Selling Partner API Developer Guide for more information.
Approval for the Direct-to-Consumer Delivery (Restricted) role in your developer profile.
The Direct-to-Consumer Delivery (Restricted) role selected in the App registration page for your application.

# Step 1. Retrieve the Restricted Data Token required to access the regulated information

You will need an RDT to retrieve an order's regulated information in step 2 of this tutorial. This step shows you how to retrieve the RDT required for Step 2.

Call the createRestrictedDataToken operation, passing the following parameters:

Parameter	Description	Required
restrictedResources	A list of restricted resources. Type: array<RestrictedResource>	Yes

Request example:

POST https://sellingpartnerapi-eu.amazon.com/tokens/2021-03-01/restrictedDataToken
{
  "restrictedResources": [
    {
      "method": "GET",
      "path": "/orders/v0/orders/{orderId}/regulatedInfo"
    }
  ]
}

1
2
3
4
5
6
7
8
9

Response
See CreateRestrictedDataTokenResponse in the Tokens API reference for additional details about the response properties.

Response example:

{
  "expiresIn": 3600,
  "restrictedDataToken": "Atz..."
}

1
2
3
4

Save the restrictedDataToken value (the RDT) to use in Step 2. Retrieve the regulated information associated with an order.

# Step 2. Retrieve the regulated information associated with an order

Call the getOrderRegulatedInfo operation, passing the orderId for the order that has the regulated information that you want to retrieve. Be sure to include the RDT from the prior step in the x-amz-access-token header of your call to getOrderRegulatedInfo.

Path parameter

Parameter	Description	Required
orderId	An Amazon-defined order identifier, in 3-7-7 format. Type: string	Yes

Request example:

GET https://sellingpartnerapi-eu.amazon.com/orders/v0/orders/205-1725759-9209952/regulatedInfo

Response

A successful response includes information about the order, whether a dosage label is required, the verification status of the order, and the requested regulated information, depending on the status of the order. For detailed information about the objects and properties that may be included in a successful response, see OrderRegulatedInfo in the API reference.

Response example (pending order):

{
  "payload": {
    "AmazonOrderId": "205-1725759-9209952",
    "RequiresDosageLabel": true,
    "RegulatedInformation": {
      "Fields": [
        {
          "FieldLabel": "Species",
          "FieldId": "petsSpecies",
          "FieldValue": "Cat",
          "FieldType": "Text"
        }, {
          "FieldLabel": "Pet name",
          "FieldId": "petsName",
          "FieldValue": "Snowy",
          "FieldType": "Text"
        }, {
          "FieldLabel": "Birth date",
          "FieldId": "petsDateOfBirth",
          "FieldValue": "15 August 2021",
          "FieldType": "Text"
        }, {
          "FieldLabel": "Weight",
          "FieldId": "petsWeight",
          "FieldValue": "1 kg",
          "FieldType": "Text"
        }, {
          "FieldLabel": "Gender",
          "FieldId": "petsGender",
          "FieldValue": "Female",
          "FieldType": "Text"
        }, {
          "FieldLabel": "Is your pet lactating?",
          "FieldId": "petsLactating",
          "FieldValue": "No",
          "FieldType": "Text"
        }, {
          "FieldLabel": "Is your pet pregnant?",
          "FieldId": "petsPregnant",
          "FieldValue": "Yes",
          "FieldType": "Text"
        }, {
          "FieldLabel": "Pregnancy stage",
          "FieldId": "petsPregnancyStage",
          "FieldValue": "Second trimester",
          "FieldType": "Text"
        }, {
          "FieldLabel": "Does your pet have allergies?",
          "FieldId": "petsAllergies",
          "FieldValue": "Yes",
          "FieldType": "Text"
        }, {
          "FieldLabel": "Is your pet neutered?",
          "FieldId": "petsNeutered",
          "FieldValue": "No",
          "FieldType": "Text"
        }, {
          "FieldLabel": "Is your pet on any other medication?",
          "FieldId": "petsAdditionalMedicationRadio",
          "FieldValue": "No",
          "FieldType": "Text"
        }, {
          "FieldLabel": "snowy prescription 1",
          "FieldId": "snowy prescription 1",
          "FieldValue": "https://...",
          "FieldType": "FileAttachment"
        }
      ]
    },
    "RegulatedOrderVerificationStatus": {
      "Status": "Pending",
      "RequiresMerchantAction": true,
      "ValidRejectionReasons": [
        {
          "RejectionReasonId": "shield_pom_v_reject_pregnant_only",
          "RejectionReasonDescription": "Not suitable for pregnant pet"
        }, {
          "RejectionReasonId": "shield_pom_v_reject_product",
          "RejectionReasonDescription": "This product is not suitable"
        }, {
          "RejectionReasonId": "shield_pom_v_reject_reject_age",
          "RejectionReasonDescription": "Your pet is too young for this medicine."
        }
      ]
    }
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87

Response example (approved order):

{
  "payload": {
    "AmazonOrderId": "205-1725759-9209952",
    "RequiresDosageLabel": true,
    "RegulatedInformation": {
      "Fields": [
        {
          "FieldLabel": "Species",
          "FieldId": "petsSpecies",
          "FieldValue": "Cat",
          "FieldType": "Text"
        }
      ]
    },
    "RegulatedOrderVerificationStatus": {
      "Status": "Approved",
      "RequiresMerchantAction": false,
      "ExternalReviewerId": "externalId",
      "ReviewDate": "1970-01-19T03:59:27Z",
      "ValidRejectionReasons": []
    }
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

Response example (rejected order):

{
  "payload": {
    "AmazonOrderId": "205-1725759-9209952",
    "RequiresDosageLabel": true,
    "RegulatedInformation": {
      "Fields": [
        {
          "FieldLabel": "Species",
          "FieldId": "petsSpecies",
          "FieldValue": "Cat",
          "FieldType": "Text"
        }
      ]
    },
    "RegulatedOrderVerificationStatus": {
      "Status": "Rejected",
      "RequiresMerchantAction": false,
      "ExternalReviewerId": "externalId",
      "ReviewDate": "1970-01-19T03:59:27Z",
      "RejectionReason": {
        "RejectionReasonId": "shield_pom_vps_reject_species",
        "RejectionReasonDescription": "This medicine is not suitable for this pet’s species"
      }
      "ValidRejectionReasons": []
    }
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

Response example (cancelled order)

{
  "payload": {
    "AmazonOrderId": "202-5156092-2672318",
    "RequiresDosageLabel": false,
    "RegulatedInformation": {
      "Fields": [
        {
          "FieldLabel": "Species",
          "FieldId": "petsSpecies",
          "FieldValue": "Dog",
          "FieldType": "Text"
        }, {
          "FieldLabel": "Birth date",
          "FieldId": "petsDateOfBirth",
          "FieldValue": "8 March 2019",
          "FieldType": "Text"
        }, {
          "FieldLabel": "Weight",
          "FieldId": "petsWeight",
          "FieldValue": "44 kg",
          "FieldType": "Text"
        }, {
          "FieldLabel": "Gender",
          "FieldId": "petsGender",
          "FieldValue": "Male",
          "FieldType": "Text"
        }, {
          "FieldLabel": "Does your pet have allergies?",
          "FieldId": "petsAllergies",
          "FieldValue": "No",
          "FieldType": "Text"
        }, {
          "FieldLabel": "Is your pet neutered?",
          "FieldId": "petsNeutered",
          "FieldValue": "No",
          "FieldType": "Text"
        }, {
          "FieldLabel": "Is your pet on any other medication?",
          "FieldId": "petsAdditionalMedicationRadio",
          "FieldValue": "No",
          "FieldType": "Text"
        }
      ]
    },
    "RegulatedOrderVerificationStatus": {
      "Status": "Cancelled",
      "RequiresMerchantAction": false,
      "ValidRejectionReasons": []
    }
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

Response example (expired order)

{
  "payload": {
    "AmazonOrderId": "205-2554781-3212354",
    "RequiresDosageLabel": true,
    "RegulatedInformation": {
      "Fields": [
        {
          "FieldLabel": "Species",
          "FieldId": "petsSpecies",
          "FieldValue": "Cat",
          "FieldType": "Text"
        }, {
          "FieldLabel": "Birth date",
          "FieldId": "petsDateOfBirth",
          "FieldValue": "25 January 2020",
          "FieldType": "Text"
        }, {
          "FieldLabel": "Weight",
          "FieldId": "petsWeight",
          "FieldValue": "2 kg",
          "FieldType": "Text"
        }, {
          "FieldLabel": "Gender",
          "FieldId": "petsGender",
          "FieldValue": "Male",
          "FieldType": "Text"
        }, {
          "FieldLabel": "Does your pet have allergies?",
          "FieldId": "petsAllergies",
          "FieldValue": "No",
          "FieldType": "Text"
        }, {
          "FieldLabel": "Is your pet neutered?",
          "FieldId": "petsNeutered",
          "FieldValue": "No",
          "FieldType": "Text"
        }, {
          "FieldLabel": "Is your pet on any other medication?",
          "FieldId": "petsAdditionalMedicationRadio",
          "FieldValue": "No",
          "FieldType": "Text"
        }, {
          "FieldLabel": "JPEG 2 prescription 1",
          "FieldId": "JPEG 2 prescription 1",
          "FieldValue": "https://...",
          "FieldType": "FileAttachment"
        }
      ]
    },
    "RegulatedOrderVerificationStatus": {
      "Status": "Expired",
      "RequiresMerchantAction": false,
      "ValidRejectionReasons": []
    }
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57

# Tutorial: How to approve or reject a regulated order

This tutorial shows you how to approve or reject an order that contains regulated information.

Prerequisites

To complete this tutorial, you will need:

Authorization from the seller for whom you are making calls. See Selling Partner API Developer Guide for more information.
Approval for the Direct-to-Consumer Delivery (Restricted) role in your developer profile.
The Direct-to-Consumer Delivery (Restricted) role selected in the App registration page for your application.

# Step 1. Approve or reject a regulated order

Call the updateVerificationStatus operation, passing the following parameters:

Path parameter

Parameter	Description	Required
orderId	An Amazon-defined order identifier, in 3-7-7 format. Type: string	Yes

Body parameter

Parameter	Description	Required
regulatedOrderVerificationStatus	The updated verification status properties. Type: UpdateVerificationStatusRequestBody	Yes

Request example (Approved):

PATCH https://sellingpartnerapi-eu.amazon.com/orders/v0/orders/205-1725759-9209952/regulatedInfo
{
  "regulatedOrderVerificationStatus": {
    "status": "Approved",
    "externalReviewerId": "reviewer1234"
  }
}

1
2
3
4
5
6
7

Request example (Rejected):

PATCH https://sellingpartnerapi-eu.amazon.com/orders/v0/orders/205-1725759-9209952/regulatedInfo
{
  "regulatedOrderVerificationStatus": {
    "status": "Rejected",
    "externalReviewerId": "reviewer1234",
    "rejectionReasonId": "shield_pom_vps_reject_incorrect_weight"
  }
}

1
2
3
4
5
6
7
8

Response

Note: Response is empty for this operation

Registering your Application Reports API Best Practices

Amazon Selling Partner API - spapi.cyou

Choose mode