Captures and Returns¶
Once the checkout process is complete, a Purchase Order becomes
an actual Purchase (or just an order) in our system.
There are many operations you can execute on an order: capturing, returning, updating and getting its details. Here we cover two of the most important actions.
Captures¶
Capturing an order is done whenever a merchant sends purchased items to a customer. It signals that the “captured” money can be paid out to the merchant, and the customer will now be charged for the specified amount.
New Capture¶
You can either capture the full amount or a part of it by specifying the items that are being charged for. It is possible to do multiple captures until all of the items in the order have been covered.
Use this operation when an order is fulfilled. Ideally, once the items you are charging for are shipped or delivered to the customer.
Capture All¶
The easiest way to capture an order is to include all items. Only do this if you ship
all the items in an order at the same time. Capturing all items is done using the
newPurchaseCaptureAll mutation.
Similarly to many other mutations in the API, we require an idempotencyKey for this call.
We recommend that you use your own capture id or shipment id as the idempotencyKey.
Hint
If you used the editors to complete a purchase in the previous chapter, use the
resulting purchaseId and place it in the “Query Variables” tab.
Capture Individual Items¶
If you ship items in multiple batches, you can choose to charge the customer as soon as each batch is shipped.
We require you to specify exactly what items are delivered, and to restate the price for those items. This allows you to fine-tune the amounts being charged to the customer.
An order is considered fully-captured only when all items have been shipped and the amounts charged are equal to the total purchase amount.
In order to create a new partial capture, use the newPurchaseCapture mutation:
Capture By Item References¶
Another convenient way of capturing specific items without having to specify amounts is by using
the newPurchaseCaptureWithItemReferences mutation. You only need to specify a list of item
references and the system will automatically use the initially provided amounts when the purchase was
created.
Returns¶
Returning an order or items in the order means that the customer is sending back those items and they will not be charged for them. Conversely, the money corresponding to those items will be deducted from the payout to the merchant.
The total amount of a return must not be higher than the captured amount for the corresponding items.
Returns can be used as well to signal that certain items won’t be delivered at all, regardless of the reason the merchant decides to do so.
Make a Return¶
You can either return an entire order or a part of it by specifying the items that are being returned. It is possible to do multiple returns for the same order.
Full Return¶
Use the newPurchaseReturnAll to mark all items in a purchase as returned, regardless
of whether they have been captured or not. After this operation the order will be closed
and no other changes to it will be accepted.
This operation requires an idempotencyKey. If you track refunds in your own system,
we recommend that you use the same identifier as the idempotencyKey.
Partial Returns¶
If a customer returns items on different occasions for the same order, you can choose to create multiple returns with our API.
We require you to specify exactly which items are being returned and to restate the price for those items. This allows you to fine-tune the amounts being refunded to the customer.
An order is considered fully-returned only when all items have been returned.
In order to create a new partial capture, use the newPurchaseReturn mutation: