NAV Navbar
cURL C# Ruby Python JS PHP Java
  • Wayfair API Documentation
  • Authentication
  • Test Endpoint
  • GraphQL
  • Inventory
  • Product
  • Orders
  • Shipping
  • Errors
  • Terms of Use & Privacy Policy
  • Wayfair API Documentation

    Welcome to Wayfair’s public API documentation. The Wayfair API provides a set of actions allowing external users to seamlessly integrate with Wayfair. We hope that this documentation helps you get up and running with your Wayfair integration.

    If you are a currently active Wayfair supplier who is interested in integrating with Wayfair's APIs, please submit a ticket here by selecting Inventory & EDI > Set Up an Inventory Feed or EDI Connection with Wayfair from the dropdown menus, then select the API Integration option. You should make these selections even if your initial API integration is for something other than Inventory.

    If you are not a Wayfair supplier and would like to become one, please visit our Sell on Wayfair page, which will help you get set up as a Wayfair supplier.

    Potential technology partners can visit the Wayfair Developer Network to learn about the advantages of integrating with Wayfair, obtain the necessary information to build a Wayfair integration, and initiate their onboarding process.

    Wayfair's API utilizes the OAuth client-credentials grant in a non-interactive profile for authentication and authorization. The majority of API functionality has been made available via GraphQL queries and mutations.

    Tooling

    All our tooling currently exists on Wayfair's Partner Home. If you do not have access and would like to build an integration please reach out to your integration contact.

    Authentication

    To get a token (JWT) use this code:

    using Newtonsoft.Json;
    using RestSharp;
    
    var authClient = new RestClient("https://sso.auth.wayfair.com/oauth/token");
    var requestBody = new {
        grant_type = "client_credentials",
        client_id = clientId,
        client_secret = clientSecret,
        audience = "https://sandbox.api.wayfair.com/"
    };
    var response = authClient.Execute(
        new RestRequest(Method.POST)
            .AddHeader("content-type", "application/json")
            .AddParameter("application/json", JsonConvert.SerializeObject(requestBody), ParameterType.RequestBody)
    );
    
    import java.io.IOException;
    import javax.json.*;
    import org.apache.http.HttpClient;
    import org.apache.http.HttpPost;
    import org.apache.http.HttpResponse;
    
    public class Wayfair_Auth_Client {
        public static void main(String[] args) throws IOException {
            HttpClient client = HttpClient.creadeDefault();
    
            HttpPost authRequest = new HttpPost("https://sso.auth.wayfair.com/oauth/token");
            authRequest.setHeader("Content-Type", "application/json");
    
            JsonObject authRequestBody = Json.createObjectBuilder()
                .add("client_id", InventoryMutator.clientId)
                .add("client_secret", InventoryMutator.clientSecret)
                .add("audience", "https://sandbox.api.wayfair.com/")
                .add("grant_type", "client_credentials")
                .build();
            authRequest.setEntity(new StringEntity(authRequestBody.toString()));
            HttpResponse response = client.execute(authRequest);
        }
    }
    
    var settings = {
      'async': true,
      'crossDomain': true,
      'url': 'https://sso.auth.wayfair.com/oauth/token',
      'method': 'POST',
      'headers': {
        'content-type': 'application/json',
        'cache-control': 'no-cache',
      },
      'data': {
        'grant_type':'client_credentials',
        'client_id': client_id,
        'client_secret': client_secret,
        'audience': 'https://sandbox.api.wayfair.com/'
      }
    }
    $.ajax(settings).done(function (response) {
      console.log(response);
    });
    
    $client = new \GuzzleHttp\Client();
    $response = $client->post(
      'https://sso.auth.wayfair.com/oauth/token',
      [
        'headers' => ['Content-Type' => 'application/json'],
        'body' => json_encode([
          'client_id' => $clientId,
          'client_secret' => $clientSecret,
          'audience' => 'https://sandbox.api.wayfair.com/',
          'grant_type' => 'client_credentials'
        ])
      ]
    );
    
    #! /bin/python
    import json
    import requests
    url = "https://sso.auth.wayfair.com/oauth/token"
    payload = '''
    {
      "grant_type":"client_credentials",
      "client_id": client_id,
      "client_secret": client_secret,
      "audience": "https://sandbox.api.wayfair.com/"
    }
    '''
    headers = {
        'content-type': "application/json",
        'cache-control': "no-cache",
    }
    response = requests.request("POST", url, data=payload, headers=headers)
    
    require "http"
    require "json"
    
    response = HTTP.headers({
      "Content-Type" => "application/json",
    }).post(
      "https://sso.auth.wayfair.com/oauth/token",
      :json => {
        "client_id" => client_id,
        "client_secret" => client_secret,
        "audience" => "https://sandbox.api.wayfair.com/",
        "grant_type" => "client_credentials"
      }
    )
    
    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://sandbox.api.wayfair.com/"
        }
      '
    

    Sample response:

    {
      "access_token":"eyJ0eXAiOiJKV1Qi...X1rNJFNVGBwmFQ5tepKwno7DEIjDg",
      "expires_in":43200,
      "scope":"read:inventory write:inventory",
      "token_type":"Bearer"
    }
    

    Authentication is performed using an OAuth client-credentials workflow. You POST your client id and secret to the token retrieval endpoint in order to get a new access token. This authenticated token must be included in all future API calls.

    Tokens have an expiration of 12 hours, so check the exp field in the token for the expiration date/time in seconds to see when you will need to re-authenticate by grabbing a new token. It is recommended that you maintain a buffer between the current time and time of expiration. For example, fetching a token every 6 hours would provide you some leeway to get a new token in the event of an outage.

    In order to use the Wayfair API you will need to register an application, which will allocate a client id and secret to you. You will pass these client id and secret values to the token endpoint.

    The token response will include your access token (access_token), an expiration length in seconds (expires_in), the scopes currently assigned to the token (scope), and the type of the token (token_type). When making requests to the API, you will need to set your HTTP Authorization header to {token_type} {access_token} from your token response. This will look something like Authorization: Bearer eyJ0eXAiOiJKV1Qi...X1rNJFNVGBwmFQ5tepKwno7DEIjDg.

    Note that the audience URL differs for Sandbox and Production applications. Sandbox applications should use https://sandbox.api.wayfair.com/, whereas production applications should use https://api.wayfair.com/.

    Test Endpoint

    Make a request to the test endpoint:

    using Newtonsoft.Json;
    using RestSharp;
    
    using System;
    using System.IO;
    using System.Linq;
    using System.Net;
    
    var client = new RestClient("https://sandbox.api.wayfair.com/v1/demo/clock");
    var response = client.Get(
        new RestRequest(Method.GET)
            .AddHeader("accept", "application/json")
            .AddHeader("content-type", "application/json")
            .AddHeader("authorization", string.Format("Bearer {0}", token))
    );
    
    import org.apache.http.HttpResponse;
    import org.apache.http.client.HttpClient;
    import org.apache.http.client.methods.HttpGet;
    import org.apache.http.impl.client.HttpClients;
    import java.io.IOException;
    
    public class ApiClient {
    
        public static void main(String[] args) throws IOException {
            HttpGet request = new HttpGet("https://sandbox.api.wayfair.com/v1/demo/clock");
            clockRequest.setHeader("Accept", "application/json");
            clockRequest.setHeader("Authorization", "Bearer " + token);
            clockRequest.setHeader("Content-Type", "application/json");
    
            HttpClient client = HttpClients.createDefault();
            HttpResponse response = client.execute(request);
        }
    }
    
    var clockRequestSettings = {
      'async': true,
      'crossDomain': true,
      'url': 'https://sandbox.api.wayfair.com/v1/demo/clock',
      'method': 'GET',
      'headers': {
        'authorization': 'Bearer ' + token,
        'cache-control': 'no-cache',
        'content-type': 'application/json'
      }
    };
    $.ajax(clockRequestSettings).done(function (response) {
      console.log(response);
    });
    
    $client = new \GuzzleHttp\Client();
    $response = $client->get(
      'https://sandbox.api.wayfair.com/v1/demo/clock',
      [
        'headers' => [
          'Authorization' => 'Bearer ' + token,
          'Content-Type' => 'application/json',
        ]
      ]
    );
    
    #! /bin/python
    import json
    import requests
    url = "https://sandbox.api.wayfair.com/v1/demo/clock"
    headers = {
        'Authorization': 'Bearer ' + token 
        'Content-Type': 'application/json',
    }
    response = requests.request('GET', url, headers=headers)
    
    require "http"
    require "json"
    
    response = HTTP.headers({
      "Authorization" => "Bearer " + token
      "Content-Type" => "application/json",
    }).get("https://sandbox.api.wayfair.com/v1/demo/clock")
    
    curl -X GET https://sandbox.api.wayfair.com/v1/demo/clock \
      -H 'Authorization: Bearer ${token}' \
      -H 'Content-Type: application/json'
    

    Sample response:

    {  
        "errors": [],  
        "data": {  
            "datetime": "2018-10-17T15:53:08-04:00",  
            "username": "1aphQ6YCp7MXrQDiy4ftv2lU5FQriktUw"  
        }  
    }  
    

    In order to get you off the ground We expose a test endpoint you can use to test both that your credentials work and that you can make requests to the API without issue. Our demo endpoint exists at https://sandbox.api.wayfair.com/v1/demo/clock, feel free to hit it and get the current time!

    Note that you'll probably want to use these samples in conjunction with the authentication samples.

    GraphQL

    Example Query

    query {
      identity {
        username,
        email,
        applications {
          name
        }
      }
    }
    

    Example Response

    {
      "identity": {
        "username": "john.doe",
        "email": "john.doe@gmail.com",
        "applications": [
          {
            "name": "John's First WayPI client"
          },
          {
            "name": "John's inventory client"
          }
        ]
      }
    }
    

    GraphQL is an API query language. It allows the client to ask the server for only the data which it needs. You can find a primer to GraphQL at graphql.org. GraphQL requests still happen via an HTTP POST, will always have query as a member of the POST body, and might also have variables as part of the post body.

    Note that due to GraphQL's type system, not all types will be included in these documents. You should visit GraphiQL for further schema exploration.

    Why GraphQL

    We use GraphQL because it gives power back to you to determine just what information you want from the API. GraphQL neatly solves the problems of overfetching and underfetching. You tell the server what data you want, and you only get back the data you wanted.

    Retrieving Data

    Query #1:

    {
      identity {
        username
        email
        applications {
          clientId
          name
        }
      }
    }
    

    Query #2: Simplified

    {
      identity {
        username
        email
      }
    }
    

    Query #3: Complex

    {
      identity {
        username
        email
        applications {
          clientId
          name
          description
          permissions {
            scope {
              name
              description
            }
          }
        }
      }
    }
    

    Queries are requests for reading information. Think of them like a normal REST GET request. Queries describe the shape of the data you want to receive, and look like the examples on the right.

    Depending on your needs, you can further refine the query. If, for instance, you weren't interested in your application information, you can drop it from the query. Query #2 on the right highlights this. Since we no longer need application information to be returned to our client we drop that field from the query. Now the query only contains the information we really need and the response will match.

    You can go the other way too, for instance, if you need more application information you can add the fields you need to the query. For instance, let's retrieve application permissions. In Query #3 we have expanded the query to load some additional information that we didn't have before. Different clients need different data and the flexibility of GraphQL allows our clients to retrieve no more or less than what they need without needing to change the endpoint or performing additional requests.

    Updating Data

    Example Mutation

    mutation {
        applications {
            update(
                application: {
                    clientId: "my client id",
                    name: "A better name than before",
                    description: "An even better description!"
                }
            ) {
                clientId
                name
                description
            }
        }
    }
    

    Mutations are how you update data in GraphQL. Mutations look very similar to queries, but require a bit more information. Mutations are always labeled as such, and usually get a name. Consider the example on the right, which updates the name and description of an application.

    This mutation updates the application, and receives an application back. If you don't need some of the fields back from the mutation, you can drop them just like you would for a query.

    Variables

    Payload for GraphQL call

    {
      "query":"
        mutation updateApplication($myApplication: ApplicationInput!) {
          applications {
            update(
              application: $myApplication
            ) {
              clientId
              name
              description
            }
          }
        }
      ",
      "variables": {
        "myApplication": {
          "clientId": "my client id",
          "name": "My variable application",
          "description": "A variable description!"
        }
      }
    }
    

    The above example shows how we might send a crafted mutation to the server with values interpolated directly into the request query member. While this is allowed, it's much better to send your data in the request variables member. In this case our request looks a bit different.

    We have made the query text reusable, and the server will now run the mutation with the values you've sent in the variables member of your request. In this case, the payload would look like the example to the right.

    Inventory

    The Inventory API is used to read and update your inventory with us.

    Inventory Query

    query inventory {  
        inventory(  
            limit: 10
        ) {  
            supplierPartNumber,  
            quantityOnHand,  
            quantityBackordered,  
            quantityOnOrder,  
            discontinued,  
            itemNextAvailabilityDate  
        }  
    }  
    

    There is currently only one inventory query. This query allows suppliers to load the current inventory Wayfair has in their system. Inventory queries will usually look similar to the example on the right.

    Input

    Name Type Description
    filters InventoryFilterInput = [] A set of filters for limiting the result set.
    ordering orderingInput = [{asc: "supplierPartNumber"}] A list of ordering types that determine the order the result set should be presented.
    limit Int = 10 The maximum number of records to return.
    offset Int = 0 How deep into the result set to look for the first item.

    Output

    Type Description
    [Inventory] A list where each item represents the inventory information for a single part.

    InventoryFilterInput Type

    Name Type Description
    supplierPartNumber String! The part number of the product.
    quantityOnHand Int! The number of units on hand and still available for sale.
    quantityBackorder Int The number of backordered units.
    quantityOnOrder Int The number of units allocated to open orders.
    discontinued Boolean = false Whether or not the product has been discontinued.
    itemNextAvailabilityDate String The next time this product will be available.

    OrderingInput Type

    Name Type Description
    asc String The ascending ordering.
    desc String The descending ordering.

    Save Inventory Mutation

    {
      "query": "
        mutation inventory($inventory: [inventoryInput]!) {  
          inventory {  
            save(  
              inventory: $inventory,  
              feed_kind: DIFFERENTIAL
            ) {  
              id,  
              handle,  
              status,  
              submittedAt,  
              completedAt  
            }  
          }  
        }  
      ",
      "variables": {
        "inventory": [  
          {  
            "supplierId": 5000,  
            "supplierPartNumber": "XXXXXXXX",  
            "quantityOnHand": 5,  
            "quantityBackordered": 10,  
            "quantityOnOrder": 2,  
            "itemNextAvailabilityDate": "05-31-2021 00:00:00",  
            "discontinued": true,  
            "productNameAndOptions": "My Awesome Product"  
          },  
          {
            "supplierId": 5000,
            "supplierPartNumber": "YYYYYYYY",
            "quantityOnHand": 5,
            "quantityBackordered": 10,
            "quantityOnOrder": 2,
            "itemNextAvailabilityDate": "05-31-2021 00:00:00",
            "discontinued": true,
            "productNameAndOptions": "My Awesome Product"
          }
       ]  
     }
    }
    

    The inventory mutation allows you to update your inventory with us. The mutation takes a list of inventory inputs, which can be as long or as short as you like (you'll start getting errors if it gets too long). For the sake of bandwidth, we suggest that you queue your inventory updates and send them no faster than once per minute.

    Input

    Name Type Description
    inventory [InventoryInput]! A list of inventory data. One row per part.
    feed_kind inventoryFeedKind = DIFFERENTIAL DIFFERENTIAL if the mutation only contains some of a supplier's inventory, otherwise TRUE_UP.

    Output

    Type Description
    TransactionStatus! Updating inventory is an asynchronous operation that will take up to 15 minutes to be finalized. The transaction returned by this mutation is how clients can track the progress of the operation.

    InventoryInput Type

    Name Type Description
    supplierId Int! The id of the supplier/warehouse that has this product.
    supplierPartNumber String! The part number of the product.
    quantityOnHand Int! The number of units on hand and still available for sale.
    quantityBackorder Int The number of backordered units.
    quantityOnOrder Int The number of units allocated to open orders.
    itemNextAvailabilityDate String The next time this product will be available.
    discontinued Boolean = false Whether or not the product has been discontinued.
    productNameAndOptions String The name of the product along with any options to be submitted for it.

    Inventory error details

    Product

    Wayfair has a GraphQL API endpoint for updating live product information, as well as a status checker endpoint for checking the statuses of previously submitted product information updates through the update endpoint.

    Product Update Mutation

    {
        "query":"
          mutation product($supplierId: Int32!, $products:[UpdateProductInput!]!) {
            product {
                update(
                    supplierId: $supplierId,
                    products: $products
                    dryRun: true
                ) {
                    handle,
                    status,
                    submittedAt,
                    completedAt,
                    errors {
                        key,
                        message
                    }
                }
            }
        }
        ",
        "variables":{
            "supplierId": 2603,
            "products":[
                {
                    "supplierPartNumber": "xxxx1234",
                    "shipVia": "SMALL_PARCEL"
                },
                {
                    "supplierPartNumber": "xxxx5678",
                    "shipVia": "WHITE_GLOVE_GOLD"
                }
    
        ]
        }
    }
    

    The Product Update Mutation allows for updating fields pertinent to live products. The mutation allows for updating multiple products at a time. The information is queued to be processed asynchronously. The status of the updates can be checked via the Product Update Status Query.

    Input

    Name Type Description Default
    supplierId Int32! The ID of the Supplier updating or owning the product information NA
    products [UpdateProductInput!]! A list of update product input types representing product information NA
    dryRun Boolean The dry run flag lets you choose whether to run a dry run for the update or to actually run the mutation to update live product information true

    UpdateProductInput Type

    Name Type Description
    supplierPartNumber String! The supplier part number of the product being updated
    shipVia ShipClass This input field represents the new ship type value for the product

    Output

    Type Description
    TransactionStatus! Product update is an asynchronous operation. The handle string returned with the transaction data can be used to track the progress of your mutation using the Product Update Status Query.

    Product Update Status Query

    {
        "query":"
            query productUpdateStatus {
                productUpdateStatus(
                    handle: "1A2B3C4D-2B3D-1A2B-1234-2A1B3C4D1A4B"
                ) {
                    status,
                    productTransactions {
                        supplierPartNumber,
                        status,
                        properties {
                            message,
                            status,
                            propertyName
                        }
                    },
                    message
                }
            }"
    }
    

    The Product Update Status Query allows suppliers to check the progress of product updates submitted with the Product Update Mutation. Since the product updates submitted through the product update mutation are processed in an asynchronous manner, this query allows the user to check the status of the updates for each individual product and it's specified fields.

    Input

    Name Type Description
    handle String! The unique identifier string used to track the progress of a product update mutation

    Output

    Name Type Description
    productUpdateStatus ProductUpdateTransactionStatus The data object containing product update status information.

    ProductUpdateTransactionStatus Type

    Name Type Description
    handle String! The identifier string for the product update transaction submitted.
    status TransactionState! The field that represents one of four states of a transaction (NEW, PROCESSING, ERROR, COMPLETE).
    productTransactions [SupplierPartUpdateTransactionStatus!]! The data object containing product update status information at the product or supplier part level and the property or field level.
    message String Any information the user must know regarding the product update status query submitted, such as validation errors or internal server errors.

    SupplierPartUpdateTransactionStatus Type

    Name Type Description
    handle String! The identifier string for the product update transaction submitted.
    supplierPartNumber String! The supplier part number of the product whose status is being returned.
    status TransactionState! The field that represents one of four states of a transaction (NEW, PROCESSING, ERROR, COMPLETE).
    properties [ProductAttributeUpdateTransactionStatus!]! The data object containing product update status information at the property or field level.

    ProductAttributeUpdateTransactionStatus Type

    Name Type Description
    handle String! The identifier string for the product update transaction submitted.
    message String Any information the user must know regarding the product update status query submitted, such as validation errors or internal server errors at the property or field level.
    status TransactionState! The field which represents one of four states of a transaction (NEW, PROCESSING, ERROR, COMPLETE).
    propertyName String! The name of the field or property of the product whose update status is being returned.

    Product Errors

    The Product Update Status Query handles reporting update failures by returning a transaction state of type ERROR as well as by returning error messages. The query currently returns a user readable error message for different types of update failures for the shipVia field.

    Business Case Update Failure

    This is an update failure which gets triggered due to an unsupported business case for the field update. Currently, this failure can get triggered for a product's shipVia update if there is a business exception that prevents the product's shipVia value to be updated. The specific error message returned is "Unable to update. Please create a ticket for this request." which notifies the user making the request to create a ticket for this failure so that the business case can be implemented.

    Update Service Failure

    This is an update failure which gets triggered if the service responsible to update the field fails. Currently, this failure can get triggered for a product's shipVia update if the shipVia service responsible for updating the shipVia value of a product fails. The specific error message returned is "Unable to update ship via at this time. Please try again later." which notifies the user making the request to retry the update when the service failure might have been resolved.

    Product Category Query

    {
        "query":"
            query productCategories {
                productCategories(
                    limit: 10
                ) {
                    id,
                    name
                }
            }"
    }
    

    The Product Category Query allows users to query existing product categories based on specified filters. The filters are specified as query parameter inputs while executing the query.

    Input

    Name Type Description Default
    limit Int This is the limit parameter used to get a specific number of product categories ordered by their (id)s in ascending order 10
    offset Int The index of the result set to start at. If an offset is provided as an input parameter, all items at an index before the offset will be eliminated from the results. 0
    ordering [orderingInput] A list of orderings to order the result set by. The first item in the list has the highest priority and the last has the least. NA
    filters [ProductCategoryFilterInput] A list of filter input types for filtering class data to be retrieved. []

    ProductCategoryFilterInput Type

    Name Type Description
    field ProductCategoryFilterFields The filterable fields on the query's return type.
    conjunction FilterConjunction The conjunction to add to the filter. Accepted values: AND, OR. If only one filter exists for the query, this will be ignored
    equals String The equals (=) comparator. A value of the ProductCategory type should be provided for checking equality while querying
    greaterThan String The greater than (>) comparator. A value of the ProductCategory type should be provided for checking if the vaue is greater than the specified while querying
    greaterThanOrEqualTo String The greater than or equal (>=) to comparator. A value of the ProductCategory type should be provided for checking if the vaue is greater than or equal to the specified while querying
    lessThan String The less than (<) comparator. A value of the ProductCategory type should be provided for checking if the vaue is lesser than the specified while querying
    lessThanOrEqualTo String The less than or equal (<=) to comparator. A value of the ProductCategory type should be provided for checking if the vaue is lesser than or equal to the specified while querying
    notEqualTo String The not equal (!=) comparator. A value of the ProductCategory type should be provided for checking if the vaue is not equal to the specified while querying
    in [String] This parameter is used to specify values of the ProductCategory type as a list of strings to check if the retrieved values should be confined to the ones specified.
    notIn [String] This parameter is used to specify values of the ProductCategory Type as a list of strings to check if the retrieved values are not in the ones specified.
    isNull Boolean This parameter is used to specify whether null values in the result set should be included

    ProductCategoryFilterFields Type

    Name Description
    id The id of the product category
    name The name of the product category

    OrderingInput Type

    Name Type Description
    asc String A key input parameter specifier you can use in the orderingInput dictionary to specify a product category attribute to be used to order the result set in ascending.
    desc String A key input parameter specifier you can use in the orderingInput dictionary to specify a product category attribute to be used to order the result set in descending.

    Output

    Name Type Description
    productCategories [ProductCategory] The data object containing a list of product categories.

    ProductCategory Type

    Name Type Description
    id Int! The unique identifier for a product category.
    name String! The name of the product category.

    Product Class Query

    {
        "query":"
            query productClasses {
                productClasses(
                    limit: 10,
                    filters:{
                        field:id,
                        in:["6","3"]    
                        }
                ){
                    id,
                    name,
                    categoryId,
                    categoryName
                }
            }"
    }
    

    The Product Class Query allows users to query existing product classes based on specified input parameters.

    Input

    Name Type Description Default
    limit Int This is the limit parameter used to get a specific number of product classes ordered by their (id)s in ascending order 10
    offset Int The index of the result set to start at. If an offset is provided as an input parameter, all items at an index before the offset will be eliminated from the results. 0
    ordering [orderingInput] A list of orderings to order the result set by. The first item in the list has the highest priority and the last has the least. NA
    filters [ProductClassFilterInput] A list of filter input types for filtering class data to be retrieved. []

    OrderingInput Type

    Name Type Description
    asc String A key input parameter specifier you can use in the orderingInput dictionary to specify a product class attribute to be used to order the result set in ascending.
    desc String A key input parameter specifier you can use in the orderingInput dictionary to specify a product class attribute to be used to order the result set in descending.

    ProductClassFilterInput Type

    Name Type Description
    field ProductClassFilterFields The filterable fields on the query's return type.
    conjunction FilterConjunction The conjunction to add to the filter. Accepted values: AND, OR. If only one filter exists for the query, this will be ignored.
    equals String The equals (=) comparator. A value of the ProductClass type should be provided for checking equality while querying.
    greaterThan String The greater than (>) comparator. A value of the ProductClass type should be provided for checking if the vaue is greater than the specified while querying.
    greaterThanOrEqualTo String The greater than or equal (>=) to comparator. A value of the ProductClass type should be provided for checking if the vaue is greater than or equal to the specified while querying.
    lessThan String The less than (<) comparator. A value of the ProductClass type should be provided for checking if the vaue is lesser than the specified while querying.
    lessThanOrEqualTo String The less than or equal (<=) to comparator. A value of the ProductClass type should be provided for checking if the vaue is lesser than or equal to the specified while querying.
    notEqualTo String The not equal (!=) comparator. A value of the ProductClass type should be provided for checking if the vaue is not equal to the specified while querying.
    in [String] This parameter is used to specify values of the ProductClassType as a list of strings to check if the retrieved values should be confined to the ones specified.
    notIn [String] This parameter is used to specify values of the ProductClassType as a list of strings to check if the retrieved values are not in the ones specified.
    isNull Boolean This parameter is used to specify whether null values in the result set should be included

    ProductClassFilterFields Type

    Name Description
    id The id of the product class.
    name The name of the product class.
    categoryId The category id of the product class.
    categoryName The category name of the product class.
    catalogLanguage The language for which we are retrieving the classes. If none is specified we default to ENGLISH_US.

    Output

    Name Type Description
    productClasses [ProductClass] The data object containing a list of product classes.

    ProductClass Type

    Name Type Description
    id Int! The unique identifier for a product class.
    name String! The name of the product class.
    categoryId String! The unique identifier for the product category that the class is a part of.
    categoryName String! The name of the product category that the class is a part of.
    options [ProductClassOption] List of product class options including category name and rank.
    attributes [ProductClassAttribute] List of product class attributes.

    ProductClassOption Type

    Name Type Description
    categoryName String Name of the option category.
    rank String The rank of the option.

    ProductClassAttribute Type

    Name Type Description
    id Int Unique identifier for a product attribute associated with the class.
    name String The name of the product attribute associated with the class.
    parentId Int If the attribute is a child attribute, this id is a unique identifier of the attribute's parent.
    priority String The priority of the attribute.
    dataType String The data type that the attribute is represented by.
    definition String A descriptive definition of what the attribute actually represents
    displayRank Int The display rank or the display priority of the attribute.
    enumValues [String] List of enumerated values for the attribute. This list specifies if the attribute value should be in a list of specific values.

    Orders

    The Order Management APIs allow suppliers to retrieve dropship and CastleGate purchase orders from Wayfair and send updates on milestones in the fulfillment process. Orders can retrieved based off filters such as date or whether it has received a response.

    Dropship Order Query

    query getDropshipPurchaseOrders {
        getDropshipPurchaseOrders(
            limit: 10,
            hasResponse: false,
            sortOrder: DESC
        ) {
            poNumber,
            poDate,
            estimatedShipDate,
            customerName,
            customerAddress1,
            customerAddress2,
            customerCity,
            customerState,
            customerPostalCode,
            orderType,
            shippingInfo {
              shipSpeed,
              carrierCode
            },
            packingSlipUrl,
            warehouse {
              id,
              name
            },
            products {
                partNumber,
                quantity,
                price,
                event {
                  startDate,
                  endDate
                }
            },
        }
    }
    

    The Dropship APIs allow you to accept dropship orders and inform Wayfair when you have shipped the order (backorder or reject responses will still need to be actioned via Partner Home).

    The query arguments can be tailored to your needs. For instance, the query in the examples section will pull only open orders (i.e orders with no response), but you could flip the hasResponse filter to only pull closed orders or omit it altogether to pull all orders.

    NOTE: By default, we prefer suppliers to use the getDropshipPurchaseOrders query to review their purchase orders. If you are using the older purchaseOrders query, please contact your Wayfair Integration Representative with any questions.

    Input

    Name Type Description
    limit Int = 10 The maximum number of results to return. If a limit is set and the result set contains more items than the limit, then a subset of the results with a count equal to limit will be returned. If no limit is set, the default is 10.
    hasResponse Boolean Whether a Purchase Order has received a response (usually an order acceptance). If the Purchase Order doesn't have a response (hasResponse = false), it corresponds to an OPEN status.
    fromDate IsoDateTime The Purchase Order starting date period. Specifies the starting date from which to grab purchase orders.
    poNumbers [String] = [] The list of Purchase Order numbers to filter by.
    sortOrder SortOrder = ASC Order the result set by ascending or descending order of poDate.

    Output

    Type Description
    [PurchaseOrder] A list of purchase orders. The result set will abide by the input arguments provided.

    Accept Order Mutation

    {
      "query": "
        mutation acceptOrder($poNumber: String!, $shipSpeed: ShipSpeed!, $lineItems: [AcceptedLineItemInput!]!) {
          purchaseOrders {
            accept(
              poNumber: $poNumber,
              shipSpeed: $shipSpeed,
              lineItems: $lineItems
            ) {
              id,
              handle,
              status,
              submittedAt,
              completedAt
            }
          }
        }
      ",
      "variables": {
        "poNumber": "CS12345678",
        "shipSpeed": "GROUND",
        "lineItems": [
          {
            "partNumber": "ABC123456",
            "quantity": 1,
            "unitPrice": 17.07,
            "estimatedShipDate": "2020-04-27 10:16:44.000000 -04:00"
          },
          {
            "partNumber": "CBA654321",
            "quantity": 1,
            "unitPrice": 15.05,
            "estimatedShipDate": "2020-04-27 10:16:44.000000 -04:00"
          }
        ]
      }
    }
    

    This mutation lets Wayfair know you have accepted a set of order items. We expect that you have added this to a list of items that need to be picked and shipped from your warehouse. We also expect that you are going to update your inventory shortly using the Inventory API (or another method) to let us know how much product you have in stock.

    Input

    Name Type Description
    poNumber String! The number of the order you received from Wayfair that you want to accept.
    shipSpeed ShipSpeed! The delivery method of the order.
    lineItems [AcceptedLineItemInput!] A list of the parts on the order that are being accepted.

    Output

    Type Description
    TransactionStatus! Accepting orders is an asynchronous operation. The transaction data returned to you can be used to track the progress of your mutation.

    AcceptedLineItemInput Type

    Name Type Description
    partNumber String! The part number of the item being accepted.
    quantity Int! The number of this item that are being accepted.
    unitPrice Float! The item's unit price.
    estimatedShipDate IsoDateTime! The item's estimated ship date

    Ship Notification Mutation

    {
      "query": "
        mutation shipment($notice: ShipNoticeInput!) {
            purchaseOrders {
              shipment(notice: $notice) {
                id,
                handle,
                status,
                submittedAt,
                completedAt
               }
            }
        }
      ",
      "variables": {
        "notice": {  
            "poNumber": "AB123456789",   
            "supplierId": 5000,   
            "packageCount": 2,   
            "weight": 184,   
            "volume": 22986.958176,   
            "carrierCode": "FDEG",   
            "shipSpeed": "SECOND_DAY_AIR",   
            "trackingNumber": "210123456789",   
            "shipDate": "2020-04-10 12:16:19.000000 -06:00",   
            "sourceAddress": {
              "name": "Wayfair",
              "streetAddress1": "4 Copley Place",
              "city": "Boston",
              "state": "MA",
              "postalCode": "02120",
              "country": "USA"
            },
            "destinationAddress": {  
              "name": "Jane Doe",   
              "streetAddress1": "123 Main St.",   
              "city": "Boston",   
              "state": "MA",   
              "postalCode": "02122",   
              "country": "USA"
            },  
            "largeParcelShipments": [  
              {  
                "partNumber":"ABA1012GAB",  
                "packages":[  
                  {  
                    "code":{  
                      "type":"TRACKING_NUMBER",  
                      "value":"210123456781"  
                    },  
                    "weight": 150  
                  }  
                ]  
              },  
              {  
                "partNumber":"ABA1012GAC",  
                "packages":[  
                  {  
                    "code":{  
                      "type":"TRACKING_NUMBER",  
                      "value":"210123456782"  
                    },  
                    "weight": 150  
                  }  
                ]  
              }  
            ],  
            "smallParcelShipments": [  
              {  
                "package": {  
                  "code": {  
                    "type": "TRACKING_NUMBER",   
                    "value": "210123456783"  
                  },   
                  "weight": 92  
                },   
                "items": [  
                  {  
                    "partNumber": "ABA1012GAD",   
                    "quantity": 1  
                  }  
                ]  
              },   
              {  
                "package": {  
                  "code": {  
                    "type": "TRACKING_NUMBER",   
                    "value": "210123456784"  
                  },   
                  "weight": 92  
                },   
                "items": [  
                  {  
                    "partNumber": "ABA1012GAB",   
                    "quantity": 1  
                  }  
                ]  
              }  
            ]  
          }
      }
    }
    

    Alert Wayfair when you have shipped an item.

    Input

    Name Type Description
    notice ShipNoticeInput! This input contains all the information about the shipment that Wayfair needs to track the package and relay the information to the customer.

    Output

    Type Description
    TransactionStatus The Ship Notification is an asynchronous operation. The transaction data returned to you can be used to track the progress of your mutation.

    ShipNoticeInput Type

    Name Type Description
    poNumber String! The identifier for the purchase order that this notice is acknowledging shipment for.
    supplierId ID! The identifier of the supplier that is shipping this purchase order out.
    packageCount Int! The total number of packages that are a part of this order.
    weight Float The total weight of all the packages in this purchase order in pounds.
    volume Float The volume of all the packages in this purchase order in cubic feet.
    carrierCode String! The standard carrier alpha code (SCAC).
    shipSpeed ShipSpeed! The ship speed of this purchase order.
    trackingNumber String! The tracking number of the order.
    shipDate IsoDateTime! The date the order was shipped. Must be fewer than 10 days in the past and no more than 1 day in the future.
    sourceAddress AddressInput! The address the order shipped from.
    destinationAddress AddressInput! The address the order is shipping to.
    smallParcelShipments [SmallParcelShipmentInput!] A list of the small parcel packages that were shipped.
    largeParcelShipments [LargeParcelShipmentInput!] A list of the large parcel items and their packages that were shipped.

    ShipSpeed Type

    Name Description
    SECOND_DAY_AIR 2nd Day Air Delivery.
    SECOND_DAY_AIR_FREE 2-Day Delivery -- Free!
    FIVE_DAY_DIRECT Global 5-Day Direct Delivery
    THREE_DAY 3 Day Delivery
    CONTAINER Container
    EMAIL Zustellung per Email
    FEDEX_HOME FedEx Home Delivery
    GROUND Small Parcel Courier
    PAKETVERSAND Small Parcel Courier
    IMPERIAL_POOL_FREIGHT Imperial Pool Freight
    NEXT_DAY Next Day Air
    NEXT_DAY_OVERSEAS Next Day Air (AK,HI,PR)
    NEXT_MORNING UK - SP - Next day before noon
    NEXT_DAY_BEFORE_NINE UK - SP - Next day before 9am
    WILL_CALL Will Call
    SATURDAY_DELIVERY UK - SP - Saturday delivery
    TRUCK_FREIGHT_CASKETS_ONE_DAY Casket Delivery - 1 Day
    TRUCK_FREIGHT_CASKETS_TWO_DAY Casket Delivery - 2 Day
    CURBSIDE_WITH_UNLOAD Curbside with unload service
    TRUCK_LOAD Truck Load
    CURBSIDE Curbside without unload service
    WHITE_GLOVE_BRONZE Spedition - frei Bordsteinkante
    WHITE_GLOVE_GOLD Room of Choice & Packaging Removal
    WHITE_GLOVE_TWO_MAN Premium 2-Man Delivery
    WHITE_GLOVE_PLATINUM Room of Choice Delivery with Installation
    WHITE_GLOVE_SILVER Room of Choice
    TRUCK_FREIGHT_THRESHOLD Truck Freight - Threshold
    STANDARD_VERSAND_SPERRGUT Standard-Versand Sperrgut
    ALMO ALMO - Room of Choice + Removal of Old Appliance
    LARGE_PARCEL_COURIER Large Parcel Courier
    EUROPEAN_LINE_HAUL European Line Haul
    ECONOMY Economy
    WHITE_GLOVE_ROOM_OF_CHOICE White Glove Delivery - Room of Choice
    TINY_PARCEL Small Parcel
    GROUND_OVERSEA GROUND (AK,HI,PR)
    LOW_COST_CARRIER Low Cost Carrier

    AddressInput Type

    Name Type Description
    name String! The name of the residence.
    streetAddress1 String! Primary street address information.
    streetAddress2 String! Secondary street address information.
    city String! The city.
    state String! The state or province.
    postalCode String! The postal code.
    country String! The country code.

    SmallParcelShipmentInput Type

    Name Type Description
    package PurchaseOrderPackageInput! A small parcel package
    items [SmallParcelItemInput!] A list of items that are in this small parcel package.

    LargeParcelShipmentInput Type

    Name Type Description
    partNumber String! The part number of the item being shipped large parcel.
    packages [PurchaseOrderPackageInput!] The packages that the large parcel item is being sent in.

    PurchaseOrderPackageInput Type

    Name Type Description
    code PackageTrackingCode! The tracking code for the package.
    weight Float The total weight of the package.

    SmallParcelItemInput Type

    Name Type Description
    partNumber String! The part number of the item.
    quantity Int! The number of this item in the small parcel package.

    PackageTrackingCode Type

    Name Type Description
    packageTrackingCodeTypeEnum PackageTrackingCodeTypeEnum! The type of tracking code.
    value String! The value of the tracking code.

    PackageTrackingCodeTypeEnum Type

    Name Description
    TRACKING_NUMBER A simple package tracking number.
    UCC_128 A UCC-128 code.

    CastleGate Order Query

    query getCastleGatePurchaseOrders {
        getCastleGatePurchaseOrders(
            limit: 10,
            hasResponse: false,
            sortOrder: DESC
        ) {
            poNumber,
            poDate,
            estimatedShipDate,
            customerName,
            customerAddress1,
            customerAddress2,
            customerCity,
            customerState,
            customerPostalCode,
            orderType,
            shippingInfo {
                shipSpeed,
                carrierCode
            },
            packingSlipUrl,
            warehouse {
                id,
                name
            },
            products {
                partNumber,
                quantity,
                price,
                event {
                    startDate,
                    endDate
                }
            }
        }
    }
    

    For CastleGate purchase orders, you can send an acknowledgment of receipt of the order.

    The query arguments can be tailored to your needs. For instance, the query in the examples section will pull only open orders (i.e orders with no response), but you could flip the hasResponse filter to only pull closed orders or omit it altogether to pull all orders.

    Input

    Name Type Description
    limit Int = 10 The maximum number of results to return. If no limit is set, the default is 10.
    hasResponse Boolean Whether a CastleGate Purchase Order has received an acknowledgment via API.
    fromDate IsoDateTime The CastleGate Purchase Order starting date period. Specifies the starting date from which to grab purchase orders.
    poNumbers [String] = [] The list of Purchase Order numbers to filter by.
    sortOrder SortOrder = ASC Order the result set by ascending or descending order of poDate.

    Output

    Type Description
    [PurchaseOrder] A list of purchase orders. The result set will abide by the input arguments provided.

    Acknowledge CastleGate Order Mutation

    {
      "query": "
        mutation acknowledgeCastleGate($poNumber: String!) {
          purchaseOrders {
            acknowledgeCastleGate(
              poNumber: $poNumber
            ) {
              id,
              handle,
              status,
              submittedAt,
              completedAt
            }
          }
        }
      ",
      "variables": {
        "poNumber": "CS12345678"
      }
    }
    

    This mutation lets Wayfair know you have acknowledged receipt of a CastleGate purchase order via an earlier query.

    Input

    Name Type Description
    poNumber String! The number of the order you received from Wayfair that you want to acknowledge.

    Output

    Type Description
    TransactionStatus! Acknowledging CastleGate orders is an asynchronous operation. The transaction data returned to you can be used to track the progress of your mutation.

    CastleGate Warehouse Shipping Advice

    When Wayfair ships a CastleGate Purchase Order, we create a Warehousing Shipping Advice (WSA) with our own unique identifier called a "WSA ID." Suppliers can query and acknowledge WSAs, and update their current product quantities accordingly.

    Get CastleGate Warehouse Shipping Advice Query

    {
      "query": "
        query getCastleGateWarehouseShippingAdvice($limit: Int32!, $hasResponse: Boolean!, $fromDate: IsoDateTime!, $wsaIds: [String]!) {
          purchaseOrders {
            getCastleGateWarehouseShippingAdvice(
              limit: $limit,
              hasResponse: $hasResponse,
              wsaIds: $wsaId,
              fromDate: $fromDate
            ) {
            'wsaId',
            'supplierId',
            'retailerOrderNumber',
            'fulfillmentPurchaseOrderNumber',
            'creationDate',
            'shipDate',
            'shipSpeed',
            'carrierCode',
            'totalShipmentWeight',
            'totalQuantity',
            'clientNumber',
            'warehouseId',
            'packages' => [
                'packageWeight',
                'trackingNumber',
            ],
            'shipTo' => [
                'name',
                'address1',
                'address2',
                'city',
                'state',
                'country',
                'postalCode',
            ],
            'shipFrom' => [
                'name',
                'address1',
                'address2',
                'city',
                'state',
                'country',
                'postalCode',
            ],
            'products' => [
                'quantityOrdered',
                'partNumber',
                'name',
                'quantityShipped',
                'upc',
                'sku',
                'forceQuantityMultiplier',
            ],
            }
          }
        }
      ",
      "variables": {
        "limit": 10,
        "hasResponse": false,
        "wsaIds": "6F96C5C4-C3C-4D29-84CA-0B050F7E961A",
        "fromDate": "2020-04-05 00:05:00"
      }
    }
    

    Get Warehouse Shipping Advice for CastleGate purchase orders.

    Input

    Name Type Description
    limit Int32 = 10! The maximum number of records to return.
    hasResponse Boolean Indicates whether or not the WSA has been acknowledged.
    WSAIds [String] The identifier of the WSA you received from Wayfair.
    fromDate IsoDateTime The date beyond which you want to retrieve WSAs in your query output.
    sortOrder SortOrder = ASC Order the result set by ascending or descending order of creationDate.

    Output

    Type Description
    WarehouseShippingAdvice Details about the requested CastleGate WSA. This result will also contain the list of products & packages associated with the WSA.

    Acknowledge CastleGate Warehouse Shipping Advice Mutation

    {
      "query": "
        mutation acknowledgeCastleGateWarehouseShippingAdvice($WSAIds: [String]!) {
          purchaseOrders {
            acknowledgeCastleGateWarehouseShippingAdvice(
              WSAIds: $WSAIds
            ) {
              id,
              handle,
              status,
              submittedAt,
              completedAt,
              errors {
                message
              }
            }
          }
        }
      ",
      "variables": {
        "WSAIds": ["6F96C5C4-C3C7-4D29-84CA-0B050F7E961A"]
      }
    }
    

    This mutation lets Wayfair know you have acknowledged the receipt of a CastleGate Warehouse Shipping Advice from a query.

    Input

    Name Type Description
    WSAIds List[String]! A list of identifiers of the WSA you received from Wayfair that you want to acknowledge.

    Output

    Type Description
    TransactionStatus! Acknowledging CastleGate WSAs is a synchronous operation. The transaction data returned to you can be used to track the status of your mutation.

    Shipping

    Wayfair has a full suite of APIs to develop automated shipping solutions. They are coordinated to work via the following high-level process:

    1. Register the orders for shipment
      • Call the Register Mutation API for each purchase order received from Wayfair that the supplier plans to ship
    2. Retrieve shipping documents for the registered orders. For each already registered order, a user can:

    Shipping error details

    Register Mutation

    {
       "query": "
        mutation register($params: RegistrationInput!) {
            purchaseOrders {
                register(
                    registrationInput: $params
                    ) {
                    id,
                    eventDate,
                    pickupDate,
                    consolidatedShippingLabel {
                      url,
                    },
                    shippingLabelInfo {
                      carrier,
                    },
                    purchaseOrder {
                      poNumber,
                      shippingInfo {
                        carrierCode
                      }
                    }
                }
            }
        }  
       ",
       "variables": {
         "params":  
         {  
           "poNumber": "CS1234567",  
           "warehouseId": "5000",
           "requestForPickupDate": "2019-03-26 15:30:00"              
         }  
       }
     }
    

    The Register Mutation is a required prerequisite to almost all integrations for shipping Wayfair orders. Through registration, the supplier lets us know that an order is ready to be shipped from the its warehouse or storage location and Wayfair is able to initiate its planning processes for the upcoming shipment.

    Consolidated Items Registration

    Additionally to being able to retrieve shipping documents directly in the response of the mutation, you can also push and alter a purchase order's data via the Register Mutation to consolidate items into shipping package. In the following examples, we will only focus on the fields included in the params Registration Input and perform items consolidation by putting item "ABC123" and "DEF456" in the same package unit.

    {
       "query": "
        mutation register($params: RegistrationInput!) {
            purchaseOrders {
                register(
                    registrationInput: $params
                    ) {
                    id,
                    eventDate,
                    pickupDate,
                    poNumber
                    consolidatedShippingLabel {
                      url
                    }
                    billOfLading {
                      url
                    }
                    generatedShippingLabels {
                      poNumber
                      fullPoNumber
                      carrier
                      carrierCode
                      trackingNumber
                    }
                    customsDocument {
                      required
                      url
                    }
                }
            }
        }    
       ",
         "variables": {
           "params":{  
             "poNumber": "CS1234567",  
             "warehouseId": "5000",
             "requestForPickupDate": "2019-03-26 15:30:00",
             "packageUnits": [
               {
                 "unitType": "CARTON",
                 "weight":{
                   "value": 10,
                   "unit": "KILOGRAMS"
                 },
                 "dimensions":{
                   "width":{
                     "value": 10,
                     "unit": "CENTIMETERS"
                   },
                   "length":{
                     "value": 10,
                     "unit": "CENTIMETERS"
                   },
                   "height":{
                     "value": 10,
                     "unit": "CENTIMETERS"
                   }
                 },
                 "containedParts":[
                   {
                     "partNumber": "ABC123",
                     "groupIdentifier": 1
                   },
                   {
                     "partNumber": "DEF456",
                     "groupIdentifier": 1
                   }        
                 ]
               }
             ]              
           }  
         }
       }
    

    Input

    Name Type Description
    registrationInput RegistrationInput! The input object required to register a purchase order for shipment

    Output

    Type Description
    LabelGenerationEvent! An object representing the request to generate shipping documents

    RegistrationInput Type

    An input for registering package shipments with Wayfair.

    Name Type Description Default
    poNumber String! The ID of the purchase order to register NA
    warehouseId ID The ID of the warehouse that is going to fulfill the purchase order The warehouse ID already assigned to the order in Wayfair's systems
    requestForPickupDate IsoDateTime The requested datetime for the order to be picked up for shipping Time of the registration request
    packageUnits [PackageUnit!] The individual package units associated with the purchase order which can be used to consolidate labels for a single purchase order Defaults to the shipping data found in Wayfair's catalog

    PackageUnit Type

    An input representing a shipping package unit.

    Name Type Description
    unitType PackageUnitTypeEnum! The type of shipping unit.
    weight WeightInput! The weight of the package.
    dimensions DimensionInput! The length dimensions of the package.
    freightClass FreightClassEnum The shipping unit's freight class, which is broadly categorized by weight.
    containedParts [ContainedPart!]! The products that should be in a single package.

    PackageUnitTypeEnum Type

    The types of packaging units that can be shipped.

    Value Description
    CARTON A carton (box) unit.
    BAG A sealed plastic bag unit.
    ROLL A rolled-up unit.
    OTHER Any shipping unit that cannot be defined as a carton, roll, or bag.

    WeightInput Type

    An input for weight measurements.

    Name Type Description
    value float! The numeric value of the weight measurement.
    unit WeightUnitEnum! The unit in which the value is measured. The value for unit can either be 1 for Pounds (lbs) or 2 for Kilograms (kg)

    WeightUnitEnum Type

    An enumeration of the different weight units that are supported.

    Value Description
    1 Pounds (lbs)
    2 Kilograms (kg)

    DimensionInput Type

    An input for a set of 3D (L x W x H) dimensions.

    Name Type Description
    length MeasurementInput The associated object's length
    width MeasurementInput The associated object's width
    height MeasurementInput The associated object's height

    MeasurementInput Type

    An input for 1D-measurements (length and unit).

    Name Type Description Default
    value Float! The measurement value None
    unit LengthUnitEnum The unit type with which to evaluate the measure value 1 (Inches)

    LengthUnitEnum Type

    Units that can be used to measure a length.

    Value Description
    1 Inches
    2 Centimeters

    FreightClassEnum Type

    Enumeration of shipping freight classes, broadly categorized as weight range per cubic foot. E.g., class 500 is used to represent freight with a weight density of 0-1 lbs per cubic foot.

    Value Description
    500 Less than 1 lb - Bags of gold dust, ping pong balls
    400 1-2 lbs - Deer antlers.
    300 2-3 lbs - Wood cabinets, tables, chairs setup, model boats.
    250 3-4 lbs - Bamboo furniture, mattress and box spring, plasma TV.
    200 4-5 lbs - Auto sheet metal parts, aircraft parts, aluminum table, packaged mattresses.
    175 5-6 lbs - Clothing, couches stuffed furniture.
    150 6-7 lbs - Auto sheet metal parts, bookcases.
    125 7-8 lbs - Small Household appliances.
    110 8-9 lbs - Cabinets, framed artwork, table saws.
    100 9-10.5 lbs - Boat covers, car covers, canvas, wine cases, caskets.
    92.5 10.5-12 lbs - Computers, monitors, refrigerators.
    85 12-13.5 lbs - Crated machinery, cast iron stoves.
    77.5 13.5-15 lbs - Tires, bathroom fixtures.
    70 15-22.5 lbs - Car accessories & car parts, food items, automobile engines.
    65 22.5-30 lbs - Car accessories & car parts, bottled beverages, books in boxes.
    60 30-35 lbs - Car accessories & car parts.
    55 35-50 lbs - Bricks, cement, mortar, hardwood flooring.
    50 Over 50 lbs - Fits on standard shrink-wrapped 4X4 pallet, very durable.

    ContainedPart Type

    An input representing a product part that is packaged for shipping.

    Name Type Description
    partNumber string! The ordered product's identifier.
    groupIdentifier integer! A positive integer to indicate which box the item has this partNumber was placed into.

    LabelGenerationEvent Type

    Name Type Description
    id ID! A numeric identifier for the event
    eventDate IsoDateTime! The date and time that the register mutation was called
    pickupDate IsoDateTime! The date and time to pick up the shipment
    billOfLading BillOfLading! A document describing the contents of the full purchase
    consolidatedShippingLabel ShippingLabel! A document containing all the shipping labels required for the packages of the shipment
    generatedShippingLabels [GeneratedShippingLabels]! List of information about generated shipping labels (data available only after label was retrieved)
    customsDocument CustomsDocument! Information about a specific customs document

    GeneratedShippingLabels Type

    Name Type Description
    poNumber Int! Purchase order number without prefix
    fullPoNumber String! Purchase order number with prefix
    numberOfLabels Int! Number of labels
    carrier String! Carrier for the shipping label
    carrierCode String! Carrier code for the shipping label
    trackingNumber String! Tracking number for the shipping label

    CustomsDocument Type

    Information about a specific customs document.

    Name Type Description
    required boolean! A boolean representing customs document is required or not
    url string A URL for downloading this customs document

    Registration errors details

    Packing Slip Retrieval

    using Newtonsoft.Json;
    using RestSharp;
    
    using System;
    using System.IO;
    using System.Linq;
    using System.Net;
    
    var client = new RestClient(string.Fromat("https://api.wayfair.com/v1/packing_slip/{0}", purchaseOrderNumber));
    var response = client.Get(
        new RestRequest(Method.GET)
            .AddHeader("accept", "application/json")
            .AddHeader("content-type", "application/json")
            .AddHeader("authorization", string.Format("Bearer {0}", token))
    );
    
    import org.apache.http.HttpResponse;
    import org.apache.http.client.HttpClient;
    import org.apache.http.client.methods.HttpGet;
    import org.apache.http.impl.client.HttpClients;
    import java.io.IOException;
    
    public class ApiClient {
    
        public static void main(String[] args) throws IOException {
            HttpGet request = new HttpGet("https://api.wayfair.com/v1/packing_slip/" + purchaseOrderNumber);
            clockRequest.setHeader("Accept", "application/json");
            clockRequest.setHeader("Authorization", "Bearer " + token);
            clockRequest.setHeader("Content-Type", "application/json");
    
            HttpClient client = HttpClients.createDefault();
            HttpResponse response = client.execute(request);
        }
    }
    
    var packingSlipRequestSettings = {
      'async': true,
      'crossDomain': true,
      'url': 'https://api.wayfair.com/v1/packing_slip/' + purchaseOrderNumber,
      'method': 'GET',
      'headers': {
        'authorization': 'Bearer ' + token,
        'cache-control': 'no-cache',
        'content-type': 'application/json'
      }
    };
    $.ajax(packingSlipRequestSettings).done(function (response) {
      console.log(response);
    });
    
    $client = new \GuzzleHttp\Client();
    $response = $client->get(
      'https://api.wayfair.com/v1/packing_slip/' + purchaseOrderNumber,
      [
        'headers' => [
          'Authorization' => 'Bearer ' + token,
          'Content-Type' => 'application/json',
        ]
      ]
    );
    
    #! /bin/python
    import json
    import requests
    url = "https://api.wayfair.com/v1/packing_slip/" + purchaseOrderNumber
    headers = {
        'Authorization': 'Bearer ' + token
        'Content-Type': 'application/json',
    }
    response = requests.request('GET', url, headers=headers)
    
    require "http"
    require "json"
    
    response = HTTP.headers({
      "Authorization" => "Bearer " + token
      "Content-Type" => "application/json",
    }).get("https://api.wayfair.com/v1/packing_slip" + purchaseOrderNumber)
    
    curl -X GET 'https://api.wayfair.com/v1/packing_slip/${purchaseOrderNumber}' \
      -H 'Authorization: Bearer ${token}' \
      -H 'Content-Type: application/json'
    

    Sample response: A PDF document download of the requested packing slip.

    The Packing Slip Retrieval API provides a simple way to download the packing slip for an individual purchase order.

    Input

    Name Type Description
    purchaseOrderNumber string The purchase order number (e.g. "CS12345678") for which to retrieve a packing slip

    Output

    Type Description
    PDF / octetstream The packing slip document for the requested purchase order

    Shipping Label Retrieval

    using Newtonsoft.Json;
    using RestSharp;
    
    using System;
    using System.IO;
    using System.Linq;
    using System.Net;
    
    var client = new RestClient(string.Fromat("https://api.wayfair.com/v1/shipping_label/{0}", purchaseOrderNumber));
    var response = client.Get(
        new RestRequest(Method.GET)
            .AddHeader("accept", "application/json")
            .AddHeader("content-type", "application/json")
            .AddHeader("authorization", string.Format("Bearer {0}", token))
    );
    
    import org.apache.http.HttpResponse;
    import org.apache.http.client.HttpClient;
    import org.apache.http.client.methods.HttpGet;
    import org.apache.http.impl.client.HttpClients;
    import java.io.IOException;
    
    public class ApiClient {
    
        public static void main(String[] args) throws IOException {
            HttpGet request = new HttpGet("https://api.wayfair.com/v1/shipping_label/" + purchaseOrderNumber);
            clockRequest.setHeader("Accept", "application/json");
            clockRequest.setHeader("Authorization", "Bearer " + token);
            clockRequest.setHeader("Content-Type", "application/json");
    
            HttpClient client = HttpClients.createDefault();
            HttpResponse response = client.execute(request);
        }
    }
    
    var shippingLabelRequestSettings = {
      'async': true,
      'crossDomain': true,
      'url': 'https://api.wayfair.com/v1/shipping_label/' + purchaseOrderNumber,
      'method': 'GET',
      'headers': {
        'authorization': 'Bearer ' + token,
        'cache-control': 'no-cache',
        'content-type': 'application/json'
      }
    };
    $.ajax(shippingLabelRequestSettings).done(function (response) {
      console.log(response);
    });
    
    $client = new \GuzzleHttp\Client();
    $response = $client->get(
      'https://api.wayfair.com/v1/shipping_label/' + purchaseOrderNumber,
      [
        'headers' => [
          'Authorization' => 'Bearer ' + token,
          'Content-Type' => 'application/json',
        ]
      ]
    );
    
    #! /bin/python
    import json
    import requests
    url = "https://api.wayfair.com/v1/shipping_label/" + purchaseOrderNumber
    headers = {
        'Authorization': 'Bearer ' + token
        'Content-Type': 'application/json',
    }
    response = requests.request('GET', url, headers=headers)
    
    require "http"
    require "json"
    
    response = HTTP.headers({
      "Authorization" => "Bearer " + token
      "Content-Type" => "application/json",
    }).get("https://api.wayfair.com/v1/shipping_label" + purchaseOrderNumber)
    
    curl -X GET 'https://api.wayfair.com/v1/shipping_label/${purchaseOrderNumber}' \
      -H 'Authorization: Bearer ${token}' \
      -H 'Content-Type: application/json'
    

    Sample response: A PDF or ZPL document download of the requested shipping labels

    The Shipping Label Retrieval API provides a simple way to download all the shipping labels for an individual purchase order.

    Input

    Name Type Description
    purchaseOrderNumber string The purchase order number (e.g. "CS12345678") for which to retrieve shipping labels

    Output

    Type Description
    PDF / ZPL / octetstream A document containing the shipping labels for the requested purchase order

    Bill of Lading Retrieval

    using Newtonsoft.Json;
    using RestSharp;
    
    using System;
    using System.IO;
    using System.Linq;
    using System.Net;
    
    var client = new RestClient(string.Fromat("https://api.wayfair.com/v1/bill_of_lading/{0}", purchaseOrderNumber));
    var response = client.Get(
        new RestRequest(Method.GET)
            .AddHeader("accept", "application/json")
            .AddHeader("content-type", "application/json")
            .AddHeader("authorization", string.Format("Bearer {0}", token))
    );
    
    import org.apache.http.HttpResponse;
    import org.apache.http.client.HttpClient;
    import org.apache.http.client.methods.HttpGet;
    import org.apache.http.impl.client.HttpClients;
    import java.io.IOException;
    
    public class ApiClient {
    
        public static void main(String[] args) throws IOException {
            HttpGet request = new HttpGet("https://api.wayfair.com/v1/bill_of_lading/" + purchaseOrderNumber);
            clockRequest.setHeader("Accept", "application/json");
            clockRequest.setHeader("Authorization", "Bearer " + token);
            clockRequest.setHeader("Content-Type", "application/json");
    
            HttpClient client = HttpClients.createDefault();
            HttpResponse response = client.execute(request);
        }
    }
    
    var shippingLabelRequestSettings = {
      'async': true,
      'crossDomain': true,
      'url': 'https://api.wayfair.com/v1/bill_of_lading/' + purchaseOrderNumber,
      'method': 'GET',
      'headers': {
        'authorization': 'Bearer ' + token,
        'cache-control': 'no-cache',
        'content-type': 'application/json'
      }
    };
    $.ajax(shippingLabelRequestSettings).done(function (response) {
      console.log(response);
    });
    
    $client = new \GuzzleHttp\Client();
    $response = $client->get(
      'https://api.wayfair.com/v1/bill_of_lading/' + purchaseOrderNumber,
      [
        'headers' => [
          'Authorization' => 'Bearer ' + token,
          'Content-Type' => 'application/json',
        ]
      ]
    );
    
    #! /bin/python
    import json
    import requests
    url = "https://api.wayfair.com/v1/bill_of_lading/" + purchaseOrderNumber
    headers = {
        'Authorization': 'Bearer ' + token
        'Content-Type': 'application/json',
    }
    response = requests.request('GET', url, headers=headers)
    
    require "http"
    require "json"
    
    response = HTTP.headers({
      "Authorization" => "Bearer " + token
      "Content-Type" => "application/json",
    }).get("https://api.wayfair.com/v1/bill_of_lading" + purchaseOrderNumber)
    
    curl -X GET 'https://api.wayfair.com/v1/bill_of_lading/${purchaseOrderNumber}' \
      -H 'Authorization: Bearer ${token}' \
      -H 'Content-Type: application/json'
    

    Sample response: A PDF document download of the requested Bill of Lading

    The Bill of Lading Retrieval API provides a simple way to download the Bill of Lading (BOL) for an individual purchase order.

    Input

    Name Type Description
    purchaseOrderNumber string The purchase order number (e.g. "CS12345678") for which to retrieve a BOL

    Output

    Type Description
    PDF / octetstream The Bill of Lading (BOL) document for the requested purchase order

    Label Generation Events Query

    query labelGenerationEvents {
      labelGenerationEvents(
        limit: 1
      ) {
          id,
          eventDate,
          pickupDate
           consolidatedShippingLabel {
             url
           }
           billOfLading {
             url
           }
           purchaseOrder {
             poNumber
           }
           generatedShippingLabels {
             poNumber
             fullPoNumber
             numberOfLabels
             carrier
             carrierCode
             trackingNumber
           }
        }
      }
    }  
    

    The Label Generation Events Query returns data associated with previously committed registrations (calls to the Register Mutation). The query can be used to retrieve the appropriate shipping document endpoint URLs, as well as the submitted pick-up date for the shipment and all the information for the related purchase order. After retrieving shipping label it also contains information about generated shipping labels.

    Input

    Name Type Description
    filters LabelGenerationEventFilterInput = [] A set of filters for limiting the result set.
    ordering [orderingInput] = [{asc: "id"}] A list of ordering types that determine the order in which the result set should be presented.
    limit Int = 10 The maximum number of records to return.
    offset Int = 0 How deep into the result set to look for the first item.

    Output

    Type Description
    [LabelGenerationEvent!] A list of Label Generation Events, where each item represents a call to the Register Mutation

    Errors

    Since we use GraphQL, you'll receive errors in an additional errors key on the json response. Even though an error has occurred, you'll still receive an HTTP 200 for the status code, and need to check for the presence of errors on the response object. Below are some business and validation errors that a developer can encounter while performing GraphQL API operations:

    Inventory Errors

    Fatal Errors

    If you receive one of the following errors, your request was not processed. Please fix the issue causing the error and re-submit the request.

    User Message Description
    Your application has not been verified to upload inventory via this API. Please complete the steps in the testing section of this article https://partners.wayfair.com/help/3/article/16. Unverified application tried to submit production inventory data via the API
    You do not have access to inventory for any suppliers. Client does not have the scopes required to submit inventory for any suppliers
    The "inventory" argument cannot be empty. Received inventory mutation request with no inventory data
    Required inputs are missing: {Field Names} One or more required data fields are missing from the input object. {Field Names} is a list of the required input field not found in the request.

    Validation Errors

    If you receive one of the following errors, the valid inputs in the request were successfully processed. Please fix the invalid input and submit another request with the updated data.

    Code User Message Description
    4001 Quantity on hand cannot be less than -1. Supplier Part Number: {Part Number} On-hand inventory quantity for the specified part is invalid. Valid quantities are integers greater than or equal to -1. A value of -1 is only used for distributors whose lead time changes drastically between when the item is in stock and when it needs to be ordered from the manufacturer. If both the distributor and manufacturer do not have an item in stock, the item should be considered out of stock. If you think this situation might apply to you, please contact your Wayfair Integration Manager.
    4002 Invalid supplier id given: {supp_id}. Supplier Part Number: {part_num} Invalid or incorrect Supplier ID provided with the part number specified in the request. Please ensure the part number exists for that supplier.
    4003 Invalid 'quantity_on_hand' or 'item_next_availability_date' for discontinued product for supplier id: {supp_id}. Supplier Part Number: {part_num} Invalid inputs provided for a product that has been discontinued by the supplier. This to prevent any operations on products that aren't/ won't be available in inventory.

    Order Errors

    General Errors

    User Message Description
    Your application has not been verified to accept purchase orders via this API. Please complete the steps in the testing section of this article {Article Name} Unverified application tried to accept purchase order via the API.
    Invalid purchase order number provided. Invalid purchase order number for client. PO: {PO Number}
    Invalid quantity provided for one or more parts. Invalid quantity accepted for at least one part

    Accept Order Errors

    User Message Description
    Cannot accept a purchase order without any line items. Accept purchase order mutation called with no line items
    Ship speed provided does not match previously provided ship speeds Supplier attempted to change the ship speed of a previously provided PO response
    Purchase Order {PO Number} does not contain part {PO Part Number} Supplier attempted to respond to a purchase order with a part that was not part of the order

    Registration Errors

    User Message Description
    Failed Label Generation Failed Label Generation
    Invalid pickup date provided Invalid pickup date provided. PO: {PO Number}. If the request for pickup date has an invalid format or fails one of the region (EU) constraints, this error is encountered
    Invalid warehouse ID provided. Invalid warehouse ID for client. PO:{PO Number}, SuID:{Warehouse ID}
    Failed Registration: {Reason(s)} Failed Registration: {Reason(s)}

    Shipment Errors

    User Message Description
    At least one small parcel or large parcel shipment must be provided Attempted to submit ship notice without any small parcel or large parcel shipments
    Supplier provided is not assigned to the given purchase order Attempted to submit ship notice for a PO with the wrong supplier
    Ship date cannot be in the future Attempted to submit ship notice with a ship date in the future
    A package cannot be empty Attempted to submit ship notice with an empty package
    At least one part number is not part of this purchase order Attempted to submit ship notice with one or more products that were not part of the provided PO
    Ship notice has products with higher quantity than the purchase order Attempted to submit ship notice with a higher quantity for a product than the PO has

    If you receive one of the following errors, the valid inputs in the request were successfully processed. Please fix the invalid input and submit another request with the updated data.

    Code User Message Description
    7001 The supplied value '{sourceAddress.country}' for sourceAddress.country should be a 2 or 3 character country code. Country fields have a limit of three characters and will truncate any letters beyond that limit.
    7002 The supplied value '{destinationAddress.country}' for destinationAddress.country should be a 2 or 3 character country code. Country fields have a limit of three characters and will truncate any letters beyond that limit.

    Terms of Use & Privacy Policy

    Please see Wayfair's Terms of Use and Privacy Policy