> ## 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: Address Validation, Cancellation & Claims

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

An **Order** represents the physical fulfillment event. It is created **directly by your system** in the **Embedded Marketplace** model, 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>

<Info>
  This page focuses on the **Embedded Marketplace 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

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 always 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 [Webhooks & Events](/pages/webhook-event-types).
</Tip>

***

## Key Concepts & Business Rules

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

Even in the Embedded Marketplace model where your system places the order directly, a Gift object is created internally. The Order lives within that Gift and cannot exist independently.

#### **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**

If an Order is cancelled, a new one can be placed against the same Gift. 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 /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 validity 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

**Place Order** *(Embedded Marketplace)*

Placing an order in the Embedded Marketplace model requires two sequential API calls:

1. **Create the Gift** - Call <kbd>POST /gifts</kbd> with the Campaign ID and recipient details. At this stage you only need to provide the Campaign and recipient information - no variant or shipping address is required yet.

```text theme={null}
POST /gifts
```

Required fields:

* `companyId` - the Company placing the order
* `campaignId` - the Campaign under which the gift and order will be created
* `recipients` - the recipient's details including name and email

2. **Claim the Gift** - Call <kbd>POST /gifts//claim</kbd> with the Gift ID returned in the previous step, along with the selected variant ID and the recipient's shipping address. This finalizes the Gift and places the Order immediately.

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

Required fields:

* variantId - the specific product Variant to order
* recipient - the order recipient and their shipping address

<Tip>
  Use the <kbd>giftid</kbd> from Step 1 to track order delivery status via <kbd>GET /gifts/</kbd> or Webhooks.
</Tip>

<Note>
  A dedicated `POST /orders` endpoint is coming soon, which will allow you to create a gift and place an order in a single API call. See [Embedded Marketplace Recipe](/pages/direct-fulfillment) for details.
</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}
POST /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}
POST /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}
GET /orders/addresses/autocomplete
```