Skip to main content

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.

Full capture​

You can capture the entire order by simply 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.

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

Part capture​

You can capture part of the order by providing order items, specifying quantity to capture.

Please note

The item object is a best match effort. This means that the more data you provide the probability of finding a unique article will increase. If no unique match can be made an error will be thrown. You are required to provide the unitPrice and quantity property.

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


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.

Please note

This is only available for B2C stores

Capturing by amount will replace any line items previously present on the order.

Not only will the customer experience be slightly worse, but you can no longer capture on the original line items.

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

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.

Please note

When performing a partial capture, the remaining uncaptured amount will be consolidated into a single uncaptured row without VAT. You can call this endpoint multiple times to add new items if needed. Include all fields to ensure the new items are properly displayed on the invoice.

Remember to set replaceItems to true in order to overwrite the existing items on the order.

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 status codeDescription
202Capture accepted
401Token missing, expired, or invalid
403No permission for this store, or the order has not finished syncing
404Order not found, or the order has not finished syncing
409A request with the same idempotency key is already in progress
422Validation or state error. See error codes

See Errors for what to do about each of these.

Data Model​

Request​

Request headers​
HeaderRequiredExplanation
AuthorizationYesInstructions on how to generate the Bearer token value can be found here
Request body​
PropertyRequiredExplanationTypeNotes
amountYesThe amount to capture. Must match provided total summary of order items being captured.numberMaximum 2 decimals
descriptionNoA description for the capture. This will be visible in the order history and on the invoice.stringVisible on invoices if applicable. Maximum 50 characters.
actionReferenceNoA reference to this specific capture. This will be visible on settlement files for reconciliation.stringThis will appear as a data property on the settlement report. Maximum 255 characters.
itemsNoThe article items and quantity to capture.arrayCapture 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​

CodeMessage
CAPTURE_ITEMS_AMOUNT_NOT_EQUAL_TO_TOTAL_AMOUNTWhen items are provided, amount must equal to total sum of the items
CAPTURE_DESCRIPTION_TOO_LONGDescription has a max limit of 50 characters
CAPTURE_AMOUNT_MUST_NOT_BE_NEGATIVEThe amount to be captured must be zero or greater
CAPTURE_AMOUNT_TOO_LARGEThe amount to be captured cannot be larger than the sum of all items
CAPTURE_AMOUNT_HAS_TOO_MANY_DECIMALSThe amount to be captured cannot have more than 2 decimals
CAPTURE_ORDER_ALREADY_CAPTUREDA captured order cannot be captured again
CAPTURE_AMOUNT_GREATER_THAN_INVOICE_AMOUNTThe amount to be captured cannot be larger than the current order amount
CAPTURE_ITEMS_UNITPRICE_HAS_TOO_MANY_DECIMALSThe UnitPrice of an item in the items list has too many decimals
CAPTURE_INVALID_INVOICE_STATUSYou cannot capture an order in state closed or expired
CAPTURE_ITEMS_MISSING_IDWhen replacing items Id has to be set
CAPTURE_ACTIVATION_OF_INVOICE_DENIEDCapture was denied because the order or customer state does not allow the order to be captured
Idempotency

To prevent multiple requests by mistake, the idempotency header can be used to single out requests. The API supports idempotency for safely retrying requests that only should be performed once. This could be useful if responses are not received due to network connectivity problems. For example, if a response for a request to add an invoice is not received, you can retry the request with the same idempotency key again and be guaranteed that no more than one invoice is added.

You will need to generate a guid/uuid v4 and send it in with the header x-idempotency for every unique operation:

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