### Confirm Credentials with Curl (Sandbox)

Source: https://developer.wayfair.io/posts/catalog-read-v2

Use this curl command against the sandbox endpoint to verify your API credentials and authentication setup. It expects a successful SupplierCatalogItems payload or a SupplierCatalogItemsError.

```bash
curl -X POST \
  https://api.wayfair.io/sandbox/v1/product-catalog-api/graphql \
  -H 'Authorization: Bearer <token>' \
  -H 'X-SELECTED-SUPPLIER-ID: <supplierId>' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "query ($page: String) { supplierCatalogItems(pagination: {limit: 10, page: $page}) { paginationInfo { nextPage totalCount } supplier { supplierId } catalogItems { itemId attributes { name value } } } }",
    "variables": {
      "page": "1"
    }
  }'
```

--------------------------------

### Query Open CastleGate Purchase Orders

Source: https://developer.wayfair.io/posts/Cg-Orders-Guide

Use the getCastleGatePurchaseOrders query to retrieve a list of new orders. This is the first step in the CastleGate order management workflow. The example below is a starting point; the full list of available fields is extensive and can be found in the GraphQL specification documentation and Wayfair’s API Playground.

```graphql
query getCastleGatePurchaseOrders($filter: CastleGateOrderFilterInput) {
  getCastleGatePurchaseOrders(filter: $filter) {
    purchaseOrderNumber
    orderDate
    customerOrderNumber
    orderType
    orderStatus
    shippingMethod
    shippingAddress {
      name
      street1
      street2
      city
      state
      zip
      country
    }
    billingAddress {
      name
      street1
      street2
      city
      state
      zip
      country
    }
    items {
      sku
      quantity
      unitPrice
      description
    }
    totalPrice
    currency
    acknowledgementStatus
    notes
  }
}
```

--------------------------------

### Get Warehouse Shipping Advice Input

Source: https://developer.wayfair.io/posts/multichannel-orders

This JSON structure is used to request shipping advice for multichannel orders within a specified date range.

```json
{
  "warehouseShippingAdviceInput": {
    "supplierId": 1803,
    "fulfillmentOrderItemIds": ["MC_ORDER_001_ITEM_1"],
    "fromDate": "2025-01-01T00:00:00.000Z",
    "toDate": "2025-12-31T23:59:59.999Z"
  }
}
```

--------------------------------

### WarehouseShippingAdvices

Source: https://developer.wayfair.io/posts/multichannel-orders

Retrieves warehouse shipment advices (WSA) to get tracking information and shipping updates for fulfillment order items.

```APIDOC
## WarehouseShippingAdvices

### Description
Retrieves warehouse shipment advices (WSA) to get tracking information and shipping updates for fulfillment order items.

### Method
Query

### Endpoint
warehouseShippingAdvices

### Parameters
#### Query Parameters
- **warehouseShippingAdviceInput** (WarehouseShippingAdviceInput!) - Required - Input object for filtering and paginating warehouse shipping advices.

### Request Example
```graphql
query WarehouseShippingAdvices($warehouseShippingAdviceInput: WarehouseShippingAdviceInput!) {
  warehouseShippingAdvices(warehouseShippingAdviceInput: $warehouseShippingAdviceInput) {
    pageInfo {
      hasNextPage
      hasPreviousPage
      totalPages
      totalItems
    }
    nodes {
      fulfillmentOrderItemId
      warehouseShippingAdviceDate
      fulfillmentOrderRequestId
      fulfillmentPurchaseOrderNumber
      supplierId
      retailer {
        name
        retailerId
        orderNumber
      }
      productDetails {
        fulfillmentOrderItemId
        productId
        partNumber
        supplierProductName
        supplierPartNumber
        status
        statusLabel
        failureReasons
        quantityOrdered
        quantityShipped
        option
        forcedQuantityMultiplier
        unitPrice
        trackingNumbers
        errors {
          errorType
          errorSource
          errorCode
          errorMessage
        }
      }
      shippingDetails {
        shippingAddress {
          name
          address1
          address2
          city
          stateShortName
          postalCode
          countryShortName
          companyName
        }
        shippingFromAddress {
          name
          address1
          address2
          city
          stateShortName
          postalCode
          countryShortName
          companyName
        }
        warehouse {
          warehouseId
          name
        }
      }
      tracking {
        carrier
        carrierScac
        expectedShippingDate
        shippingDate
        shipSpeed
        shipSpeedCode
        trackingNumbers
      }
    }
  }
}
```

### Variables
#### Required Variables
- **supplierId** (Integer) - Your Wayfair supplier ID.
- **fulfillmentOrderItemIds** ([String]) - Array of specific item IDs to track.

#### Optional Variables
- **warehouseShippingAdviceDateInterval** (FulfillmentOrderDateInterval) - Date interval for filtering shipping updates.
  - **from** (String) - Start of the date interval (ISO 8601).
  - **to** (String) - End of the date interval (ISO 8601).

### Response
#### Success Response (200)
- **pageInfo** (object) - Pagination information.
- **nodes** (array) - List of warehouse shipping advices.
  - **fulfillmentOrderItemId** (String) - The ID of the fulfillment order item.
  - **warehouseShippingAdviceDate** (String) - The date and time the shipping advice was generated.
  - **fulfillmentOrderRequestId** (String) - The request ID from createFulfillmentOrder.
  - **fulfillmentPurchaseOrderNumber** (String) - The purchase order number.
  - **supplierId** (String) - The parent supplier ID.
  - **retailer** (object) - Retailer information.
  - **productDetails** (object) - Product information for the item.
  - **shippingDetails** (object) - Shipping details for the advice.
  - **tracking** (object) - Tracking information for the shipment.
```

--------------------------------

### Get CastleGate Warehouse Shipment Advices

Source: https://developer.wayfair.io/posts/Cg-Orders-Guide

Retrieves a list of warehouse shipment advices for CastleGate purchase orders. Supports filtering by response status, date, specific shipment IDs, and sorting.

```APIDOC
## getCastleGateWarehouseShippingAdvice

### Description
Retrieves a list of warehouse shipment advices for CastleGate purchase orders.

### Method
QUERY

### Endpoint
getCastleGateWarehouseShippingAdvice

### Parameters
#### Variables
- **limit** (Int32) - Optional - The maximum number of shipments to return in one call. Default is 10.
- **hasResponse** (Boolean) - Optional - Filters shipments based on whether a response has already been sent. Use `false` for new shipments, `true` for acknowledged shipments.
- **fromDate** (IsoDateTime) - Optional - Retrieves shipments created after a specific date/time (UTC).
- **wsaIds** ([String]) - Optional - Retrieves only the specific shipment IDs provided in the list.
- **sortOrder** (SortOrder) - Optional - Sorts the results by `shipDate`. Can be `ASC` (oldest first) or `DESC` (newest first).

### Request Example
```graphql
query getCastleGateWarehouseShippingAdvice(
  $limit: Int32,
  $hasResponse: Boolean,
  $fromDate: IsoDateTime,
  $wsaIds: [String],
  $sortOrder: SortOrder
) {
  getCastleGateWarehouseShippingAdvice(
    limit: $limit,
    hasResponse: $hasResponse,
    fromDate: $fromDate,
    wsaIds: $wsaIds,
    sortOrder: $sortOrder
  ) {
    wsaId
    supplierId
    poNumber
    shipDate
    shipSpeed
    carrierCode
    warehouseId
    products {
      quantityOrdered
      partNumber
      quantityShipped
    }
  }
}
```

### Response
#### Success Response
- **wsaId** (String) - The unique identifier for the warehouse shipment advice.
- **supplierId** (String) - The identifier of the supplier.
- **poNumber** (String) - The purchase order number associated with the shipment.
- **shipDate** (IsoDateTime) - The date and time the shipment was sent.
- **shipSpeed** (String) - The shipping speed.
- **carrierCode** (String) - The code for the shipping carrier.
- **warehouseId** (String) - The identifier of the warehouse.
- **products** (Array) - A list of products included in the shipment.
  - **quantityOrdered** (Int) - The quantity of the item ordered.
  - **partNumber** (String) - The part number of the item.
  - **quantityShipped** (Int) - The quantity of the item shipped.

#### Response Example
```json
{
  "data": {
    "getCastleGateWarehouseShippingAdvice": [
      {
        "wsaId": "WSA98765",
        "supplierId": "SUPPLIER001",
        "poNumber": "PO12345",
        "shipDate": "2023-10-27T10:00:00Z",
        "shipSpeed": "Standard",
        "carrierCode": "UPS",
        "warehouseId": "WH001",
        "products": [
          {
            "quantityOrdered": 5,
            "partNumber": "PN-ABC-123",
            "quantityShipped": 5
          }
        ]
      }
    ]
  }
}
```
```

--------------------------------

### Sample API Response for Inventory Adjustments

Source: https://developer.wayfair.io/integrations/api/playground

This is a mocked response for the inventory adjustment list query, showing the structure of the returned data including page information and adjustment details.

```json
{
  "data": {
    "inventoryAdjustmentList": {
      "pageInfo": {
        "pageNumber": 2,
        "pageSize": 3,
        "totalPages": 84,
        "totalElements": 4159000
      },
      "nodes": [
        {
          "eventDate": "2023-12-12T19:53:09.000Z",
          "adjustmentType": "Damage Adjustment",
          "supplierPartNumber": "SuppPart-1",
          "quantity": 1,
          "description": "Adj Out - Due to damage that occurred in the warehouse",
          "warehouse": {
            "warehouseId": 1234,
            "name": "Your CastleGate Warehouse",
            "address": {
              "address1": "4 Copley Pl",
              "address2": null,
              "address3": null,
              "city": "Boston",
              "stateShortName": "MA",
              "postalCode": "02126",
              "country": "USA"
            }
          }
        },
        {
          "eventDate": "2023-12-12T15:34:28.000Z",
          "adjustmentType": "Damage Adjustment",
          "supplierPartNumber": "SuppPart-2",
          "quantity": 1,
          "description": "Adj Out - Due to inventory arriving at the warehouse in damaged condition",
          "warehouse": {
            "warehouseId": 1234,
            "name": "Your CastleGate Warehouse",
            "address": {
              "address1": "4 Copley Pl",
              "address2": null,
              "address3": null,
              "city": "Boston",
              "stateShortName": "MA",
              "postalCode": "02126",
              "country": "USA"
            }
          }
        },
        {
          "eventDate": "2023-12-12T14:07:27.000Z",
          "adjustmentType": "Returns Process Adjustment",
          "supplierPartNumber": "SuppPart-3",
          "quantity": 1,
          "description": "Adj Out - Product was not physically returned",
          "warehouse": {
            "warehouseId": 1234,
            "name": "Your CastleGate Warehouse",
            "address": {
              "address1": "4 Copley Pl",
              "address2": null,
              "address3": null,
              "city": "Boston",
              "stateShortName": "MA",
              "postalCode": "02126",
              "country": "USA"
            }
          }
        }
      ]
    }
  }
}
```

--------------------------------

### Generate Production Access Token

Source: https://developer.wayfair.io/posts/go-live

Use this cURL command to generate a production access token by sending a POST request to the authentication server with your production Client ID and Client Secret. Ensure you replace 'YOUR_CLIENT_ID' and 'YOUR_CLIENT_SECRET' with your actual credentials.

```shell
curl -X POST https://sso.auth.wayfair.com/oauth/token \
-H 'content-type: application/json' \
-d '{
  "grant_type": "client_credentials",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "audience": "https://api.wayfair.com/"
}'
```

--------------------------------

### Python SDK for Paginated Catalog Item Retrieval

Source: https://developer.wayfair.io/posts/catalog-read-v2

This Python code snippet demonstrates a full implementation for paginating through all catalog items. It includes rate-limit pacing and shows how to apply filters for specific `catalogItemStatuses`.

```APIDOC
## Paginated Catalog Item Retrieval with Python SDK

### Description
This Python function `iter_all` allows you to iterate through all available catalog items for a supplier. It handles pagination automatically and includes a rate-limiting mechanism (`time.sleep(0.1)`) to prevent exceeding API limits. You can optionally pass a filter to retrieve specific items, for example, those with a `NOT_LIVE` status.

### Method
```python
import time
import requests

def iter_all(filter_=None):
    page = 1
    while True:
        variables = {"input": {"paginationOptions": {"page": page, "pageSize": 30}}}
        if filter_:
            variables["input"]["filter"] = filter_
        
        body = requests.post(ENDPOINT, headers=HEADERS, json={"query": QUERY, "variables": variables}, timeout=10).json()
        
        if body.get("errors"):
            raise RuntimeError(f"Validation error: {body['errors']}")
        
        result = body["data"]["supplierCatalogItems"]
        if result.get("httpError") or result.get("internalError"):
            raise RuntimeError(f"API error: {result}")
        
        yield from result["catalogItems"]
        
        if not result["paginationInfo"]["hasNextPage"]:
            break
        
        page += 1
        time.sleep(0.1)  # rate-limit pacing
```

### Endpoint
`https://api.wayfair.io/sandbox/v1/product-catalog-api/graphql`

### Headers
```json
{
    "Authorization": "Bearer <YOUR_TOKEN>",
    "X-SELECTED-SUPPLIER-ID": "<YOUR_SUPPLIER_ID>",
    "Content-Type": "application/json"
}
```

### Query
```graphql
query ($input: SupplierCatalogItemsInput!) {
  supplierCatalogItems(input: $input) {
    ... on SupplierCatalogItems {
      paginationInfo { page hasNextPage totalCount }
      catalogItems { supplierPartNumber catalogItemStatus }
    }
    ... on SupplierCatalogItemsError {
      httpError { code message }
      internalError { code message }
    }
  }
}
```

### Usage Example
```python
# To process items with status NOT_LIVE:
# for item in iter_all(filter_={'catalogItemStatuses': ['NOT_LIVE']}):
#     process(item)
```

### Error Handling
- The code raises a `RuntimeError` for validation errors returned in the `errors` field of the response.
- It also raises a `RuntimeError` for API-specific errors indicated by `httpError` or `internalError` in the response.
```

--------------------------------

### Get CastleGate Purchase Orders

Source: https://developer.wayfair.io/posts/Cg-Orders-Guide

Retrieves a list of CastleGate purchase orders based on specified filters and limits. This is the primary method for fetching order data.

```APIDOC
## GET getCastleGatePurchaseOrders

### Description
Retrieves a list of CastleGate purchase orders based on specified filters and limits. This is the primary method for fetching order data.

### Method
GET

### Endpoint
/v1/graphql

### Parameters
#### Query Parameters
- **limit** (Integer) - Optional - The maximum number of orders to return in one call. Default is 10.
- **hasResponse** (Boolean) - Required - Filters orders based on whether you have already sent a response. Use false to get new, open orders. Use true to look up orders you've already acknowledged.
- **fromDate** (String) - Optional - Retrieves orders created after a specific date/time (UTC).
- **poNumbers** (Array of Strings) - Optional - Retrieves only the specific PO numbers you provide in a list.
- **sortOrder** (String) - Optional - Sorts the results by poDate. Can be ASC (oldest first) or DESC (newest first).

### Response
#### Success Response (200)
- **id** (String) - The unique identifier for the purchase order.
- **poNumber** (String) - The purchase order number.
- **poDate** (String) - The date the purchase order was created.
- **supplierId** (String) - The identifier for the supplier.
- **products** (Array of Objects) - A list of products included in the purchase order.
  - **partNumber** (String) - The part number of the product.
  - **quantity** (Integer) - The quantity of the product ordered.
  - **price** (Float) - The price of the product.
  - **totalCost** (Float) - The total cost for this product line item.
```

--------------------------------

### Querying for All Orders

Source: https://developer.wayfair.io/posts/Cg-Orders-Guide

Use this snippet to query for all orders with a limit of 10 and no response.

```json
{
  "limit": 10,
  "hasResponse": false
}
```

--------------------------------

### Catalog API Product Addition

Source: https://developer.wayfair.io/integrations/api/playground

Provides endpoints for adding products to the catalog. Uses GraphQL.

```APIDOC
## Query brandQuery

### Description
Queries for brand information.

### Method
Query

### Endpoint
https://api.wayfair.io/v1/product-catalog-api/graphql
```

```APIDOC
## Query taxonomyCategories

### Description
Retrieves taxonomy categories.

### Method
Query

### Endpoint
https://api.wayfair.io/v1/product-catalog-api/graphql
```

```APIDOC
## Query GetQuestions

### Description
Retrieves questions related to products.

### Method
Query

### Endpoint
https://api.wayfair.io/v1/product-catalog-api/graphql
```

```APIDOC
## Query mediaMetaDataTags

### Description
Retrieves media metadata tags.

### Method
Query

### Endpoint
https://api.wayfair.io/v1/product-catalog-api/graphql
```

```APIDOC
## Mutation submitProductAddition

### Description
Submits a new product addition to the catalog.

### Method
Mutation

### Endpoint
https://api.wayfair.io/v1/product-catalog-api/graphql
```

```APIDOC
## Query productAddition

### Description
Retrieves information about a product addition.

### Method
Query

### Endpoint
https://api.wayfair.io/v1/product-catalog-api/graphql
```

--------------------------------

### Illustrative Response for One Catalog Item

Source: https://developer.wayfair.io/posts/catalog-read-v2

This is a trimmed response showing a single catalog item. It includes details like supplier information, item status, class, insights, attributes, and listings.

```json
1{ "data": { "supplierCatalogItems": {
2  "paginationInfo": { "page": 1, "hasNextPage": true, "totalCount": 249625 },
3  "supplier": { "supplierId": "2603", "supplierName": "US Extranet Test Supplier" },
4  "catalogItems": [{
5    "supplierPartNumber": "test345",
6    "marketContext": { "locale": "en-US", "country": "US", "brand": "WF", "channel": "ECM", "segment": "B2C", "location": "Primary" },
7    "catalogItemStatus": "NOT_LIVE",
8    "class": { "classId": "1318", "className": "Wall Art" },
9    "insights": {
10      "problems": [],
11      "warnings": [{ "insightId": "423462e3-...", "title": "Missing Legal Attributes", "insightTypeId": "productPerformance.missingRequiredAttributes", "monthsInViolation": 3, "resolution": { "resolutionId": "edit_required_product_attributes_v2", "url": "https://supplier.wayfair.com/x/attributes", "description": "Update Required Attributes" } }],
12      "opportunities": []
13    },
14    "attributes": [{
15      "attribute": { "attributeId": "154290", "title": "Overall Shape", "requirement": "OPTIONAL", "answerType": "STRING", "isMultiValue": false },
16      "chosenAttributeValues": [{ "value": ["Square"] }],
17      "permission": { "canEdit": { "isAllowed": true, "message": "You can edit this attribute" } }
18    }],
19    "listings": [{ "listingId": "WVT1567", "attributes": [/* same shape as catalog-level */] }]
20  }]
21}}}
```

--------------------------------

### Get CastleGate Purchase Orders Query

Source: https://developer.wayfair.io/posts/Cg-Orders-Guide

This query retrieves CastleGate purchase orders with various filtering and sorting options. Use the 'hasResponse' variable set to false to fetch new, open orders.

```graphql
query getCastleGatePurchaseOrders(
    $limit: Int32,
    $hasResponse: Boolean,
    $fromDate: IsoDateTime,
    $poNumbers: [String],
    $sortOrder: SortOrder
  ) {
    getCastleGatePurchaseOrders(
      limit: $limit,
      hasResponse: $hasResponse,
      fromDate: $fromDate,
      poNumbers: $poNumbers,
      sortOrder: $sortOrder
    ) {
      id
      poNumber
      poDate
      supplierId
      products {
        partNumber
        quantity
        price
        totalCost
      }
    }
  }
```

--------------------------------

### Query CastleGate Warehouse Shipment Advices

Source: https://developer.wayfair.io/posts/Cg-Orders-Guide

Retrieve a list of warehouse shipment advices (WSAs) for CastleGate purchase orders. Use filters like `hasResponse` (set to false for new shipments) and `fromDate` for effective data retrieval. The `limit` parameter controls the number of results.

```graphql
query getCastleGateWarehouseShippingAdvice(
  $limit: Int32,
  $hasResponse: Boolean,
  $fromDate: IsoDateTime,
  $wsaIds: [String],
  $sortOrder: SortOrder
) {
  getCastleGateWarehouseShippingAdvice(
    limit: $limit,
    hasResponse: $hasResponse,
    fromDate: $fromDate,
    wsaIds: $wsaIds,
    sortOrder: $sortOrder
  ) {
    wsaId
    supplierId
    poNumber
    shipDate
    shipSpeed
    carrierCode
    warehouseId
    products {
      quantityOrdered
      partNumber
      quantityShipped
    }
  }
}
```

--------------------------------

### Query Supplier Catalog Items

Source: https://developer.wayfair.io/posts/catalog-read-v2

Use this cURL command to query for supplier catalog items. Ensure you replace placeholders with your actual token and supplier ID. The query fetches basic catalog item details and pagination information.

```bash
curl --location 'https://api.wayfair.io/sandbox/v1/product-catalog-api/graphql' \
--header 'Authorization: Bearer <YOUR_TOKEN>' \
--header 'X-SELECTED-SUPPLIER-ID: <YOUR_SUPPLIER_ID>' \
--header 'Content-Type: application/json' \
--data '{ "query": "query { supplierCatalogItems(input: {\npaginationOptions: { page: 1, pageSize: 5 } }) { ... on
SupplierCatalogItems { paginationInfo { page hasNextPage totalCount
} catalogItems { supplierPartNumber catalogItemStatus class {
classId className } } } ... on SupplierCatalogItemsError { 
httpError { code message } internalError { code message } } } }" }'
```

--------------------------------

### Accept Purchase Order

Source: https://developer.wayfair.io/posts/dropship-orders-asn

This mutation allows you to accept a purchase order, specifying the shipping speed and line items you can fulfill. It returns a handle and the status of the acceptance.

```APIDOC
## Accept Purchase Order

### Description
This mutation allows you to accept a purchase order, specifying the shipping speed and line items you can fulfill. It returns a handle and the status of the acceptance.

### Method
POST

### Endpoint
https://sandbox.api.wayfair.com/v1/graphql

### Parameters
#### Query Parameters
None

#### Request Body
##### Variables
- **poNumber** (String!) - Required - The purchase order number you are responding to.
- **shipSpeed** (String!) - Required - The shipping speed for the order (e.g., "GROUND"). Must match the PO.
- **lineItems** (Array[Object]!) - Required - An array of objects, where each object represents a line item and contains the fields below:
  - **partNumber** (String!) - Required - The part number of the item being accepted. Must match the PO exactly.
  - **quantity** (Integer!) - Required - The number of units of this item you are accepting.
  - **unitPrice** (Float!) - Required - The item's unit price. Must match the PO exactly.
  - **estimatedShipDate** (String!) - Required - Your estimated ship date in ISO 8601 or "MM-DD-YYYY HH:MM:SS" format (UTC).

### Request Example
```graphql
mutation accept($poNumber: String!, $shipSpeed: ShipSpeed!, $lineItems: [AcceptedLineItemInput!]!) {
    purchaseOrders {
        accept(poNumber: $poNumber, shipSpeed: $shipSpeed, lineItems: $lineItems) {
            handle
            status
        }
    }
}
```

### Response
#### Success Response (200)
- **handle** (String) - The unique ID for this transaction.
- **status** (String) - The overall status (e.g., PROCESSING).

#### Response Example
```json
{
  "data": {
    "purchaseOrders": {
      "accept": {
        "handle": "some-handle-id",
        "status": "PROCESSING"
      }
    }
  }
}
```
```

--------------------------------

### Multichannel Order API

Source: https://developer.wayfair.io/integrations/api/playground

Provides endpoints for multichannel order management. Uses GraphQL.

```APIDOC
## Query FulfillmentOrderDetails

### Description
Retrieves details for a fulfillment order.

### Method
Query

### Endpoint
https://api.wayfair.io/v1/supplier-order-api/graphql
```

```APIDOC
## Query FulfillmentOrderDetailsList

### Description
Retrieves a list of fulfillment order details.

### Method
Query

### Endpoint
https://api.wayfair.io/v1/supplier-order-api/graphql
```

```APIDOC
## Query WarehouseShippingAdvices

### Description
Retrieves warehouse shipping advices.

### Method
Query

### Endpoint
https://api.wayfair.io/v1/supplier-order-api/graphql
```

```APIDOC
## Mutation CreateFulfillmentOrder

### Description
Creates a new fulfillment order.

### Method
Mutation

### Endpoint
https://api.wayfair.io/v1/supplier-order-api/graphql
```

```APIDOC
## Mutation CancelFulfillmentOrder

### Description
Cancels an existing fulfillment order.

### Method
Mutation

### Endpoint
https://api.wayfair.io/v1/supplier-order-api/graphql
```

--------------------------------

### Request Catalog Items with Pagination

Source: https://developer.wayfair.io/posts/catalog-read-v2

Use this snippet to request catalog items with specified pagination options. Ensure the paginationOptions object is correctly formatted.

```json
1{ "input": { "paginationOptions": { "page": 1, "pageSize": 30 } } }
```

--------------------------------

### Accept Purchase Order Mutation

Source: https://developer.wayfair.io/posts/dropship-orders-asn

Use this GraphQL mutation to accept a purchase order. Ensure all required variables, including line item details and estimated ship dates, are provided.

```graphql
mutation accept($poNumber: String!, $shipSpeed: ShipSpeed!, $lineItems: [AcceptedLineItemInput!]!) {
    purchaseOrders {
        accept(poNumber: $poNumber, shipSpeed: $shipSpeed, lineItems: $lineItems) {
            handle
            status
        }
    }
}
```

--------------------------------

### Query Open Orders

Source: https://developer.wayfair.io/posts/dropship-orders-asn

Use this JSON payload to query for open purchase orders. Set 'limit' to control the number of results and 'hasResponse' to indicate if a response is expected.

```json
{
    "limit": 10,
    "hasResponse": false
}
```

--------------------------------

### Python Full Pagination Loop for Catalog Items

Source: https://developer.wayfair.io/posts/catalog-read-v2

This Python script paginates through all catalog items, including rate-limit pacing. It demonstrates how to handle API responses, errors, and iterate through paginated results. Filtering options can be applied via the 'filter_' argument.

```python
import time, requests
ENDPOINT = "https://api.wayfair.io/sandbox/v1/product-catalog-api/graphql"
HEADERS = {
    "Authorization": "Bearer <YOUR_TOKEN>",
    "X-SELECTED-SUPPLIER-ID": "<YOUR_SUPPLIER_ID>",
    "Content-Type": "application/json",
}
QUERY = """
query ($input: SupplierCatalogItemsInput!) {
  supplierCatalogItems(input: $input) {
    ... on SupplierCatalogItems {
      paginationInfo { page hasNextPage totalCount }
      catalogItems { supplierPartNumber catalogItemStatus }
    }
    ... on SupplierCatalogItemsError {
      httpError { code message }
      internalError { code message }
    }
  }
}
"""
def iter_all(filter_=None):
    page = 1
    while True:
        variables = {"input": {"paginationOptions": {"page": page, "pageSize": 30}}}
        if filter_:
            variables["input"]["filter"] = filter_
        
        body = requests.post(ENDPOINT, headers=HEADERS, json={"query": QUERY, "variables": variables}, timeout=10).json()
        
        if body.get("errors"):
            raise RuntimeError(f"Validation error: {body['errors']}")
        
        result = body["data"]["supplierCatalogItems"]
        if result.get("httpError") or result.get("internalError"):
            raise RuntimeError(f"API error: {result}")
        
        yield from result["catalogItems"]
        
        if not result["paginationInfo"]["hasNextPage"]:
            break
        
        page += 1
        time.sleep(0.1)  # rate-limit pacing
# Usage:
# for item in iter_all(filter_={"catalogItemStatuses": ["NOT_LIVE"]}):
#     process(item)
```

--------------------------------

### Inventory API

Source: https://developer.wayfair.io/integrations/api/playground

Provides endpoints for inventory management. Uses GraphQL.

```APIDOC
## Mutation SaveInventory

### Description
Saves inventory updates.

### Method
Mutation

### Endpoint
https://api.wayfair.com/v1/graphql
```

--------------------------------

### Querying for Specific Orders

Source: https://developer.wayfair.io/posts/Cg-Orders-Guide

Use this snippet to query for specific orders using PO numbers, date ranges, and sort order.

```json
{
  "limit": 4,
  "hasResponse": false,
  "poNumbers": ["PO11112"],
  "fromDate": "2025-04-27 10:16:44.000000 -04:00",
  "sortOrder": "ASC"
}
```

--------------------------------

### Create Fulfillment Order

Source: https://developer.wayfair.io/posts/multichannel-orders

This mutation creates a new fulfillment order. It requires detailed input including seller order ID, supplier ID, customer and retailer information, items to be fulfilled, and shipping details. Optional fields include delivery signature requirement and billing address.

```APIDOC
## CreateFulfillmentOrder Mutation

### Description
Creates a new fulfillment order with specified details.

### Method
`mutation`

### GraphQL Operation
`createFulfillmentOrder`

### Parameters
#### Input: `CreateFulfillmentOrderInput`
- **sellerFulfillmentOrderId** (String) - Optional - Your unique identifier for this fulfillment order
- **supplierId** (Integer) - Required - Your Wayfair supplier ID
- **customer** (Object) - Required - Customer information including order number
- **retailer** (Object) - Required - Retailer details including retailer ID and order number
- **items** (Array) - Required - Array of products being fulfilled
- **shippingDetails** (Object) - Required - Shipping configuration including account and speed
- **deliverySignatureRequired** (Boolean) - Optional - Whether signature is required for delivery
- **billingAddress** (Object) - Optional - Customer billing address information
- **shippingAddress** (Object) - Required - Customer shipping address information

#### `customer` Object Fields:
- **orderNumber** (String) - Required - Customer’s order number

#### `retailer` Object Fields:
- **retailerId** (Integer) - Required - Wayfair-assigned retailer identifier. Must be greater than 0
- **orderNumber** (String) - Required - Retailer's order number

#### `items` Object Fields:
- **supplierPartNumber** (String) - Required - Your part number for the product.
- **quantity** (Integer) - Required - Number of units to fulfill. Must be greater than 0
- **supplierProductName** (String) - Optional - The supplier's name of the product
- **fulfillmentWarehouseId** (Integer) - Optional - The supplier choice of fulfillment warehouse Id. Must be greater than 0

#### `shippingDetails` Object Fields:
- **shippingAccountNumber** (String) - Optional - Shipping account number for billing
- **shipSpeedCode** (String) - Optional - Shipping speed code (e.g., "FDHD" for FedEx Home Delivery)
- **carrierScac** (String) - Optional - The Standard Carrier Alpha Code to identify the transportation company to be used. E.g., FDEG

#### `billingAddress` and `shippingAddress` Object Fields:
- **name** (String) - Required - Customer or facility name (For shipping address - max 35 characters)
- **address1** (String) - Required - Primary address line (For shipping address - max 35 characters)
- **address2** (String) - Optional - Secondary address line (For shipping address - max 35 characters)
- **city** (String) - Required - City name
- **stateShortName** (String) - Optional - State or province code
- **postalCode** (String) - Required - Postal or ZIP code
- **companyName** (String) - Optional - Name of the company at this address
- **countryShortName** (String) - Required - 2 or 3 character country code
- **phoneNumber** (String) - Optional - Phone number

### Response
#### Success Response (200 OK)
- **fulfillmentOrderRequestId** (String) - Unique order ID
- **requestStatus** (String) - Processing status (e.g., ACCEPTED)
- **errors** (Array) - Validation or business errors
  - **code** (String)
  - **message** (String)
  - **field** (String)
  - **value** (String)

### Request Example
```graphql
mutation CreateFulfillmentOrder($fulfillmentOrderInput: CreateFulfillmentOrderInput!) {
  createFulfillmentOrder(fulfillmentOrderInput: $fulfillmentOrderInput) {
    fulfillmentOrderRequestId
    requestStatus
    errors {
      code
      message
      field
      value
    }
  }
}
```

### Response Example
```json
{
  "data": {
    "createFulfillmentOrder": {
      "fulfillmentOrderRequestId": "12345-ABCDE",
      "requestStatus": "ACCEPTED",
      "errors": []
    }
  }
}
```
```

--------------------------------

### Query Supplier Catalog Items

Source: https://developer.wayfair.io/posts/catalog-read-v2

This snippet demonstrates how to query for supplier catalog items using the GraphQL API. It includes pagination options and specifies the fields to retrieve.

```APIDOC
## POST /product-catalog-api/graphql

### Description
Queries for supplier catalog items with specified pagination options.

### Method
POST

### Endpoint
https://api.wayfair.io/sandbox/v1/product-catalog-api/graphql

### Headers
- Authorization: Bearer <YOUR_TOKEN>
- X-SELECTED-SUPPLIER-ID: <YOUR_SUPPLIER_ID>
- Content-Type: application/json

### Request Body
- **query** (string) - Required - The GraphQL query string.
  - **supplierCatalogItems** (SupplierCatalogItemsInput) - Required - The root query field for retrieving catalog items.
    - **input** (SupplierCatalogItemsInput) - Required - Input for the supplierCatalogItems query.
      - **paginationOptions** (PaginationOptions) - Required - Options for pagination.
        - **page** (integer) - Optional - The page number to retrieve. Defaults to 1. Must be >= 1.
        - **pageSize** (integer) - Optional - The number of items per page. Defaults to 30. Must be in range [1, 30].

### Request Example
```json
{
  "query": "query { supplierCatalogItems(input: { paginationOptions: { page: 1, pageSize: 5 } }) { ... on SupplierCatalogItems { paginationInfo { page hasNextPage totalCount } catalogItems { supplierPartNumber catalogItemStatus class { classId className } } } ... on SupplierCatalogItemsError { httpError { code message } internalError { code message } } } }"
}
```

### Response
#### Success Response (200)
- **paginationInfo** (PaginationInfo) - Information about the pagination.
  - **page** (integer) - The current page number.
  - **hasNextPage** (boolean) - Indicates if there is a next page.
  - **totalCount** (integer) - The total number of items.
- **catalogItems** (array) - An array of catalog items.
  - **supplierPartNumber** (string) - The supplier's part number for the catalog item.
  - **catalogItemStatus** (string) - The status of the catalog item.
  - **class** (Class) - The category information for the product.
    - **classId** (string) - The ID of the class.
    - **className** (string) - The name of the class.
#### Error Response (e.g., 400, 500)
- **httpError** (HttpError) - HTTP-related error details.
  - **code** (string) - The HTTP error code.
  - **message** (string) - The HTTP error message.
- **internalError** (InternalError) - Internal system error details.
  - **code** (string) - The internal error code.
  - **message** (string) - The internal error message.

### Response Example
```json
{
  "data": {
    "supplierCatalogItems": {
      "paginationInfo": {
        "page": 1,
        "hasNextPage": true,
        "totalCount": 150
      },
      "catalogItems": [
        {
          "supplierPartNumber": "XYZ123",
          "catalogItemStatus": "ACTIVE",
          "class": {
            "classId": "12345",
            "className": "Chairs"
          }
        }
      ]
    }
  }
}
```
```

--------------------------------

### Request Access Token

Source: https://developer.wayfair.io/posts/api-access-tokens

Use this cURL request to obtain an access token from the authentication server. Replace placeholders with your actual Client ID and Client Secret.

```curl
curl -X POST https://sso.auth.wayfair.com/oauth/token \
-H 'content-type: application/json' \
-d '{
  "grant_type": "client_credentials",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
}'
```

--------------------------------

### Create Fulfillment Order GraphQL Mutation Structure

Source: https://developer.wayfair.io/posts/multichannel-orders

Defines the structure of the createFulfillmentOrder mutation and the variables it accepts for submitting a new fulfillment order.

```graphql
mutation createFulfillmentOrder($input: CreateFulfillmentOrderInput!) {
  createFulfillmentOrder(input: $input) {
    orderId
    orderNumber
    status
    errors {
      code
      message
    }
  }
}
```

--------------------------------

### Registration API

Source: https://developer.wayfair.io/integrations/api/playground

Provides endpoints for registration-related operations. Uses GraphQL.

```APIDOC
## Mutation RegisterPurchaseOrder

### Description
Registers a purchase order.

### Method
Mutation

### Endpoint
https://api.wayfair.com/v1/graphql
```

```APIDOC
## Query LabelGenerationEvents

### Description
Retrieves label generation events.

### Method
Query

### Endpoint
https://api.wayfair.com/v1/graphql
```

```APIDOC
## Query ConsolidatedBolDocument

### Description
Retrieves a consolidated Bill of Lading document.

### Method
Query

### Endpoint
https://api.wayfair.io/v1/supplier-order-api/graphql
```

--------------------------------

### Castlegate Inventory Onhand API

Source: https://developer.wayfair.io/integrations/api/playground

Provides endpoints for Castlegate inventory on-hand information. Uses GraphQL.

```APIDOC
## Query InventorySummaryList

### Description
Retrieves a list of inventory summaries for Castlegate.

### Method
Query

### Endpoint
https://api.wayfair.io/v1/supplier-order-api/graphql
```

--------------------------------

### Query Order List

Source: https://developer.wayfair.io/posts/multichannel-orders

Use this JSON payload to query a list of orders associated with a specific supplier ID.

```json
{
  "orderDetailsListInput": {
    "supplierId": 1803
  }
}
```

--------------------------------

### Create Fulfillment Order GraphQL Mutation

Source: https://developer.wayfair.io/posts/multichannel-orders

Use this mutation to create a new fulfillment order. Ensure all required fields in the input object are populated with valid data.

```graphql
mutation CreateFulfillmentOrder($fulfillmentOrderInput: CreateFulfillmentOrderInput!) {
  # Creates a new fulfillment order
  createFulfillmentOrder(fulfillmentOrderInput: $fulfillmentOrderInput) {
    fulfillmentOrderRequestId    # Unique order ID
    requestStatus                # Processing status (e.g., ACCEPTED)
    errors {
      code
      message
      field
      value
    }
  }
}
```

--------------------------------

### Querying for Acknowledged Orders

Source: https://developer.wayfair.io/posts/Cg-Orders-Guide

Use this snippet to query for acknowledged orders with a limit of 10.

```json
{
  "limit": 10,
  "hasResponse": true
}
```

--------------------------------

### CastleGate Orders and WSA API

Source: https://developer.wayfair.io/integrations/api/playground

Provides endpoints for CastleGate orders and Warehouse Shipping Advice (WSA). Uses GraphQL.

```APIDOC
## Query GetCastleGatePurchaseOrders

### Description
Retrieves CastleGate purchase orders.

### Method
Query

### Endpoint
https://api.wayfair.com/v1/graphql
```

```APIDOC
## Query GetCastleGateWarehouseShippingAdvice

### Description
Retrieves CastleGate Warehouse Shipping Advice.

### Method
Query

### Endpoint
https://api.wayfair.com/v1/graphql
```

```APIDOC
## Mutation AcknowledgeCastleGate

### Description
Acknowledges CastleGate orders.

### Method
Mutation

### Endpoint
https://api.wayfair.com/v1/graphql
```

```APIDOC
## Mutation AcknowledgeCastleGateWarehouseShippingAdvice

### Description
Acknowledges CastleGate Warehouse Shipping Advice.

### Method
Mutation

### Endpoint
https://api.wayfair.com/v1/graphql
```