openapi: 3.0.3
info:
  title: Square Catalog Orders API
  description: Square API provides payment processing, commerce, customer management, and business operations capabilities for sellers, developers, and merchants. Supports point-of-sale, ecommerce, invoicing, loyalty, gift cards, and more.
  version: 2026-01-22
  contact:
    name: Square Developer Support
    url: https://developer.squareup.com/forums
  termsOfService: https://squareup.com/us/en/legal/general/developer
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://connect.squareup.com/v2
  description: Production
- url: https://connect.squareupsandbox.com/v2
  description: Sandbox
security:
- BearerAuth: []
- OAuth2: []
tags:
- name: Orders
  description: Create and manage orders
paths:
  /orders:
    post:
      operationId: create-order
      summary: Block Square Create Order
      description: Creates a new order that can include information on products for purchase.
      tags:
      - Orders
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
            examples:
              create-order:
                summary: Order with line items
                value:
                  idempotency_key: 8193148c-9586-11e6-99f9-28cfe91d33d5
                  order:
                    location_id: L1234567890
                    line_items:
                    - name: New York Strip Steak
                      quantity: '1'
                      base_price_money:
                        amount: 3000
                        currency: USD
                x-microcks-default: true
      responses:
        '200':
          description: Order created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateOrderResponse'
              examples:
                created-order:
                  summary: Created order
                  value:
                    order:
                      id: CAISENgvlJ6jLWAzERDzjyHVybY
                      location_id: L1234567890
                      state: OPEN
                      version: 1
                      total_money:
                        amount: 3000
                        currency: USD
                      created_at: '2026-01-15T10:05:00Z'
                      updated_at: '2026-01-15T10:05:00Z'
                  x-microcks-default: true
      x-microcks-operation:
        delay: 100
        dispatcher: SCRIPT
components:
  schemas:
    CreateOrderRequest:
      type: object
      required:
      - order
      properties:
        idempotency_key:
          type: string
          example: 8193148c-9586-11e6-99f9-28cfe91d33d5
        order:
          $ref: '#/components/schemas/Order'
    CreateOrderResponse:
      type: object
      properties:
        order:
          $ref: '#/components/schemas/Order'
    Money:
      type: object
      description: Represents an amount of money in a specific currency.
      properties:
        amount:
          type: integer
          description: Amount in the smallest denomination of the currency.
          example: 1500
        currency:
          type: string
          description: 3-letter ISO 4217 currency code.
          example: USD
    Order:
      type: object
      description: Represents an order for products and services.
      properties:
        id:
          type: string
          description: Unique ID for this order.
          example: CAISENgvlJ6jLWAzERDzjyHVybY
        location_id:
          type: string
          description: The ID of the seller location that this order is associated with.
          example: L1234567890
        state:
          type: string
          description: Current state of the order (OPEN, COMPLETED, CANCELED, DRAFT).
          example: OPEN
        version:
          type: integer
          description: Version number to enable optimistic concurrency control.
          example: 1
        total_money:
          $ref: '#/components/schemas/Money'
        created_at:
          type: string
          format: date-time
          example: '2026-01-15T10:05:00Z'
        updated_at:
          type: string
          format: date-time
          example: '2026-01-15T10:05:00Z'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Personal access token for Square API
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://connect.squareup.com/oauth2/authorize
          tokenUrl: https://connect.squareup.com/oauth2/token
          scopes:
            PAYMENTS_READ: Read payments
            PAYMENTS_WRITE: Write payments
            ORDERS_READ: Read orders
            ORDERS_WRITE: Write orders
            CUSTOMERS_READ: Read customers
            CUSTOMERS_WRITE: Write customers
x-generated-from: documentation
x-source-url: https://developer.squareup.com/reference/square