91 posts tagged with "API"

As Nautical continues to evolve, APIs undergo periodic reorganization and improvement. Over time, certain APIs that have been deprecated are removed.

We want to make sure you have advanced notice that we are removing a number of deprecated APIs in January 2024. You will need to update any code using the types, inputs, queries, and mutations outlined below.

Many of the API entities being removed have already been replaced with new entities. To ensure your code remains up to date with the latest API, we have provided guidance below on how to update your code accordingly.

These changes will start rolling out on January 19, 2024.

Recurring billing (Alpha)​

Introducing the ability to set up recurring orders, allowing you to create subscription-based offerings with customizable frequencies and durations. For example, you can offer subscriptions on a monthly, weekly, or daily basis.

Customers' payment information is securely stored in the payment gateway, such as Stripe, and used for future payments.

• Transform a standard checkout into a recurring order using the checkoutConvertToSubscription. Learn more ->

• Manually initiate a recurring order with the subscriptionCreate mutation. Learn more ->

• Retrieve details of recurring orders using the subscriptions query. Learn more ->

Save cards for future payment (Alpha)​

Introduced the ability to save and reuse payment methods for future transactions:

• Within user.storedPaymentSources, you can now query the id field to retrieve a stored payment method token for a customer. Learn more ->

• The paymentInformation.paymentMethodToken input field in the getClientSecret query enables processing payments using a payment source id obtained from user.storedPaymentSources, instead of entering full payment details. Learn more ->

Sort sellers by creation date​

Added the ability to sort sellers by the created field using the sortBy argument.

Updated webhook payloads​

Updated webhook payloads for the following events to be more structured and robust. The structure and contents of the following webhook payloads have been changed:

• checkout_created
• checkout_updated
• fulfillment_created

As a result of these changes, existing logic that utilizes the above webhooks should be updated to align with this new webhook format.

Learn more ->

Enhanced product pricing fields​

All fields within the ProductPricingInfo and VariantPricingInfo types are now non-nullable.

Also, when multicurrency is disabled, the currency-related fields will now return values in the local domiciled currency.

Token required for payment gateways​

All gateways now require tokens to be supplied to checkoutPaymentCreate or nauticalOrderPaymentCreate.

This should not impact any existing checkouts, as Stripe payments already required a payment token.

Version for plugins​

Added the version field to the plugins model.

Fixed an issue where Stripe webhooks could refund events to Nautical on cancellations in some cases.

Fixed an issue where capture_failed transactions sometimes failed to display an error message.

Fixed an issue with converting a checkout to a quote order with a null shipping method.

Removed VATLayer plugin​

Removed the VATLayer plugin, which has not been supported for some time.

Removed purchase order plugin​

The purchase_order payment gateway has been removed.

Removed credit limits model​

Removed the CreditLimits model, which was not in use.

Removed invoice webhooks​

Removed invoice webhooks, which were not in use.

Removed translations​

Removed the translation model.

Removed deprecated permissions​

Removed the manage_gift_cards and manage_credit_limits permissions.

Base amount money field for better accuracy​

Added a baseAmount field to all money-related objects (Money, MoneyRange, TaxedMoney). This field represents the monetary value in the smallest unit of the currency, offering greater accuracy over the existing amount floating point field.

For example, in currencies with two decimal places like USD, $12.45 will be represented as baseAmount=1245.

The amount field is now deprecated and will be removed in 6 months.

Allow buyer to query suborders​

A buyer can now query me.NauticalOrder.subOrders for the seller order information. Payout-related fields on the seller order will not be visible to the buyer.

Seller ID on multi seller shipping method​

Added the sellerId field to the MultiSellerShippingMethodtype.

Improved webhook logging​

Added webhook logging for request time outs and connection errors.

Fixed an issue where duplicate transaction records could be created against the same Stripe payment intent. This did not affect the actual payment captured by Stripe.

Deprecated money fields​

The amount and localized fields on the money type have been deprecated and will be removed after a deprecation period.

Removed dummy_credit_card payment gateway​

Removed the dummy_credit_card payment gateway. All test payments should be done through the dummy gateway going forward.

Removed RazorPay payment gateway​

Removed the RazorPay payment gateway.

Removed gift card model​

Removed the GiftCard model, including all related queries and mutations.

Order line item notes​

Added the ability to add a note per order line item. The following mutations have been added to add line-level notes:

• checkoutLineAddNote: Adds a note to a CheckoutLine.
  note

  When the checkout is converted to an order, any CheckoutLines are converted to NauticalOrder and Order lines.

• nauticalOrderLineAddNote: Adds a note to a NauticalOrderLine.
• orderLineAddNote: Adds a note to an OrderLine.

Learn more ->

New locations queries​

Added the locationSearch and locationGeocode queries, to replace the deprecated mutations.

Email payloads with order line item thumbnails​

Added the original.url field to images on order line items for SendGrid email payloads. This new field provides the URL of the unprocessed, original image, facilitating the integration of image thumbnails in dynamic email templates.

This update provides a way around the SendGrid limitation with accessing the sized thumbnail URLs, which were previously available but incompatible with SendGrid handlebars.

Validation error when payment token already used​

Added a validation error for instances where a token has already been used for a payment.

Sort products or variants by brand or manufacturer​

Added the ability to sort products or variants by the brand and manufacturer fields.

Deprecated location mutations​

The locationSearch and locationGeocode mutations have been deprecated. Instead, use the new locations queries.

Deprecated secondary address​

Deprecated the ShippingMethod.requiresSecondaryAddress and secondaryAddress fields, which were non-functional.

Deprecated shipping fields​

The checkout.shippingMethod and nauticalOrder.shippingMethodName fields have been marked deprecated. These fields were not functional as shipping is stored on the seller order (order).

Removed NauticalFulfillment model​

The following models have bee removed, as fulfillments are tracked at the seller order level.

• NauticalFulfillment
• NauticalFulfillmentLine

This change has been made backwards-compatible. To keep backwards compatibility for NauticalOrder.fulfillments, the type of that field is changed to Fulfillment but the resolver is changed to an empty list.

Removed connection between seller order and payments​

Removed the connection between seller orders (order) and payment objects. This connection had already logically been empty since the deprecation in version 1.9.

As a result, any existing logic querying orders must not explicitly include payments.

Removed taxRate field from order lines​

The taxRate field has been removed from the NauticalOrderLine and OrderLine objects.

Removed nauticalSuborders query​

The nauticalSuborders query has been removed.

Enhanced Stripe integration with webhook listeners​

Added webhook listeners for Stripe integrations, ensuring automatic updates to order payment statuses in Nautical. This is particularly useful for Stripe transactions where payment completion is delayed, like ACH payments.

Nautical will now reflect the following Stripe events:

• payment_intent.amount_capturable_updated
• payment_intent.canceled
• payment_intent.payment_failed
• payment_intent.processing
• payment_intent.succeeded

Decline all order lines​

You can now decline all order lines in a seller order. If all lines are cancelled, the seller order status updates to Cancelled. Additionally, the shipping cost for that order resets to $0, and its total cost is deducted from the marketplace order total.

Filter orders by invoice number​

Added the ability to use the search filter to find orders and nauticalOrders by invoice number.

Invoice refresh mutation​

Added the invoiceRefresh mutation, which regenerates an order document using the same invoice number as originally generated.

Learn more ->

Removed items section on invoices​

Invoice documents for orders with declined fulfillments now include a "Removed Items" section, listing each line item that was removed from the order.

Payment token validation​

Updated the checkoutPaymentCreate and nauticalOrderPaymentCreate mutations to include validation of the supplied token. The validation checks ensure:

• The token has not been previously used, preventing duplicate tokens.
• The token is valid according to the gateway, and the amount provided to the API is appropriate for the token.

For Stripe in particular, we now perform the following validation:

• The payment intent specified by the token exists
• The payment amount specified matches the payment intent amount in Stripe
• The payment intent status is either processing, requires_capture, or succeeded

Transaction error enum replaced​

The Transaction.error field is now a string type instead of an enum.

Breaking change for webhooks​

Implemented strictly typed data classes for more robust and structured webhooks. This approach negates the need for custom webhook fields, as we can now generate model-like payloads with more complex nested data structures.

The structure and contents of the following webhook payloads have been changed:

• Product webhooks: product_created, product_updated, product_deleted
• Variant webhooks: variant_created, variant_updated, variant_deleted
• Warehouse webhooks: warehouse_created, warehouse_updated, warehouse_deleted
• Stock webhooks: stock_created, stock_updated, stock_deleted
• Stock allocation webhooks: stock_allocated, stock_deallocated
• Agreement webhooks: agreement_created, agreement_updated, agreement_deleted
• Microsite webhooks: microsite_created, microsite_updated
• Collection webhooks: collection_created, collection_updated, collection_deleted

As a result of these changes, existing logic that utilizes the above webhooks should be updated to align with this new, more structured webhook format. Follow the learn more link below to view the new webhooks.

Learn more ->

Plugin allow sellers field​

The plugin model now has the allowSellers boolean field, which indicates whether sellers can configure the plugin.

Fixed an issue where the option to fulfill items remained available from the marketplace order even after a seller order was cancelled.

Fixed an issue where stock allocated to draft orders wasn't being deallocated upon bulk deletion of those orders.

Fixed an issue that could prevent order emails from being sent with the type error Object of type X is not JSON serializable.

Fixed an issue that prevented the activation of the HERE plugin.

Backorders API​

Added the ability to enable backorders with customizable settings, allowing you to set backorder thresholds and selectively activate this feature for specific product variants.

To activate the backorders feature, a new marketplace configuration enableBackorders field has been introduced. Once enabled, you can control which items are eligible for backordering through the allowBackorders boolean field on each product variant. By default, both fields are set to false (off) to maintain your current settings.

When adding or adjusting stock, StockInput now accepts the outOfStockThreshold field, which defaults to 0. This field allows you to set a negative value for how far stock levels can go below zero. When backorders and thresholds are set up, the quantityAvailable field can take on a negative value, but it cannot go past the limits defined by the outOfStockThreshold.

Learn more ->

Webhook queue manager plugins​

Refactored webhooks to enhance security and functionality in conjunction with queue manager plugins. If any of the following plugins are enabled, webhooks will now be directed to their respective queues:

• Amazon Simple Queue Service
• Google Cloud Pub/Sub
• Microsoft Azure Service Bus

Store PO number on Checkout and NauticalOrder​

Added the capability to store Purchase Order (PO) numbers in both the Checkout and NauticalOrder models. This includes the ability to search for purchase order numbers using the search filter.

During the checkout process, you can use the checkoutAddPoNumbers mutation to input one or more PO numbers, allowing buyers to easily reference these during transactions. You can also use the checkoutRemovePoNumber mutation to remove a PO number.

Once the checkout is completed, these PO numbers are saved to the resulting NauticalOrder. This ensures that each marketplace order can have one or more associated PO numbers for record-keeping and future reference. After checkout, you can manage PO numbers by updating the NauticalOrder directly.

Fixed an issue where bulk creation of variants resulted in a GraphQL error ID cannot represent value: None.

Fixed an issue that prevented searching for seller orders by the customer's company name. The search filter now includes the customer's company name if the token running the GraphQL query has the manage_users permission.

Fixed an issue where the orderCancel or orderBulkCancel mutations were not triggering stock deallocated webhooks upon cancelling orders.

Fixed an issue where changing the customer in a draft marketplace order did not update the customer address. Now, when you select a different customer, the address fields will automatically update to reflect the new customer's information.

API v1.12.1​

Surface PO number on invoice​

Invoices now display PO numbers if they are available on the corresponding marketplace order (NauticalOrder). Invoices must be regenerated for this change to take effect.

Fixed an issue where declining the full quantity of an order line from a marketplace order did not update the nauticalOrder.total.tax.amount value to reflect the adjusted tax amount. This inconsistency also affected invoice information, making invoices different from what was displayed on the Order Details page in the Dashboard.

Fixed an issue related to the caching of invoice shipping prices and order line tax amounts.

Fixed an issue where the query for top-performing products incorrectly included deleted variants.

API v1.12.2​

Sort orders by PO number​

Added the ability to sort marketplace orders (nauticalOrder) by PO numbers.

Fixed an issue where, when enableStockAllocationForDrafts=true, stock was not being deallocated after deleting draft orders.

Fixed an issue where the Shopify price sync toggle was not appearing for sellers with existing integrations.

API v1.12.3​

Fixed an issue that prevented the order_creation email to send in certain circumstances with an TypeError: Object of type X is not JSON serializable error.

New webhooks​

Added the following webhook event types:

• category_deleted
• category_updated
• collection_created
• collection_deleted
• collection_updated
• price_book_created
• price_book_updated
• product_deleted
• refund_created
• refund_deleted
• refund_updated
• stock_deleted
• variant_deleted
• warehouse_created
• warehouse_deleted
• warehouse_updated

Learn more ->

Sync prices with Shopify​

Added a new setting to the Shopify app, is_product_price_sync_enabled, that updates Nautical product prices when they are updated in Shopify. Note that this is a one-way sync, with Shopify serving as the source of truth for pricing.

Marketplace timezone​

Added the timezone field to the MarketplaceConfiguration model, which accepts the IANA timezone name. This field is now honored in queries for the insights APIs. We will be honoring it in other timezone fields in a future release.

We are now storing the total price for each line item as returned from the tax-engine, eliminating several tax-related rounding errors.

The marketplace order can now be accessed as part of payment queries through a new nautical_order field on the Payment type

We made several performance improvements around draft order APIs when the order contains a high number of line items.

The orders and nauticalOrders queries have a new filter to query by company name.

Breaking change in decline fulfillments API​

The orderDeclineFulfillment mutation now requires the quantity to be listed with the associated warehouse via a new stocks field. This allows the declined items to be deallocated back to the correct warehouse.

mutation {
  orderDeclineFulfillment(
    order: "T3JkZXI6MTMzMDk="
    input: {
      notifyCustomer: true
      lines: {
        orderLineId: "T3JkZXJMaW5lOjMwMzIy",
        stocks: [
          {
            quantityDeclined: 1,
            warehouse: "V2FyZWhvd...mUyYWYxZQ=="
          }
        ]
      }
    }
  ) {
    fulfillments {
      id
      status
      totalLinesQuantity
      lines {
        id
        quantity
      }
    }
}

Fixed an issue where refunds were not including taxes in the refundPayment total. A new total_gross field is introduced to process the refundPayment with taxes included.

Fixed an issue where seller staff members could view products owned by other sellers when working with categories.

Fixed an issue where the stock_allocated, stock_deallocated, and stock_updated webhooks were not being triggered by order events.

Fixed an issue where the payout_updated and vendor_payout_updated webhooks were not being triggered by certain payout events.

Fixed an issue where the seller_updated webhook was not being triggered when metadata updates.

Fixed an issue filtering categories when the seller is a member of a master marketplace.

Fixed an issue where the quantity field on order types should be required. Note: This field has been deprecated. We will eventually prefer the quantityOrdered field.

Fixed an issue where line quantity updates were not always triggering updates in tax calculation plugins.

API v1.11.2​

Add vouchers to quote and draft orders​

Added the ability to add and remove vouchers on a draft or quote order. Vouchers can be managed on draft or quote orders through the following new mutations:

• NauticalOrderUpdateApplyVoucherCode
• NauticalOrderUpdateDeleteDiscount
• OrderUpdateApplyVoucherCode
• OrderUpdateDeleteDiscount

mutation {
  NauticalOrderUpdateApplyVoucherCode(
    id: "TmF1dGljYWxPcmRlcjo1"
    voucherCode: "SEPT10OFF"
  ) {
    nauticalOrder {
      id
      discount {
        amount
      }
      voucher {
        id
        name
        code
      }
    }
    orderErrors {
      field
      message
      code
    }
  }
}

Display marketplace tax ID on invoices​

Added the display of VAT Business Identification No to invoices generated from a marketplace order. The value is pulled from the taxId field on the seller account reserved for the marketplace (seller #1).

Learn more ->

Fixed an issue where the updateSeller mutation would fail if the seller did not have an attached agreement.

Reduced database calls to improve speeds of various queries, including product and currency queries.

Added the following webhook events:

• agreement_created
• agreement_updated
• agreement_deleted
• category_created

Learn more ->

Fixed an issue with inaccurate tax calculations for refunds when the initial order was not subject to tax.

Fixed an issue with where checkoutLinesUpdate could encounter an error applying discounts in multi-currency environments.

Decline fulfillments API​

Added the orderDeclineFulfillment mutation and object to remove order lines that cannot be fulfilled. A new field, quantityDeclined, has been added to the OrderLine object to track declined quantities.

When this mutation is called, the order total and taxes are recalculated, omitting the unfulfillable line items. However, shipping costs remain unchanged. This mutation must be used before payment has been captured.

The existing ORDER_FULFILLED webhook is triggered by the orderDeclineFulfillment mutation. You may need to update your webhook consumption to check the fulfillment status.

The DECLINED status is added to the FulfillmentStatus enum. Both order.fulfillments and nauticalOrder.fulfillments will now include declined fulfillments. Please note that the quantity value for these declined fulfillments is a positive integer. You may need to adjust your calculations involving fulfillment quantities accordingly.

mutation {
  orderDeclineFulfillment(
    order: "T3JkZXI6MTMzMDk="
    input: {
      notifyCustomer: true
      lines: {
        orderLineId: "T3JkZXJMaW5lOjMwMzIy",
        quantityDeclined: 1
        }
    }
  ) {
    order {
      id
      status
    }
    fulfillments {
      id
      status
      totalLinesQuantity
      lines {
        id
        quantity
      }
    }
    orderErrors {
      field
      code
      message
      orderLine
    }
  }
}

Learn more ->

Checkout performance improvements​

Introduced significant optimizations to checkout API calls, with the following changes:

• Leveraging cached shipping rates for quicker calculations
• Utilizing cached foreign exchange rates for multi-currency support
• Elimination of multiple N+1 queries for checkout line items, reducing database load
• Improvements to checkoutComplete execution time.

Braintree upgrade​

Upgraded Braintree integration to use Braintree version 4.21.0.

Asynchronous webhooks​

The following webhooks are now asynchronous: SELLER_AGREEMENT_ACKNOWLEDGED, PAYOUT_UPDATED, VENDOR_PAYOUT_UPDATED, PRODUCT_CREATED, and PRODUCT_UPDATED.

quantity​

The quantity field has been deprecated on the following types, and replaced with a more explicit name quantityOrdered:

• OrderLine
• SecondaryOrderLine
• NauticalOrderLine
• NauticalSecondaryOrderLine

quantityFulfilled​

The quantityFulfilled field has been deprecated on the following types:

• NauticalOrder
• NauticalOrderLine

Instead, retrieve quantityFulfilled from the underlying seller orderLine. To make this easier, nauticalOrder.lines now returns sellerOrderline with the underlying seller order lines.

Fixed an issue where stock could be deallocated from a warehouse different from the one it was originally allocated to.

Fixed an issue that prevented editing prices for product variants.

Stock allocation webhooks​

Added new webhooks for stock events:

• STOCK_ALLOCATED: Triggered by new order stock allocation.
• STOCK_DEALLOCATED: Triggered by order stock fulfillment or removal/cancellation of order line items.

Learn more ->

Sort products in microsite​

Added support for SortOrder when querying products in a microsite.

Refresh order tax​

Added the nauticalOrderRefreshTaxes mutation and object to force a recalculation of taxes on a non-finalized marketplace order, such as an order in the draft, offer, or quote stage.

Learn more ->

Performance improvements​

Enhanced performance for faster loading times across various product catalog queries, product availability in multi-currency environments, and the orderFulfill mutation.

Seller order payment fields and actions​

Various fields and mutations around payments on the seller order have been deprecated in order to build a more flexible and stable solution. Payments were, and continue to be, captured against the marketplace-level NauticalOrder, not the seller-level Order. The following components have been deprecated:

• Order.paymentStatus, Order.paymentStatusDisplay, and Order.is_paid will now return values based on the underlying NauticalOrder.
• Order.payments and Order.actions are deprecated and will now return an empty list. After a deprecation period, these will be removed.
• Order.total_authorized, Order.total_captured, and Order.total_balance are deprecated and will now return 0. After a deprecation period, these will be removed.
• orderCapture, orderMarkAsPaid, orderRefund, and orderVoid mutations are now non-operational. These mutations are now deprecated and will be removed after the deprecation period.

Fixed an issue where apps with seller-level configurations, such as Shopify or WooCommerce, could experience issues syncing data.

Fixed an issue where the accountConfirm mutation did not trigger the CUSTOMER_UPDATED webhook.

Fixed an issue where the customerBulkDelete mutation did not trigger the CUSTOMER_DELETED webhook.

Fixed an issue where the PAYOUT_UPDATED and VENDOR_PAYOUT_UPDATED webhooks were not being triggered by edits to payouts.

Fixed an issue where cancelling a quote or offer order deleted the order instead of moving the order to the cancelled state.

Fixed an issue where multiple nauticalOrder records could be created in certain scenarios when finalizing an offer order.

Fixed an issue with the user query, where querying the checkout.discountType field returned an error.

Fixed an issue where quantityAllocated was not being decreased after cancelling an order.

Fixed an issue where the STOCK_ALLOCATED event was not created when an item was added to an order or quote from the storefront.