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

# Get Order by External ID

> Get details about a specific order by its commerce `external_id`.



## OpenAPI

````yaml get /orders/external/{externalId}
openapi: 3.1.0
info:
  title: Orders API
  version: v1
  description: >-
    The Orders API allows managing your shop's orders within the Loop Platform.


    ### Resource identifier format


    Resource identifiers (the `id` field and related global-identifier fields)
    are returned as JSON

    integers by default. To receive them as strings instead, send the

    `X-Loop-Global-Identifier-Type: string` request header.
  contact:
    name: Loop Returns
    url: https://loopreturns.com/
servers:
  - url: https://api.loopreturns.com/api/v1
security: []
tags:
  - name: Orders
paths:
  /orders/external/{externalId}:
    get:
      tags:
        - Orders
      summary: Get Order by External ID
      description: Get details about a specific order by its commerce `external_id`.
      operationId: getOrderByExternalId
      parameters:
        - in: path
          name: externalId
          schema:
            type: string
            maxLength: 64
          required: true
          description: The identifier used by an external source to identify the order.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  order:
                    $ref: '#/components/schemas/OrderResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      security:
        - read: []
components:
  schemas:
    OrderResponse:
      title: OrderResponse
      type: object
      properties:
        id:
          type: integer
          format: int64
          minimum: 1
          examples:
            - 810772123123123
          readOnly: true
        external_id:
          type:
            - string
            - 'null'
          examples:
            - 564400c7-7a6b-4f29-b6a5-7bb580b2992c
        name:
          type: string
        secondary_identifier:
          type:
            - string
            - 'null'
        source:
          type:
            - string
            - 'null'
        sales_channel:
          type:
            - string
            - 'null'
          description: The name of the channel.
          examples:
            - shopify
        customer:
          type: object
          properties:
            id:
              type: integer
              description: The global identifier of the customer.
              examples:
                - 123123123123123
            external_id:
              type:
                - string
                - 'null'
              examples:
                - 564400c7-7a6b-4f29-b6a5-7bb580b2992c
            sales_channel:
              type:
                - string
                - 'null'
              description: The name of the channel associated with the customer.
              examples:
                - shopify
            first_name:
              type: string
            last_name:
              type: string
            email:
              type: string
            phone:
              type: string
        status:
          type: string
          enum:
            - active
            - archived
            - cancelled
            - unknown
          description: Status of the Order.
        shipping_address:
          $ref: '#/components/schemas/Address'
        billing_address:
          $ref: '#/components/schemas/Address'
        taxes_included:
          type: boolean
        total_price:
          $ref: '#/components/schemas/MoneySet'
          description: >
            The price of the order in minor units, such as cents, with its
            corresponding currency.
        total_price_presentment:
          $ref: '#/components/schemas/MoneySet'
          description: >
            The price of the order in minor units, such as cents. This is
            included if the price was shown to the customer in an alternate
            currency.
        total_discounts:
          $ref: '#/components/schemas/MoneySet'
          description: >
            The deduction from the original order price as a way to promote
            sales, special offers, or customer loyalty rewards.
        total_discounts_presentment:
          $ref: '#/components/schemas/MoneySet'
          description: >
            The deduction from the original order price as a way to promote
            sales, special offers, or customer loyalty rewards. This price is
            discounted from the original price according to the customer's local
            currency.
        shipping_lines:
          $ref: '#/components/schemas/ShippingLines'
          description: The shipping lines for the order.
        order_discounts:
          $ref: '#/components/schemas/OrderDiscounts'
          description: The discounts for the order.
        total_taxes:
          $ref: '#/components/schemas/MoneySet'
          description: The tax amount for the order.
        total_taxes_presentment:
          $ref: '#/components/schemas/MoneySet'
          description: >-
            The tax amount for the order according to the customer's local
            currency.
        tags:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/TagRequestData'
        refunds:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/RefundItemsResponse'
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/LineItemResponse'
        fulfillments:
          type: array
          items:
            $ref: '#/components/schemas/FulfillmentResponse'
        created_at:
          oneOf:
            - $ref: '#/components/schemas/Date'
            - type: 'null'
        updated_at:
          oneOf:
            - $ref: '#/components/schemas/Date'
            - type: 'null'
        financial_status:
          type:
            - string
            - 'null'
          enum:
            - pending
            - authorized
            - partially_paid
            - paid
            - partially_refunded
            - refunded
            - voided
            - null
          description: The financial status of the order.
        cancel_reason:
          type:
            - string
            - 'null'
          enum:
            - customer
            - declined
            - fraud
            - inventory
            - other
            - staff
            - null
          description: The reason the order was cancelled, if applicable.
        processed_at:
          oneOf:
            - $ref: '#/components/schemas/Date'
            - type: 'null'
          description: The date and time when the order was processed in the source system.
        browser_ip:
          oneOf:
            - type: string
              format: ipv4
            - type: string
              format: ipv6
            - type: 'null'
          maxLength: 45
          description: The IP address of the browser used to place the order.
        client_details_user_agent:
          type:
            - string
            - 'null'
          maxLength: 1000
          description: The user agent string of the browser used to place the order.
        total_tip_received:
          anyOf:
            - $ref: '#/components/schemas/MoneySet'
            - type: 'null'
          description: The total tip amount received for the order.
        warnings:
          type:
            - array
            - 'null'
          description: >-
            Non-fatal warnings about the order, surfaced after a successful
            write.
          items:
            type: object
            required:
              - code
              - message
            properties:
              code:
                type: string
              message:
                type: string
    Address:
      type: object
      properties:
        name:
          type:
            - string
            - 'null'
          maxLength: 100
          description: Recipient name.
        company:
          type:
            - string
            - 'null'
          maxLength: 100
          description: Recipient company.
        address1:
          type: string
          maxLength: 125
          description: Address line 1.
        address2:
          type:
            - string
            - 'null'
          maxLength: 125
          description: Address line 2.
        city:
          type:
            - string
          maxLength: 100
          description: City.
        region:
          type:
            - string
            - 'null'
          maxLength: 100
          description: State or Region.
        postal_code:
          type:
            - string
            - 'null'
          maxLength: 16
          description: Postal Code.
        country_code:
          type: string
          maxLength: 2
          description: Must be a valid 2 character country code.
      required:
        - address1
        - city
        - country_code
      examples:
        - name: John Smith
          company: Acme, Co
          address1: 123 Example St
          address2: Box 123
          city: Columbus
          region: OH
          postal_code: 12345
          country_code: US
    MoneySet:
      type: object
      examples:
        - amount: 50000
          currency_code: USD
        - amount: 25000
        - amount: 1500
          currency_code: EUR
      properties:
        amount:
          type: integer
          format: int32
          examples:
            - 25000
        currency_code:
          type:
            - string
          default: USD
          examples:
            - EUR
      required:
        - amount
        - currency_code
    ShippingLines:
      title: ShippingLines
      type: array
      items:
        $ref: '#/components/schemas/ShippingLine'
    OrderDiscounts:
      title: OrderDiscounts
      type: array
      items:
        $ref: '#/components/schemas/OrderDiscount'
    TagRequestData:
      type: string
      description: A tag used to classify and group orders.
      examples:
        - VIP
    RefundItemsResponse:
      title: RefundItemsResponse
      type: array
      items:
        $ref: '#/components/schemas/OrderRefundResponse'
    LineItemResponse:
      title: LineItemResponse
      type: object
      properties:
        id:
          type: integer
          format: int64
          minimum: 1
          readOnly: true
        external_id:
          type:
            - string
            - 'null'
          maxLength: 64
        product:
          $ref: '#/components/schemas/ProductResponse'
        product_variant:
          anyOf:
            - $ref: '#/components/schemas/ProductVariantResponse'
            - type: 'null'
        quantity:
          type:
            - integer
            - 'null'
        unit_price:
          $ref: '#/components/schemas/MoneySet'
          description: >
            The price of the order line item in minor units, such as cents, with
            its corresponding currency.
        unit_price_presentment:
          anyOf:
            - $ref: '#/components/schemas/MoneySet'
            - type: 'null'
          description: >
            The price of the order line item in minor units, such as cents. This
            is included if the price was shown to the customer in an alternate
            currency.
        unit_discounts:
          anyOf:
            - $ref: '#/components/schemas/MoneySet'
            - type: 'null'
          description: >
            The deduction from the original order line item price as a way to
            promote sales, special offers, or customer loyalty rewards.
        unit_discounts_presentment:
          anyOf:
            - $ref: '#/components/schemas/MoneySet'
            - type: 'null'
          description: >
            The deduction from the original order line item price as a way to
            promote sales, special offers, or customer loyalty rewards. This
            price is discounted from the original price according to the
            customer's local currency.
        taxable:
          type:
            - boolean
            - 'null'
        tax_lines:
          oneOf:
            - $ref: '#/components/schemas/TaxLines'
            - type: 'null'
        refunds:
          oneOf:
            - $ref: '#/components/schemas/LineItemRefundItemsResponse'
            - type: 'null'
        discounts:
          oneOf:
            - $ref: '#/components/schemas/OrderLineItemDiscounts'
            - type: 'null'
        duties:
          oneOf:
            - $ref: '#/components/schemas/Duties'
            - type: 'null'
    FulfillmentResponse:
      title: FulfillmentResponse
      type: object
      required:
        - status
      properties:
        id:
          type: integer
          format: int64
          readOnly: true
          description: The global identifier for the fulfillment.
        external_id:
          type:
            - string
            - 'null'
          maxLength: 64
        status:
          type: string
          enum:
            - success
            - failure
            - cancelled
            - pending
            - open
            - error
          description: >
            Status of the fulfillment:

            - `success` - The fulfillment was successful.

            - `failure` - The fulfillment request failed.

            - `cancelled` - The fulfillment was cancelled.

            - `pending` - Loop has created the fulfillment and is waiting for
            the fulfillment
              service to transition it to `open` or `success`.

            - `open` - The fulfillment has been acknowledged by the fulfillment
            service and is being processed.

            - `error` - There was an error with the fulfillment request.
        fulfilled_at:
          type:
            - string
            - 'null'
          format: date-time
          description: The date and time the line item was fulfilled.
        shipping_carrier:
          type: string
        location:
          anyOf:
            - type: 'null'
            - $ref: '#/components/schemas/FulfillmentLocationResponse'
        fulfillment_line_items:
          $ref: '#/components/schemas/FulfillmentLineItems'
        tracking_numbers:
          type:
            - array
            - 'null'
          items:
            type: string
    Date:
      type: string
      format: date-time
      examples:
        - '2023-04-25T13:25:00-05:00'
    ShippingLine:
      title: ShippingLine
      type: object
      properties:
        title:
          type:
            - string
        price:
          $ref: '#/components/schemas/MoneySet'
        discounts:
          $ref: '#/components/schemas/ShippingLineDiscount'
        tax_lines:
          $ref: '#/components/schemas/TaxLines'
    OrderDiscount:
      title: OrderDiscount
      type: object
      properties:
        external_id:
          type:
            - string
            - 'null'
          maxLength: 100
          examples:
            - 564400c7-7a6b-4f29-b6a5-7bb580b2992c
        name:
          type:
            - string
          maxLength: 64
        discount_type:
          type: string
          description: Type of discount.
          enum:
            - amount
            - bonus
            - bonus_choice
            - fixed_price
            - free
            - percentage
            - percentage_off_options
            - price_book_price
            - total_fixed_price
        code:
          type:
            - string
          maxLength: 100
        reason:
          type:
            - string
          maxLength: 512
        rate:
          type:
            - number
        tax_adjustment_money:
          $ref: '#/components/schemas/MoneySet'
        net_adjustment_money:
          $ref: '#/components/schemas/MoneySet'
    OrderRefundResponse:
      title: OrderRefundResponse
      type: object
      properties:
        id:
          type: integer
          format: int64
          readOnly: true
          description: The global identifier for the refund.
        external_id:
          type:
            - string
            - 'null'
        type:
          type:
            - string
            - 'null'
          description: Type of refund.
          enum:
            - line_item
            - shipping
            - other
        amount:
          $ref: '#/components/schemas/MoneySet'
        line_item:
          description: Present when `type` is `line_item`.
          anyOf:
            - $ref: '#/components/schemas/RefundLineItemResponse'
            - type: 'null'
        created_at:
          oneOf:
            - $ref: '#/components/schemas/Date'
            - type: 'null'
        updated_at:
          oneOf:
            - $ref: '#/components/schemas/Date'
            - type: 'null'
    ProductResponse:
      title: ProductResponse
      type: object
      properties:
        id:
          type: integer
          format: int64
          readOnly: true
          description: The global identifier for the product.
        external_id:
          type:
            - string
            - 'null'
          maxLength: 100
          description: The external identifier for the product.
    ProductVariantResponse:
      title: ProductVariantResponse
      type: object
      properties:
        id:
          type: integer
          format: int64
          readOnly: true
          description: The global identifier for the product variant.
        external_id:
          type:
            - string
            - 'null'
          maxLength: 100
          description: The external identifier for the product variant.
    TaxLines:
      title: TaxLines
      type: array
      items:
        $ref: '#/components/schemas/TaxLine'
    LineItemRefundItemsResponse:
      title: LineItemRefundItemsResponse
      description: |
        Refunds nested under a line item in an order response.
      type: array
      items:
        $ref: '#/components/schemas/LineItemRefundResponse'
    OrderLineItemDiscounts:
      title: OrderLineItemDiscounts
      type: array
      items:
        $ref: '#/components/schemas/OrderLineItemDiscount'
    Duties:
      title: Duties
      type: array
      items:
        $ref: '#/components/schemas/Duty'
    FulfillmentLocationResponse:
      title: FulfillmentLocationResponse
      type: object
      properties:
        id:
          type: integer
          format: int64
          readOnly: true
          description: The global identifier for the location.
        external_id:
          type:
            - string
            - 'null'
          maxLength: 100
          description: The external identifier for the location.
    FulfillmentLineItems:
      title: FulfillmentLineItems
      type: array
      items:
        $ref: '#/components/schemas/FulfillmentLineItem'
    ShippingLineDiscount:
      title: ShippingLineDiscount
      type: object
      properties:
        external_id:
          type:
            - string
            - 'null'
          maxLength: 64
          examples:
            - 564400c7-7a6b-4f29-b6a5-7bb580b2992c
        name:
          type:
            - string
        discount_type:
          type:
            - string
            - 'null'
          description: Type of discount.
          enum:
            - amount
            - bonus
            - bonus_choice
            - fixed_price
            - free
            - percentage
            - percentage_off_options
            - price_book_price
            - total_fixed_price
        code:
          type:
            - string
        reason:
          type:
            - string
        rate:
          type:
            - number
        net_adjustment_money:
          $ref: '#/components/schemas/MoneySet'
        tax_adjustment_money:
          $ref: '#/components/schemas/MoneySet'
    RefundLineItemResponse:
      title: RefundLineItemResponse
      type: object
      properties:
        id:
          type: integer
          format: int64
          readOnly: true
          description: The global identifier for the order line item.
        external_id:
          type:
            - string
            - 'null'
          maxLength: 100
          description: The external identifier for the order line item.
        quantity:
          type:
            - integer
            - 'null'
        restock:
          type:
            - boolean
            - 'null'
    TaxLine:
      title: TaxLine
      type: object
      required:
        - title
        - rate
        - price
      properties:
        title:
          type:
            - string
          maxLength: 100
        rate:
          type: number
          description: Tax rate as a decimal (e.g. `0.08` for 8%).
        price:
          $ref: '#/components/schemas/MoneySet'
    LineItemRefundResponse:
      title: LineItemRefundResponse
      type: object
      properties:
        id:
          type: integer
          format: int64
          readOnly: true
          description: The global identifier for the refund.
        external_id:
          type:
            - string
            - 'null'
        type:
          type:
            - string
            - 'null'
          description: Type of refund.
          enum:
            - line_item
            - shipping
            - other
        amount:
          $ref: '#/components/schemas/MoneySet'
        line_item:
          description: Present when `type` is `line_item`.
          anyOf:
            - $ref: '#/components/schemas/LineItemRefundLineItem'
            - type: 'null'
        created_at:
          oneOf:
            - $ref: '#/components/schemas/Date'
            - type: 'null'
        updated_at:
          oneOf:
            - $ref: '#/components/schemas/Date'
            - type: 'null'
    OrderLineItemDiscount:
      title: OrderLineItemDiscount
      type: object
      properties:
        external_id:
          type:
            - string
            - 'null'
          maxLength: 100
          examples:
            - 564400c7-7a6b-4f29-b6a5-7bb580b2992c
        discount_type:
          type: string
          description: Type of discount.
          enum:
            - amount
            - bonus
            - bonus_choice
            - fixed_price
            - free
            - percentage
            - percentage_off_options
            - price_book_price
            - total_fixed_price
        discount_relation:
          type:
            - string
            - 'null'
          description: Discount Relation.
          enum:
            - prereq
            - entitled
            - x
            - 'y'
        name:
          type:
            - string
          maxLength: 64
        code:
          type:
            - string
          maxLength: 100
        reason:
          type:
            - string
          maxLength: 512
        rate:
          type:
            - number
        tax_adjustment_money:
          $ref: '#/components/schemas/MoneySet'
        net_adjustment_money:
          $ref: '#/components/schemas/MoneySet'
    Duty:
      title: Duty
      type: object
      properties:
        hs_code:
          type:
            - string
            - 'null'
          maxLength: 10
        country_of_origin:
          type:
            - string
            - 'null'
          maxLength: 2
          examples:
            - US
            - CA
        price:
          $ref: '#/components/schemas/MoneySet'
        tax_lines:
          $ref: '#/components/schemas/TaxLines'
    FulfillmentLineItem:
      title: FulfillmentLineItem
      type: object
      properties:
        external_id:
          type:
            - string
            - 'null'
          maxLength: 64
          examples:
            - 564400c7-7a6b-4f29-b6a5-7bb580b2992c
        order_line_item_external_id:
          type: string
          maxLength: 64
          examples:
            - 564400c7-7a6b-4f29-b6a5-7bb580b2992c
        quantity:
          type: integer
    LineItemRefundLineItem:
      title: LineItemRefundLineItem
      type: object
      description: >
        Refund details when nested under a line item. Identifiers are not
        accepted; the parent line item provides the context.
      properties:
        quantity:
          type:
            - integer
            - 'null'
        restock:
          type:
            - boolean
            - 'null'
      additionalProperties: false
  responses:
    Unauthorized:
      description: >-
        Example response if request submitted without a valid API Key in
        X-Authorization.
      content:
        application/json:
          schema:
            type: object
            required:
              - errors
            properties:
              errors:
                type: string
                examples:
                  - Unauthorized.
      headers:
        X-Loop-Request-ID:
          schema:
            type: string
            examples:
              - 5a748e7c-5fcc-4fb0-a777-6a4d28e60d4c
            format: uuid
          description: UUID to aid in debugging API issues.
    NotFound:
      description: The requested entity could not be found.
      content:
        application/json:
          schema:
            type: object
            required:
              - message
            properties:
              message:
                type: string
                examples:
                  - Resource not found.
      headers:
        X-Loop-Request-ID:
          schema:
            type: string
          description: UUID to aid in debugging API issues.
  securitySchemes:
    read:
      type: apiKey
      in: header
      name: X-Authorization
      description: 'API Scope: "Order (read)"'
      x-scope: Order (Read)

````