Shopify Orders API

openapi: 3.1.0
info:
  title: Shopify Admin REST About Orders API
  description: The Shopify Admin REST API lets you build apps and integrations that extend and enhance the Shopify admin. Access products, customers, orders, inventory, fulfillment, and more. Endpoints are organized by resource type and versioned by release date.
  version: 2025-01
  contact:
    name: Shopify
    url: https://shopify.dev/docs/api/admin-rest
    email: api@shopify.com
  license:
    name: Shopify API Terms
    url: https://www.shopify.com/legal/api-terms
  x-date: '2026-03-04'
servers:
- url: https://{store}.myshopify.com/admin/api/2025-01
  description: Shopify Admin REST API
  variables:
    store:
      default: my-store
      description: The Shopify store subdomain
security:
- AccessToken: []
tags:
- name: Orders
  description: Manage orders
paths:
  /orders.json:
    get:
      operationId: listOrders
      summary: Shopify Retrieve a list of orders
      description: Retrieves a list of orders. By default only orders from the last 60 days are returned. Use status=any to include all statuses.
      tags:
      - Orders
      parameters:
      - name: ids
        in: query
        description: Comma-separated list of order IDs
        schema:
          type: string
      - name: limit
        in: query
        description: Maximum number of results (max 250, default 50)
        schema:
          type: integer
          default: 50
          maximum: 250
      - name: since_id
        in: query
        description: Return orders after the specified ID
        schema:
          type: integer
      - name: status
        in: query
        description: Filter by order status
        schema:
          type: string
          enum:
          - open
          - closed
          - cancelled
          - any
          default: open
      - name: financial_status
        in: query
        description: Filter by financial status
        schema:
          type: string
          enum:
          - authorized
          - pending
          - paid
          - partially_paid
          - refunded
          - voided
          - partially_refunded
          - any
          - unpaid
      - name: fulfillment_status
        in: query
        description: Filter by fulfillment status
        schema:
          type: string
          enum:
          - shipped
          - partial
          - unshipped
          - any
          - unfulfilled
      - name: created_at_min
        in: query
        description: Show orders created after this date
        schema:
          type: string
          format: date-time
      - name: created_at_max
        in: query
        description: Show orders created before this date
        schema:
          type: string
          format: date-time
      - name: updated_at_min
        in: query
        description: Show orders updated after this date
        schema:
          type: string
          format: date-time
      - name: updated_at_max
        in: query
        description: Show orders updated before this date
        schema:
          type: string
          format: date-time
      - name: fields
        in: query
        description: Comma-separated list of fields to include
        schema:
          type: string
      responses:
        '200':
          description: A list of orders
          content:
            application/json:
              schema:
                type: object
                properties:
                  orders:
                    type: array
                    items:
                      $ref: '#/components/schemas/Order'
    post:
      operationId: createOrder
      summary: Shopify Create an order
      description: Creates an order. Orders created via the API do not trigger payment processing. Use the order to represent sales from external channels.
      tags:
      - Orders
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - order
              properties:
                order:
                  $ref: '#/components/schemas/OrderInput'
      responses:
        '201':
          description: The created order
          content:
            application/json:
              schema:
                type: object
                properties:
                  order:
                    $ref: '#/components/schemas/Order'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /orders/count.json:
    get:
      operationId: getOrderCount
      summary: Shopify Retrieve a count of orders
      description: Retrieves a count of orders matching the given criteria.
      tags:
      - Orders
      parameters:
      - name: status
        in: query
        description: Filter by order status
        schema:
          type: string
          enum:
          - open
          - closed
          - cancelled
          - any
      - name: financial_status
        in: query
        description: Filter by financial status
        schema:
          type: string
      - name: fulfillment_status
        in: query
        description: Filter by fulfillment status
        schema:
          type: string
      - name: created_at_min
        in: query
        description: Count orders created after this date
        schema:
          type: string
          format: date-time
      - name: updated_at_min
        in: query
        description: Count orders updated after this date
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: The order count
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
  /orders/{order_id}.json:
    get:
      operationId: getOrder
      summary: Shopify Retrieve a single order
      description: Retrieves a single order by ID including line items and details.
      tags:
      - Orders
      parameters:
      - $ref: '#/components/parameters/OrderId'
      - name: fields
        in: query
        description: Comma-separated list of fields to include
        schema:
          type: string
      responses:
        '200':
          description: The requested order
          content:
            application/json:
              schema:
                type: object
                properties:
                  order:
                    $ref: '#/components/schemas/Order'
        '404':
          description: Order not found
    put:
      operationId: updateOrder
      summary: Shopify Update an order
      description: Updates an existing order. Note, tags, email, phone, shipping address, and metafields can be updated.
      tags:
      - Orders
      parameters:
      - $ref: '#/components/parameters/OrderId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - order
              properties:
                order:
                  $ref: '#/components/schemas/OrderInput'
      responses:
        '200':
          description: The updated order
          content:
            application/json:
              schema:
                type: object
                properties:
                  order:
                    $ref: '#/components/schemas/Order'
    delete:
      operationId: deleteOrder
      summary: Shopify Delete an order
      description: Deletes an order. Orders that interact with an online gateway cannot be deleted.
      tags:
      - Orders
      parameters:
      - $ref: '#/components/parameters/OrderId'
      responses:
        '200':
          description: Order deleted successfully
        '404':
          description: Order not found
  /orders/{order_id}/cancel.json:
    post:
      operationId: cancelOrder
      summary: Shopify Cancel an order
      description: Cancels an order. Optionally refunds payment and restocks items.
      tags:
      - Orders
      parameters:
      - $ref: '#/components/parameters/OrderId'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
                  description: Cancellation reason
                  enum:
                  - customer
                  - fraud
                  - inventory
                  - declined
                  - other
                email:
                  type: boolean
                  description: Whether to send a cancellation email
                restock:
                  type: boolean
                  description: Whether to restock items
      responses:
        '200':
          description: The cancelled order
          content:
            application/json:
              schema:
                type: object
                properties:
                  order:
                    $ref: '#/components/schemas/Order'
  /orders/{order_id}/close.json:
    post:
      operationId: closeOrder
      summary: Shopify Close an order
      description: Closes an order, marking it as completed.
      tags:
      - Orders
      parameters:
      - $ref: '#/components/parameters/OrderId'
      responses:
        '200':
          description: The closed order
          content:
            application/json:
              schema:
                type: object
                properties:
                  order:
                    $ref: '#/components/schemas/Order'
  /orders/{order_id}/open.json:
    post:
      operationId: reopenOrder
      summary: Shopify Re-open a closed order
      description: Re-opens a previously closed order.
      tags:
      - Orders
      parameters:
      - $ref: '#/components/parameters/OrderId'
      responses:
        '200':
          description: The re-opened order
          content:
            application/json:
              schema:
                type: object
                properties:
                  order:
                    $ref: '#/components/schemas/Order'
  /admin/api/2020-01/customers/{customer_id}/orders.json:
    get:
      summary: Shopify Retrieves All Orders Belonging To A Customer
      description: https://shopify.dev/docs/admin-api/rest/reference/customers/customer#orders-2020-01
      parameters:
      - in: path
        name: customer_id
        required: true
        schema:
          type: string
        description: customer_id
      tags:
      - Orders
      responses:
        '200':
          description: ''
      operationId: deprecated_202001_get_customers_param_customer_id_orders
      x-api-evangelist-processing:
        PascalCaseOperationSummaries: true
        ChooseTags: true
  /admin/api/2020-04/customers/{customer_id}/orders.json:
    get:
      summary: Shopify Retrieves All Orders Belonging To A Customer
      description: https://shopify.dev/docs/admin-api/rest/reference/customers/customer#orders-2020-04
      parameters:
      - in: path
        name: customer_id
        required: true
        schema:
          type: string
        description: customer_id
      tags:
      - Orders
      responses:
        '200':
          description: ''
      operationId: deprecated_202004_get_customers_param_customer_id_orders
      x-api-evangelist-processing:
        PascalCaseOperationSummaries: true
        ChooseTags: true
  /admin/api/2020-07/customers/{customer_id}/orders.json:
    get:
      summary: Shopify Retrieves All Orders Belonging To A Customer
      description: https://shopify.dev/docs/admin-api/rest/reference/customers/customer#orders-2020-07
      parameters:
      - in: path
        name: customer_id
        required: true
        schema:
          type: string
        description: customer_id
      tags:
      - Orders
      responses:
        '200':
          description: ''
      operationId: deprecated_202007_get_customers_param_customer_id_orders
      x-api-evangelist-processing:
        PascalCaseOperationSummaries: true
        ChooseTags: true
  /admin/api/2020-10/customers/{customer_id}/orders.json:
    get:
      summary: Shopify Retrieves All Orders Belonging To A Customer
      description: https://shopify.dev/docs/admin-api/rest/reference/customers/customer#orders-2020-10
      parameters:
      - in: path
        name: customer_id
        required: true
        schema:
          type: string
        description: customer_id
      tags:
      - Orders
      responses:
        '200':
          description: ''
      operationId: get_customers_param_customer_id_orders
      x-api-evangelist-processing:
        PascalCaseOperationSummaries: true
        ChooseTags: true
  /admin/api/2021-01/customers/{customer_id}/orders.json:
    get:
      summary: Shopify Retrieves All Orders Belonging To A Customer
      description: https://shopify.dev/docs/admin-api/rest/reference/customers/customer#orders-2021-01
      parameters:
      - in: path
        name: customer_id
        required: true
        schema:
          type: string
        description: customer_id
      tags:
      - Orders
      responses:
        '200':
          description: ''
      operationId: deprecated_202101_get_customers_param_customer_id_orders
      x-api-evangelist-processing:
        PascalCaseOperationSummaries: true
        ChooseTags: true
  /admin/api/unstable/customers/{customer_id}/orders.json:
    get:
      summary: Shopify Retrieves All Orders Belonging To A Customer
      description: https://shopify.dev/docs/admin-api/rest/reference/customers/customer#orders-unstable
      parameters:
      - in: path
        name: customer_id
        required: true
        schema:
          type: string
        description: customer_id
      tags:
      - Orders
      responses:
        '200':
          description: ''
      operationId: deprecated_unstable_get_customers_param_customer_id_orders
      x-api-evangelist-processing:
        PascalCaseOperationSummaries: true
        ChooseTags: true
  /admin/api/2020-01/orders.json:
    get:
      summary: Shopify Retrieves A List Of Orders
      description: https://shopify.dev/docs/admin-api/rest/reference/orders/order#index-2020-01
      parameters:
      - in: query
        name: ids
        description: Retrieve only orders specified by a comma-separated list of order IDs.
        schema: {}
        required: false
      - in: query
        name: limit
        description: "The maximum number of results to show on a page.\n                  (default: 50, maximum: 250)"
        schema: {}
        required: false
      - in: query
        name: since_id
        description: Show orders after the specified ID.
        schema: {}
        required: false
      - in: query
        name: created_at_min
        description: 'Show orders created at or after date (format: 2014-04-25T16:15:47-04:00).'
        schema: {}
        required: false
      - in: query
        name: created_at_max
        description: 'Show orders created at or before date (format: 2014-04-25T16:15:47-04:00).'
        schema: {}
        required: false
      - in: query
        name: updated_at_min
        description: 'Show orders last updated at or after date (format: 2014-04-25T16:15:47-04:00).'
        schema: {}
        required: false
      - in: query
        name: updated_at_max
        description: 'Show orders last updated at or before date (format: 2014-04-25T16:15:47-04:00).'
        schema: {}
        required: false
      - in: query
        name: processed_at_min
        description: 'Show orders imported at or after date (format: 2014-04-25T16:15:47-04:00).'
        schema: {}
        required: false
      - in: query
        name: processed_at_max
        description: 'Show orders imported at or before date (format: 2014-04-25T16:15:47-04:00).'
        schema: {}
        required: false
      - in: query
        name: attribution_app_id
        description: Show orders attributed to a certain app, specified by the app ID. Set as current to show orders for the app currently consuming the API.
        schema: {}
        required: false
      - in: query
        name: status
        description: "Filter orders by their status.\n                  (default: open)\n                    \n                        open: Show only open orders.\n                        closed: Show only closed orders.\n                        cancelled: Show only canceled orders.\n                        any: Show orders of any status, including archived orders."
        schema: {}
        required: false
      - in: query
        name: financial_status
        description: "Filter orders by their financial status.\n                  (default: any)\n                    \n                        authorized: Show only authorized orders\n                        pending: Show only pending orders\n                        paid: Show only paid orders\n                        partially_paid: Show only partially paid orders\n                        refunded: Show only refunded orders\n                        voided: Show only voided orders\n                        partially_refunded: Show only partially refunded orders\n                        any: Show orders of any financial status.\n                        unpaid: Show authorized and partially paid orders."
        schema: {}
        required: false
      - in: query
        name: fulfillment_status
        description: "Filter orders by their fulfillment status.\n                  (default: any)\n                    \n                        shipped: Show orders that have been shipped. Returns orders with fulfillment_status of fulfilled.\n                        partial: Show partially shipped orders.\n                        unshipped: Show orders that have not yet been shipped. Returns orders with fulfillment_status of null.\n                        any: Show orders of any fulfillment status.\n                        unfulfilled: Returns orders with fulfillment_status of null or partial."
        schema: {}
        required: false
      - in: query
        name: fields
        description: Retrieve only certain fields, specified by a comma-separated list of fields names.
        schema: {}
        required: false
      tags:
      - Orders
      responses:
        '200':
          description: ''
      operationId: deprecated_202001_get_orders
      x-api-evangelist-processing:
        PascalCaseOperationSummaries: true
        ChooseTags: true
  /admin/api/2020-01/orders/{order_id}/cancel.json:
    post:
      requestBody:
        content:
          application/json:
            schema: {}
            examples:
              example1:
                value: {}
                summary: Cancel an order
              example2:
                value:
                  amount: '10.00'
                  currency: USD
                summary: Cancel and refund an order using the amount property
              example3:
                value:
                  amount: '109.00'
                  currency: USD
                summary: When an order has multiple refundable transactions, refunding an amount less than its net payment without a refund property fails with an error
              example4:
                value:
                  refund:
                    note: Customer made a mistake
                    shipping:
                      full_refund: true
                    refund_line_items:
                    - line_item_id: 466157049
                      quantity: 1
                      restock_type: cancel
                      location_id: 48752903
                    transactions:
                    - parent_id: 1072844756
                      amount: '10.00'
                      kind: refund
                      gateway: bogus
                    - parent_id: 1072844757
                      amount: '100.00'
                      kind: refund
                      gateway: gift_card
                summary: Cancel and refund an order using the refund property
              example5:
                value: {}
                summary: Canceling an order that has fulfillments fails with an error
      summary: Shopify For Multi-currency Orders
      description: https://shopify.dev/docs/admin-api/rest/reference/orders/order#cancel-2020-01
      parameters:
      - in: path
        name: order_id
        required: true
        schema:
          type: string
        description: order_id
      - in: query
        name: amount
        description: The amount to refund. If set, Shopify attempts to void or refund the payment, depending on its status. Shopify refunds through a manual gateway in cases where the original transaction was not made in Shopify. Refunds through a manual gateway are recorded as a refund on Shopify, but the customer is not refunded.
        schema: {}
        required: false
      - in: query
        name: currency
        description: The currency of the refund that's issued when the order is canceled. Required for multi-currency orders whenever the amount property is provided.
        schema: {}
        required: false
      - in: query
        name: "restock\n                  deprecated"
        description: "Whether to restock refunded items back to your store's inventory.\n                  (default: false)"
        schema: {}
        required: false
      - in: query
        name: reason
        description: "The reason for the order cancellation. Valid values: customer, inventory, fraud, declined, and other.)\n                  (default: other)"
        schema: {}
        required: false
      - in: query
        name: email
        description: "Whether to send an email to the customer notifying them of the cancellation.\n                  (default: false)"
        schema: {}
        required: false
      - in: query
        name: refund
        description: The refund transactions to perform. Required for some more complex refund situations. For more information, see the Refund API.
        schema: {}
        required: false
      tags:
      - Orders
      responses:
        '200':
          description: ''
      operationId: deprecated_202001_create_orders_param_order_id_cancel
      x-api-evangelist-processing:
        PascalCaseOperationSummaries: true
        ChooseTags: true
  /admin/api/2020-04/orders.json:
    get:
      summary: Shopify Retrieves A List Of Orders
      description: https://shopify.dev/docs/admin-api/rest/reference/orders/order#index-2020-04
      parameters:
      - in: query
        name: ids
        description: Retrieve only orders specified by a comma-separated list of order IDs.
        schema: {}
        required: false
      - in: query
        name: limit
        description: "The maximum number of results to show on a page.\n                  (default: 50, maximum: 250)"
        schema: {}
        required: false
      - in: query
        name: since_id
        description: Show orders after the specified ID.
        schema: {}
        required: false
      - in: query
        name: created_at_min
        description: 'Show orders created at or after date (format: 2014-04-25T16:15:47-04:00).'
        schema: {}
        required: false
      - in: query
        name: created_at_max
        description: 'Show orders created at or before date (format: 2014-04-25T16:15:47-04:00).'
        schema: {}
        required: false
      - in: query
        name: updated_at_min
        description: 'Show orders last updated at or after date (format: 2014-04-25T16:15:47-04:00).'
        schema: {}
        required: false
      - in: query
        name: updated_at_max
        description: 'Show orders last updated at or before date (format: 2014-04-25T16:15:47-04:00).'
        schema: {}
        required: false
      - in: query
        name: processed_at_min
        description: 'Show orders imported at or after date (format: 2014-04-25T16:15:47-04:00).'
        schema: {}
        required: false
      - in: query
        name: processed_at_max
        description: 'Show orders imported at or before date (format: 2014-04-25T16:15:47-04:00).'
        schema: {}
        required: false
      - in: query
        name: attribution_app_id
        description: Show orders attributed to a certain app, specified by the app ID. Set as current to show orders for the app currently consuming the API.
        schema: {}
        required: false
      - in: query
        name: status
        description: "Filter orders by their status.\n                  (default: open)\n                    \n                        open: Show only open orders.\n                        closed: Show only closed orders.\n                        cancelled: Show only canceled orders.\n                        any: Show orders of any status, including archived orders."
        schema: {}
        required: false
      - in: query
        name: financial_status
        description: "Filter orders by their financial status.\n                  (default: any)\n                    \n                        authorized: Show only authorized orders\n                        pending: Show only pending orders\n                        paid: Show only paid orders\n                        partially_paid: Show only partially paid orders\n                        refunded: Show only refunded orders\n                        voided: Show only voided orders\n                        partially_refunded: Show only partially refunded orders\n                        any: Show orders of any financial status.\n                        unpaid: Show authorized and partially paid orders."
        schema: {}
        required: false
      - in: query
        name: fulfillment_status
        description: "Filter orders by their fulfillment status.\n                  (default: any)\n                    \n                        shipped: Show orders that have been shipped. Returns orders with fulfillment_status of fulfilled.\n                        partial: Show partially shipped orders.\n                        unshipped: Show orders that have not yet been shipped. Returns orders with fulfillment_status of null.\n                        any: Show orders of any fulfillment status.\n                        unfulfilled: Returns orders with fulfillment_status of null or partial."
        schema: {}
        required: false
      - in: query
        name: fields
        description: Retrieve only certain fields, specified by a comma-separated list of fields names.
        schema: {}
        required: false
      tags:
      - Orders
      responses:
        '200':
          description: ''
      operationId: deprecated_202004_get_orders
      x-api-evangelist-processing:
        PascalCaseOperationSummaries: true
        ChooseTags: true
  /admin/api/2020-04/orders/{order_id}/cancel.json:
    post:
      requestBody:
        content:
          application/json:
            schema: {}
            examples:
              example1:
                value: {}
                summary: Cancel an order
              example2:
                value:
                  amount: '10.00'
                  currency: USD
                summary: Cancel and refund an order using the amount property
              example3:
                value:
                  amount: '109.00'
                  currency: USD
                summary: When an order has multiple refundable transactions, refunding an amount less than its net payment without a refund property fails with an error
              example4:
                value:
                  refund:
                    note: Customer made a mistake
                    shipping:
                      full_refund: true
                    refund_line_items:
                    - line_item_id: 466157049
                      quantity: 1
                      restock_type: cancel
                      location_id: 48752903
                    transactions:
                    - parent_id: 1072844756
                      amount: '10.00'
                      kind: refund
                      gateway: bogus
                    - parent_id: 1072844757
                      amount: '100.00'
                      kind: refund
                      gateway: gift_card
                summary: Cancel and refund an order using the refund property
              example5:
                value: {}
                summary: Canceling an order that has fulfillments fails with an error
      summary: Shopify For Multi-currency Orders
      description: https://shopify.dev/docs/admin-api/rest/reference/orders/order#cancel-2020-04
      parameters:
      - in: path
        name: order_id
        required: true
        schema:
          type: string
        description: order_id
      - in: query
        name: amount
        description: The amount to refund. If set, Shopify attempts to void or refund the payment, depending on its status. Shopify refunds through a manual gateway in cases where the original transaction was not made in Shopify. Refunds through a manual gateway are recorded as a refund on Shopify, but the customer is not refunded.
        schema: {}
        required: false
      - in: query
        name: currency
        description: The currency of the refund that's issued when the order is canceled. Required for multi-currency orders whenever the amount property is provided.
        schema: {}
        required: false
      - in: query
        name: "restock\n                  deprecated"
        description: "Whether to restock refunded items back to your store's inventory.\n                  (default: false)"
        schema: {}
        required: false
      - in: query
        name: reason
        description: "The reason for the order cancellation. Valid values: customer, inventory, fraud, declined, and other.)\n                  (default: other)"
        schema: {}
        required: false
      - in: query
        name: email
        description: "Whether to send an email to the customer notifying them of the cancellation.\n                  (default: false)"
        schema: {}
        required: false
      - in: query
        name: refund
        description: The refund transactions to perform. Required for some more complex refund situations. For more information, see the Refund API.
        schema: {}
        required: false
      tags:
      - Orders
      responses:
        '200':
          description: ''
      operationId: deprecated_202004_create_orders_param_order_id_cancel
      x-api-evangelist-processing:
        PascalCaseOperationSummaries: true
        ChooseTags: true
  /admin/api/2020-07/orders.json:
    get:
      summary: Shopify Retrieves A List Of Orders
      description: https://shopify.dev/docs/admin-api/rest/reference/orders/order#index-2020-07
      parameters:
      - in: query
        name: ids
        description: Retrieve only orders specified by a comma-separated list of order IDs.
        schema: {}
        required: false
      - in: query
        name: limit
        description: "The maximum number of results to show on a page.\n                  (default: 50, maximum: 250)"
        schema: {}
        required: false
      - in: query
        name: since_id
        description: Show orders after the specified ID.
        schema: {}
        required: false
      - in: query
        name: created_at_min
        description: 'Show orders created at or after date (format: 2014-04-25T16:15:47-04:00).'
        schema: {}
        required: false
      - in: query
        name: created_at_max
        description: 'Show orders created at or before date (format: 2014-04-25T16:15:47-04:00).'
        schema: {}
        required: false
      - in: query
        name: updated_at_min
        description: 'Show orders last updated at or after date (format: 2014-04-25T16:15:47-04:00).'
        schema: {}
        required: false
      - in: query
        name: updated_at_max
        description: 'Show orders last updated at or before date (format: 2014-04-25T16:15:47-04:00).'
        schema: {}
        required: false
      - in: query
        name: processed_at_min
        description: 'Show orders imported at or after date (format: 2014-04-25T16:15:47-04:00).'
        schema: {}
        required: false
      - in: query
        name: processed_at_max
        description: 'Show orders imported at or before date (format: 2014-04-25T16:15:47-04:00).'
        schema: {}
        required: false


# --- truncated at 32 KB (126 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/shopify/refs/heads/main/openapi/shopify-orders-api-openapi.yml