Changelog
We regularly update our API and provide detailed notes on each release. We first release to staging, then to production about a week later. Learn more about our release process.
: Staging
: Production
The nautical_event_type and nautical_event_timestamp fields are now part of every webhook payload body, whereas previously this information was only accessible from the header. For example:
"nautical_event_type": "nautical_order_created",
"nautical_event_timestamp": "2024-02-22T15:24:19.374608-05:00",
: Staging
: Production
Added support to connect to Firebase authentication, a tool that supports various sign-in methods, including social logins and email/password combinations. This plugin leverages Firebase's secure user token to authenticate users within Nautical, proving a seamless sign-on experience.
Added the availableShippingStrategy field to the MarketplaceConfiguration model. This field determines how available shipping methods are calculated for price-based shipping rates.
SELLER_LINES (default), the calculation of available shipping methods for each seller is based solely on that seller's order total.MARKETPLACE_LINES, the calculation includes the entire marketplace order total for determining available shipping methods for each seller.Fixed an issue where the vendor_payout_confirmation email was not being sent after processing payouts.
Fixed an issue where you could not filter sellers with the PAUSED status.
Fixed an issue where a customer user could use another customer's order token to access details of that order via the API.
: Staging
: Production
Deprecated the payout.penalties field in favor of negative adjustments. This field is scheduled for removal after July 1, 2024.
: Staging
: Production
Added the ability to generate refund receipts with the invoiceRequest mutation. You must provide the refundId as an argument, for example:
mutation {
invoiceRequest(refundId: "UmVmdW5kOjUzOA==") {
invoice {
id
url
}
}
}
Added the nautical.payments.paypal plugin for using PayPal as the payout gateway.
Added the nautical.payments.trolley plugin for using Trolley as the payout gateway.
Improved the logging of webhook events for queue management plugins, such as Google PubSub. Whereas previously logs were only created for failed transmissions, we now also capture and log successful webhook events.
Order webhooks now include the number field, which is populated with the seller order number.
Fixed an issue where voucher discounts requiring a minimum order value were applied based on the gross total, including tax, rather than the net order total.
: Staging
: Production
Refund lines can now be scoped to an OrderLine, allowing you to target refunds to specific individual order lines. To achieve this, use the refundLinesAdd mutation and set the refundScope to the id of the desired order line. Additionally, specify the quantity of the order line that should be included in the refund.
Added the following mutations for uploading a CSV file to create draft order lines:
nauticalOrderLinesCsvUploadorderLinesCsvUploadThe CSV file must have at least three columns: id_type, id, and quantity. See the following sample format:
id_type, id, quantity
NSN, 5669abb7-8c4f-477f-8662-4540af3bcdac, 5
ID, UHJvZHVjdFZhcmlhbnQ6MjEx, 5
SKU, 998323573, 5
ID, UHJvZHVjdFZhcmlhbnQ6MjEz, 5
Added a "Nautical Test Taxes" plugin, which can be used for development and testing with taxes.
Within the plugin settings, you can input a single tax percentage, which should fall within the range of 0 to 100%. This plugin respects tax settings such as "Charge taxes on shipping rates" and "All products prices are entered with tax included."
This plugin is intended solely for development and testing and is not for use in production environments.
When processing a manual refund for a fixed amount, taxes are no longer added separately. The fixed amount entered is the after-tax amount.
Fixed amount refunds do not automatically adjust records in the tax engine, such as Avalara. If you need to modify the amount of tax to remit, you must manually create a tax adjustment within Avalara.
: Staging
: Production
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:
order_created order_updatedorder_cancelled order_fully_paid order_fulfilled payment_createdAs a result of these changes, existing logic that utilizes the above webhooks should be updated to align with this new webhook format.
Made several API performance improvements around handling orders and refunds, including:
Fixed an issue where the userOverride argument on the checkoutComplete mutation did not override the user assigned to the checkout. Marketplace operators can now override the user during checkout completion using this argument.
Fixed an issue where buyers were unable to add digital products to the checkout, particularly when it was the first item being added to the checkout.
Fixed an issue where the order_number, created, and total_gross_amounts fields were missing from the recently updated NauticalOrder webhooks.
Fixed an issue that could prevent marketplace operators from finalizing draft orders in multi-currency environments, with a 'NoneType' object has no attribute 'unit_price_net' error message.
: Staging
: Production
Added support for storing metadata on the CheckoutLine, OrderLine, and NauticalOrderLine objects, providing more flexibility in adding custom line-level data within an order.
me queryEnhanced the ability for users to filter orders retrieved from the me query. The CustomerOrderFilterInput, which previously only supported filtering by status, now supports many different filter fields.
One such is the ids filter field, which allows users to find a specific order by id.
Updated the order-related customer SendGrid email payloads to include the recipient_first_name and recipient_last_name fields. If the order is for a guest, these fields will be empty.
Made the following improvements to webhooks:
token to checkout webhook payloads.Made several performance improvements around order management, including:
Improved the ability to store payment sources for Stripe payments:
brand, expMonth, and expYear can now be stored.paymentMethodType.Fixed an issue where event notifications were not being sent during the NauticalDraftOrderLinesBulkDelete mutation.
Fixed an issue preventing full refunds of orders with declined fulfillments.
: Staging
: Production
Added the isActive boolean filter to the customers query.
Added the following fields to the Seller model:
approvedDatefirstOrderPlaedDatefirstProductCreatedDateUpdated webhook payloads for the following events to be more structured and robust. The structure and contents of the following webhook payloads have been changed:
nautical_order_creatednautical_order_updatednautical_order_fully_paidnautical_order_cancelledAs a result of these changes, existing logic that utilizes the above webhooks should be updated to align with this new webhook format.
Fixed an issue where volume discounts were being incorrectly deducted from seller order payouts.
Fixed an issue with the Yotpo Ratings and Reviews app not properly utilizing ProductSchema fields.
Fixed an issue where the variant_created webhook was not triggered upon bulk creation of product variants.
: Staging
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.
| Query | Upgrade guidance |
|---|---|
barcodeLookup | N/A |
draftOrders.created | Use the filter field instead. |
drugLookup | N/A |
nauticalDraftOrders.created | Use the filter field instead. |
NauticalOrders.created | Use the filter field instead. |
NauticalOrders.status | Use the filter field instead. |
Orders.created | Use the filter field instead. |
Orders.status | Use the filter field instead. |
serviceAccount | Use the app query instead. |
serviceAccounts | Use the apps query instead. |
upcItemDb | N/A |
webhooks | Use the webhooks field on the app or apps query instead. |
| Mutation | Upgrade guidance |
|---|---|
acceptBid | Use the bidAccept mutation instead. |
accountSetDefaultAddress | Use the accountAddressSetDefault mutation instead. |
acknowledgeSellerAgreement | Use the sellerAgreementAcknowledge mutation instead. |
attributeReorderValues | Use the attributeValuesReorder mutation instead. |
bulkFulfillmentReturn | Use the fulfillmentBulkReturn mutation instead. |
checkoutShippingMethodUpdate | Use the CheckoutSellerShippingMethodsUpdate mutation. |
confirmAccount | Use the accountConfirm mutation. |
confirmEmailChange | Use the emailChangeConfirm mutation. |
createCoreData | Use the coreDataCreate mutation. |
createDesigerData | Use the designerDataCreate mutation. |
createHashtag | Use the hashtagCreate mutation. |
createMention | Use the mentionCreate mutation. |
createSellerData | Use the sellerDataCreate mutation. |
createSellerShell | Use the sellerShellCreate mutation. |
createSellerUserMapping | Use the sellerUserMappingCreate mutation. |
createWarehouse | Use the warehouseCreate mutation. |
deleteBrandingImages | Use the brandingImagesDelete mutation. |
deleteMetadata | Use the metadataDelete mutation. |
deletePrivateMetadata | Use the privateMetadataDelete mutation. |
deleteWarehouse | Use the warehouseDelete mutation. |
exportCatalog | Use the catalogExport mutation. |
exportProducts | Use the productsExport mutation. |
getPayoutOnboardingLink | Use the vendorPayoutOnboardingLinkRequest mutation. |
importCatalog | Use the catalogImport mutation. |
importProducts | Use the productsImport mutation. |
nauticalOrderRefund | Use the refundCreate mutation instead and then add the nautical order using the refundLinesAdd mutation. |
orderCapture | Direct capture against seller orders is unsupported as Payments are only attached to the NauticalOrder. Use nauticalOrderCapture instead. |
orderFulfillmentUpdateReturnStatus | Use the fulfillmentBulkReturn mutation instead. |
orderMarkAsPaid | Direct update of seller orders to paid is unsupported as Payments are only attached to the NauticalOrder. Use nauticalOrderMarkAsPaid instead. |
orderRefund | Use the refundCreate mutation instead and then add the order using the refundLinesAdd mutation. |
orderVoid | Direct void against seller orders is unsupported as Payments are only attached to the NauticalOrder. Use nauticalOrderVoid instead. |
paymentRefund | Use the refundCreate mutation instead and then utilize the refundPaymentsAdd mutation. |
productVariantReorder | Use the productReorderVariants mutation. |
rejectBid | Use the bidReject mutation. |
requestEmailChange | Use the emailChangeRequest mutation. |
requestPasswordReset | Use the passwordRequestReset field. |
sellerAddNote | Use the sellerNoteCreate mutation. |
sendQuoteToCustomer | Use the nauticalQuoteOrderSendToCustomer mutation. |
serviceAccountCreate | Use the appCreate mutation instead. |
serviceAccountDelete | Use the appDelete mutation instead. |
serviceAccountTokenCreate | Use the appTokenCreate mutation instead. |
serviceAccountTokenDelete | Use the appTokenDelete mutation instead. |
serviceAccountUpdate | Use the appUpdate mutation instead. |
setPassword | Use the passwordSet mutation. |
setWishlistAsDefault | Use the wishlistSetDefault mutation. |
submitRatingAndReview | Use the productReviewSubmit mutation instead. |
updatebranding | Use the brandingUpdate mutation |
updateCoreData | Use the coreDataUpdate mutation. |
updateDesignerData | Use the designerDataUpdate mutation. |
updateMetadata | Use the metadataUpdate mutation. |
updatePrivateMetadata | Use the privateMetadataUpdate mutation. |
updateSellerData | Use the sellerDataUpdate mutation. |
updateSellerSettings | Use the sellerSettingsUpdate mutation. |
updateWarehouse | Use the warehouseUpdate mutation. |
variantImageAssign | Use the productVariantImageAssign mutation instead. |
variantImageUnassign | Use the productVariantImageUnassign mutation instead. |
| Input | Upgrade guidance |
|---|---|
AppInput.isActive | Use the appActivate and appDeactivate mutations instead. |
AttributeInput.value | Use values instead. |
CheckoutCustomerAttach.customer_id | The ID of the customer. To identify a customer you should authenticate with JWT. |
DetailedSellerInput.status | This field will be ignored in the mutation and a seller will be created in pending status |
DocumentAdd.documentId | To attach a document to related instances, use documentAttach mutation instead. |
DocumentAdd.ids | To attach a document to related instances, use documentAttach mutation instead. |
DraftOrderInput.discount | Use nauticalOrderUpdateApplyVoucherCode mutation instead. |
DraftOrderInput.shippingMethod | Unsupported field. Use orderUpdateShipping mutation instead. |
DraftOrderInput.voucher | Use nauticalOrderUpdateApplyVoucherCode mutation instead. |
NauticalHistoricalOrderInput.shippingMethod | Use nauticalOrderUpdateShipping mutation instead. |
WebhookCreateInput.serviceAccount | Use the app field instead. |
WebhookUpdateInput.serviceAccount | Use the app field instead. |
| Type | Upgrade guidance |
|---|---|
*.*.errors | Removal impacts all mutations that have the errors field. Use typed errors with error codes, for example checkoutErrors. |
Category.url | N/A |
Checkout.availableShippingMethods | Use the availableShippingMethodsBySeller field instead. |
Money.localized | Price formatting according to the current locale should be handled by the frontend client. |
NauticalOrder.availableShippingMethods | Use the availableShippingMethodsBySeller field instead. |
NauticalOrderLine.quantity | Use the more explicit quantityOrdered instead. |
NauticalOrderLine.quantityFulfilled | Marketplace Orders are not fulfilled. Use quantityFulfilled on the seller OrderLine instead. |
NauticalSecondaryOrderLine.quantity | Use the more explicit quantityOrdered instead. |
OrderLine.quantity | Use the more explicit quantityOrdered instead. |
Product.url | N/A |
ProductVariant.isAvailable | Use the stocks field instead. |
ProductVariant.quantity | Use the stocks field instead. |
ProductVariant.quantityAllocated | Use the stocks field instead. |
ProductVariant.stockQuantity | Use the quantityAvailable field instead. |
SecondaryOrderLine.quantity | Use the more explicit quantityOrdered instead. |
Webhook.serviceAccount | Use the app field instead. |
: Staging
: Production
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 ->
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 ->
Added the ability to sort sellers by the created field using the sortBy argument.
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_createdcheckout_updatedfulfillment_createdAs a result of these changes, existing logic that utilizes the above webhooks should be updated to align with this new webhook format.
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.
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.
Fixed an issue where Stripe webhooks could refund events to Nautical on cancellations in some cases.
Fixed an isse where capture_failed transactions sometimes failed to display an error message.
Fixed an isse with converting a checkout to a quote ordder with a null shipping method.
Removed the VATLayer plugin, which has not been supported for some time.
Removed the manage_gift_cards and manage_credit_limits permissions.