Capture order

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.

Works on NotActivated and PartActivated orders

Any other status is rejected. See Order lifecycle for what each status allows, and 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 that partial captures can be matched against.

Request

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"
}

Response

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.

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.

Request

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
    }
  ]
}

Response

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.

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.

Request

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"
}

Response

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.

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.

Request

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
}

Response

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

See Errors for what to do about each of these.

Data Model

Request

Request headers

Header	Required	Explanation
Authorization	Yes	See 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

Response

A successful capture or part capture answers 202 Accepted with an empty body and a Location header pointing at the order.

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 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

Retry safely with an idempotency key

A response you never receive, because of a network problem for example, leaves you unsure whether the request went through. Retrying it blind risks doing the same thing twice.

Generate a v4 UUID and send it as the Walley-Idempotency header on every unique operation:

Walley-Idempotency: 03304b06-cb33-4f78-bcea-86cb4b202ba0

Retry with the same key and Walley applies the operation only once.