Squarespace Transactions API

openapi: 3.1.0
info:
  title: Squarespace Transactions API
  description: >-
    The Squarespace Transactions API returns Document resource objects representing
    collections of financial transactions for orders and donations on a merchant
    site. It provides detailed payment data and supports multiple payment gateways
    including Squarespace Payments, Stripe, PayPal, and Square. The API is useful
    for building financial reporting tools, reconciliation workflows, and accounting
    integrations. Access requires a Commerce Basic, Commerce Advanced, or higher
    Squarespace plan.
  version: '1.0'
  contact:
    name: Squarespace Developer Support
    url: https://developers.squarespace.com/commerce-apis/transactions-overview
  termsOfService: https://www.squarespace.com/terms-of-service
externalDocs:
  description: Squarespace Transactions API Documentation
  url: https://developers.squarespace.com/commerce-apis/transactions-overview
servers:
  - url: https://api.squarespace.com/1.0
    description: Production Server
tags:
  - name: Transactions
    description: Financial transaction retrieval for orders and donations
security:
  - bearerAuth: []
paths:
  /commerce/transactions:
    get:
      operationId: listTransactions
      summary: Retrieve All Transactions
      description: >-
        Returns a paginated list of financial transaction documents for all orders
        and donations on the merchant site. Supports filtering by transaction date
        range. By default returns up to 50 transaction documents per page. Use the
        cursor parameter from a previous response to paginate through all results.
        Each document groups the financial details for a single order or donation.
      tags:
        - Transactions
      parameters:
        - $ref: '#/components/parameters/cursor'
        - name: modifiedAfter
          in: query
          description: >-
            ISO 8601 UTC date-time string. Only returns transactions modified after
            this date and time.
          required: false
          schema:
            type: string
            format: date-time
        - name: modifiedBefore
          in: query
          description: >-
            ISO 8601 UTC date-time string. Only returns transactions modified before
            this date and time.
          required: false
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: Successful response with paginated list of transaction documents
          content:
            application/json:
              schema:
                type: object
                properties:
                  documents:
                    type: array
                    items:
                      $ref: '#/components/schemas/TransactionDocument'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /commerce/transactions/{transactionIds}:
    get:
      operationId: getTransactions
      summary: Retrieve Specific Transactions
      description: >-
        Retrieves financial transaction documents for one or more specific orders
        or donations by their transaction document IDs. IDs should be provided as
        a comma-separated list in the path. Returns detailed payment information
        including gateway data, totals, and individual transaction line entries.
      tags:
        - Transactions
      parameters:
        - $ref: '#/components/parameters/transactionIds'
      responses:
        '200':
          description: Successful response with the requested transaction documents
          content:
            application/json:
              schema:
                type: object
                properties:
                  documents:
                    type: array
                    items:
                      $ref: '#/components/schemas/TransactionDocument'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Authenticate using an API key or OAuth access token. Include the token
        in the Authorization header as "Bearer YOUR_TOKEN".
  responses:
    BadRequest:
      description: The request was malformed or contained invalid parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication credentials are missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: The authenticated user does not have permission to access this resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    cursor:
      name: cursor
      in: query
      description: >-
        Pagination cursor from a previous response's pagination.nextPageCursor field.
        Omit or leave empty to retrieve the first page.
      required: false
      schema:
        type: string
    transactionIds:
      name: transactionIds
      in: path
      description: Comma-separated list of transaction document IDs to retrieve
      required: true
      schema:
        type: string
  schemas:
    TransactionDocument:
      type: object
      description: >-
        A document grouping financial transaction details for a single order or
        donation. Contains payment gateway information and line-level financial data.
      properties:
        id:
          type: string
          description: Unique identifier for the transaction document
        createdOn:
          type: string
          format: date-time
          description: ISO 8601 UTC timestamp when the transaction document was created
        modifiedOn:
          type: string
          format: date-time
          description: ISO 8601 UTC timestamp when the document was last modified
        totalSales:
          $ref: '#/components/schemas/Money'
        totalNetPayment:
          $ref: '#/components/schemas/Money'
        payments:
          type: array
          description: List of individual payment records associated with this document
          items:
            $ref: '#/components/schemas/Payment'
        lineItems:
          type: array
          description: Financial line items for the order or donation
          items:
            $ref: '#/components/schemas/TransactionLineItem'
        orderDocumentType:
          type: string
          description: The type of commerce activity this document represents
          enum:
            - ORDER
            - DONATION
    Payment:
      type: object
      description: A single payment record including gateway and amount information
      properties:
        id:
          type: string
          description: Unique identifier for the payment record
        paymentGateway:
          type: string
          description: Name of the payment gateway that processed this payment
          enum:
            - SQUARESPACE
            - STRIPE
            - PAYPAL
            - SQUARE
        creditCardType:
          type: string
          description: Type of credit card used for the payment, if applicable
        amount:
          $ref: '#/components/schemas/Money'
        refundedAmount:
          $ref: '#/components/schemas/Money'
        externalTransactionId:
          type: string
          description: Transaction identifier from the payment gateway's system
        createdOn:
          type: string
          format: date-time
          description: ISO 8601 UTC timestamp when the payment was recorded
    TransactionLineItem:
      type: object
      description: A financial line item within a transaction document
      properties:
        id:
          type: string
          description: Unique identifier for the transaction line item
        lineItemType:
          type: string
          description: Classification of this financial line item
          enum:
            - PRODUCT
            - SHIPPING
            - TAX
            - DISCOUNT
            - TIP
        amount:
          $ref: '#/components/schemas/Money'
        taxName:
          type: string
          description: Name of the tax applied, if this is a tax line item
        taxRate:
          type: string
          description: Tax rate as a decimal string, if this is a tax line item
    Money:
      type: object
      description: A monetary value with currency
      properties:
        value:
          type: string
          description: Decimal string representation of the monetary amount
          pattern: '^-?\d+(\.\d+)?$'
        currency:
          type: string
          description: ISO 4217 three-letter currency code
          pattern: '^[A-Z]{3}$'
    Pagination:
      type: object
      description: Pagination metadata included with list responses
      properties:
        hasNextPage:
          type: boolean
          description: Indicates whether additional pages of results are available
        nextPageCursor:
          type: string
          description: Cursor value to pass in the next request to retrieve the next page
        nextPageUrl:
          type: string
          format: uri
          description: Full URL for retrieving the next page of results
    Error:
      type: object
      description: Standard error response returned by the Squarespace API
      properties:
        type:
          type: string
          description: Machine-readable error type identifier
        subtype:
          type: string
          description: Optional more specific error subtype
        message:
          type: string
          description: Human-readable description of the error
        statusCode:
          type: integer
          description: HTTP status code associated with the error