Skip to main content

API v1.3.3

⛵ Added​

Advanced search filter on products and variants​

Added an advancedSearch filter to search by specific fields for a faster, more targeted search, as opposed to the pre-existing search filter, which searches across all fields.

You can use the advancedSearch argument in the ProductFilterInput for advanced filtering by search term when querying products and variants.

The fields you can target for search are defined in the ProductSearchFieldEnum and ProductVariantSearchFieldEnum. If you don't define search fields, the filter defaults to search only by NAME. 

query {
  products(
    first: 25
    filter: {
      advancedSearch: {
        searchTerm: "shiny"
        searchFields: [
          NAME, 
          VARIANT_NAME, 
          DESCRIPTION, 
          CATEGORY_NAME]
      }
    }
  ) {
    edges {
      node {
        id
        name
        description
      }
    }
  }
}
Show more ↓

Learn more ->

Retrieve Avalara tax exempt codes​

Added the ability to retrieve the list of Avalara tax exempt codes through a new taxExemptCodes query. 

query {
  taxExemptCodes {
    code
    name
    validCountries
  }
}

Dimension argument for marketplace insights​

Added the dimension argument to filter by time period for the following marketplace insight queries:

  • insightsOrdersMarketplaceSummary
  • insightsMarketplacePaymentsSummary
  • insightsMarketplaceTaxSummary

The values for the dimension argument are defined by the InsightDimensionEnum.

Breaking changes for insight queries 💥
Consider the following breaking changes if you're using pre-existing API integrations for marketplace insights:
  • The filter fields startDate and endDate are now required for all insights queries.
  • The perspective filter argument input type changed from string to PerformancePerspective.
    This must be updated in any logic using the following queries:
    • insightsTopPerformingCategories
    • insightsTopPerformingProducts
  • The input type for the dimension argument changed from string to InsightDimensionEnum. This must be updated in any logic using insightsOrdersMarketplaceSummary queries.
  • Fields used for report logic are now required, including queries that use ColumnObjectType, FilterObjectType, and other fields depending on the report type. For example, InReportMarketplaceAffiliatePayoutsSummaryType now requires category, title, summary, and report.
  • In the GraphDataType object, the period field was renamed to dimension.

Set availability on productCreate​

Added the ability to set product availability while creating products through the API. The productCreate mutation input now supports the isAvailable and startDate fields. 

mutation {
  productCreate(
    input: {
      isAvailable: true
      productType: "UHJvZHVjdFR5cGU6NDM5"
      name: "Snow Pants"
      seller: "U2VsbGVyOjI="
      basePrice: "50"
    }
  )
  {
    product {
      name
      isAvailable
    }
  }
}

Force order fulfillment​

Added the ability for users with the Manage marketplace permission to force order fulfillment for a line with a deleted variant, by passing the allowNullVariants field with the orderFulfill mutation input. 

mutation {
  orderFulfill(
    order: "T3JkZXI6MQ==",
    input: {
      lines: [
        {
          orderLineId: "ABC=",
          stocks: [
            {
              quantity: 1,
              warehouse: "ABC=="
            }
          ]
        }
      ],
      notifyCustomer: false,
      allowNullVariants: true
    }
  ) {
    orderErrors {
      field
      message
      code
      warehouse
      orderLine
      variant
    }
    order {
      id
      number
    }
    fulfillments {
      id
      fulfillmentOrder
      status
    }
  }
}

Show more ↓

Set status on sellerDataCreate​

Added the ability to set the seller status while adding a new seller with the sellerDataCreate mutation.

A new status field is added to SellerInput. The status field accepts values from the SellerStatusEnum. If unspecified, the status defaults to PENDING. 

mutation {
  sellerDataCreate(
    input: {
      name: "Cosmic Shirts Co"
      owner: "VXNlcjo3NDM4"
      plan: "QWdyZWtZW50Ojc="
      status: APPROVED
    } 
  ){
    ok
    seller {
      id
      companyName
      status
    }
  }
}

Available payout balance on orders​

Added the availablePayoutBalance read-only field to the order object, to return the balance remaining to be paid out. 

query {
  order(
    id: "T3JkZXI6MTIyMTY="
  )
  {
    id
    availablePayoutBalance {
        amount
      currency
    }
  }
}

Filter orders by payout status​

Added the ability to filter the orders query by payoutStatus, which accepts values from the OrderPayoutStatusEnum. 

query {
  orders(
    first: 10
    filter: {
      payoutStatus: READY_FOR_PAYOUT
    }
  )
  {
    totalCount
    edges {
      node {
        id
        availablePayoutBalance {
          amount
        }
      }
    }
  }
}
Show more ↓

Convert offer to quote order​

Added the orderOfferConvertToNauticalQuoteOrder mutation to convert an offer order to a Nautical (marketplace) quote order. You can target the id of either an order or Nautical order.

mutation {
  orderOfferConvertToNauticalQuoteOrder
  (id: "VXNlcjo3MtYw") 
  {
    order {
      id
      status
      created
    }
    orderErrors {
      field
      code
      message
    }
  }
}

Add public metadata on customer checkout​

Added the ability for a customer to add and manage public metadata to their own checkout(s) through the API, for example using the metadataUpdate mutation on checkout.

This functionality must be turned on in your environment before it can be used. Contact a Nautical support representative to enable this functionality in your marketplace.

VAT identification number for customers​

Added the vatIdentificationNumber field to the user object, for example to store and display a customer's VAT identification number on an invoice. 

query {
  user(
    id:"VXNlcjo3MjYw"
  )
  {
    vatIdentificationNumber
  }
}

Assign Avalara tax exempt codes​

Added the ability to assign Avalara tax exempt codes to users, through a new Tax Exempt Code field on the customer object.

Through the API, you can assign tax codes by passing the taxExemptCode field through the customerUpdate mutation. 

mutation {
  customerUpdate(
    id: "VXNlcjo3MjI2"
    input: {
      taxExemptCode: "R"
    }
  )
  {
    user {
      id
      taxExemptCode
    }
  }
}

🌊 Changed​

Show Error Messages on SellerDataUpdate​

Updated the sellerDataUpdate mutation response to show error messages, by adding the ability to return sellerErrors in addition to the existing ok boolean success indicator.

🪲 Fixed​

  • Fixed an issue that prevented exporting products as either a .csv or .xlsx file when one or more fields were selected for export.
  • Fixed an issue with sorting and pagination by attributes for the products and productVariants query.
  • Fixed an issue where taxes were not being calculated properly for quote orders when the associated marketplace order did yet not have order lines.
  • Fixed an issue with stock allocation and de-allocation for grouped products, which could cause a seller issues with fulfilling an order with grouped products.
  • Fixed an issue in master-product marketplaces, where products created by a seller user with Manage marketplace permissions were not created as master products.
  • Fixed an issue with processing checkouts with Stripe with the Store Customer Cards setting enabled.

Was this page helpful?