> ## Documentation Index
> Fetch the complete documentation index at: https://docs.snappy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Orders API (V2): Address Validation, Cancellation & Claims

> Validate addresses, claim gifts to place orders, cancel orders, and autocomplete shipping data with the V2 Snappy Orders API.

An **Order** represents the physical fulfillment event. In V2, Orders are not first-class API resources - they're created as a side effect of the Gifts flow. An Order can be created either **directly by your system** in the **Direct Fulfillment** model (via the two-step gift-claim flow), or automatically by Snappy when a recipient claims their gift in the **Triggered Gifting** model.

<Tip>
  Want to understand how **Orders** fit into the bigger picture? Check out the [Core Concepts & Data Models](/pages/snappy-core-concepts-and-data-models) page.
</Tip>

<Note>
  Looking for the V3 endpoints? See [Orders (V3)](/modules/api/v3/orders/overview). V3 introduces Orders as first-class resources with a dedicated `POST /v3/orders` endpoint that replaces the V2 two-step flow - and adds direct order retrieval, listing, and cancellation by `orderId`. Both V2 and V3 are supported in parallel.
</Note>

<Info>
  This page focuses on the **Direct Fulfillment** model, where your system places orders directly. If you're working with the **Triggered Gifting** model, Orders are created automatically when recipients claim their gift - see [Gifts](/modules/api/v2/gifts/overview) for details.
</Info>

***

## The Order Object

In V2, the Order object is returned as part of the Gift object. A Gift can hold multiple Orders - for example, if an original Order was cancelled and a new one was placed. The active Order's delivery details are surfaced at the top level of the Gift object for convenience.

### Core Fields

| Field             | Type   | Description                                                                                         |
| :---------------- | :----- | :-------------------------------------------------------------------------------------------------- |
| `id`              | string | Unique identifier for the Order                                                                     |
| `status`          | string | Current status of the Order. See [Order Statuses](#order-statuses) below                            |
| `orderRecipient`  | object | The recipient details used for this specific Order. Contains `firstName`, `lastName`, and `country` |
| `orderedProducts` | array  | The products included in this Order. See [Ordered Products](#ordered-products) below                |

***

### Ordered Products

| Field                                           | Type   | Description                                                                        |
| :---------------------------------------------- | :----- | :--------------------------------------------------------------------------------- |
| `orderedProducts[].selectedProduct.variantId`   | string | The Variant ID of the product ordered                                              |
| `orderedProducts[].selectedProduct.title`       | string | The title of the ordered product                                                   |
| `orderedProducts[].selectedProduct.type`        | string | The product type (e.g. `physicalGift`, `digital`)                                  |
| `orderedProducts[].selectedProduct.orderStatus` | string | The fulfillment status of this specific product within the Order                   |
| `orderedProducts[].deliveryDetails`             | object | Delivery details for this product. See [Delivery Details](#delivery-details) below |

***

### Delivery Details

| Field                                          | Type   | Description                                                                |
| :--------------------------------------------- | :----- | :------------------------------------------------------------------------- |
| `deliveryDetails.status`                       | string | Current delivery status. See [Delivery Statuses](#delivery-statuses) below |
| `deliveryDetails.carrier`                      | string | The shipping carrier handling the delivery                                 |
| `deliveryDetails.trackingNumber`               | string | The carrier's tracking number                                              |
| `deliveryDetails.trackingLink`                 | string | A direct link to the carrier's tracking page                               |
| `deliveryDetails.deliveryDates.outForDelivery` | string | ISO 8601 timestamp of when the item was marked out for delivery            |
| `deliveryDetails.deliveryDates.estimated`      | string | ISO 8601 timestamp of the estimated delivery date                          |
| `deliveryDetails.deliveryDates.deliveredAt`    | string | ISO 8601 timestamp of when the item was delivered                          |

***

## Order Statuses

| Status      | Description                             |
| :---------- | :-------------------------------------- |
| `active`    | The Order is active and being processed |
| `cancelled` | The Order has been cancelled            |

***

## Delivery Statuses

| Status           | Description                                |
| :--------------- | :----------------------------------------- |
| `orderReceived`  | The fulfillment request has been received  |
| `processing`     | The item is being prepared for shipment    |
| `inTransit`      | The item has been picked up by the carrier |
| `outForDelivery` | The item is expected to be delivered today |
| `delivered`      | The item has reached its final destination |

<Tip>
  Use Webhooks to track delivery status changes in real time rather than polling. See [Webhook Event Types](/pages/webhook-event-types).
</Tip>

***

## Key Concepts & Business Rules

#### An Order is a sub-entity of a Gift

In V2, the Order lives within a Gift - even when your system places the order directly via the Direct Fulfillment flow, a Gift object is created internally and the Order is attached to it. V3 changes this: Orders are first-class resources you can retrieve, list, and cancel directly by `orderId`.

#### Variants are required - not Products

When placing an order, you must always specify the `variantId`, not the `productId`. Every Product has at least one Variant, even if it has no variations. See [Products & Variants](/modules/api/v2/products/overview).

#### Orders can only be cancelled before processing

Once an Order has been picked up by the fulfillment partner and is in transit, it can no longer be cancelled. Use the `order-out-of-stock` and `order-canceled` webhook events to handle edge cases proactively.

#### A Gift can have multiple Orders but only one is active

A Gift maintains a history of all Orders placed against it. If an Order is cancelled, a new one can be placed against the same Gift - but only one Order is active at any time. The Gift's top-level `deliveryDetails` always reflects the active Order. The `orders` array on the Gift object contains the full Order history, including cancelled ones..

#### Address validation reduces fulfillment failures

Invalid or incomplete shipping addresses are a common cause of fulfillment failures. We recommend calling `POST /v2/orders/addresses/validate` before placing any order, especially when addresses are entered by end users in your platform UI.

#### Billing is triggered at Order creation

The Billing Method is debited when an Order is successfully placed. If the Billing Method has insufficient funds at the time of the request, the order will not be processed.

#### Order Status vs. Delivery Status

The top-level Order `status` indicates the lifecycle of the transaction (`active` vs. `cancelled`). The actual shipping progress is tracked inside the `deliveryDetails.status` of each ordered product.

***

## How to Work with Orders (V2)

**Claim a Gift**

Claiming a Gift programmatically places an Order on behalf of the recipient. Provide the selected variant and shipping address - Snappy creates the Order, debits the Billing Method, and begins fulfillment.

```text theme={null} theme={null}
POST /v2/gifts/{giftId}/claim
```

Required fields:

* `variantId` - the specific product Variant to order
* `recipient` - the order recipient's contact details and shipping address

Common use cases:

* **Auto-claim fallback** - a Gift sent through Triggered Gifting hasn't been claimed by the recipient within a defined window. Your system auto-claims with a pre-selected variant and a known shipping address, ensuring the gift still goes out.
* **Embedded Marketplace** - your platform creates a Gift via `POST /v2/gifts` and immediately claims it on the recipient's behalf, placing the Order in a single flow inside your UI.

<Tip>
  Use the `giftId` to track order delivery status via `GET /v2/gifts/{giftId}` or Webhooks.
</Tip>

<Note>
  V3 introduces `POST /v3/orders` as a single-call alternative for placing orders without the Gift-and-claim pattern. If you're starting a new integration, consider [V3 Orders](/modules/api/v3/orders/overview).
</Note>

**Cancel an Order**

Cancel an order that has not yet been processed or shipped. A successful request returns the cancelled order ID and its updated status:

```text theme={null} theme={null}
POST /v2/gifts/{giftId}/cancel
```

<Warning>
  Orders can only be cancelled before they have been processed or shipped. Once a shipment is in transit, cancellation is no longer possible.
</Warning>

**Validate Order Address**

Validate a shipping address before placing an order. Use this endpoint to catch address errors early and reduce the likelihood of fulfillment failures:

```text theme={null} theme={null}
POST /v2/orders/addresses/validate
```

<Tip>
  We recommend calling this endpoint as part of your order placement flow, especially when addresses are entered by end users in your platform UI.
</Tip>

**Autocomplete Order Address**

Retrieve address suggestions based on a partial input string. Useful for building address input fields in your platform UI that help users enter accurate shipping addresses:

```text theme={null} theme={null}
GET /v2/orders/addresses/autocomplete
```