Copy page

Transactions API overview

Current version: 1.0
For versioning details, read the Versioning guide.

Use the Transactions API to access financial transactions for orders and donations made on a Squarespace merchant site.

Payment gateways and processing errors

Transactions from a merchant site occur through a payment gateway. The Transactions API supports the following payment gateways: SQUARESPACE, STRIPE, PAYPAL, and SQUARE.

Payment gateway processing errors are logged by the Transactions API as one of the following:

GATEWAY_FEE_PROCEESING_ERROR An error occurred while retrieving payment processing fees; contact the payment gateway for more details.

GATEWAY_API_PERMISSION_ERROR The payment gateway has not granted Squarespace API access. Payment gateway needs to reconfigure API permission.

GATEWAY_DISCONNNECTED The payment gateway credentials configured for the site have expired or are missing; a connection to the payment gateway could not be established.

What information isn't available?

• Order or donation details unrelated to payments, such as product information, merchant notes, and form data
• Refunds initiated outside of Squarespace, e.g. via Stripe

API resources

The Transactions API returns Document resource objects. A Document is a collection of transactions for an order or a donation. There's a 1:1 relationship between a Document and an order or donation.

Document resources include information like:

• Totals for an order or a donation, summing item sales, discounts, fees, shipping, taxes, and the grand total
• Payments and payment types
• Refunds
• Payment gateway errors

Note: Only refunds initiated through Squarespace are captured and made available through the Transactions API.

Resource fields are described under Response example for each Transactions API endpoint.

Fetching transactions for a specific order

The retrieve transactions endpoint accepts an optional orderId query parameter to fetch the Document for a specific order without paging through the full collection. This is useful for reconciliation workflows and for any case where the order ID is already known.

Payment Plans

For orders placed using Payment Plans (an initial deposit followed by a series of installments collected on a schedule), the payments array on the Document grows over time as each installment is collected. The deposit appears as the first entry in payments; each subsequent installment is appended when it is successfully captured.

A few things to keep in mind when working with Payment Plan orders:

• payments only contains what has already been collected. A Payment Plan order with a deposit and one collected installment will have two entries in payments, even if more installments are still scheduled. Future-scheduled installments are not exposed on the public Transactions API (they live on the merchant's Orders panel).
• Each TransactionPayment has its own paidOn, amount, and refund state. You can use this to reconstruct the timeline of when the order has been paid.
• Refunds can be issued per individual payment. Refund detail is recorded under the relevant TransactionPayment.refunds array, so a partially refunded Payment Plan order will show refunds attached to specific installments.
• For the overall payment status of the parent order (paid, partially paid, refunded, etc.), use the paymentState field on the Order resource (see the Orders API overview).

Further reading

• Become familiar with common commerce terms and how they're related to the API
• Obtain an API key or use OAuth
• Read the FAQ guide for answers to common questions