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.

Please note

This can only be done on orders with status NotActivated or PartActivated.

The API operates on an eventual consistency model, implying that there might be a delay between the creation of an order and the availability of API functionalities to manage said order. We recommend retrying failed requests using idempotency.

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 // (Please note! Different hostname in production)
Authorization: Bearer bXlVc2VybmFtZTpmN2E1ODA4MGQzZTk0M2VmNWYyMTZlMDE...

{
  "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 // (Please note! Different hostname in production)
Authorization: Bearer bXlVc2VybmFtZTpmN2E1ODA4MGQzZTk0M2VmNWYyMTZlMDE...

{
  "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 // (Please note! Different hostname in production)
Authorization: Bearer bXlVc2VybmFtZTpmN2E1ODA4MGQzZTk0M2VmNWYyMTZlMDE...

{
  "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.

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 // (Please note! Different hostname in production)
Authorization: Bearer bXlVc2VybmFtZTpmN2E1ODA4MGQzZTk0M2VmNWYyMTZlMDE...

{
  "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
202Order captured
401Unauthorized, token verification needed. See: Authentication for more information
403Permissions needed e.g. trying to handle content for a store you don't have permission to or the order has not yet been fully synced on our side
404Order not found or the order has not yet been fully synced on our side
422See error codes

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
itemsNoThe article items and quantity to capture.arrayCapture Item

Response​

The response will be 202 Accepted for a successful capture or part capture.

Please note

Due to the asynchronous nature of an Accepted status answer, it can take a few seconds before the update can be shown in various systems and responses to API requests. You should design your system to accomodate this.

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 have 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 amount cannot have more than 2 decimals
CAPTURE_ORDER_ALREADY_CAPTUREDAn 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
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