Skip to content

Commit 3465a8e

Browse files
alexphelpsalexphelps
committed
add collect payment endpoint step for swap items flow
1 parent abcd60c commit 3465a8e

1 file changed

Lines changed: 116 additions & 103 deletions

File tree

‎docs/api/admin/guides/order-management.md‎

Lines changed: 116 additions & 103 deletions
Original file line numberDiff line numberDiff line change
@@ -5,12 +5,128 @@ sidebar_position: 1
55
tags:
66
- Guide
77
---
8+
import MoveFulfillmentOrders from '@site/_snippets/_moving-fulfillment-orders.mdx';
89

910
Order management operations can be automated through the Admin API for more efficient operations and bulk actions on large quanities of orders.
1011

1112
Below are best practices and guides for common scenarios merchants and partners use to manage orders on the Admin API.
1213

1314

15+
### Order Items Editing
16+
17+
Editing items on an order is common practice, such as swapping products purchased for a different size or color with the same value without needing to collect payment or create a refund.
18+
19+
:::info Only Available on 2024-04-01 API Version
20+
Order editing APIs are only available on 2024-04-01 API Version and above, if you are still using older versions we recommend you upgrade your integration.
21+
22+
Order editing APIs also do not affect order payment within each request. To remove items with an associated refund, see [order refunds](#order-refunds). Using order edit APIs can result in the customer owing or the merchant owing to the customer.
23+
:::
24+
25+
#### Line Item Quantities Explained
26+
27+
Order line items have 4 quantity attributes that represent quantities at different states in an order life cycle.
28+
29+
- `quantity` - Item quantity total ever added to the order in this line.
30+
- `current_quantity` - Current item quantity that have not yet been removed.
31+
- `fulfillable_quantity` - Item quantity that have not yet been fulfilled, such as a partial fulfillment.
32+
- `editable_quantity` - Item quantity that currently can be edited.
33+
34+
```json title="Line Item Quantities Explained"
35+
"lines": [
36+
{
37+
...
38+
"quantity": 3, // quantity of items ever added
39+
"current_quantity": 2, // current quantity that have not been removed
40+
"fulfillable_quantity": 1, // quantity that have not yet been fulfilled
41+
"editable_quantity": 1, // quantity that can be edited
42+
...
43+
}
44+
]
45+
```
46+
47+
### Swap Items Flow
48+
49+
```mermaid
50+
stateDiagram-v2
51+
direction LR
52+
lines: Retrieve Order Lines
53+
removeLine: Remove Unwanted Items
54+
addLine: Add New Items
55+
collectPayment: Collect Payment
56+
lines --> removeLine
57+
removeLine --> addLine
58+
addLine --> collectPayment
59+
```
60+
61+
Swapping Items on an order is a 4 step process:
62+
63+
1. Retrieve order line items using the [ordersRetrieve](/docs/api/admin/reference/?v=2024-04-01#/operations/ordersRetrieve) endpoint and check `editable_quantity` is > 0.
64+
2. Update/Remove line items using the [ordersLinesPartialUpdate](/docs/api/admin/reference/?v=2024-04-01#/operations/ordersLinesPartialUpdate) or [ordersLinesDestroy](/docs/api/admin/reference/?v=2024-04-01#/operations/ordersLinesDestroy) endpoint.
65+
3. Create new line item [ordersLinesCreate](/docs/api/admin/reference/?v=2024-04-01#/operations/ordersLinesCreate) endpoint.
66+
4. [Collect payment for an outstanding](#collect-payment-for-outstanding-balance) balance using the [ordersCollectPaymentCreate](/docs/api/admin/reference/?v=2024-04-01#/operations/ordersCollectPaymentCreate) endpoint.
67+
68+
69+
#### Update Existing Line Item
70+
71+
Below is an example API call to change the quantity of a line item to 1. If the existing quantity was 2, this would remove 1 quantity, can also be used to increase line item quantity. This endpoint only accepts quantity changes, to change the product or price, see [ordersLinesCreate](/docs/api/admin/reference/?v=2024-04-01#/operations/ordersLinesCreate) endpoint.
72+
73+
```json title="Update Existing Line Item"
74+
// PATCH https://{store}.29next.store/api/admin/orders/{number}/lines/{lineID}/
75+
// -H "Authorization: Bearer <API ACCESS TOKEN>" -H "X-29Next-Api-Version: 2024-04-01"
76+
77+
{
78+
"quantity": 1, // change quantity to 1
79+
"reason": "product swap" // optional
80+
}
81+
```
82+
83+
#### Remove Full Line Item
84+
85+
Below is an example DELETE request to the [ordersLinesDestroy](/docs/api/admin/reference/?v=2024-04-01#/operations/ordersLinesDestroy) endpoint to remove a line item.
86+
87+
```json title="Remove Line Item"
88+
// DELETE https://{store}.29next.store/api/admin/orders/{number}/lines/{lineID}/
89+
// -H "Authorization: Bearer <API ACCESS TOKEN>" -H "X-29Next-Api-Version: 2024-04-01"
90+
```
91+
92+
93+
:::info Check Line Item Editable Quantity
94+
Line items have `editable_quantity` which represents the item quantity not already in process of being fulfilled, already fulfilled, or already removed from the order.
95+
96+
**If `editable_quantity` is `0`, the line item cannot be edited.**
97+
:::
98+
99+
100+
#### Create New Line Item
101+
102+
Below is an example POST request to the [ordersLinesCreate](/docs/api/admin/reference/?v=2024-04-01#/operations/ordersLinesCreate) endpoint to create a new line item.
103+
104+
```json title="Create New Line Item"
105+
// POST https://{store}.29next.store/api/admin/orders/{number}/lines/
106+
// -H "Authorization: Bearer <API ACCESS TOKEN>" -H "X-29Next-Api-Version: 2024-04-01"
107+
108+
{
109+
"product_id": 184,
110+
"quantity": 1,
111+
"price": 89.99, // optional
112+
"reason": "product swap" // optional
113+
}
114+
```
115+
116+
#### Collect Payment for Outstanding Balance
117+
118+
Orders can have an outstanding balance owed by the customer as a result of changing items on the order. To collect the outstanding balance, use the [ordersCollectPaymentCreate](/docs/api/admin/reference/?v=2024-04-01#/operations/ordersCollectPaymentCreate) endpoint to initate a payment transaction with the order's initial payment method.
119+
120+
```json title="Collect Payment for Outstanding Balance"
121+
// POST https://{store}.29next.store/api/admin/orders/{number}/collect-payment/
122+
// -H "Authorization: Bearer <API ACCESS TOKEN>" -H "X-29Next-Api-Version: 2024-04-01"
123+
124+
{
125+
"send_payment_notification": true // optionally send notificaiton to customer
126+
}
127+
```
128+
129+
:::
14130

15131
### Order Refunds
16132

@@ -152,104 +268,6 @@ Depending on the product type and status of the line items being refunded, there
152268
- If fulfilled, restock_type must be `no_restock`.
153269
:::
154270

155-
### Order Items Editing
156-
157-
Editing items on an order is common practice, such as swapping products purchased for a different size or color with the same value without needing to collect payment or create a refund.
158-
159-
:::info Only Available on 2024-04-01 API Version
160-
Order editing APIs are only available on 2024-04-01 API Version and above, if you are still using older versions we recommend you upgrade your integration.
161-
162-
Order editing APIs also do not affect order payment within each request. To remove items with an associated refund, see [order refunds](#order-refunds). Using order edit APIs can result in the customer owing or the merchant owing to the customer.
163-
:::
164-
165-
#### Line Item Quantities Explained
166-
167-
Order line items have 4 quantity attributes that represent quantities at different states in an order life cycle.
168-
169-
- `quantity` - Item quantity total ever added to the order in this line.
170-
- `current_quantity` - Current item quantity that have not yet been removed.
171-
- `fulfillable_quantity` - Item quantity that have not yet been fulfilled, such as a partial fulfillment.
172-
- `editable_quantity` - Item quantity that currently can be edited.
173-
174-
```json title="Line Item Quantities Explained"
175-
"lines": [
176-
{
177-
...
178-
"quantity": 3, // quantity of items ever added
179-
"current_quantity": 2, // current quantity that have not been removed
180-
"fulfillable_quantity": 1, // quantity that have not yet been fulfilled
181-
"editable_quantity": 1, // quantity that can be edited
182-
...
183-
}
184-
]
185-
```
186-
187-
#### Swap Items Flow
188-
189-
```mermaid
190-
stateDiagram-v2
191-
direction LR
192-
lines: Retrieve Order Lines
193-
removeLine: Remove Unwanted Items
194-
addLine: Add Line Item
195-
lines --> removeLine
196-
removeLine --> addLine
197-
```
198-
199-
Swapping Items on an order is a 3-step process:
200-
1. Retrieve order line items using the [ordersRetrieve](/docs/api/admin/reference/?v=2024-04-01#/operations/ordersRetrieve) endpoint to obtain line items and check `editable_quantity` is > 0.
201-
2. Update/Remove line items using the [ordersLinesPartialUpdate](/docs/api/admin/reference/?v=2024-04-01#/operations/ordersLinesPartialUpdate) or [ordersLinesDestroy](/docs/api/admin/reference/?v=2024-04-01#/operations/ordersLinesDestroy) endpoint.
202-
3. Create new line item [ordersLinesCreate](/docs/api/admin/reference/?v=2024-04-01#/operations/ordersLinesCreate) endpoint.
203-
204-
205-
#### Update Existing Line Item
206-
207-
Below is an example API call to change the quantity of a line item to 1. If the existing quantity was 2, this would remove 1 quantity, can also be used to increase line item quantity. This endpoint only accepts quantity changes, to change the product or price, see [ordersLinesCreate](/docs/api/admin/reference/?v=2024-04-01#/operations/ordersLinesCreate) endpoint.
208-
209-
```json title="Update Existing Line Item"
210-
// PATCH https://{store}.29next.store/api/admin/orders/{number}/lines/{lineID}/
211-
// -H "Authorization: Bearer <API ACCESS TOKEN>" -H "X-29Next-Api-Version: 2024-04-01"
212-
213-
{
214-
"quantity": 1, // change quantity to 1
215-
"reason": "product swap" // optional
216-
}
217-
```
218-
219-
#### Remove Full Line Item
220-
221-
Below is an example DELETE request to the [ordersLinesDestroy](/docs/api/admin/reference/?v=2024-04-01#/operations/ordersLinesDestroy) endpoint to remove a line item.
222-
223-
```json title="Remove Line Item"
224-
// DELETE https://{store}.29next.store/api/admin/orders/{number}/lines/{lineID}/
225-
// -H "Authorization: Bearer <API ACCESS TOKEN>" -H "X-29Next-Api-Version: 2024-04-01"
226-
```
227-
228-
229-
:::info Check Line Item Editable Quantity
230-
Line items have `editable_quantity` which represents the item quantity not already in process of being fulfilled, already fulfilled, or already removed from the order.
231-
232-
**If `editable_quantity` is `0`, the line item cannot be edited.**
233-
:::
234-
235-
236-
#### Create New Line Item
237-
238-
Below is an example POST request to the [ordersLinesCreate](/docs/api/admin/reference/?v=2024-04-01#/operations/ordersLinesCreate) endpoint to create a new line item.
239-
240-
```json title="Create New Line Item"
241-
// POST https://{store}.29next.store/api/admin/orders/{number}/lines/
242-
// -H "Authorization: Bearer <API ACCESS TOKEN>" -H "X-29Next-Api-Version: 2024-04-01"
243-
244-
{
245-
"product_id": 184,
246-
"quantity": 1,
247-
"price": 89.99, // optional
248-
"reason": "product swap" // optional
249-
}
250-
```
251-
252-
253271
### Update Shipping Address
254272

255273
Updating an order shipping address is a common task that can be done with a PATCH request to the [ordersUpdate](/docs/api/admin/reference/#/operations/ordersUpdate) endpoint.
@@ -347,12 +365,7 @@ stateDiagram-v2
347365

348366
### Move Fulfillment Orders
349367

350-
```mdx-code-block
351-
352-
import MoveFulfillmentOrders from '@site/_snippets/_moving-fulfillment-orders.mdx';
353-
354368
<MoveFulfillmentOrders />
355-
```
356369

357370
### Cancel Order
358371

0 commit comments

Comments
 (0)