--- id: capture title: "Capture order" sidebar_label: Capture order hide_title: true description: "Management API - Orders - Capture order" --- import Tabs from "@theme/Tabs"; import TabItem from "@theme/TabItem"; import Ingress from "../../../src/components/ingress/ingress.react"; import Idempotency from "../idempotency.mdx"; When order items are ready to be delivered to the end customer they should be captured. Use this endpoint to capture the entire order, part capture individual items, or a specific quantity of items of an order. :::note Works on `NotActivated` and `PartActivated` orders Any other status is rejected. See [Order lifecycle](/docs/manage/concepts/order-lifecycle) for what each status allows, and [Asynchronous operations](/docs/manage/concepts/asynchronous-operations) for why a brand new order can answer `403` or `404` for a few seconds. ::: ## Examples ### Full capture You can capture the entire order by specifying the amount to capture. This only allows for the full amount left on the order to be captured. If you are doing a part capture, you will have to provide [items in the request](/docs/manage/orders/models/capture-item) that partial captures can be matched against. ```http POST /manage/orders/{{orderId}}/capture HTTP/1.1 Host: api.uat.walleydev.com // Test environment. Production uses a different hostname. Authorization: Bearer {{accessToken}} Content-Type: application/json { "amount": 285.0, "description": "Capture description", "actionReference": "test-captureref-123" } ``` ```http HTTP/1.1 202 Accepted Location: /manage/orders/1b1f5ef6-92n1-4b46-b1dc-ae2e00c4c315 /* No body */ ``` ### Part capture You can capture part of the order by providing order items, specifying quantity to capture. :::note Items are matched on a best effort basis The more data you send, the more likely it is that Walley finds a unique article. If no unique match can be made, the request fails. `unitPrice` and `quantity` are required. ::: ```http POST /manage/orders/{{orderId}}/capture HTTP/1.1 Host: api.uat.walleydev.com // Test environment. Production uses a different hostname. Authorization: Bearer {{accessToken}} Content-Type: application/json { "amount": 285.0, "actionReference": "test-captureref-123", "items": [ { "id": "10001", "description": "Shoes", "unitPrice": 95, "quantity": 1 }, { "id": "10002", "description": "T-Shirt", "unitPrice": 95, "quantity": 2 } ] } ``` ```http HTTP/1.1 202 Accepted Location: /manage/orders/1b1f5ef6-92n1-4b46-b1dc-ae2e00c4c315 /* No body */ ``` ### Part capture by amount You can also capture part of the order by providing an amount only, omitting the items. The 'description' field can be used to provide a description. If omitted, left blank or null a default value will be used. :::danger Capturing by amount discards the line items This is available on B2C stores only. Capturing by amount replaces every line item already on the order. The customer sees less detail, and you can no longer capture against the original items. There is no way back once you do it. ::: ```http POST /manage/orders/{{orderId}}/capture HTTP/1.1 Host: api.uat.walleydev.com // Test environment. Production uses a different hostname. Authorization: Bearer {{accessToken}} Content-Type: application/json { "amount": 285.0, "description": "capture description", "actionReference": "test-captureref-123" } ``` ```http HTTP/1.1 202 Accepted Location: /manage/orders/1b1f5ef6-92n1-4b46-b1dc-ae2e00c4c315 /* No body */ ``` ### Full or part capture while replacing items You have the option to fully or partially capture an order while simultaneously replacing the ordered items. This can be achieved by specifying the new items and including a parameter to override the default matching behavior. :::note Set `replaceItems` to `true` Without it, the existing items on the order are not overwritten. On a partial capture, the remaining uncaptured amount is consolidated into a single uncaptured row without VAT. You can call this endpoint again to add more items. Send every field so the new items show up correctly on the invoice. ::: ```http POST /manage/orders/{{orderId}}/capture HTTP/1.1 Host: api.uat.walleydev.com // Test environment. Production uses a different hostname. Authorization: Bearer {{accessToken}} Content-Type: application/json { "amount": 285.0, "actionReference": "test-captureref-123", "items": [ { "id": "10001", "description": "Shoes", "unitPrice": 95, "quantity": 1, "vat": 25 }, { "id": "10002", "description": "T-Shirt", "unitPrice": 95, "quantity": 2, "vat": 25 } ], "replaceItems": true } ``` ```http HTTP/1.1 202 Accepted Location: /manage/orders/1b1f5ef6-92n1-4b46-b1dc-ae2e00c4c315 /* No body */ ``` | Http status code | Description | | ---------------- | ------------------------------------------------------------------------------------------- | | 202 | Capture accepted | | 401 | Token missing, expired, or invalid | | 403 | No permission for this store, or the order has not finished syncing | | 404 | Order not found, or the order has not finished syncing | | 409 | A request with the same idempotency key is already in progress | | 422 | Validation or state error. See [error codes](/docs/manage/orders/capture#error-codes) | See [Errors](/docs/manage/errors) for what to do about each of these. ## Data Model ### Request #### Request headers | Header | Required | Explanation | | ----------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- | | **Authorization** | Yes | See [Authentication](/docs/manage/getting-started/authentication) for how to generate the Bearer token value | #### Request body | Property | Required | Explanation | Type | Notes | | ------------------- | -------- | -------------------------------------------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------- | | **amount** | Yes | The amount to capture. Must match provided total summary of order items being captured. | number | Maximum 2 decimals | | **description** | No | A description for the capture. This will be visible in the order history and on the invoice. | string | Visible on invoices if applicable. Maximum 50 characters. | | **actionReference** | No | A reference to this specific capture. This will be visible on settlement files for reconciliation. | string | This will appear as a data property on the settlement report. Maximum 255 characters. | | **items** | No | The article items and quantity to capture. | array | [Capture Item](/docs/manage/orders/models/capture-item) | ### Response A successful capture or part capture answers `202 Accepted` with an empty body and a `Location` header pointing at the order. :::note The capture is not live yet `202` means Walley accepted the request, not that it has been applied. Reading the order back right away usually returns the old version. See [Asynchronous operations](/docs/manage/concepts/asynchronous-operations) for how to read the result and retry safely. ::: ### Error codes | Code | Message | | ---------------------------------------------- | ---------------------------------------------------------------------------------------------- | | CAPTURE_ITEMS_AMOUNT_NOT_EQUAL_TO_TOTAL_AMOUNT | When items are provided, amount must equal to total sum of the items | | CAPTURE_DESCRIPTION_TOO_LONG | Description has a max limit of 50 characters | | CAPTURE_AMOUNT_MUST_NOT_BE_NEGATIVE | The amount to be captured must be zero or greater | | CAPTURE_AMOUNT_TOO_LARGE | The amount to be captured cannot be larger than the sum of all items | | CAPTURE_AMOUNT_HAS_TOO_MANY_DECIMALS | The amount to be captured cannot have more than 2 decimals | | CAPTURE_ORDER_ALREADY_CAPTURED | A captured order cannot be captured again | | CAPTURE_AMOUNT_GREATER_THAN_INVOICE_AMOUNT | The amount to be captured cannot be larger than the current order amount | | CAPTURE_ITEMS_UNITPRICE_HAS_TOO_MANY_DECIMALS | The UnitPrice of an item in the items list has too many decimals | | CAPTURE_INVALID_INVOICE_STATUS | You cannot capture an order in state closed or expired | | CAPTURE_ITEMS_MISSING_ID | When replacing items Id has to be set | | CAPTURE_ACTIVATION_OF_INVOICE_DENIED | Capture was denied because the order or customer state does not allow the order to be captured |