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

# Commerce Data

<Warning>
  This guide assumes you have API access and the necessary permissions. For help
  enabling these features or to request sandbox/testing access, contact your
  Loop point of contact or [support@loopreturns.com](mailto:support@loopreturns.com).
</Warning>

## 🧭 Overview

The **Commerce Data APIs** allow you to populate Loop's ecosystem with commerce data from any source—your commerce platform, ERP, OMS, middleware, or custom systems. These APIs are intended for custom integrations where Loop doesn't have a prebuilt app for your commerce platform; if you're using a platform with native Loop integration, commerce data is synced automatically.

By syncing products, orders, customers, locations, inventory, and collections into Loop, you enable Loop to validate return eligibility, power exchange workflows, and maintain accurate records across your systems.

<Tip>
  **Your Platform as the Source of Truth**

  These APIs are designed to receive data pushes from whatever systems manage your commerce data. Whether you're integrating a single platform or consolidating data from multiple sources, Loop acts as the destination for your product catalog and order history.
</Tip>

***

## 📦 API Reference

The Commerce Data APIs are organized into six main domains. Each API follows a consistent pattern with support for **Create**, **List**, **Get**, **Update**, **Upsert**, and **Delete** operations.

<Tip>
  **Upsert Operations**

  Most Commerce Data APIs support an "Upsert" operation (`PUT` on the collection endpoint) which creates a new record if it doesn't exist, or updates it if it does. This is identified by the `external_id` field and is ideal for sync workflows.
</Tip>

***

### 🛍️ Products API

The Products API provides Loop with standardized product data from any eCommerce system, ensuring accurate return processing and exchange matching.

* **Product Metadata** — Unique product IDs, SKUs, names, descriptions, and vendor details
* **Pricing & Classification** — Price, product type, collections, and tags
* **Identifiers** — Barcodes and external references for cross-platform tracking
* **Variants & Options** — Attributes like colors, sizes, and associated variants
* **Media & Assets** — Product images for return experience consistency

This data allows Loop to validate return items, process exchanges accurately, and maintain catalog consistency across platforms.

<Note>
  **ID Mapping Requirement**

  When syncing products, your middleware **must** store the returned `loop_product_id` mapped to your platform's `external_id`. You'll reference these Loop IDs when creating orders.
</Note>

| Operation                                                       | Method   | Description                                                  |
| --------------------------------------------------------------- | -------- | ------------------------------------------------------------ |
| [List Products](/api-reference/latest/products/list-products)   | `GET`    | Retrieve products with filters (external\_id, barcode, tags) |
| [Create Product](/api-reference/latest/products/create-product) | `POST`   | Create a new product                                         |
| [Upsert Product](/api-reference/latest/products/upsert-product) | `PUT`    | Create or update by `external_id`                            |
| [Get Product](/api-reference/latest/products/get-product)       | `GET`    | Get details for a single product                             |
| [Update Product](/api-reference/latest/products/update-product) | `PUT`    | Update an existing product                                   |
| [Delete Product](/api-reference/latest/products/delete-product) | `DELETE` | Delete a product                                             |

**Product Variants** are managed as sub-resources of products:

| Operation                                                               | Method   | Description                               |
| ----------------------------------------------------------------------- | -------- | ----------------------------------------- |
| [List Variants](/api-reference/latest/products/list-product-variants)   | `GET`    | List variants for a product               |
| [Create Variant](/api-reference/latest/products/create-product-variant) | `POST`   | Create a new variant                      |
| [Upsert Variant](/api-reference/latest/products/upsert-product-variant) | `PUT`    | Create or update variant by `external_id` |
| [Get Variant](/api-reference/latest/products/get-product-variant)       | `GET`    | Get variant details                       |
| [Update Variant](/api-reference/latest/products/update-product-variant) | `PATCH`  | Update a variant                          |
| [Delete Variant](/api-reference/latest/products/delete-product-variant) | `DELETE` | Delete a variant                          |

***

### 📋 Orders API

The Orders API provides a comprehensive view of transactional data from any eCommerce system, ensuring Loop has the necessary context to facilitate seamless return and exchange processing.

* **Order Metadata** — Unique order identifiers, status, and associated sales channels
* **Customer Information** — Buyer details, including contact information and external references
* **Financial Details** — Total price, applied discounts, tax calculations, and refund history
* **Shipping & Fulfillment** — Shipping addresses, carrier details, fulfillment statuses, and tracking numbers
* **Line Items & Adjustments** — Purchased products, pricing, applied discounts, duties, and refund eligibility

This data allows Loop to validate return eligibility, create returns, and help facilitate refunds, store credit, and exchanges efficiently across any platform.

<Note>
  **Prerequisite:** Products must exist in Loop before syncing orders. Order line items should reference **Loop Product IDs** (from your ID mapping) rather than external IDs for accurate return processing.
</Note>

| Operation                                                 | Method   | Description                           |
| --------------------------------------------------------- | -------- | ------------------------------------- |
| [List Orders](/api-reference/latest/orders/list-orders)   | `GET`    | Retrieve orders with optional filters |
| [Create Order](/api-reference/latest/orders/create-order) | `POST`   | Create a new order                    |
| [Upsert Order](/api-reference/latest/orders/upsert-order) | `PUT`    | Create or update by `external_id`     |
| [Get Order](/api-reference/latest/orders/get-order)       | `GET`    | Get details for a single order        |
| [Update Order](/api-reference/latest/orders/update-order) | `PUT`    | Update an existing order              |
| [Delete Order](/api-reference/latest/orders/delete-order) | `DELETE` | Delete an order                       |

**Key Order Fields:**

* **`line_items`** — Array of purchased items, each referencing a product/variant
* **`fulfillments`** — Fulfillment data including status, tracking, and fulfilled line items
* **`refunds`** — Refund data for reconciliation
* **`shipping_address` / `billing_address`** — Customer address information

***

### 👤 Customers API

The Customers API stores essential customer data to support return validation and exchange processing across platforms.

* **Customer Identity** — Unique customer IDs, external references, and contact details
* **Order & Return Context** — Flexible tags for purchase history, return status, and customer segmentation
* **Channel Association** — Identifies where the customer was created or last interacted

Customers can be created independently or through the Orders API, making this collection flexible for managing return history and personalizing the return experience across platforms.

| Operation                                                          | Method   | Description                              |
| ------------------------------------------------------------------ | -------- | ---------------------------------------- |
| [List Customers](/api-reference/latest/customers/list-customers)   | `GET`    | Retrieve customers with optional filters |
| [Create Customer](/api-reference/latest/customers/create-customer) | `POST`   | Create a new customer                    |
| [Upsert Customer](/api-reference/latest/customers/upsert-customer) | `PUT`    | Create or update by `external_id`        |
| [Get Customer](/api-reference/latest/customers/get-customer)       | `GET`    | Get details for a single customer        |
| [Update Customer](/api-reference/latest/customers/update-customer) | `PUT`    | Update an existing customer              |
| [Delete Customer](/api-reference/latest/customers/delete-customer) | `DELETE` | Delete a customer                        |

**Key Customer Fields:**

* **`first_name` / `last_name`** — Customer name
* **`email`** — Email address
* **`phone`** — Phone number
* **`tags`** — Array of tags for customer segmentation

***

### 📍 Locations API

The Locations API provides Loop with a standardized view of return and fulfillment locations, ensuring accurate routing and inventory management.

* **Location Metadata** — Unique location IDs, external references, and status
* **Physical Address** — Warehouse or store details, including company name and full address
* **Channel Association** — Identifies where the location is sourced from

This data enables efficient return routing, inventory restocking, and location-based return policies across platforms.

| Operation                                                          | Method   | Description                              |
| ------------------------------------------------------------------ | -------- | ---------------------------------------- |
| [List Locations](/api-reference/latest/locations/list-locations)   | `GET`    | Retrieve locations with optional filters |
| [Create Location](/api-reference/latest/locations/create-location) | `POST`   | Create a new location                    |
| [Upsert Location](/api-reference/latest/locations/upsert-location) | `PUT`    | Create or update by `external_id`        |
| [Get Location](/api-reference/latest/locations/get-location)       | `GET`    | Get details for a single location        |
| [Update Location](/api-reference/latest/locations/update-location) | `PUT`    | Update an existing location              |
| [Delete Location](/api-reference/latest/locations/delete-location) | `DELETE` | Delete a location                        |

**Key Location Fields:**

* **`name`** — Location name (e.g., "Main Warehouse")
* **`status`** — `active` or `inactive`
* **`address`** — Full address object with address1, city, region, postal\_code, country\_code

***

### 📊 Inventories API

The Inventories API provides real-time visibility into stock levels across locations, ensuring accurate return processing and exchange fulfillment.

* **Stock Availability** — Tracks available inventory counts for product variants
* **Product Details** — SKU, barcode, name, and weight for precise identification
* **Location Association** — Links inventory to specific warehouses or return locations

This data helps prevent overselling, streamline restocking, and ensure exchange availability across platforms.

<Note>
  Inventory records are keyed by the combination of `productVariantId` and `locationId`. Both Products and Locations must exist in Loop before creating inventory records.
</Note>

| Operation                                                              | Method   | Description                                      |
| ---------------------------------------------------------------------- | -------- | ------------------------------------------------ |
| [List Inventories](/api-reference/latest/inventories/list-inventories) | `GET`    | List inventories (filter by location or variant) |
| [Create Inventory](/api-reference/latest/inventories/create-inventory) | `POST`   | Create inventory record                          |
| [Get Inventory](/api-reference/latest/inventories/get-inventory)       | `GET`    | Get inventory for variant at location            |
| [Upsert Inventory](/api-reference/latest/inventories/upsert-inventory) | `PUT`    | Create or update inventory                       |
| [Delete Inventory](/api-reference/latest/inventories/delete-inventory) | `DELETE` | Delete inventory record                          |

**Key Inventory Fields:**

* **`available_count`** — Number of units available at the specified location

***

### 🏷️ Collections API

The Collections API organizes products into logical groupings, helping Loop maintain structured catalog data for returns and exchanges.

* **Collection Metadata** — Unique collection IDs, external references, and names
* **Associated Products** — SKUs, names, and external references for grouped items
* **Channel Association** — Identifies where the collection data originates

This data ensures consistent product categorization, enabling efficient return policies and exchange logic across platforms.

| Operation                                                                          | Method   | Description                                |
| ---------------------------------------------------------------------------------- | -------- | ------------------------------------------ |
| [List Collections](/api-reference/latest/collections/list-collections)             | `GET`    | Retrieve collections with optional filters |
| [Create Collection](/api-reference/latest/collections/create-collection)           | `POST`   | Create a new collection                    |
| [Upsert Collection](/api-reference/latest/collections/upsert-collection)           | `PUT`    | Create or update by `external_id`          |
| [Get Collection](/api-reference/latest/collections/get-collection)                 | `GET`    | Get details for a single collection        |
| [Update Collection](/api-reference/latest/collections/update-collection)           | `PUT`    | Update an existing collection              |
| [Delete Collection](/api-reference/latest/collections/delete-collection)           | `DELETE` | Delete a collection                        |
| [Add Product](/api-reference/latest/collections/add-product-to-collection)         | `POST`   | Attach a product to a collection           |
| [Remove Product](/api-reference/latest/collections/delete-product-from-collection) | `DELETE` | Remove a product from a collection         |

***

## ⚠️ Technical Considerations

When integrating with the Commerce Data APIs, keep these critical implementation details in mind:

| Consideration       | Requirement                                                                      |
| ------------------- | -------------------------------------------------------------------------------- |
| **Monetary Values** | All prices must be in **minor units (cents)**. Example: `$10.00` → `1000`        |
| **Date Formatting** | Use **ATOM / RFC 3339** format without milliseconds: `YYYY-MM-DDTHH:mm:ss+00:00` |
| **Order Status**    | Map external statuses to: `active`, `archived`, `cancelled`, `unknown`           |
| **Sync Order**      | Always sync **Products before Orders**                                           |

***

## 🔄 Common Sync Patterns

### Initial Data Sync (Historical Backfill)

When onboarding, you'll typically sync data in this order:

<Tip>
  **How far back should I sync orders?**

  At minimum, sync orders going back to match your return policy window (e.g., 30 days, 60 days, 90 days). This ensures customers can initiate returns on any order that's still within the eligible return period.
</Tip>

<Steps>
  <Step title="Sync Products & Variants">
    Push your entire product catalog. Store the returned Loop IDs for each product/variant.
  </Step>

  <Step title="Sync Customers">
    Push customer records from your platform. (Note: Customers can also be created via the Orders API.)
  </Step>

  <Step title="Sync Orders">
    Push historical orders, referencing Loop Product IDs in line items.
  </Step>

  <Step title="Sync Locations (Exchanges Only)">
    Create location records for warehouses and fulfillment centers. Required if offering exchanges.
  </Step>

  <Step title="Sync Inventory (Exchanges Only)">
    Push stock levels per variant and location. Required if offering exchanges.
  </Step>

  <Step title="Sync Collections (Optional)">
    Create collections and attach products. Useful for defining advanced exchange rules.
  </Step>
</Steps>

### Real-Time Sync

For ongoing operations, set up event-driven syncs to keep Loop updated:

* **New Orders** — Push to Loop when an order is placed
* **Product Updates** — Sync when products are created, updated, or discontinued
* **Inventory Changes** — Update stock levels after sales, returns, or restocks
* **Order Status Changes** — Update fulfillment status, refunds, and cancellations

***

## ✅ Conclusion

The Commerce Data APIs provide the foundation for integrating Loop with any commerce platform. By syncing your products, orders, customers, locations, inventory, and collections, you enable Loop to accurately validate returns, power exchange workflows, and maintain data consistency across your systems. Whether you're performing a one-time historical backfill or building real-time sync pipelines, these APIs give you the flexibility to keep Loop in sync with your source of truth.