Square
Square Subscriptions API

The Subscriptions API from Square — 11 operation(s) for subscriptions.
Documentation GitHub OpenAPI
OpenAPI Specification

openapi: 3.0.0
info:
  version: '2.0'
  title: Square ApplePay Subscriptions API
  description: 'Supercharge Square for sellers of every size. Our entire connected commerce platform  from elegant hardware to a rich suite of Square APIs  is yours to build with. Whether youre developing an app or composing a bespoke solution, this is the place to make it happen. '
  termsOfService: https://connect.squareup.com/tos
  contact:
    name: Square Developer Platform
    email: developers@squareup.com
    url: https://squareup.com/developers
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  externalDocs:
    description: 'Read the official documentation here:'
    url: https://docs.connect.squareup.com/
  x-server-configuration:
    default-environment: production
    default-server: default
    environments:
    - name: production
      servers:
      - name: default
        url: https://connect.squareup.com
    - name: sandbox
      servers:
      - name: default
        url: https://connect.squareupsandbox.com
    - name: custom
      servers:
      - name: default
        url: '{custom_url}'
    parameters:
    - name: custom_url
      description: Sets the base URL requests are made to. Defaults to `https://connect.squareup.com`
      type: string
      example: https://connect.squareup.com
  x-square-generic-error-codes:
  - ACCESS_TOKEN_EXPIRED
  - ACCESS_TOKEN_REVOKED
  - API_VERSION_INCOMPATIBLE
  - APPLICATION_DISABLED
  - ARRAY_EMPTY
  - ARRAY_LENGTH_TOO_LONG
  - ARRAY_LENGTH_TOO_SHORT
  - BAD_CERTIFICATE
  - BAD_GATEWAY
  - BAD_REQUEST
  - CONFLICT
  - CONFLICTING_PARAMETERS
  - CURRENCY_MISMATCH
  - EXPECTED_ARRAY
  - EXPECTED_BASE64_ENCODED_BYTE_ARRAY
  - EXPECTED_BOOLEAN
  - EXPECTED_FLOAT
  - EXPECTED_INTEGER
  - EXPECTED_JSON_BODY
  - EXPECTED_MAP
  - EXPECTED_OBJECT
  - EXPECTED_STRING
  - FORBIDDEN
  - GATEWAY_TIMEOUT
  - GONE
  - IDEMPOTENCY_KEY_REUSED
  - INCORRECT_TYPE
  - INSUFFICIENT_SCOPES
  - INTERNAL_SERVER_ERROR
  - INVALID_ARRAY_VALUE
  - INVALID_CONTENT_TYPE
  - INVALID_CURSOR
  - INVALID_ENUM_VALUE
  - INVALID_FORM_VALUE
  - INVALID_SORT_ORDER
  - INVALID_SQUARE_VERSION_FORMAT
  - INVALID_TIME
  - INVALID_TIME_RANGE
  - INVALID_VALUE
  - LOCATION_MISMATCH
  - MAP_KEY_LENGTH_TOO_LONG
  - MAP_KEY_LENGTH_TOO_SHORT
  - MERCHANT_SUBSCRIPTION_NOT_FOUND
  - METHOD_NOT_ALLOWED
  - MISSING_REQUIRED_PARAMETER
  - NOT_ACCEPTABLE
  - NOT_FOUND
  - NOT_IMPLEMENTED
  - NO_FIELDS_SET
  - RATE_LIMITED
  - REQUEST_ENTITY_TOO_LARGE
  - REQUEST_TIMEOUT
  - SANDBOX_NOT_SUPPORTED
  - SERVICE_UNAVAILABLE
  - TOO_MANY_MAP_ENTRIES
  - UNAUTHORIZED
  - UNEXPECTED_VALUE
  - UNKNOWN_BODY_PARAMETER
  - UNKNOWN_QUERY_PARAMETER
  - UNPROCESSABLE_ENTITY
  - UNSUPPORTED_MEDIA_TYPE
  - V1_ACCESS_TOKEN
  - V1_APPLICATION
  - VALUE_EMPTY
  - VALUE_REGEX_MISMATCH
  - VALUE_TOO_HIGH
  - VALUE_TOO_LONG
  - VALUE_TOO_LOW
  - VALUE_TOO_SHORT
servers:
- url: https://connect.squareup.com
  variables: {}
tags:
- name: Subscriptions
paths:
  /v2/subscriptions:
    post:
      tags:
      - Subscriptions
      summary: Square Create Subscription
      operationId: CreateSubscription
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      description: 'Enrolls a customer in a subscription.


        If you provide a card on file in the request, Square charges the card for

        the subscription. Otherwise, Square sends an invoice to the customer''s email

        address. The subscription starts immediately, unless the request includes

        the optional `start_date`. Each individual subscription is associated with a particular location.


        For more information, see [Create a subscription](https://developer.squareup.com/docs/subscriptions-api/manage-subscriptions#create-a-subscription).'
      x-release-status: PUBLIC
      security:
      - oauth2:
        - CUSTOMERS_READ
        - PAYMENTS_WRITE
        - SUBSCRIPTIONS_WRITE
        - ITEMS_READ
        - ORDERS_WRITE
        - INVOICES_WRITE
      parameters: []
      requestBody:
        required: true
        description: 'An object containing the fields to POST for the request.


          See the corresponding object definition for field details.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSubscriptionRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSubscriptionResponse'
      x-endpoint-errors:
      - error-code: CARD_PROCESSING_NOT_ENABLED
      - error-code: CUSTOMER_MISSING_EMAIL
      - error-code: CUSTOMER_MISSING_NAME
      - error-code: CUSTOMER_NOT_FOUND
      - error-code: INVALID_CARD
      - error-code: INVALID_DATE
  /v2/subscriptions/bulk-swap-plan:
    post:
      tags:
      - Subscriptions
      summary: Square Bulk Swap Plan
      operationId: BulkSwapPlan
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      description: 'Schedules a plan variation change for all active subscriptions under a given plan

        variation. For more information, see [Swap Subscription Plan Variations](https://developer.squareup.com/docs/subscriptions-api/swap-plan-variations).'
      x-release-status: BETA
      security:
      - oauth2:
        - SUBSCRIPTIONS_WRITE
        - SUBSCRIPTIONS_READ
        - ITEMS_READ
      parameters: []
      requestBody:
        required: true
        description: 'An object containing the fields to POST for the request.


          See the corresponding object definition for field details.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkSwapPlanRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkSwapPlanResponse'
      x-endpoint-errors:
      - error-code: CARD_PROCESSING_NOT_ENABLED
      - error-code: CUSTOMER_NOT_FOUND
  /v2/subscriptions/search:
    post:
      tags:
      - Subscriptions
      summary: Square Search Subscriptions
      operationId: SearchSubscriptions
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      description: 'Searches for subscriptions.


        Results are ordered chronologically by subscription creation date. If

        the request specifies more than one location ID,

        the endpoint orders the result

        by location ID, and then by creation date within each location. If no locations are given

        in the query, all locations are searched.


        You can also optionally specify `customer_ids` to search by customer.

        If left unset, all customers

        associated with the specified locations are returned.

        If the request specifies customer IDs, the endpoint orders results

        first by location, within location by customer ID, and within

        customer by subscription creation date.'
      x-release-status: PUBLIC
      security:
      - oauth2:
        - SUBSCRIPTIONS_READ
      parameters: []
      requestBody:
        required: true
        description: 'An object containing the fields to POST for the request.


          See the corresponding object definition for field details.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchSubscriptionsRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchSubscriptionsResponse'
      x-endpoint-errors:
      - error-code: CUSTOMER_NOT_FOUND
  /v2/subscriptions/{subscription_id}:
    get:
      tags:
      - Subscriptions
      summary: Square Retrieve Subscription
      operationId: RetrieveSubscription
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      description: Retrieves a specific subscription.
      x-release-status: PUBLIC
      security:
      - oauth2:
        - SUBSCRIPTIONS_READ
      parameters:
      - name: subscription_id
        description: The ID of the subscription to retrieve.
        schema:
          type: string
        in: path
        required: true
      - name: include
        description: "A query parameter to specify related information to be included in the response. \n\nThe supported query parameter values are: \n\n- `actions`: to include scheduled actions on the targeted subscription."
        schema:
          type: string
        in: query
        required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveSubscriptionResponse'
    put:
      tags:
      - Subscriptions
      summary: Square Update Subscription
      operationId: UpdateSubscription
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      description: 'Updates a subscription by modifying or clearing `subscription` field values.

        To clear a field, set its value to `null`.'
      x-release-status: PUBLIC
      security:
      - oauth2:
        - CUSTOMERS_READ
        - PAYMENTS_WRITE
        - SUBSCRIPTIONS_WRITE
        - ITEMS_READ
        - ORDERS_WRITE
        - INVOICES_WRITE
      parameters:
      - name: subscription_id
        description: The ID of the subscription to update.
        schema:
          type: string
        in: path
        required: true
      requestBody:
        required: true
        description: 'An object containing the fields to POST for the request.


          See the corresponding object definition for field details.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSubscriptionRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateSubscriptionResponse'
      x-endpoint-errors:
      - error-code: CUSTOMER_NOT_FOUND
      - error-code: INVALID_CARD
  /v2/subscriptions/{subscription_id}/actions/{action_id}:
    delete:
      tags:
      - Subscriptions
      summary: Square Delete Subscription Action
      operationId: DeleteSubscriptionAction
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      description: Deletes a scheduled action for a subscription.
      x-release-status: BETA
      security:
      - oauth2:
        - SUBSCRIPTIONS_WRITE
      parameters:
      - name: subscription_id
        description: The ID of the subscription the targeted action is to act upon.
        schema:
          type: string
        in: path
        required: true
      - name: action_id
        description: The ID of the targeted action to be deleted.
        schema:
          type: string
        in: path
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteSubscriptionActionResponse'
  /v2/subscriptions/{subscription_id}/billing-anchor:
    post:
      tags:
      - Subscriptions
      summary: Square Change Billing Anchor Date
      operationId: ChangeBillingAnchorDate
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      description: 'Changes the [billing anchor date](https://developer.squareup.com/docs/subscriptions-api/subscription-billing#billing-dates)

        for a subscription.'
      x-release-status: BETA
      security:
      - oauth2:
        - SUBSCRIPTIONS_WRITE
        - SUBSCRIPTIONS_READ
        - ITEMS_READ
      parameters:
      - name: subscription_id
        description: The ID of the subscription to update the billing anchor date.
        schema:
          type: string
        in: path
        required: true
      requestBody:
        required: true
        description: 'An object containing the fields to POST for the request.


          See the corresponding object definition for field details.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangeBillingAnchorDateRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChangeBillingAnchorDateResponse'
  /v2/subscriptions/{subscription_id}/cancel:
    post:
      tags:
      - Subscriptions
      summary: Square Cancel Subscription
      operationId: CancelSubscription
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      description: "Schedules a `CANCEL` action to cancel an active subscription. This \nsets the `canceled_date` field to the end of the active billing period. After this date, \nthe subscription status changes from ACTIVE to CANCELED."
      x-release-status: PUBLIC
      security:
      - oauth2:
        - SUBSCRIPTIONS_WRITE
      parameters:
      - name: subscription_id
        description: The ID of the subscription to cancel.
        schema:
          type: string
        in: path
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelSubscriptionResponse'
  /v2/subscriptions/{subscription_id}/events:
    get:
      tags:
      - Subscriptions
      summary: Square List Subscription Events
      operationId: ListSubscriptionEvents
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      description: Lists all [events](https://developer.squareup.com/docs/subscriptions-api/actions-events) for a specific subscription.
      x-release-status: PUBLIC
      security:
      - oauth2:
        - SUBSCRIPTIONS_READ
      parameters:
      - name: subscription_id
        description: The ID of the subscription to retrieve the events for.
        schema:
          type: string
        in: path
        required: true
      - name: cursor
        description: "When the total number of resulting subscription events exceeds the limit of a paged response, \nspecify the cursor returned from a preceding response here to fetch the next set of results.\nIf the cursor is unset, the response contains the last page of the results.\n\nFor more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)."
        schema:
          type: string
        in: query
        required: false
      - name: limit
        description: 'The upper limit on the number of subscription events to return

          in a paged response.'
        schema:
          type: integer
        in: query
        required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSubscriptionEventsResponse'
  /v2/subscriptions/{subscription_id}/pause:
    post:
      tags:
      - Subscriptions
      summary: Square Pause Subscription
      operationId: PauseSubscription
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      description: Schedules a `PAUSE` action to pause an active subscription.
      x-release-status: BETA
      security:
      - oauth2:
        - CUSTOMERS_READ
        - PAYMENTS_WRITE
        - SUBSCRIPTIONS_WRITE
        - ITEMS_READ
        - ORDERS_WRITE
        - INVOICES_WRITE
      parameters:
      - name: subscription_id
        description: The ID of the subscription to pause.
        schema:
          type: string
        in: path
        required: true
      requestBody:
        required: true
        description: 'An object containing the fields to POST for the request.


          See the corresponding object definition for field details.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PauseSubscriptionRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PauseSubscriptionResponse'
      x-endpoint-errors:
      - error-code: CARD_PROCESSING_NOT_ENABLED
      - error-code: CUSTOMER_NOT_FOUND
      - error-code: INVALID_PAUSE_LENGTH
      - error-code: INVALID_DATE
  /v2/subscriptions/{subscription_id}/resume:
    post:
      tags:
      - Subscriptions
      summary: Square Resume Subscription
      operationId: ResumeSubscription
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      description: Schedules a `RESUME` action to resume a paused or a deactivated subscription.
      x-release-status: PUBLIC
      security:
      - oauth2:
        - CUSTOMERS_READ
        - PAYMENTS_WRITE
        - SUBSCRIPTIONS_WRITE
        - ITEMS_READ
        - ORDERS_WRITE
        - INVOICES_WRITE
      parameters:
      - name: subscription_id
        description: The ID of the subscription to resume.
        schema:
          type: string
        in: path
        required: true
      requestBody:
        required: true
        description: 'An object containing the fields to POST for the request.


          See the corresponding object definition for field details.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResumeSubscriptionRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResumeSubscriptionResponse'
      x-endpoint-errors:
      - error-code: CARD_PROCESSING_NOT_ENABLED
      - error-code: CUSTOMER_MISSING_EMAIL
      - error-code: CUSTOMER_MISSING_NAME
      - error-code: CUSTOMER_NOT_FOUND
      - error-code: INVALID_CARD
      - error-code: INVALID_DATE
  /v2/subscriptions/{subscription_id}/swap-plan:
    post:
      tags:
      - Subscriptions
      summary: Square Swap Plan
      operationId: SwapPlan
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      description: "Schedules a `SWAP_PLAN` action to swap a subscription plan variation in an existing subscription. \nFor more information, see [Swap Subscription Plan Variations](https://developer.squareup.com/docs/subscriptions-api/swap-plan-variations)."
      x-release-status: BETA
      security:
      - oauth2:
        - CUSTOMERS_READ
        - PAYMENTS_WRITE
        - SUBSCRIPTIONS_WRITE
        - ITEMS_READ
        - ORDERS_WRITE
        - INVOICES_WRITE
      parameters:
      - name: subscription_id
        description: The ID of the subscription to swap the subscription plan for.
        schema:
          type: string
        in: path
        required: true
      requestBody:
        required: true
        description: 'An object containing the fields to POST for the request.


          See the corresponding object definition for field details.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SwapPlanRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SwapPlanResponse'
      x-endpoint-errors:
      - error-code: CARD_PROCESSING_NOT_ENABLED
      - error-code: CUSTOMER_NOT_FOUND
components:
  schemas:
    CancelSubscriptionResponse:
      type: object
      description: "Defines output parameters in a response from the \n[CancelSubscription](api-endpoint:Subscriptions-CancelSubscription) endpoint."
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Errors encountered during the request.
        subscription:
          $ref: '#/components/schemas/Subscription'
          description: The specified subscription scheduled for cancellation according to the action created by the request.
        actions:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionAction'
          description: A list of a single `CANCEL` action scheduled for the subscription.
          x-release-status: BETA
      example:
        subscription:
          canceled_date: '2023-06-05'
          card_id: ccof:qy5x8hHGYsgLrp4Q4GB
          created_at: '2022-01-19T21:53:10Z'
          customer_id: CHFGVKYY8RSV93M5KCYTG4PN0G
          id: 910afd30-464a-4e00-a8d8-2296e
          invoice_ids:
          - inv:0-ChCHu2mZEabLeeHahQnXDjZQECY
          - inv:0-ChrcX_i3sNmfsHTGKhI4Wg2mceA
          location_id: S8GWD5R9QB376
          paid_until_date: '2023-12-31'
          plan_variation_id: 6JHXF3B2CW3YKHDV4XEM674H
          source:
            name: My Application
          start_date: '2022-01-19'
          status: ACTIVE
          timezone: America/Los_Angeles
          version: 3
    ErrorCategory:
      type: string
      enum:
      - API_ERROR
      - AUTHENTICATION_ERROR
      - INVALID_REQUEST_ERROR
      - RATE_LIMIT_ERROR
      - PAYMENT_METHOD_ERROR
      - REFUND_ERROR
      - MERCHANT_SUBSCRIPTION_ERROR
      - EXTERNAL_VENDOR_ERROR
      x-enum-elements:
      - name: API_ERROR
        description: An error occurred with the Connect API itself.
      - name: AUTHENTICATION_ERROR
        description: 'An authentication error occurred. Most commonly, the request had

          a missing, malformed, or otherwise invalid `Authorization` header.'
      - name: INVALID_REQUEST_ERROR
        description: 'The request was invalid. Most commonly, a required parameter was

          missing, or a provided parameter had an invalid value.'
      - name: RATE_LIMIT_ERROR
        description: 'Your application reached the Square API rate limit. You might receive this error if your application sends a high number of requests

          to Square APIs in a short period of time.


          Your application should monitor responses for `429 RATE_LIMITED` errors and use a retry mechanism with an [exponential backoff](https://en.wikipedia.org/wiki/Exponential_backoff)

          schedule to resend the requests at an increasingly slower rate. It is also a good practice to use a randomized delay (jitter) in your retry schedule.'
      - name: PAYMENT_METHOD_ERROR
        description: 'An error occurred while processing a payment method. Most commonly,

          the details of the payment method were invalid (such as a card''s CVV

          or expiration date).'
      - name: REFUND_ERROR
        description: An error occurred while attempting to process a refund.
      - name: MERCHANT_SUBSCRIPTION_ERROR
        description: An error occurred when checking a merchant subscription status
      - name: EXTERNAL_VENDOR_ERROR
        description: An error that is returned from an external vendor's API
      description: 'Indicates which high-level category of error has occurred during a

        request to the Connect API.'
      x-release-status: PUBLIC
    ErrorCode:
      type: string
      enum:
      - INTERNAL_SERVER_ERROR
      - UNAUTHORIZED
      - ACCESS_TOKEN_EXPIRED
      - ACCESS_TOKEN_REVOKED
      - CLIENT_DISABLED
      - FORBIDDEN
      - INSUFFICIENT_SCOPES
      - APPLICATION_DISABLED
      - V1_APPLICATION
      - V1_ACCESS_TOKEN
      - CARD_PROCESSING_NOT_ENABLED
      - MERCHANT_SUBSCRIPTION_NOT_FOUND
      - BAD_REQUEST
      - MISSING_REQUIRED_PARAMETER
      - INCORRECT_TYPE
      - INVALID_TIME
      - INVALID_TIME_RANGE
      - INVALID_VALUE
      - INVALID_CURSOR
      - UNKNOWN_QUERY_PARAMETER
      - CONFLICTING_PARAMETERS
      - EXPECTED_JSON_BODY
      - INVALID_SORT_ORDER
      - VALUE_REGEX_MISMATCH
      - VALUE_TOO_SHORT
      - VALUE_TOO_LONG
      - VALUE_TOO_LOW
      - VALUE_TOO_HIGH
      - VALUE_EMPTY
      - ARRAY_LENGTH_TOO_LONG
      - ARRAY_LENGTH_TOO_SHORT
      - ARRAY_EMPTY
      - EXPECTED_BOOLEAN
      - EXPECTED_INTEGER
      - EXPECTED_FLOAT
      - EXPECTED_STRING
      - EXPECTED_OBJECT
      - EXPECTED_ARRAY
      - EXPECTED_MAP
      - EXPECTED_BASE64_ENCODED_BYTE_ARRAY
      - INVALID_ARRAY_VALUE
      - INVALID_ENUM_VALUE
      - INVALID_CONTENT_TYPE
      - INVALID_FORM_VALUE
      - CUSTOMER_NOT_FOUND
      - ONE_INSTRUMENT_EXPECTED
      - NO_FIELDS_SET
      - TOO_MANY_MAP_ENTRIES
      - MAP_KEY_LENGTH_TOO_SHORT
      - MAP_KEY_LENGTH_TOO_LONG
      - CUSTOMER_MISSING_NAME
      - CUSTOMER_MISSING_EMAIL
      - INVALID_PAUSE_LENGTH
      - INVALID_DATE
      - UNSUPPORTED_COUNTRY
      - UNSUPPORTED_CURRENCY
      - APPLE_TTP_PIN_TOKEN
      - CARD_EXPIRED
      - INVALID_EXPIRATION
      - INVALID_EXPIRATION_YEAR
      - INVALID_EXPIRATION_DATE
      - UNSUPPORTED_CARD_BRAND
      - UNSUPPORTED_ENTRY_METHOD
      - INVALID_ENCRYPTED_CARD
      - INVALID_CARD
      - PAYMENT_AMOUNT_MISMATCH
      - GENERIC_DECLINE
      - CVV_FAILURE
      - ADDRESS_VERIFICATION_FAILURE
      - INVALID_ACCOUNT
      - CURRENCY_MISMATCH
      - INSUFFICIENT_FUNDS
      - INSUFFICIENT_PERMISSIONS
      - CARDHOLDER_INSUFFICIENT_PERMISSIONS
      - INVALID_LOCATION
      - TRANSACTION_LIMIT
      - VOICE_FAILURE
      - PAN_FAILURE
      - EXPIRATION_FAILURE
      - CARD_NOT_SUPPORTED
      - INVALID_PIN
      - MISSING_PIN
      - MISSING_ACCOUNT_TYPE
      - INVALID_POSTAL_CODE
      - INVALID_FEES
      - MANUALLY_ENTERED_PAYMENT_NOT_SUPPORTED
      - PAYMENT_LIMIT_EXCEEDED
      - GIFT_CARD_AVAILABLE_AMOUNT
      - ACCOUNT_UNUSABLE
      - BUYER_REFUSED_PAYMENT
      - DELAYED_TRANSACTION_EXPIRED
      - DELAYED_TRANSACTION_CANCELED
      - DELAYED_TRANSACTION_CAPTURED
      - DELAYED_TRANSACTION_FAILED
      - CARD_TOKEN_EXPIRED
      - CARD_TOKEN_USED
      - AMOUNT_TOO_HIGH
      - UNSUPPORTED_INSTRUMENT_TYPE
      - REFUND_AMOUNT_INVALID
      - REFUND_ALREADY_PENDING
      - PAYMENT_NOT_REFUNDABLE
      - PAYMENT_NOT_REFUNDABLE_DUE_TO_DISPUTE
      - REFUND_DECLINED
      - INSUFFICIENT_PERMISSIONS_FOR_REFUND
      - INVALID_CARD_DATA
      - SOURCE_USED
      - SOURCE_EXPIRED
      - UNSUPPORTED_LOYALTY_REWARD_TIER
      - LOCATION_MISMATCH
      - IDEMPOTENCY_KEY_REUSED
      - UNEXPECTED_VALUE
      - SANDBOX_NOT_SUPPORTED
      - INVALID_EMAIL_ADDRESS
      - INVALID_PHONE_NUMBER
      - CHECKOUT_EXPIRED
      - BAD_CERTIFICATE
      - INVALID_SQUARE_VERSION_FORMAT
      - API_VERSION_INCOMPATIBLE
      - CARD_PRESENCE_REQUIRED
      - UNSUPPORTED_SOURCE_TYPE
      - CARD_MISMATCH
      - PLAID_ERROR
      - PLAID_ERROR_ITEM_LOGIN_REQUIRED
      - PLAID_ERROR_RATE_LIMIT
      - CARD_DECLINED
      - VERIFY_CVV_FAILURE
      - VERIFY_AVS_FAILURE
      - CARD_DECLINED_CALL_ISSUER
      - CARD_DECLINED_VERIFICATION_REQUIRED
      - BAD_EXPIRATION
      - CHIP_INSERTION_REQUIRED
      - ALLOWABLE_PIN_TRIES_EXCEEDED
      - RESERVATION_DECLINED
      - UNKNOWN_BODY_PARAMETER
      - NOT_FOUND
      - APPLE_PAYMENT_PROCESSING_CERTIFICATE_HASH_NOT_FOUND
      - METHOD_NOT_ALLOWED
      - NOT_ACCEPTABLE
      - REQUEST_TIMEOUT
      - CONFLICT
      - GONE
      - REQUEST_ENTITY_TOO_LARGE
      - UNSUPPORTED_MEDIA_TYPE
      - UNPROCESSABLE_ENTITY
      - RATE_LIMITED
      - NOT_IMPLEMENTED
      - BAD_GATEWAY
      - SERVICE_UNAVAILABLE
      - TEMPORARY_ERROR
      - GATEWAY_TIMEOUT
      x-enum-elements:
      - name: INTERNAL_SERVER_ERROR
        description: A general server error occurred.
        error-category: API_ERROR
      - name: UNAUTHORIZED
        description: A general authorization error occurred.
        error-category: AUTHENTICATION_ERROR
      - name: ACCESS_TOKEN_EXPIRED
        description: The provided access token has expired.
        error-category: AUTHENTICATION_ERROR
      - name: ACCESS_TOKEN_REVOKED
        description: The provided access token has been revoked.
        error-category: AUTHENTICATION_ERROR
      - name: CLIENT_DISABLED
        description: The provided client has been disabled.
        error-category: AUTHENTICATION_ERROR
      - name: FORBIDDEN
        description: A general access error occurred.
        error-category: AUTHENTICATION_ERROR
      - name: INSUFFICIENT_SCOPES
        description: 'The provided access token does not have permission

          to execute the requested action.'
        error-category: AUTHENTICATION_ERROR
      - name: APPLICATION_DISABLED
        description: The calling application was disabled.
        error-category: INVALID_REQUEST_ERROR
      - name: V1_APPLICATION
        description: 'The calling application was created prior to

          2016-03-30 and is not compatible with v2 Square API calls.'
        error-category: INVALID_REQUEST_ERROR
      - name: V1_ACCESS_TOKEN
        description: 'The calling application is using an access token

          created prior to 2016-03-30 and is not compatible with v2 Square API

          calls.'
        error-category: INVALID_REQUEST_ERROR
      - name: CARD_PROCESSING_NOT_ENABLED
        description: 'The location provided in the API call is not

          enabled for credit card processing.'
        error-category: INVALID_REQUEST_ERROR
      - name: MERCHANT_SUBSCRIPTION_NOT_FOUND
        description: A required subscription was not found for the merchant
        error-category: MERCHANT_SUBSCRIPTION_ERROR
      - name: BAD_REQUEST
        description: A general error occurred with the request.
        error-category: INVALID_REQUEST_ERROR
      - name: MISSING_REQUIRED_PARAMETER
        description: 'The request is missing a required path, query, or

          body parameter.'
        error-category: INVALID_REQUEST_ERROR
      - name: INCORRECT_TYPE
        description: 'The value provided in the request is the wrong

          type. For example, a string instead of an integer.'
        error-category: INVALID_REQUEST_ERROR
      - name: INVALID_TIME
        description: 'Formatting for the provided time value is

          incorrect.'
        error-category: INVALID_REQUEST_ERROR
      - name: INVALID_TIME_RANGE
        description: 'The time range provided in the request is invalid.

          For example, the end time is before the start time.'
        error-category: INVALID_REQUEST_ERROR
      - name: INVALID_VALUE
        description: 'The provided value is invalid. For example,

          including `%` in a phone number.'
        error-category: INVALID_REQUEST_ERROR
      - name: INVALID_CURSOR
        description: 'The pagination cursor included in the request is

          invalid.'
        error-category: INVALID_REQUEST_ERROR
      - name: UNKNOWN_QUERY_PARAMETER
        description: 'The query parameters provided is invalid for the

          requested endpoint.'
        error-category: INVALID_REQUEST_ERROR
      - name: CONFLICTING_PARAMETERS
        description: 'One or more of the request parameters conflict with

          each other.'
        error-category: INVALID_REQUEST_ERROR
      - name: EXPECTED_JSON_BODY
        description: The request body is not a JSON object.
        error-category: INVALID_REQUEST_ERROR
      - name: INVALID_SORT_ORDER
        description: 'The provided sort order is not a valid key.

          Currently, sort order must be `ASC` or `DESC`.'
        error-category: INVALID_REQUEST_ERROR
      - name: VALUE_REGEX_MISMATCH
        description: 'The provided value does not match an expected

          regular expression.'
        error-category: INVALID_REQUEST_ERROR
      - name: VALUE_TOO_SHORT
        description: 'The provided string value is shorter than the

          minimum length allowed.'
        error-category: INVALID_REQUEST_ERROR
      - name: VALUE_TOO_LONG
        description: 'The provided string value is longer than the

          maximum length allowed.'
        error-category: INVALID_REQUEST_ERROR
      - name: VALUE_TOO_LOW
        description: 'The provided value is less than the supported

          minimum.'
        error-category: INVALID_REQUEST_ERROR
      - name: VALUE_TOO_HIGH
        description: 'The provided value is greater than the supported

          maximum.'
        error-category: INVALID_REQUEST_ERROR
      - name: VALUE_EMPTY
        description: 'The provided value has a default (empty) value

          such as a blank string.'
        error-category: INVALID_REQUEST_ERROR
      - name: ARRAY_LENGTH_TOO_LONG
        description: The provided array has too many 

# --- truncated at 32 KB (125 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/square/refs/heads/main/openapi/square-subscriptions-api-openapi.yml
Square Subscriptions API

Documentation

Specifications

Other Resources

OpenAPI Specification
