> ## Documentation Index
> Fetch the complete documentation index at: https://docs.subtotal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Connection Purchases

> Get purchases for a connection using partner OAuth Bearer authentication, or legacy X-API-Key plus a connection access token

[Subtotal Connector tool: list\_connection\_purchases](https://docs.subtotal.com/docs/connector/tools.md#list_connection_purchases)

## Purchase status

Each purchase object in the response includes a `status` field.

<Snippet file="snippets/purchase-status.mdx" />


## OpenAPI

````yaml get /connections/{connection_id}/purchases
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers: []
security: []
paths:
  /connections/{connection_id}/purchases:
    get:
      tags:
        - purchases
      summary: Get Connection Purchases
      description: >-
        Get purchases for a connection using partner OAuth Bearer
        authentication, or legacy X-API-Key plus a connection access token
      operationId: get_connection_purchases_connections__connection_id__purchases_get
      parameters:
        - name: connection_id
          in: path
          required: true
          schema:
            type: string
            title: Connection Id
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 50
            minimum: 1
            description: The maximum number of purchases to return
            examples:
              - 10
            default: 10
            title: Limit
          description: The maximum number of purchases to return
        - name: starting_after
          in: query
          required: false
          schema:
            type: string
            description: >-
              The purchase id of the last purchase you processed. The next
              purchase returned will be the next oldest purchase. An id that
              isn't one of this connection's purchases returns 400.
            examples:
              - 01J51S0JYV6N7K1030CV1ZJH30
            title: Starting After
          description: >-
            The purchase id of the last purchase you processed. The next
            purchase returned will be the next oldest purchase. An id that isn't
            one of this connection's purchases returns 400.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPurchasesResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - PartnerOAuth: []
        - ApiKey: []
          ConnectionToken: []
components:
  schemas:
    GetPurchasesResponse:
      properties:
        has_more:
          type: boolean
          title: Has More
          description: Whether there are more purchases available to fetch
          examples:
            - true
        purchases:
          items:
            $ref: '#/components/schemas/PurchaseSummary'
          type: array
          title: Purchases
          description: >-
            The list of purchases for the connection sorted in descending order
            by purchase date
          examples:
            - - date: '2024-01-01T00:00:00Z'
                purchase_id: 01J51S0JYV6N7K1030CV1ZKSJH
                purchase_type: online
                status: completed
                total: '9.34'
      type: object
      required:
        - has_more
        - purchases
      title: GetPurchasesResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    PurchaseSummary:
      properties:
        purchase_id:
          type: string
          title: Purchase Id
          description: The unique identifier for the purchase
          examples:
            - 01J51S0JYV6N7K1030CV1ZKSCF
        date:
          type: string
          title: Date
          description: The date and time of the purchase
          examples:
            - '2024-01-01T00:00:00Z'
        total:
          type: string
          pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Total
          description: The total amount of the purchase
          examples:
            - '9.34'
        purchase_type:
          anyOf:
            - $ref: '#/components/schemas/PurchaseType'
            - type: 'null'
          description: >-
            The purchase type: 'in_store', 'online', 'delivery', 'pickup' or
            'return'. Null when unknown.
          examples:
            - online
        status:
          anyOf:
            - $ref: '#/components/schemas/PurchaseStatus'
            - type: 'null'
          description: >-
            The purchase status the retailer last showed: 'pending', 'shipped',
            'ready_for_pickup', 'completed' or 'cancelled'. Null when never
            observed.
          examples:
            - completed
      type: object
      required:
        - purchase_id
        - date
        - total
      title: PurchaseSummary
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    PurchaseType:
      type: string
      enum:
        - online
        - in_store
        - delivery
        - pickup
        - return
      title: PurchaseType
      description: How the purchase reached the shopper; NULL = no signal.
    PurchaseStatus:
      type: string
      enum:
        - pending
        - shipped
        - ready_for_pickup
        - completed
        - cancelled
      title: PurchaseStatus
      description: The purchase status the retailer last showed; NULL = never observed.
  securitySchemes:
    PartnerOAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Partner OAuth: send `Authorization: Bearer <access_token>`, an OAuth
        access token from Subtotal's authorization server with the scope this
        endpoint needs.
    ApiKey:
      type: apiKey
      in: header
      name: X-Api-Key
      description: 'API key: your Subtotal API key.'
    ConnectionToken:
      type: http
      scheme: bearer
      description: >-
        Connection token: send `Authorization: Bearer <connection_token>`
        together with `X-Api-Key`. Get the token from `POST
        /connections/{connection_id}/token`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.