455 posts tagged with "API"

New order payout status​

Introduced a new NOT_PAID payout status for orders, providing clearer tracking of orders that haven't yet been included in seller payouts.

WorkOS authentication support​

Added WorkOS as an authentication option when creating customer tokens, enabling single sign-on (SSO) capabilities for customer accounts.

Update product types​

Product types can now be updated after creation, allowing you to reorganize your catalog structure without recreating products.

Custom attribute filtering​

Added support for custom attribute filters on products, giving you more flexibility in how customers browse and search your catalog.

Fixed an issue where refunds weren't being included when calculating the available payout balance for orders.

Fixed an issue where declined fulfillments were incorrectly triggering shipping cost accruals.

Fixed an issue where other sellers could inadvertently access marketplace orders using the nauticalOrderByToken query.

Fixed an issue where Stripe webhook events weren't being properly recreated during webhook processing, which could cause payment status updates to fail.

Fixed an issue where Stripe webhook handlers weren't running within database transactions, which could lead to data inconsistencies during payment processing.

Fixed an issue where buyer ledgers weren't being created automatically during account creation.

Fixed an issue where foreign exchange amounts weren't properly accounting for declined and cancelled orders.

Fixed an issue where payment captures were being recorded in ledgers even when webhook-created transactions didn't exist.

Fixed an issue where product update webhooks weren't being triggered consistently when products or variants were modified.

Fixed an issue that prevented publishing products that already had a category assigned.

Fixed an issue where seller orders without ledger entries would cause errors when calculating balances.

Added migration to manually increment Shopify API versions, ensuring compatibility with the latest Shopify platform updates.

Fixed an issue where orders were being incorrectly marked as partially paid when payments were unaccrued.

Moved partial order cancellation and pending quote email templates to the user emails section for better organization.

Fixed an issue where the payoutStatus field on orders showed incorrect values when payouts remained in draft status for extended periods.

Fixed an issue with product resolution that could cause incorrect data to be returned in certain query scenarios.

This release contains internal improvements and maintenance updates.

Update product variant associations​

Product variants can now be reassigned to different parent products, providing greater flexibility in managing product catalogs and variant structures.

Fixed an issue where multiple invoices could be created with duplicate invoice numbers for the same order.

Fixed an issue where filtering products by date could return incorrect results in certain scenarios.

Fixed several issues related to payout processing:

• Empty payouts can no longer be created in the payout flow.
• Locked payouts now properly prevent multiple concurrent payout operations.
• Payout validation messages are now clearer and more informative.
• Order line refunds are now correctly reflected in the payout summary.
• Shipping fees are now properly handled when fulfillments are cancelled.
• Fee reversals on order cancellation now only apply to fees that were actually accrued.

Voucher information in order webhooks​

Added voucher details to webhook payloads for NauticalOrder and Order events, making it easier to track discount usage in external systems.

Fixed an issue where order line metadata was not being included in email templates, ensuring all custom line-level data is now available for email personalization.

Fixed an issue where refund amounts were incorrectly included in the VendorPayout.payout_amount calculation, ensuring accurate payout totals for sellers.

Financial ledgers with queryable journals​

Added a new financial modelling system, using double-entry accounting that automatically records data to a balanced ledger through various order and payout related events.

This updated model aligns with ASC 606 revenue recognition standards, providing a clear and auditable financial trail of how revenue is recognized and split between the marketplace and its sellers. Central to this feature is the MarketplaceConfiguration.revenueAccrualStrategy field, which determines how revenue is recognized in alignment with your operational needs.

You can leverage the journalEntries query to view journal entries, using filters like order ID or journal entry type via JournalEntryFilterInput. Here's a sample GraphQL query and response that demonstrates how you can retrieve the first 10 journalEntries related to a marketplace order:

query {
  journalEntries(
    filter: { nauticalOrderIds: "TmF1dGljYWxPcmRlcjoxNjU4" }
    first: 10
    sortBy: { direction: ASC, field: DATE }
  ) {
    edges {
      node {
        id
        type
        description
        createdAt
        order {
          id
        }
        ledgerEntries {
          ledgerBalance {
            baseAmount
          }
          ledger {
            id
            type
            accountType
            balance {
              baseAmount
            }
          }
        }
      }
    }
  }
}

{
  "data": {
    "journalEntries": {
      "edges": [
        {
          "node": {
            "id": "Sm91cm5hbEVudHJ5OjEyNzk=",
            "type": "ORDER_PLACED",
            "description": "NauticalOrder TmF1dGljYWxPcmRlcjoxNjU4 placed",
            "createdAt": "2024-03-12T13:28:47.755267+00:00",
            "order": null,
            "ledgerEntries": [
              {
                "ledgerBalance": {
                  "baseAmount": -9552473
                },
                "ledger": {
                  "id": "TGVkZ2VyOjM=",
                  "type": "DEFERRED_SALES_REVENUE",
                  "accountType": "REVENUE",
                  "balance": {
                    "baseAmount": -10014369
                  }
                }
              },
              {
                "ledgerBalance": {
                  "baseAmount": -975237
                },
                "ledger": {
                  "id": "TGVkZ2VyOjEw",
                  "type": "SALES_TAX",
                  "accountType": "LIABILITY",
                  "balance": {
                    "baseAmount": -1024184
                  }
                }
              },
              {
                "ledgerBalance": {
                  "baseAmount": -274000
                },
                "ledger": {
                  "id": "TGVkZ2VyOjI=",
                  "type": "DEFERRED_SHIPPING_REVENUE",
                  "accountType": "REVENUE",
                  "balance": {
                    "baseAmount": -314000
                  }
                }
              },
              {
                "ledgerBalance": {
                  "baseAmount": 8681638
                },
                "ledger": {
                  "id": "TGVkZ2VyOjE1OQ==",
                  "type": "CUSTOMER_RECEIVABLE",
                  "accountType": "ASSET",
                  "balance": {
                    "baseAmount": 8617168
                  }
                }
              }
            ]
          }
        },
        {
          "node": {
            "id": "Sm91cm5hbEVudHJ5OjEyODA=",
            "type": "PAYMENT_CAPTURED",
            "description": "Payment UGF5bWVudDoxMjkx captured",
            "createdAt": "2024-03-12T13:29:05.541593+00:00",
            "order": null,
            "ledgerEntries": [
              {
                "ledgerBalance": {
                  "baseAmount": 10050882
                },
                "ledger": {
                  "id": "TGVkZ2VyOjU=",
                  "type": "FUNDS_PAYMENTS",
                  "accountType": "ASSET",
                  "balance": {
                    "baseAmount": 10183826
                  }
                }
              },
              {
                "ledgerBalance": {
                  "baseAmount": 8362918
                },
                "ledger": {
                  "id": "TGVkZ2VyOjE1OQ==",
                  "type": "CUSTOMER_RECEIVABLE",
                  "accountType": "ASSET",
                  "balance": {
                    "baseAmount": 8617168
                  }
                }
              }
            ]
          }
        },
        {
          "node": {
            "id": "Sm91cm5hbEVudHJ5OjEyODE=",
            "type": "ORDER_ACCRUED",
            "description": "OrderLine T3JkZXJMaW5lOjU2MTQ= accrued",
            "createdAt": "2024-03-12T13:29:15.517609+00:00",
            "order": {
              "id": "T3JkZXI6Mjg5NQ=="
            },
            "ledgerEntries": [
              {
                "ledgerBalance": {
                  "baseAmount": -9531073
                },
                "ledger": {
                  "id": "TGVkZ2VyOjM=",
                  "type": "DEFERRED_SALES_REVENUE",
                  "accountType": "REVENUE",
                  "balance": {
                    "baseAmount": -10014369
                  }
                }
              },
              {
                "ledgerBalance": {
                  "baseAmount": 124120
                },
                "ledger": {
                  "id": "TGVkZ2VyOjY0",
                  "type": "SELLER_PAYABLE",
                  "accountType": "LIABILITY",
                  "balance": {
                    "baseAmount": 181900
                  }
                }
              }
            ]
          }
        },
        {
          "node": {
            "id": "Sm91cm5hbEVudHJ5OjEyODI=",
            "type": "COMMISSION",
            "description": "OrderLine T3JkZXJMaW5lOjU2MTQ= commission",
            "createdAt": "2024-03-12T13:29:15.517719+00:00",
            "order": {
              "id": "T3JkZXI6Mjg5NQ=="
            },
            "ledgerEntries": [
              {
                "ledgerBalance": {
                  "baseAmount": 127330
                },
                "ledger": {
                  "id": "TGVkZ2VyOjY0",
                  "type": "SELLER_PAYABLE",
                  "accountType": "LIABILITY",
                  "balance": {
                    "baseAmount": 181900
                  }
                }
              },
              {
                "ledgerBalance": {
                  "baseAmount": -2939495
                },
                "ledger": {
                  "id": "TGVkZ2VyOjc=",
                  "type": "MARKETPLACE_COMMISSION",
                  "accountType": "REVENUE",
                  "balance": {
                    "baseAmount": -2997415
                  }
                }
              }
            ]
          }
        },
        {
          "node": {
            "id": "Sm91cm5hbEVudHJ5OjEyODM=",
            "type": "SHIPPING_ACCRUED",
            "description": "Order T3JkZXI6Mjg5NQ== shipping accrued",
            "createdAt": "2024-03-12T13:29:15.517770+00:00",
            "order": {
              "id": "T3JkZXI6Mjg5NQ=="
            },
            "ledgerEntries": [
              {
                "ledgerBalance": {
                  "baseAmount": -272000
                },
                "ledger": {
                  "id": "TGVkZ2VyOjI=",
                  "type": "DEFERRED_SHIPPING_REVENUE",
                  "accountType": "REVENUE",
                  "balance": {
                    "baseAmount": -314000
                  }
                }
              },
              {
                "ledgerBalance": {
                  "baseAmount": -541850
                },
                "ledger": {
                  "id": "TGVkZ2VyOjk=",
                  "type": "MARKETPLACE_FEES",
                  "accountType": "REVENUE",
                  "balance": {
                    "baseAmount": -536950
                  }
                }
              }
            ]
          }
        },
        {
          "node": {
            "id": "Sm91cm5hbEVudHJ5OjEyODQ=",
            "type": "ORDER_ACCRUED",
            "description": "OrderLine T3JkZXJMaW5lOjU2MTU= accrued",
            "createdAt": "2024-03-12T13:29:15.691871+00:00",
            "order": {
              "id": "T3JkZXI6Mjg5Ng=="
            },
            "ledgerEntries": [
              {
                "ledgerBalance": {
                  "baseAmount": -9256073
                },
                "ledger": {
                  "id": "TGVkZ2VyOjM=",
                  "type": "DEFERRED_SALES_REVENUE",
                  "accountType": "REVENUE",
                  "balance": {
                    "baseAmount": -10014369
                  }
                }
              },
              {
                "ledgerBalance": {
                  "baseAmount": 978750
                },
                "ledger": {
                  "id": "TGVkZ2VyOjY1",
                  "type": "SELLER_PAYABLE",
                  "accountType": "LIABILITY",
                  "balance": {
                    "baseAmount": 1572500
                  }
                }
              }
            ]
          }
        },
        {
          "node": {
            "id": "Sm91cm5hbEVudHJ5OjEyODU=",
            "type": "COMMISSION",
            "description": "OrderLine T3JkZXJMaW5lOjU2MTU= commission",
            "createdAt": "2024-03-12T13:29:15.692001+00:00",
            "order": {
              "id": "T3JkZXI6Mjg5Ng=="
            },
            "ledgerEntries": [
              {
                "ledgerBalance": {
                  "baseAmount": 1020000
                },
                "ledger": {
                  "id": "TGVkZ2VyOjY1",
                  "type": "SELLER_PAYABLE",
                  "accountType": "LIABILITY",
                  "balance": {
                    "baseAmount": 1572500
                  }
                }
              },
              {
                "ledgerBalance": {
                  "baseAmount": -2980745
                },
                "ledger": {
                  "id": "TGVkZ2VyOjc=",
                  "type": "MARKETPLACE_COMMISSION",
                  "accountType": "REVENUE",
                  "balance": {
                    "baseAmount": -2997415
                  }
                }
              }
            ]
          }
        },
        {
          "node": {
            "id": "Sm91cm5hbEVudHJ5OjEyODY=",
            "type": "SHIPPING_ACCRUED",
            "description": "Order T3JkZXI6Mjg5Ng== shipping accrued",
            "createdAt": "2024-03-12T13:29:15.692050+00:00",
            "order": {
              "id": "T3JkZXI6Mjg5Ng=="
            },
            "ledgerEntries": [
              {
                "ledgerBalance": {
                  "baseAmount": -266500
                },
                "ledger": {
                  "id": "TGVkZ2VyOjI=",
                  "type": "DEFERRED_SHIPPING_REVENUE",
                  "accountType": "REVENUE",
                  "balance": {
                    "baseAmount": -314000
                  }
                }
              },
              {
                "ledgerBalance": {
                  "baseAmount": -547350
                },
                "ledger": {
                  "id": "TGVkZ2VyOjk=",
                  "type": "MARKETPLACE_FEES",
                  "accountType": "REVENUE",
                  "balance": {
                    "baseAmount": -536950
                  }
                }
              }
            ]
          }
        }
      ]
    }
  }
}

Learn more ->

Voucher data in order webhooks​

The voucher field is now part of all order and nauticalOrder webhook payloads, providing the following voucher data: id, name, type, discountValue, and discountValueType.

Order line metadata in email payloads​

Non-private metadata for orderLines and nauticalOrderLines will now be included in all order-related email payloads. Update your email templates to make use of order line metadata.

Fixed an issue where vouchers created with the option "Specific products" selected caused items to be discounted automatically without entering the voucher code.

Order payouts summary​

Added a new payoutsSummary field on the Order object, providing a quick overview of payout status and amounts for marketplace orders.

Refund ledger tracking​

Refunds are now automatically recorded in financial ledgers, providing better accounting and auditability for order refunds across sellers.

Custom field templates​

Introduced custom field templates for product attributes, allowing you to define reusable attribute configurations and apply them consistently across your catalog.

Date attribute values​

Attribute values can now be resolved as dates, enabling more flexible product data modeling for time-based attributes.

Ledger data backfill​

Added a mutation to backfill historical ledger data, helping ensure financial records are complete for existing orders and refunds.

Product type input simplification​

When creating products, the productType ID is now specified directly in the ProductInput rather than nested in ProductCreateInput, simplifying the mutation structure.

Fixed an issue where cancelled refunds could be double-counted in order totals.

Fixed an issue where refunding cancelled orders would incorrectly adjust sales tax calculations.

Fixed an issue where refunding discounted orders that were later cancelled could result in incorrect ledger entries.

Fixed an issue where applying voucher codes could use invalid vouchers with the same code instead of the active one.

Fixed an issue where the is_visible field could not be updated via mutation.

Fixed an issue where the JournalEntry.refund relationship was not accessible via the API.

Visibility field for collections​

Added the isVisible boolean field to the collection object.

New seller statuses​

Added the following statuses to the SellerStatus enum:

• SUSPENDED
• BANNED
• DEACTIVATED

Customer order count​

Changed customer.numOrders to resolve the total number of marketplace orders instead of seller orders.

Fixed an issue preventing the order refund confirmation and CSV export emails from sending.

Fixed an issue with Stripe webhook processing to handle webhook errors appropriately.

Payout ledger integration​

Payouts are now tracked through the ledger system, providing improved accuracy and transparency. Payout data is now connected to orders, enabling better financial reporting and reconciliation.

Payout fee visibility​

Fees associated with vendor payouts are now exposed in the payout summary, giving sellers clearer insight into their earnings.

Order payout status tracking​

Orders now include a payoutStatus field that reflects the current payout state based on ledger data, making it easier to track which orders have been paid out to sellers.

Available payout balance​

Added availablePayoutBalance to orders, showing the amount that can be paid out to sellers at any given time.

Seller commission tracking​

Orders now include a sellerCommission field that calculates commission amounts directly from ledger data.

Additional seller status options​

Added new seller status options including "Suspended," "Banned," and "Deactivated" to provide more granular control over seller accounts.

Product type cascading deletion​

When deleting a product type where require_product_types is enabled, all associated variants and products are now automatically removed, simplifying product type management.

Collection visibility control​

Collections now include an isVisible field, allowing marketplace operators to control which collections are displayed to customers.

Order fulfillment and cancellation improvements​

Made several improvements to order handling:

• Fulfillment cancellations now update ledgers appropriately to maintain accurate financial records.
• Order cancellations are properly recorded in the ledger system.
• Declining fulfillments now correctly updates ledger entries.
• The system now accurately determines when a seller's portion of an order is completely fulfilled.

Fixed an issue where the nauticalOrderByToken query could allow sellers to access orders that didn't belong to them.

Fixed an issue where digital fulfillment revenue wasn't being accrued correctly in the ledger system.

Fixed an issue where the customer.numOrders field was counting individual seller orders instead of marketplace-level orders.

Fixed an issue with SendGrid email payloads that could cause emails to fail when data wasn't in the correct format.

Webhook event type and timestamp in payload body​

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",

Ledger-based payout system​

Introduced a new ledger-based payout system that provides more accurate financial tracking and reporting. Payouts can now be connected to individual fulfillment lines, enabling more granular commission calculations and financial record-keeping.

Journal entry queries​

Added the ability to query journal entries through the API, providing visibility into financial transaction records for accounting and reconciliation purposes.

Analytics integration for internal testing​

Enabled analytics tracking on emails for internal testing purposes, allowing the team to monitor email performance and engagement.

Enhanced payout validation​

Added validation to prevent multiple draft payouts from being created simultaneously, ensuring data consistency and preventing potential conflicts in the payout workflow.

Fixed several issues to improve system reliability:

• Resolved ledger-related issues discovered during end-to-end testing
• Corrected field definitions for the Ledger API type
• Fixed data mapping issues that could cause inconsistencies
• Resolved fixture file problems affecting development and testing environments