2022 Changes

Last Updated: 19 September 2022

August 25 - 2022

CartDelete Mutation

The cartDelete mutation has been added to out GraphQL API, this allows you to delete a cart by supplying a valid cartId

For more information on the mutations that we provide please refer to the docs here

Point In Time Pagination

When paging through large result sets, the original data set you queried may change between subsequent paging requests, which can make result processing problematic. We have introduced the ability to request a pointInTime key when making your 1st query call. You can supply the pointInTime on subsequent calls to ensure you are working with the same data set.

For more information on the queries that we provide please refer to the docs here

August 24 - 2022

OrderHistoryDownload Mutation

The orderHistoryDownload mutation has been added to the GraphQL API, this allows you to start a background job to export orders as either a CSV or XLSX file.

mutation {
  orderHistoryDownload(
    input: {
      sellerId: "U2VsbGVyLTc4"
      format: CSV
      filters: [{ updatedSince: "2022-09-01" }]
    }
  ) {
    errors {
      field
      messages
    }
  }
}

For more information on the mutations that we provide please refer to the docs here

August 23 - 2022

Webhook Sequence ID

We have added a sequence id (Marketplacer-Sequence) to the headers of our webhook POST requests. This allows consumers of the webhooks to order webhook payloads if required.

Our webhook getting started guide can be found here

International Shipping Costs Exposed on Seller

The following fields have been exposed on the Seller object:

• baseInternationalShippingCost
• internationalShippingEnabled
• internationalShippingFreeThreshold

For more information on the fields exposed on the Seller object, refer to the docs here.

New Custom Field Types

In addition to supporting plain-text custom fields, we have now added the following custom field types:

• BOOLEAN
• EMAIL_ADDRESS
• URL

For more information on the custom field data-types, refer to the docs here.

August 22 - 2022

Line Item Metadata Exposed

Prior to this change, metadata attached to invoice lineitems was not exposed via the V2 Seller API. Metadata has now been exposed on lineitems.

For more information on the Invoice endpoint please refer to the Seller API docs here

August 15 - 2022

Invoice Annotations

We use status flags on the invoice object to indicate Invoice status, however there are occasions when there may be a need for bespose workflows / statuses. We have therefore introduced “Invoice Annotations” that cater to this need. With Invoice Annotations you can create your own InvoiceAnnotationType (e.g. “Back Order”, “Package Accepted” etc.), and then create InvoiceAnnotation objects on the Invoice of a given type. This allows you to introduce simple, bespoke workflows, based around your Invoices.

For more information on the queries that we provide please refer to the docs here

For more information on the mutations that we provide please refer to the docs here

August 05 - 2022

Shipment update mutation

The shipmentUpdate mutation has been added to the GraphQL API, which allows for the update of an existing shipment object.

For more information on the queries that we provide please refer to the docs here

July 28 - 2022

API key required for all GraphQL queries

Operators can now specify that all GraphQL query endpoints require a valid API Key. By design some GraphQL query endpoints can be queried without a key, this change allows the override of that behaviour.

For more information on the queries that we provide please refer to the docs here

Product Details added to the advertUpsert mutation

The optionValueIds argument on the advertInput type has been renamed to featureOptionValueIds to avoid confusion around which option types the supplied IDs refer to. In addition to support Drop Down and Free text, productDetails has been added to the advertInput type.

For more information on the mutations that we provide please refer to the docs here

July 26 - 2022

Shipping Zone mutations

To allow for the manipulation of shippingZones using the GraphQL API, the following mutations have been added:

• shippingZoneCreateOrUpdate
• shippingZoneDelete
• shippingZoneSpreadsheetDownload

For more information on the mutations that we provide please refer to the docs here

July 25 - 2022

Filtering on Advert vetting fields added to the allAdverts query

The allAdverts query now allows you to filler on the following Advert fields:

• vetted
• requiresVetting

For more information on the queries that we provide please refer to the docs here

July 20 - 2022

remittanceRelease Mutation

Operators can now release seller remittances via the GraphQL API by using the remittancesRelease mutation.

For more information on the mutations that we provide please refer to the docs here

July 19 - 2022

Custom Fields on the Seller object

We have added the following queries and mutations to allow for the manipulation of Custom Fields on the Seller object:

• Query: customFieldGroups
• Mutation: customFieldGroupCreateOrUpdate
• Mutation: customFieldGroupDelete
• Mutation: customFieldCreateOrUpdate
• Mutation: customFieldDelete

We have provided further information on how to use Custom Fields with GraphQL here.

For more information on the mutations that we provide please refer to the docs here

July 18 - 2022

Promotion Webhook

The Promotions object has now been added to the list of available webhooks that are available, with the standard: Create, Update and Destroy events.

Our webhook getting started guide can be found here

Sort results in advertsWhere

You can now sort your result set from the advertsWhere query.

For more information on the mutations that we provide please refer to the docs here

July 15 - 2022

ShippingRule Webhook

The ShippingRule object has now been added to the list of available webhooks that are available, with the standard: Create, Update and Destroy events.

Our webhook getting started guide can be found here

Custom Fees

Custom Fees can now be supplied with the orderCreate mutation, this allows operators to add any additional fees to the order on top of things like shipping.

For more information on the mutations that we provide please refer to the docs here

July 13 - 2022

FIX: advertUpsert requires a Seller

Prior to this fix an advert could be created with the advertUpsert mutation without it being associated to a Seller. This resulted in “orphaned” Adverts (those without an associated Seller). This fix now mandates that a Seller needs to be associated when creating an Advert.

For more information on the mutations that we provide please refer to the docs here

July 07 - 2022

OptionValue Webhook

The OptionValue object has now been added to the list of available webhooks that are available, with the standard: Create, Update and Destroy events.

Our webhook getting started guide can be found here

remittanceAdviceUpdate mutation

We have added the remittanceAdviceUpdate mutation, this allows Operators to update remittance information via GraphQL, for example marking the remittances as having been paid.

For more information on the mutations that we provide please refer to the docs here

Comparable Unit Pricing (CUP) fields added to advertUpsert

To further align the GraphQL advertUpsert mutation to the current capabilities of the V2 / REST API, we have added the following fields to the advertInput type:

• comparableUnit
• comparableSize
• itemUnit
• itemSize

For more information on the mutations that we provide please refer to the docs here

July 06 - 2022

OptionType Webhook

The OptionType object has now been added to the list of available webhooks that are available, with the standard: Create, Update and Destroy events.

Our webhook getting started guide can be found here

June 30 - 2022

Additional fields added to advertUpsert

To further align the GraphQL advertUpsert mutation to the current capabilities of the V2 / REST API, we have added the following fields to the advertInput type:

• code
• externalId
• gender
• maxPurchaseQuantity
• minPurchaseQuantity
• variant
• • externalId
• • maxPurchaseQuantity
• • minPurchaseQuantity

For more information on the mutations that we provide please refer to the docs here

June 21 - 2022

Vetting field available on advertUpsert Mutation

Operators can now use the advertUpsert mutation to manipulate the vetting status of an advert through the exposure of the vetted field.

For more information on the mutations that we provide please refer to the docs here

Variants Where Query

We have now added a variantsWhere query that allows you to search directly for variants based on a range of filter criteria.

query{
  variantsWhere(variantFilters:
  {
    skus:
    [
      "12345"
    ]
  })
  {
    nodes{
      id
      label
    }
  }
}

For more information on the queries that we provide please refer to the docs here

June 21 - 2022

Promotions via GraphQL

Operators can now retrive any promitions configured in Marketplacer by using the promotions query. Additionally promotions can now be passed with the orderCreate mutation.

For more information on the mutations that we provide please refer to the docs here

June 17 - 2022

Refund Reasons Query

We have now added a refundReasons query that allows you to return the pre and post dispatch refund reasons configured on your Marketplacer instance.

query{
  refundReasons
  {
    postDispatchRefundReasons
    preDispatchRefundReasons
  }
}

For more information on the queries that we provide please refer to the docs here

June 10 - 2022

FIX: Protected GraphQL fields now available in webhook queries

Prior to this fix, some fields were not available to the GraphQL queries that are used to shape Marketplacer Webhook payloads. This has now been fixed.

Our webhook getting started guide can be found here

June 08 - 2022

Additional filters on the invoices query

The following filters have been added to the invoices query:

• externalId
• legacyId
• orderId
• buyerName
• notDispatched
• awaitingReturn
• awaitingCollection

For a complete list of all supported filters, please refer to the docs here.

For more information on the queries that we provide please refer to the docs here

June 06 - 2022

createdAt and updatedAt exposed on variant

The following fields have been exposed on the variant object in the GraphQL API:

• createdAt
• updatedAt

For more information on the queries that we provide please refer to the docs here

May 31 - 2022

FIX: applicableFilters not rendering results

Prior to this fix, when using applicableFilters with the advertSearch query, selecting optionType.category could return a “non-nullable” error. This has now been fixed.

For more information on the queries that we provide please refer to the docs here

May 26 - 2022

Shipment note field

A note field has now been exposed on the shipment object which can be retrieved when querying for shipments, as well as passed as a value when creating shipments (shipmentCreate) using the GraphQL API.

For more information on the queries that we provide please refer to the docs here

For more information on the mutations that we provide please refer to the docs here

Shipment note field

A note field is now available to both add and retrieve on shipments using the V2 Seller API. The following use-cases are covered:

• When sending an entire invoice using the Invoices endpoint

• When creating a shipment using the shipment endpoint

• When returning a collection or single invoice using the shipment endpoint

• For more information on the invoices endpoint, please refer to the docs here

• For more information on the shipments endpoint, please refer to the docs here

May 24 - 2022

FIX: Upserts on advert and variant externalIds

Prior to this fix, when creating or updating the externalIds collection on either a variant or advert, the respective webhook update event would not be triggered. This has now been fixed.

Our webhook getting started guide can be found here

May 20 - 2022

Variant update mutation

The variantUpdate mutation has now been exposed via GraphQL, for more information on the inputs supported by this mutation refer to the docs here.

For more information on the mutations that we provide please refer to the docs here

May 19 - 2022

Stock-levels spreadsheet mutations

We have added the following mutation to the GraphQL API, that will allow users to batch manipulate countOnHand for their variants:

• stockLevelsSpreadsheetDownload
• stockLevelsSpreadsheetUpload

For more information on the mutations that we provide please refer to the docs here

Seller refund management in GraphQL

Sellers can now use the GraphQL API to:

• Create a Refund / Cancellation requests
• Mark a Refund Request has having been returned
• List their Refund Requests

For a How To on this feature please refer to this article.

• For the current list of Seller-supported GraphQL Queries and Mutations, please refer to the list here.

May 17 - 2022

Create Inquiry mutation exposed

We have added the inquiryCreate mutation to the GraphQL API. This allows headless clients to raise inquiries against products and sellers. For the inputs supported by this mutation, please refer to the docs here.

For more information on the mutations that we provide please refer to the docs here

May 11 - 2022

Shipping parcel exposed on advert and variant

The ShippingParcel object is now exposed on both the Advert and Variant objects in GraphQL.

For more information on the queries that we provide please refer to the docs here

May 9 - 2022

Price Scheduling Fields added to Advert endpoint

The following fields can now be manipulated through Create, Update and Read operations on the Seller API Advert endpoint:

• sale_price_start_at
• sale_price_end_at
• wholesale_promo_price
• wholesale_promo_price_start_at
• wholesale_promo_price_end_at

They enable the “scheduling” of both sale and wholesale pricing.

For more information on the Advert endpoint please refer to the Seller API docs here

May 06 - 2022

GraphQL API accessible using a Seller API Key

Sellers with a valid Seller API Key, can now access selected Queries and Mutations using the GraphQL API. For a currently supported list please refer to the docs here.

Apr 5 - 2022

Seller Tags

When creating or editing a seller you can assign any number of free-text “tags” to that seller to denote a range of attributes not otherwise described in the main data model. These tags, can now be:

• Created via the GraphQL API (sellerCreate mutation)
• Updated via the GraphQL API (sellerUpdate mutation)
• Read via the GraphQL API (sellerSearch query)

For more information on these queries and mutations please refer to the following docs:

• Mutations
• Queries

Mar 30 - 2022

Maximum and Minimum purchase quantities

The Seller API (V2 / REST) now exposes the following attributes for create, read and update operations on both Advert and Variant resources:

• max_purchase_quantity the maximum allowable purchase quantity for the Advert or Variant
• min_purchase_quantity the minimum allowable purchase quantity for the Advert or Variant

For more information on the Advert and Variant endpoints, please refer to the following docs:

• Advert Endpoints
• Variant Endpoints

Mar 29 - 2022

Additional fields added to sellerUpdate mutation

The following fields have been added to SellerUpdateInput:

• accountName: The bank account holders name
• accountNumber: The bank account number
• bsb: The Bank State Branch number used for Direct Debt

For more information on the mutations that we provide please refer to the docs here

Mar 25 - 2022

Multi-Store Inventory on orderCreate

The orderCreate mutation now supports the ordering of “Multi-Store Inventories”. Multi-Stores are a construct in Marketplacer that allow Sellers to sell the same product with a shared seller pool of inventory. Muti-stores is not turned on by default.

For more information on the mutations that we provide please refer to the docs here

Mar 24 - 2022

HMAC Validation Available for GraphQL Mutations

HMAC Validation can now be enabled for all GraphQL mutations, (HMAC cannot currently be enabled for queries). This feature needs to be enabled at the instance level (it is turned off by default), with the HMAC Secret being generated along with your API Key.

For more information on the mutations that we provide please refer to the docs here

Mar 21 - 2022

FIX: advertSearch case-sensitivity

Prior to this fix, using advertSearch to search using businessName could yield different result sets depending on the case of the search criteria. This has not been resolved so that the search results will be the same irrespective of the search criteria.

For more information on the queries that we provide please refer to the docs here

Shipment Create Mutation

We have now exposed the shipmentCreate mutation via the GraphQL API. The primary use-case for this mutation is for those customers building their own Seller portal.

For more information on the mutations that we provide please refer to the docs here

Mar 17 - 2022

Tax Code Management via GraphQL

The taxCodeCreateOrUpdate and taxCodeDelete mutations have been added to the GraphQL API, to allow for the management of Tax Codes on each vertical.

For more information on the mutations that we provide please refer to the docs here

Mar 07 - 2022

Multi-store inventories available on the variant object

If using a multi-store set up, inventories are now available through the Variant object. An example of how to retrieve inventories is shown below:

  advertSearch {
    adverts(first: 10) {
      nodes {
        id
        title
        variants(first: 10) {
          nodes {
            id
            inventories {
              nodes {
                id
                countOnHand
                price{
                  currencyCode
                }
                salePrice{
                  currencyCode
                }
                infiniteQuantity
                seller { id }
              }
            }
          }
        }
      }
    }
  }

For more information on the queries that we provide please refer to the docs here

Feb 28 - 2022

PositionId can be set when creating Option Values

A postionId can now be supplied as an input to the optionValueCreateOrUpdate mutation. This allows users of the API to set the display ordering of Option Values.

More information on using the orderCreate mutation can be found here

Get and Set Shipping Profiles

When adding variant resources using the Seller API, you can now set the appropriate Shipping Profile for that variant.

More information on how to work with Shipping Profiles using the Seller API can be found here

Feb 23 - 2022

Order Create mutation accepts Tax on line items

The orderCreate mutation now supports individual tax values to be supplied for LineItems at both item cost and item shipping level.

More information on using the orderCreate mutation can be found here

Feb 21 - 2022

HMAC Validation Headers

Operators can now elect to supply a HMAC Key when setting up webhooks, this will result in an Marketplacer-HMAC-256 header being attached to the webhook event. Operators can then validate the authenticity of the header value by generating a comparison “checksum” and comparing.

Our webhook getting started guide can be found here

FIX: Displayable Only Variant Filter

The displayableOnly filter could return non-displayable variants when set to true. This has now been resolved with this fix.

For more information on the queries that we provide please refer to the docs here

Feb 15 - 2022

Deprecated Field: “medium” removed

The field medium was removed from the socialLink object. The suggested alternative field to use is: socialNetwork.

For more information on our Deprecated Field process please refer to the docs here

For more information on the socialLink object please refer to the docs here

Feb 14 - 2022

Search for Sellers using Metadata

The sellerSearch query now allows you to filter results using metadata key / value pairs. The values supplied for both key and value are case-sensitive. An example query is provided below.

{
  sellerSearch(attributes: {metadata: [{key: "user_type", value: "1"}]}) {
    sellers {
      nodes {
        businessName
      }
    }
  }
}

For more information on the queries that we provide please refer to the docs here

Document collection available on the Advert object

You can now return the collation of any documents attached to a Product Advert using any of the GraphQL queries that support returning Advert objects. An example is given below.

query AdvertNodeQuery {
  node(id: "QWR2ZXJ0LTEwMDAwMTkxNw==") {
    ... on Advert {
      id
      documents{
      edges{
        node{
          filename
          id
          url
          }
        }
      }
    }
  }
}

For more information on the queries that we provide please refer to the docs here

Feb 04 - 2022

OptionValueDelete Mutation

You can now use GraphQL to delete OptionValues using the optionValueDelete mutation:

mutation{
  optionValueDelete(input: {id: "T3B0aW9uVmFsdWUtNDU="})
  {
    errors{
      field
      messages
    }
    status
  }
}

For more information on the mutations that we provide please refer to the docs here

Feb 03 - 2022

FIX: Invoice attributes available on ProcessPaymentGatewayRedirection

Prior to this fix the Invoice object was not available from the ProcessPaymentGatewayRedirection mutation, which would result in an error response should you try to query that object on return. The Invoice object is now accessible via this mutation.

For more information on the mutations that we provide please refer to the docs here

Feb 02 - 2022

Add Buyer filter to Invoices Query

You can now filter the Invoices query result set by the buyer email.

query {
  invoices(
    first: 100 
    filters: 
    {buyerEmailAddress: "les.jackson@marketplacer.com"})
  {
    edges{
      node{
        id
        legacyId
        createdAt
        updatedAt
        buyerEmailAddress
        order{
          updatedAt
          id
        }
        statusFlags
      }
    }
  }
}

For more information on the queries that we provide please refer to the docs here

Feb 01 - 2022

Advert Spreadsheet Import & Export exposed via GraphQL

You can now use the following GraphQL mutations to import and export the Advert CSV:

• advertSpreadsheetUpload
• advertSpreadsheetDownload

For more information on the mutations that we provide please refer to the docs here

Jan 25 - 2022

Configurable Shipment Tracking Links

Marketplacer will auto-generate Shipment Tracking Links for shipments when:

• A shipment carrier has been supplied that has been configured in Marketplacer, and
• A tracking number has been supplied

There may be instances when you want to:

• Override the auto-generated shipment tracking link
• Use an unconfigured shipment carrier (auto-link generation would not occur)

In this case you can now optionally supply the full shipment_tracking_link when both Creating and Updating a Shipment using the Seller API.

For more information on the Shipment endpoint please refer to the docs here

Jan 21 - 2022

Klaviyo Settings can be managed via GraphQL

The following query and mutations have been added to allow operators to manage Klaviyo settings via GraphQL:

• klaviyoSettings (query)
• klaviyoSettingsCreateOrUpdate (mutation)
• klaviyoSettingsDelete (mutation)

For more information on the queries that we provide please refer to the docs here

For more information on the mutations that we provide please refer to the docs here

Sendgrid Settings can be managed via GraphQL

The following query and mutations have been added to allow operators to manage Sendgrid settings via GraphQL:

• sendgridSettings (query)
• sendgridSettingsCreateOrUpdate (mutation)
• sendgridSettingsDelete (mutation)

For more information on the queries that we provide please refer to the docs here

For more information on the mutations that we provide please refer to the docs here

Zooz Settings can be managed via GraphQL

The following query and mutations have been added to allow operators to manage Zooz settings via GraphQL:

• zoozSettings (query)
• zoozSettingsCreateOrUpdate (mutation)
• zoozSettingsDelete (mutation)

For more information on the queries that we provide please refer to the docs here

For more information on the mutations that we provide please refer to the docs here

Jan 19 - 2022

Adyen Settings can be managed via GraphQL

The following query and mutations have been added to allow operators to manage Adyen settings via GraphQL:

• adyenBillingSettings (query)
• adyenEcommerceSettings (query)
• adyenSettingsCreateOrUpdate (mutation)
• adyenSettingsDelete (mutation)

For more information on the queries that we provide please refer to the docs here

For more information on the mutations that we provide please refer to the docs here

Seller Webhook Added

Operators can now subscribe to the following Seller based events:

• Create
• Update
• Destroy

Our webhook getting started guide can be found here

Jan 13 - 2022

Postage Tax exposed on Invoice object

The following postage tax fields have been exposed on the Invoice object:

• taxShippingCents
• taxShippingFormated

For more information on the Invoice object please refer to the docs here

Jan 12 - 2022

Givex Settings can be managed via GraphQL

The following query and mutations have been added to allow operators to manage Givex settings via GraphQL:

• givexSettings (query)
• givexSettingsCreateOrUpdate (mutation)
• givexSettingsdelete (mutation)

For more information on the queries that we provide please refer to the docs here

For more information on the mutations that we provide please refer to the docs here

Jan 07 - 2022

Fix - Validate shipping quantity before dispatch

The Seller API has 2 endpoints where Invoice Shipments can be created (essentially dispatching the line items), as documented here:

• Shipment Create Endpoint
• Invoice Send Endpoint

Prior to this fix it was possible to dispatch more line items that were available for dispatch, (e.g. if some line items had gone through the Cancellation process).

This fix validates the number of line items that can be legitimately dispatched.

Please refer to the Seller endpoints highlighted above for more information