# Checkout SDK Order Management

This guide explains how to work with the order model after a successful Checkout SDK authorization.

Use this guide if your checkout success flow returns an `order_id` instead of a `charge_id`.

> **Note:** Order management is available through both the Resolve dashboard and the Merchant API. Use the dashboard if you want manual operational control, or the API if you want to automate these actions in your OMS or fulfillment workflows.


## When to use the order model

The order model is useful when you want to:

- capture only part of an authorized amount
- capture the same authorization multiple times
- manage the authorization as an order object before and during fulfillment


To use the Checkout SDK order model, your merchant must opt in to **Checkout - Order Authorization**.

## After checkout success

When checkout completes successfully in the order model, Resolve redirects the customer to your `success_url` with an `order_id` query parameter:

```
https://www.merchantsite.com/confirm?order_id=ORDlaE5wbg0
```

Store the `order_id` in your order management system. You will use it to fetch, update, capture, or cancel the authorization.

For the shared checkout lifecycle, see [Online Transaction Flow](/guides/online-transaction-flow).

## Order lifecycle

An order starts in `authorized` status. From there, you can:

- fetch the order
- update the authorized order before capture is complete
- capture all or part of the authorized amount
- cancel the remaining authorized amount


After a capture, Resolve creates a new invoice and charge for that captured amount. If you capture an order multiple times, each capture creates its own invoice and charge.

## Fetch an order

Use this when you need the latest state before acting on the order.

Key fields to monitor:

- `status`
- `amount_authorized`
- `amount_captured`
- `amount_canceled`
- `amount_remaining`
- `capture_events`


API reference:

- [Fetch an order](/merchant-api/openapi/orders#operation/fetchOrder)


## Update an order

Use this while the order is still in an authorized state and you need to adjust the authorization details before capture is complete.

Common update fields:

- `amount`
- `order_number`
- `po_number`
- `line_items`


Payload guidance:

| Field | Required | Notes |
|  --- | --- | --- |
| `amount` | No | Positive number. Use when the authorized amount needs to change. |
| `order_number` | No | Merchant order reference. |
| `po_number` | No | Purchase order reference. |
| `line_items` | No | Updated line items for the order. |


At least one field must be provided.

Example:

```json
{
  "amount": 800,
  "order_number": "ORD-1001",
  "po_number": "PO-1001",
  "line_items": [
    {
      "name": "Widget A",
      "quantity": 2,
      "unit_price": 400
    }
  ]
}
```

API reference:

- [Update an order](/merchant-api/openapi/orders/updateorder)


## Capture an order

Capture the order when you are ready to receive funds and start the customer's billing clock.

The order model supports:

- full capture
- partial capture
- multiple captures over time


Each capture creates its own invoice and charge under the order.

Payload requirements:

| Field | Required | Notes |
|  --- | --- | --- |
| `amount` | Yes | Positive number less than or equal to the remaining authorized amount. |
| `idempotency_key` | Yes | Required for safe retries. Reuse only when retrying the exact same request. |
| `number` | No | Invoice number to assign to the created invoice. |
| `line_items` | Conditionally | Provide this if you want Resolve to build the invoice from line items. |
| `merchant_invoice_url` | Conditionally | Provide this if you want Resolve to ingest an invoice PDF from a public URL. |


Exactly one of `line_items` or `merchant_invoice_url` must be provided.

Example: partial capture with line items

```json
{
  "amount": 400,
  "idempotency_key": "capture-ord-1001-partial-1",
  "line_items": [
    {
      "name": "Widget A",
      "quantity": 1,
      "unit_price": 400
    }
  ]
}
```

Example: capture with invoice PDF

```json
{
  "amount": 400,
  "idempotency_key": "capture-ord-1001-pdf-1",
  "number": "INV-1001",
  "merchant_invoice_url": "https://example.com/invoices/inv-1001.pdf"
}
```

API reference:

- [Capture an order](/merchant-api/openapi/orders/captureorder)


## Cancel an order

Cancel the order if you no longer intend to fulfill the remaining authorized amount.

Behavior:

- if the order has not been captured yet, the full remaining authorization is canceled
- if the order has already been partially captured, only the uncaptured remainder is canceled


Cancel does not reverse amounts that were already captured. For post-capture reversals, use a credit note against the captured invoice.

API reference:

- [Cancel an order](/merchant-api/openapi/orders/cancelorder)


## Refunds after capture

Refunds are not an order action.

After you capture an order, any refund or reversal should be handled against the invoice created by that capture. In Resolve, this is done by issuing a credit note.

If the order has multiple captures, make sure you identify the correct invoice for the capture you want to reverse.

Payload guidance for credit notes:

| Field | Required | Notes |
|  --- | --- | --- |
| `invoice_id` | Yes | The captured invoice you want to refund or reduce. |
| `amount` | Yes | Credit note amount. |
| `reason_code` | Yes | Reason for the refund or adjustment. |
| `number` | No | Merchant credit note number. |
| `reason_message` | No | Additional explanation. |
| `credit_note_url` | No | Public URL to the credit note PDF. |


Example:

```json
{
  "invoice_id": "PMMlaE5wbg0",
  "amount": 200,
  "reason_code": "requested_by_customer",
  "reason_message": "Customer returned part of the shipment"
}
```

API reference:

- [Create a credit note](/merchant-api/openapi/credit-notes/createcreditnote)


## Common operational patterns

### Single shipment

1. Checkout succeeds and returns `order_id`.
2. Merchant fulfills the full order.
3. Merchant captures the full amount once.


### Split shipment

1. Checkout succeeds and returns `order_id`.
2. Merchant fulfills part of the order.
3. Merchant captures only the shipped portion.
4. Merchant fulfills the remaining items later.
5. Merchant captures the remaining authorized amount.


### Partial capture, then cancel the rest

1. Checkout succeeds and returns `order_id`.
2. Merchant captures the fulfilled portion.
3. Merchant cancels the remaining authorized amount that will not ship.


## Related guides

- [Checkout SDK](/guides/checkout-sdk)
- [Online Transaction Flow](/guides/online-transaction-flow)