Getting started
Fetching relationships
How to directly fetch related resources
You can fetch either single related resources or collections by sending
GET requests to the "related" link /api/<parent_resource>/:id/<related_resource> (i.e. the parent resource endpoint, specifying the single parent resource ID and the related resource you want to retrieve).Make sure to use the relationship name and not the resource name (e.g., if you want to retrieve the billing address associated with an order, use
billing_address and not just addresses — see example)When fetching a list of related resources results can be sorted (see example) and filtered (see examples).
Examples
Fetching a single related resource (1:1 relationship)
Request
Response
The following request fetches the billing address associated with the order identified by the ID "xYZkjABcde":
1
curl -g -X GET \
2
'https://yourdomain.commercelayer.io/api/orders/xYZkjABcde/billing_address' \
3
-H 'Accept: application/vnd.api+json' \
4
-H 'Authorization: Bearer your-access-token'
Copied!
On success, the API responds with a
200 OK status code, returning the single related resource object:1
{
2
"data": {
3
"id": "yzXKjYzaCx",
4
"type": "addresses",
5
"links": {...},
6
"attributes": {
7
"business": false,
8
"first_name": "John",
9
"last_name": "Doe",
10
"company": null,
11
"full_name": "John Doe",
12
"line_1": "1234 5th Avenue",
13
"line_2": null,
14
"city": "New York",
15
"zip_code": "10018",
16
"state_code": "NY",
17
"country_code": "US",
18
"phone": "646-1234567",
19
"full_address": "1234 5th Avenue, 10018 New York NY (US) 646-1234567",
20
"name": "John Doe, 1234 5th Avenue, 10018 New York NY (US) 646-1234567",
21
"email": null,
22
"notes": null,
23
"lat": null,
24
"lng": null,
25
"is_localized": false,
26
"is_geocoded": false,
27
"provider_name": null,
28
"map_url": null,
29
"static_map_url": null,
30
"billing_info": null,
31
"created_at": "2018-01-01T12:00:00.000Z",
32
"updated_at": "2018-01-01T12:00:00.000Z",
33
"reference": null,
34
"reference_origin": null,
35
"metadata": {}
36
},
37
"relationships": {
38
"geocoder": {
39
"links": {...}
40
}
41
},
42
"meta": {
43
"mode": "test",
44
"organization_id": "JxYabZKcAw"
45
}
46
}
47
}
Copied!
Fetching a list of related resources (1:N relationship)
Request
Response
The following request fetches the order history of a specific customer, i.e. the list of orders associated with the customer identified by the ID "xYZkjABcde":
1
curl -g -X GET \
2
'https://yourdomain.commercelayer.io/api/customers/xYZkjABcde/orders' \
3
-H 'Accept: application/vnd.api+json' \
4
-H 'Authorization: Bearer your-access-token'
Copied!
On success, the API responds with a
200 OK status code, returning a paginated collection of the related resource objects:1
{
2
"data": [
3
{
4
"id": "yzXKjYzaCx",
5
"type": "orders",
6
"links": {...},
7
"attributes": {
8
"number": 1234,
9
"autorefresh": true,
10
"status": "pending",
11
"payment_status": "unpaid",
12
"fulfillment_status": "unfulfilled",
13
"guest": false,
14
"editable": true,
15
"customer_email": "[email protected]",
16
"language_code": "en",
17
"currency_code": "USD",
18
"tax_included": false,
19
"tax_rate": null,
20
"freight_taxable": null,
21
"requires_billing_info": false,
22
"country_code": "US",
23
"shipping_country_code_lock": null,
24
"coupon_code": null,
25
"gift_card_code": null,
26
"gift_card_or_coupon_code": null,
27
"subtotal_amount_cents": 3480,
28
"subtotal_amount_float": 34.8,
29
"formatted_subtotal_amount": "$34.80",
30
"shipping_amount_cents": 700,
31
"shipping_amount_float": 7.0,
32
"formatted_shipping_amount": "$7.00",
33
"payment_method_amount_cents": 0,
34
"payment_method_amount_float": 0.0,
35
"formatted_payment_method_amount": "$0.00",
36
"discount_amount_cents": 0,
37
"discount_amount_float": 0.0,
38
"formatted_discount_amount": "$0.00",
39
"adjustment_amount_cents": 0,
40
"adjustment_amount_float": 0.0,
41
"formatted_adjustment_amount": "$0.00",
42
"gift_card_amount_cents": 0,
43
"gift_card_amount_float": 0.0,
44
"formatted_gift_card_amount": "$0.00",
45
"total_tax_amount_cents": 0,
46
"total_tax_amount_float": 0.0,
47
"formatted_total_tax_amount": "$0.00",
48
"subtotal_tax_amount_cents": 0,
49
"subtotal_tax_amount_float": 0.0,
50
"formatted_subtotal_tax_amount": "$0.00",
51
"shipping_tax_amount_cents": 0,
52
"shipping_tax_amount_float": 0.0,
53
"formatted_shipping_tax_amount": "$0.00",
54
"payment_method_tax_amount_cents": 0,
55
"payment_method_tax_amount_float": 0.0,
56
"formatted_payment_method_tax_amount": "$0.00",
57
"adjustment_tax_amount_cents": 0,
58
"adjustment_tax_amount_float": 0.0,
59
"formatted_adjustment_tax_amount": "$0.00",
60
"total_amount_cents": 4180,
61
"total_amount_float": 41.8,
62
"formatted_total_amount": "$41.80",
63
"total_taxable_amount_cents": 4180,
64
"total_taxable_amount_float": 41.8,
65
"formatted_total_taxable_amount": "$41.80",
66
"subtotal_taxable_amount_cents": 3480,
67
"subtotal_taxable_amount_float": 34.8,
68
"formatted_subtotal_taxable_amount": "$34.80",
69
"shipping_taxable_amount_cents": 700,
70
"shipping_taxable_amount_float": 7.0,
71
"formatted_shipping_taxable_amount": "$7.00",
72
"payment_method_taxable_amount_cents": 0,
73
"payment_method_taxable_amount_float": 0.0,
74
"formatted_payment_method_taxable_amount": "$0.00",
75
"adjustment_taxable_amount_cents": 0,
76
"adjustment_taxable_amount_float": 0.0,
77
"formatted_adjustment_taxable_amount": "$0.00",
78
"total_amount_with_taxes_cents": 4180,
79
"total_amount_with_taxes_float": 41.8,
80
"formatted_total_amount_with_taxes": "$41.80",
81
"fees_amount_cents": 0,
82
"fees_amount_float": 0.0,
83
"formatted_fees_amount": "$0.00",
84
"duty_amount_cents": null,
85
"duty_amount_float": null,
86
"formatted_duty_amount": null,
87
"skus_count": 1,
88
"line_item_options_count": 0,
89
"shipments_count": 1,
90
"payment_source_details": null,
91
"token": "y0ur-t0K3n",
92
"cart_url": null,
93
"return_url": null,
94
"terms_url": null,
95
"privacy_url": null,
96
"checkout_url": "https://your-checkout-url/yzXKjYzaCx",
97
"placed_at": null,
98
"approved_at": null,
99
"cancelled_at": null,
100
"payment_updated_at": null,
101
"fulfillment_updated_at": null,
102
"refreshed_at": null,
103
"archived_at": null,
104
"expires_at": null,
105
"created_at": "2018-01-01T12:00:00.000Z",
106
"updated_at": "2018-01-01T12:00:00.000Z",
107
"reference": "",
108
"reference_origin": null,
109
"metadata": {}
110
},
111
"relationships": {
112
"market": {
113
"links": {...}
114
},
115
"customer": {
116
"links": {...}
117
},
118
"shipping_address": {
119
"links": {...}
120
},
121
"billing_address": {
122
"links": {...}
123
},
124
"available_payment_methods": {
125
"links": {...}
126
},
127
"available_customer_payment_sources": {
128
"links": {...}
129
},
130
"payment_method": {
131
"links": {...}
132
},
133
"payment_source": {
134
"links": {...}
135
},
136
"line_items": {
137
"links": {...}
138
},
139
"shipments": {
140
"links": {...}
141
},
142
"transactions": {
143
"links": {...}
144
},
145
"authorizations": {
146
"links": {...}
147
},
148
"captures": {
149
"links": {...}
150
},
151
"voids": {
152
"links": {...}
153
},
154
"refunds": {
155
"links": {...}
156
},
157
"order_subscriptions": {
158
"links": {...}
159
},
160
"order_copies": {
161
"links": {...}
162
},
163
"attachments": {
164
"links": {...}
165
}
166
},
167
"meta": {
168
"mode": "test",
169
"organization_id": "JxYabZKcAw"
170
}
171
},
172
{
173
"other": "... 9 orders (first page)"
174
}
175
],
176
"meta": {
177
"record_count": 70,
178
"page_count": 7
179
},
180
"links": {
181
"first": "https://yourdomain.commercelayer.io/api/customers/xYZkjABcde/orders?page[number]=1&page[size]=10",
182
"next": "https://yourdomain.commercelayer.io/api/customers/xYZkjABcde/orders?page[number]=2&page[size]=10",
183
"last": "https://yourdomain.commercelayer.io/api/customers/xYZkjABcde/orders?page[number]=7&page[size]=10"
184
}
185
}
Copied!
Last modified 2mo ago
Copy link
Contents
Examples