# Transactions API overview

**Current version: 1.0**  
_For versioning details, read the [Versioning](/commerce-apis/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](/commerce-apis/retrieve-all-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](/commerce-apis/orders-overview#payment-plans)).

## Further reading

 * Become familiar with [common commerce terms](/commerce-apis/glossary) and how they're related to the API
 * [Obtain an API key or use OAuth](/commerce-apis/authentication-and-permissions)
 * Read the [FAQ](/commerce-apis/faq) guide for answers to common questions