Orders
The Order Object
A Rutter Order represents an order processed by a merchant's store. Every order is linked to Fulfillments, Transactions, Products, Variants, and a Customer.
Every order contains a line_items array containing information about the products included in the order.
Properties
idstringThe Rutter generated unique ID of the order.
platform_idstringOptionalThe platform specific ID of the order.
cancelled_atstringOptionalThe ISO 8601 timestamp for when the order was cancelled. SHOPIFY only.
payment_statusenumThe payment status of the order.
statusenumThe status of the order.
total_discountnumberThe sum of all discounts applied to the total price.
total_pricenumberThe total price of the order.
fulfillment_statusenumnullableThe status of the fulfillment for the order.
iso_currency_codestringnullableThe ISO 4217 currency code of the order.
namestringOptionalThe name of the order. Supported for SHOPIFY only.
order_numberstringOptionalThe merchant facing order ID.
source_namestringOptionalThe source name of the order. Supported for SHOPIFY only.
total_line_items_pricenumberOptionalThe total price of all line items of the order. Supported for SHOPIFY only.
total_shippingnumbernullableThe sum of all shipping costs.
total_shipping_discountnumberOptionalThe sum of all discounts on shipping applied to the total price.
total_taxnumbernullableThe total tax paid on the order.
tagsarrayOptionalThe tags of the order. Supported for SHOPIFY only.
String array.
billing_addressobjectnullablebilling_address attributesrefundsarrayOptionalrefunds attributesshipping_addressobjectnullableshipping_address attributescustomerobjectnullablecustomer attributesline_itemsarrayThe linked variants and quantities associated with this order.
line_items attributesfulfillmentsarrayfulfillments attributestransactionsarrayOptionalAn array of Transactions linked to the order. Included if you pass the expand=transactions query parameter.
transactions attributescreated_atstringThe ISO 8601 timestamp that the order was created.
updated_atstringThe ISO 8601 timestamp that the order was last updated.
List Orders
The /orders endpoint allows developers to receive user-authorized order data for a merchant's store.
Due to the potentially large number of orders associated with an Item, results are paginated. Manipulate the count and offset parameters in conjunction with the total_orders response body field to fetch all available transactions.
Request Parameters
access_tokenstringqueryRequiredThe access token of the connection.
cursorstringqueryOptionalUsed to paginate to the next batch of objects. Should be a copy of the next_cursor value from the previous response.
limitintegerqueryOptionalUsed to limit the number of returned objects. Defaults to 50.
expandenumqueryOptionalOptionally, include transaction information when fetching orders.
created_at_maxintegerqueryOptionalUsed to filter objects with a created_at value less than or equal to the supplied value. Should be a Unix time in milliseconds.
created_at_minintegerqueryOptionalUsed to filter objects with a created_at value greater than or equal to the supplied value. Should be a Unix time in milliseconds.
fulfillment_statusenumqueryOptionalOptionally filter orders by their fulfillment_status. Supported for Squarespace, BigCommerce, Magento, Square, Shopify, Wix, Amazon, Etsy, PrestaShop, eBay, Lazada.
order_numberintegerqueryOptionalOptionally filter by order number. Supported for Squarespace, BigCommerce, Magento, WooCommerce, Square, Wix, Amazon, PrestaShop, eBay.
payment_statusenumqueryOptionalOptionally filters orders by payment_status. Supported for Squarespace, BigCommerce, Magento, Square, Shopify, Wix, Amazon, Etsy, PrestaShop, eBay, Lazada.
phonestringqueryOptionalOptionally filter by phone number. Format using only numerics. Supported for Magento, WooCommerce, Shopify, Wix.
propertiesstringqueryOptionalOptionally return only certain fields specified by a comma-separated list of field names. E.g. id,status
updated_at_maxintegerqueryOptionalUsed to filter objects with a updated_at value less than or equal to the supplied value. Should be a Unix time in milliseconds.
updated_at_minintegerqueryOptionalUsed to filter objects with a updated_at value greater than or equal to the supplied value. Should be a Unix time in milliseconds.
force_fetchenumqueryOptionalUsed to force a response even if the underlying connection has not finished its initial sync.
Response Body
1{
2 "orders": [
3 {
4 "id": "00000000-0000-0000-0000-000000000000",
5 "platform_id": "12345678",
6 "cancelled_at": "2023-01-02T02:34:56.000Z",
7 "payment_status": "paid",
8 "status": "active",
9 "total_discount": 5,
10 "total_price": 37.34,
11 "fulfillment_status": "unfulfilled",
12 "iso_currency_code": "USD",
13 "order_number": "12345",
14 "source_name": "web",
15 "total_line_items_price": 28,
16 "total_shipping": 12.34,
17 "total_shipping_discount": 0,
18 "total_tax": 2,
19 "billing_address": {
20 "address1": "123 Rutter Road",
21 "address2": "Floor 4",
22 "city": "San Francisco",
23 "country_code": "USA",
24 "first_name": "Eric",
25 "last_name": "Yu",
26 "postal_code": "94110",
27 "region": "CA",
28 "phone": "1234567890"
29 },
30 "shipping_address": {
31 "address1": "123 Rutter Road",
32 "address2": "Floor 4",
33 "city": "San Francisco",
34 "country_code": "USA",
35 "first_name": "Eric",
36 "last_name": "Yu",
37 "postal_code": "94110",
38 "region": "CA",
39 "phone": "1234567890"
40 },
41 "customer": {
42 "id": "00000000-0000-0000-0000-000000000000",
43 "platform_id": "12345678",
44 "email": "eric@rutter.com",
45 "first_name": "Eric",
46 "last_name": "Yu",
47 "phone": "1234567890",
48 "created_at": "2023-01-02T02:34:56.000Z",
49 "updated_at": "2023-01-02T02:34:56.000Z"
50 },
51 "line_items": [
52 {
53 "id": "00000000-0000-0000-0000-000000000000",
54 "platform_id": "12345678",
55 "product_id": "00000000-0000-0000-0000-000000000000",
56 "variant_id": "00000000-0000-0000-0000-000000000000",
57 "price": 14,
58 "quantity": 1,
59 "iso_currency_code": "USD",
60 "sku": "Intelligent-Soft-Table-872793",
61 "title": "Handcrafted-Practical Wooden Towels",
62 "unit_cost": 14,
63 "created_at": "2023-01-02T02:34:56.000Z",
64 "updated_at": "2023-01-02T02:34:56.000Z"
65 },
66 {
67 "id": "00000000-0000-0000-0000-000000000000",
68 "platform_id": "12345678",
69 "product_id": "00000000-0000-0000-0000-000000000000",
70 "variant_id": "00000000-0000-0000-0000-000000000000",
71 "price": 14,
72 "quantity": 1,
73 "iso_currency_code": "USD",
74 "sku": "Intelligent-Wooden-Salad-164653",
75 "title": "Incredible-Tasty Fresh Pants",
76 "unit_cost": 14,
77 "created_at": "2023-01-02T02:34:56.000Z",
78 "updated_at": "2023-01-02T02:34:56.000Z"
79 }
80 ],
81 "fulfillments": [
82 {
83 "id": "00000000-0000-0000-0000-000000000000",
84 "order_id": "00000000-0000-0000-0000-000000000000",
85 "carrier": "UPS",
86 "service": "manual",
87 "tracking_number": "https://www.ups.com/WebTracking?loc=en_US&requester=ST&trackNums=ABCDEFGH1234567890",
88 "tracking_url": "ABCDEFGH1234567890",
89 "line_items": [
90 {
91 "id": "00000000-0000-0000-0000-000000000000",
92 "product_id": "00000000-0000-0000-0000-000000000000",
93 "variant_id": "00000000-0000-0000-0000-000000000000",
94 "price": 12.34,
95 "quantity": 2,
96 "sku": "RUTTER-1",
97 "title": "Rutter Shirt (Large)"
98 }
99 ]
100 }
101 ],
102 "transactions": [
103 {
104 "id": "00000000-0000-0000-0000-000000000000",
105 "order_id": "00000000-0000-0000-0000-000000000000",
106 "payment_method_type": "card",
107 "status": "success",
108 "type": "sale",
109 "amount": 31.99,
110 "gateway": "paypal",
111 "gateway_data": null,
112 "iso_currency_code": "USD",
113 "created_at": "2023-02-01T05:21:24.000Z",
114 "updated_at": "2023-02-01T05:21:24.000Z"
115 }
116 ],
117 "created_at": "2023-01-02T02:34:56.000Z",
118 "updated_at": "2023-01-02T02:34:56.000Z"
119 }
120 ],
121 "next_cursor": null,
122 "connection": {
123 "id": "00000000-0000-0000-0000-000000000000",
124 "orgId": "00000000-0000-0000-0000-000000000000",
125 "platform": "SHOPIFY"
126 }
127}
Platform Differences
There can be some differences in field values due to platform-specific limitations or if the connection is missing required scopes.
Amazon
The total_price will be unavailable through the Amazon API and 0 in the following scenarios:
- The order status is cancelled, pending , or unshipped. Cancelled orders do not have this info, whereas pending orders could later be updated to have price info.
- If the order is a replacement order, no price info is available.
- If the order is sold through Non-Amazon sales channel it may not have price info.
Shopify
Rutter supplements the Order object with the following properties from Shopify: name, cancelled_at, source_name, total_line_items_price, tags
Ebay
Rutter currently fetches 90 days worth of orders due to Ebay's own limitation.
Fetch an Order
Request Parameters
idstringpathRequiredThe Rutter generated unique ID of the object.
access_tokenstringqueryRequiredThe access token of the connection.
expandenumqueryOptionalOptionally, include transaction information when fetching orders.
force_fetchenumqueryOptionalUsed to force a response even if the underlying connection has not finished its initial sync.
Response Body
1{
2 "order": {
3 "id": "00000000-0000-0000-0000-000000000000",
4 "platform_id": "12345678",
5 "cancelled_at": "2023-01-02T02:34:56.000Z",
6 "payment_status": "paid",
7 "status": "active",
8 "total_discount": 5,
9 "total_price": 37.34,
10 "fulfillment_status": "unfulfilled",
11 "iso_currency_code": "USD",
12 "order_number": "12345",
13 "source_name": "web",
14 "total_line_items_price": 28,
15 "total_shipping": 12.34,
16 "total_shipping_discount": 0,
17 "total_tax": 2,
18 "billing_address": {
19 "address1": "123 Rutter Road",
20 "address2": "Floor 4",
21 "city": "San Francisco",
22 "country_code": "USA",
23 "first_name": "Eric",
24 "last_name": "Yu",
25 "postal_code": "94110",
26 "region": "CA",
27 "phone": "1234567890"
28 },
29 "shipping_address": {
30 "address1": "123 Rutter Road",
31 "address2": "Floor 4",
32 "city": "San Francisco",
33 "country_code": "USA",
34 "first_name": "Eric",
35 "last_name": "Yu",
36 "postal_code": "94110",
37 "region": "CA",
38 "phone": "1234567890"
39 },
40 "customer": {
41 "id": "00000000-0000-0000-0000-000000000000",
42 "platform_id": "12345678",
43 "email": "eric@rutter.com",
44 "first_name": "Eric",
45 "last_name": "Yu",
46 "phone": "1234567890",
47 "created_at": "2023-01-02T02:34:56.000Z",
48 "updated_at": "2023-01-02T02:34:56.000Z"
49 },
50 "line_items": [
51 {
52 "id": "00000000-0000-0000-0000-000000000000",
53 "platform_id": "12345678",
54 "product_id": "00000000-0000-0000-0000-000000000000",
55 "variant_id": "00000000-0000-0000-0000-000000000000",
56 "price": 14,
57 "quantity": 1,
58 "iso_currency_code": "USD",
59 "sku": "Intelligent-Soft-Table-872793",
60 "title": "Handcrafted-Practical Wooden Towels",
61 "unit_cost": 14,
62 "created_at": "2023-01-02T02:34:56.000Z",
63 "updated_at": "2023-01-02T02:34:56.000Z"
64 },
65 {
66 "id": "00000000-0000-0000-0000-000000000000",
67 "platform_id": "12345678",
68 "product_id": "00000000-0000-0000-0000-000000000000",
69 "variant_id": "00000000-0000-0000-0000-000000000000",
70 "price": 14,
71 "quantity": 1,
72 "iso_currency_code": "USD",
73 "sku": "Intelligent-Wooden-Salad-164653",
74 "title": "Incredible-Tasty Fresh Pants",
75 "unit_cost": 14,
76 "created_at": "2023-01-02T02:34:56.000Z",
77 "updated_at": "2023-01-02T02:34:56.000Z"
78 }
79 ],
80 "fulfillments": [
81 {
82 "id": "00000000-0000-0000-0000-000000000000",
83 "order_id": "00000000-0000-0000-0000-000000000000",
84 "carrier": "UPS",
85 "service": "manual",
86 "tracking_number": "https://www.ups.com/WebTracking?loc=en_US&requester=ST&trackNums=ABCDEFGH1234567890",
87 "tracking_url": "ABCDEFGH1234567890",
88 "line_items": [
89 {
90 "id": "00000000-0000-0000-0000-000000000000",
91 "product_id": "00000000-0000-0000-0000-000000000000",
92 "variant_id": "00000000-0000-0000-0000-000000000000",
93 "price": 12.34,
94 "quantity": 2,
95 "sku": "RUTTER-1",
96 "title": "Rutter Shirt (Large)"
97 }
98 ]
99 }
100 ],
101 "transactions": [
102 {
103 "id": "00000000-0000-0000-0000-000000000000",
104 "order_id": "00000000-0000-0000-0000-000000000000",
105 "payment_method_type": "card",
106 "status": "success",
107 "type": "sale",
108 "amount": 31.99,
109 "gateway": "paypal",
110 "gateway_data": null,
111 "iso_currency_code": "USD",
112 "created_at": "2023-02-01T05:21:24.000Z",
113 "updated_at": "2023-02-01T05:21:24.000Z"
114 }
115 ],
116 "created_at": "2023-01-02T02:34:56.000Z",
117 "updated_at": "2023-01-02T02:34:56.000Z"
118 },
119 "connection": {
120 "id": "00000000-0000-0000-0000-000000000000",
121 "orgId": "00000000-0000-0000-0000-000000000000",
122 "platform": "SHOPIFY"
123 }
124}
Create an Order
Request Parameters
access_tokenstringqueryRequiredThe access token of the connection.
Request Body
orderobjectThe order to create.
order attributesResponse Body
1{
2 "order": {
3 "currency_code": "USD",
4 "line_items": [
5 {
6 "variant_id": "00000000-0000-0000-0000-000000000000",
7 "quantity": 1
8 },
9 {
10 "variant_id": "00000000-0000-0000-0000-000000000000",
11 "quantity": 2
12 }
13 ],
14 "customer": {
15 "email": "eric@rutter.com",
16 "first_name": "Eric",
17 "last_name": "Yu"
18 },
19 "billing_address": {
20 "address1": "123 Rutter Road",
21 "address2": "Floor 4",
22 "city": "San Francisco",
23 "country_code": "USA",
24 "first_name": "Eric",
25 "last_name": "Yu",
26 "postal_code": "94110",
27 "region": "CA",
28 "email": "eric@rutter.com",
29 "phone": "1234567890"
30 },
31 "shipping_address": {
32 "address1": "123 Rutter Road",
33 "address2": "Floor 4",
34 "city": "San Francisco",
35 "country_code": "USA",
36 "first_name": "Eric",
37 "last_name": "Yu",
38 "postal_code": "94110",
39 "region": "CA",
40 "email": "eric@rutter.com",
41 "phone": "1234567890"
42 }
43 }
44}
1{
2 "order": {
3 "id": "00000000-0000-0000-0000-000000000000",
4 "platform_id": "12345678",
5 "cancelled_at": "2023-01-02T02:34:56.000Z",
6 "payment_status": "paid",
7 "status": "active",
8 "total_discount": 5,
9 "total_price": 37.34,
10 "fulfillment_status": "unfulfilled",
11 "iso_currency_code": "USD",
12 "order_number": "12345",
13 "source_name": "web",
14 "total_line_items_price": 28,
15 "total_shipping": 12.34,
16 "total_shipping_discount": 0,
17 "total_tax": 2,
18 "billing_address": {
19 "address1": "123 Rutter Road",
20 "address2": "Floor 4",
21 "city": "San Francisco",
22 "country_code": "USA",
23 "first_name": "Eric",
24 "last_name": "Yu",
25 "postal_code": "94110",
26 "region": "CA",
27 "phone": "1234567890"
28 },
29 "shipping_address": {
30 "address1": "123 Rutter Road",
31 "address2": "Floor 4",
32 "city": "San Francisco",
33 "country_code": "USA",
34 "first_name": "Eric",
35 "last_name": "Yu",
36 "postal_code": "94110",
37 "region": "CA",
38 "phone": "1234567890"
39 },
40 "customer": {
41 "id": "00000000-0000-0000-0000-000000000000",
42 "platform_id": "12345678",
43 "email": "eric@rutter.com",
44 "first_name": "Eric",
45 "last_name": "Yu",
46 "phone": "1234567890",
47 "created_at": "2023-01-02T02:34:56.000Z",
48 "updated_at": "2023-01-02T02:34:56.000Z"
49 },
50 "line_items": [
51 {
52 "id": "00000000-0000-0000-0000-000000000000",
53 "platform_id": "12345678",
54 "product_id": "00000000-0000-0000-0000-000000000000",
55 "variant_id": "00000000-0000-0000-0000-000000000000",
56 "price": 14,
57 "quantity": 1,
58 "iso_currency_code": "USD",
59 "sku": "Intelligent-Soft-Table-872793",
60 "title": "Handcrafted-Practical Wooden Towels",
61 "unit_cost": 14,
62 "created_at": "2023-01-02T02:34:56.000Z",
63 "updated_at": "2023-01-02T02:34:56.000Z"
64 },
65 {
66 "id": "00000000-0000-0000-0000-000000000000",
67 "platform_id": "12345678",
68 "product_id": "00000000-0000-0000-0000-000000000000",
69 "variant_id": "00000000-0000-0000-0000-000000000000",
70 "price": 14,
71 "quantity": 1,
72 "iso_currency_code": "USD",
73 "sku": "Intelligent-Wooden-Salad-164653",
74 "title": "Incredible-Tasty Fresh Pants",
75 "unit_cost": 14,
76 "created_at": "2023-01-02T02:34:56.000Z",
77 "updated_at": "2023-01-02T02:34:56.000Z"
78 }
79 ],
80 "fulfillments": [
81 {
82 "id": "00000000-0000-0000-0000-000000000000",
83 "order_id": "00000000-0000-0000-0000-000000000000",
84 "carrier": "UPS",
85 "service": "manual",
86 "tracking_number": "https://www.ups.com/WebTracking?loc=en_US&requester=ST&trackNums=ABCDEFGH1234567890",
87 "tracking_url": "ABCDEFGH1234567890",
88 "line_items": [
89 {
90 "id": "00000000-0000-0000-0000-000000000000",
91 "product_id": "00000000-0000-0000-0000-000000000000",
92 "variant_id": "00000000-0000-0000-0000-000000000000",
93 "price": 12.34,
94 "quantity": 2,
95 "sku": "RUTTER-1",
96 "title": "Rutter Shirt (Large)"
97 }
98 ]
99 }
100 ],
101 "transactions": [
102 {
103 "id": "00000000-0000-0000-0000-000000000000",
104 "order_id": "00000000-0000-0000-0000-000000000000",
105 "payment_method_type": "card",
106 "status": "success",
107 "type": "sale",
108 "amount": 31.99,
109 "gateway": "paypal",
110 "gateway_data": null,
111 "iso_currency_code": "USD",
112 "created_at": "2023-02-01T05:21:24.000Z",
113 "updated_at": "2023-02-01T05:21:24.000Z"
114 }
115 ],
116 "created_at": "2023-01-02T02:34:56.000Z",
117 "updated_at": "2023-01-02T02:34:56.000Z"
118 }
119}
Update an Order
Request Parameters
idstringpathRequiredThe Rutter generated unique ID of the object.
access_tokenstringqueryRequiredThe access token of the connection.
Request Body
orderobjectorder attributesResponse Body
1{
2 "order": {
3 "status": "cancelled"
4 }
5}
1{
2 "order": {
3 "id": "00000000-0000-0000-0000-000000000000",
4 "platform_id": "12345678",
5 "cancelled_at": "2023-01-02T02:34:56.000Z",
6 "payment_status": "paid",
7 "status": "active",
8 "total_discount": 5,
9 "total_price": 37.34,
10 "fulfillment_status": "unfulfilled",
11 "iso_currency_code": "USD",
12 "order_number": "12345",
13 "source_name": "web",
14 "total_line_items_price": 28,
15 "total_shipping": 12.34,
16 "total_shipping_discount": 0,
17 "total_tax": 2,
18 "billing_address": {
19 "address1": "123 Rutter Road",
20 "address2": "Floor 4",
21 "city": "San Francisco",
22 "country_code": "USA",
23 "first_name": "Eric",
24 "last_name": "Yu",
25 "postal_code": "94110",
26 "region": "CA",
27 "phone": "1234567890"
28 },
29 "shipping_address": {
30 "address1": "123 Rutter Road",
31 "address2": "Floor 4",
32 "city": "San Francisco",
33 "country_code": "USA",
34 "first_name": "Eric",
35 "last_name": "Yu",
36 "postal_code": "94110",
37 "region": "CA",
38 "phone": "1234567890"
39 },
40 "customer": {
41 "id": "00000000-0000-0000-0000-000000000000",
42 "platform_id": "12345678",
43 "email": "eric@rutter.com",
44 "first_name": "Eric",
45 "last_name": "Yu",
46 "phone": "1234567890",
47 "created_at": "2023-01-02T02:34:56.000Z",
48 "updated_at": "2023-01-02T02:34:56.000Z"
49 },
50 "line_items": [
51 {
52 "id": "00000000-0000-0000-0000-000000000000",
53 "platform_id": "12345678",
54 "product_id": "00000000-0000-0000-0000-000000000000",
55 "variant_id": "00000000-0000-0000-0000-000000000000",
56 "price": 14,
57 "quantity": 1,
58 "iso_currency_code": "USD",
59 "sku": "Intelligent-Soft-Table-872793",
60 "title": "Handcrafted-Practical Wooden Towels",
61 "unit_cost": 14,
62 "created_at": "2023-01-02T02:34:56.000Z",
63 "updated_at": "2023-01-02T02:34:56.000Z"
64 },
65 {
66 "id": "00000000-0000-0000-0000-000000000000",
67 "platform_id": "12345678",
68 "product_id": "00000000-0000-0000-0000-000000000000",
69 "variant_id": "00000000-0000-0000-0000-000000000000",
70 "price": 14,
71 "quantity": 1,
72 "iso_currency_code": "USD",
73 "sku": "Intelligent-Wooden-Salad-164653",
74 "title": "Incredible-Tasty Fresh Pants",
75 "unit_cost": 14,
76 "created_at": "2023-01-02T02:34:56.000Z",
77 "updated_at": "2023-01-02T02:34:56.000Z"
78 }
79 ],
80 "fulfillments": [
81 {
82 "id": "00000000-0000-0000-0000-000000000000",
83 "order_id": "00000000-0000-0000-0000-000000000000",
84 "carrier": "UPS",
85 "service": "manual",
86 "tracking_number": "https://www.ups.com/WebTracking?loc=en_US&requester=ST&trackNums=ABCDEFGH1234567890",
87 "tracking_url": "ABCDEFGH1234567890",
88 "line_items": [
89 {
90 "id": "00000000-0000-0000-0000-000000000000",
91 "product_id": "00000000-0000-0000-0000-000000000000",
92 "variant_id": "00000000-0000-0000-0000-000000000000",
93 "price": 12.34,
94 "quantity": 2,
95 "sku": "RUTTER-1",
96 "title": "Rutter Shirt (Large)"
97 }
98 ]
99 }
100 ],
101 "transactions": [
102 {
103 "id": "00000000-0000-0000-0000-000000000000",
104 "order_id": "00000000-0000-0000-0000-000000000000",
105 "payment_method_type": "card",
106 "status": "success",
107 "type": "sale",
108 "amount": 31.99,
109 "gateway": "paypal",
110 "gateway_data": null,
111 "iso_currency_code": "USD",
112 "created_at": "2023-02-01T05:21:24.000Z",
113 "updated_at": "2023-02-01T05:21:24.000Z"
114 }
115 ],
116 "created_at": "2023-01-02T02:34:56.000Z",
117 "updated_at": "2023-01-02T02:34:56.000Z"
118 },
119 "connection": {
120 "id": "00000000-0000-0000-0000-000000000000",
121 "orgId": "00000000-0000-0000-0000-000000000000",
122 "platform": "SHOPIFY"
123 }
124}
Have questions?
Contact support for personalized guidance.