openapi: 3.1.0
info:
  title: Storefront Orders
  version: 1.0.0
paths:
  /orders/{orderId}:
    get:
      operationId: getOrder
      summary: Get Order
      description: |-
        Returns *Order* data. This will return order data immediately after an order is placed on the storefront.

        > #### Note
        > * Substitute your storefront domain for `yourstore.example.com`. 
        > * The Send a Test Request feature is not currently supported for this endpoint.
      tags:
        - order
      parameters:
        - name: orderId
          in: path
          description: ID of an Order.
          required: true
          schema:
            type: integer
        - name: include
          in: query
          description: >-
            Sub-resources to include in an Order, in a comma-separated list. The ID and the specified fields will be
            returned.
          required: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/OrdersOrderIdGetParametersIncludeSchemaItems'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
servers:
  - url: https://your_store.example.com/api/storefront
    description: https://{store_domain}/api/storefront
components:
  schemas:
    OrdersOrderIdGetParametersIncludeSchemaItems:
      type: string
      enum:
        - lineItems
        - billingAddress
        - coupons
        - currency
        - taxes
        - payments
        - consignments
      title: OrdersOrderIdGetParametersIncludeSchemaItems
    Currency:
      type: object
      properties:
        name:
          type: string
          description: The currency name.
        code:
          type: string
          description: 'ISO-4217 currency code. (See: https://www.iso.org/iso-4217-currency-codes.html.)'
        symbol:
          type: string
          description: The currency symbol.
        decimalPlaces:
          type: number
          format: double
          description: Number of decimal places for the currency. For example, USD currency has two decimal places.
      description: This will always be the same between cart and checkout.
      title: Currency
    AppliedCoupon:
      type: object
      properties:
        id:
          type: string
          description: The coupon ID.
        code:
          type: string
          description: the coupon code
        displayName:
          type: string
          description: The coupon title based on different types provided in the control panel.
        couponType:
          type: string
          description: Key name to identify the type of coupon.
        discountedAmount:
          type: number
          format: double
          description: The discounted amount applied within a given context.
      required:
        - code
      title: AppliedCoupon
    ItemPhysicalDiscounts:
      type: object
      properties: {}
      description: >-
        List of discounts applied to this item. If no discount applied, empty array is returned. If discount has been
        applied, discount object returned.
      title: ItemPhysicalDiscounts
    GiftWrapping:
      type: object
      properties:
        name:
          type: string
        message:
          type: string
        amount:
          type: number
          format: double
      title: GiftWrapping
    ItemPhysicalCategoriesItems:
      type: object
      properties: {}
      title: ItemPhysicalCategoriesItems
    ItemPhysical:
      type: object
      properties:
        id:
          type: string
          description: The line-item ID.
        parentId:
          type: string
          description: Bundled items will have their parentʼs item ID.
        variantId:
          type: number
          format: double
          description: ID of the variant.
        productId:
          type: number
          format: double
          description: ID of the product.
        sku:
          type: string
          description: SKU of the variant.
        name:
          type: string
          description: The itemʼs product name.
        url:
          type: string
          description: The product URL.
        quantity:
          type: number
          format: double
          description: Quantity of this item.
        brand:
          type: string
          description: The product's brand.
        isTaxable:
          type: boolean
          description: Whether the item is taxable.
        imageUrl:
          type: string
          description: A publicly-accessible URL for an image of this item.
        discounts:
          $ref: '#/components/schemas/ItemPhysicalDiscounts'
          description: >-
            List of discounts applied to this item. If no discount applied, empty array is returned. If discount has
            been applied, discount object returned.
        discountAmount:
          type: number
          format: double
          description: The total value of all discounts applied to this item (excluding coupon).
        couponAmount:
          type: number
          format: double
          description: The total value of all coupons applied to this item.
        listPrice:
          type: number
          format: double
          description: >-
            The net item price before discounts and coupons. BigCommerce derives an item's list price from the product
            default price or, if applicable, the sale price configured in the admin panel.
        salePrice:
          type: number
          format: double
          description: The itemʼs price after all discounts are applied. (The final price before tax calculation.)
        extendedListPrice:
          type: number
          format: double
          description: The itemʼs list price multiplied by the quantity.
        extendedSalePrice:
          type: number
          format: double
          description: The itemʼs sale price multiplied by the quantity.
        type:
          type: string
          description: the product type - physical or digital.
        addedByPromotion:
          type: boolean
          description: Whether this item has been added automatically by a promotion.
        isShippingRequired:
          type: boolean
          description: Whether this item requires shipping to a physical address.
        giftWrapping:
          $ref: '#/components/schemas/GiftWrapping'
        categories:
          type: array
          items:
            $ref: '#/components/schemas/ItemPhysicalCategoriesItems'
          description: Categories the item belongs to.
      required:
        - quantity
      title: ItemPhysical
    AppliedDiscount:
      type: object
      properties:
        coupon:
          type: number
          format: double
          description: Property key is discount ID; property value is discount amount.
      title: AppliedDiscount
    OrderItemDigitalCategoriesItems:
      type: object
      properties: {}
      title: OrderItemDigitalCategoriesItems
    OrderItemDigital:
      type: object
      properties:
        id:
          type: string
          description: The line-item ID.
        parentId:
          type: string
          description: Bundled items will have their parentʼs item ID.
        variantId:
          type: number
          format: double
          description: ID of the variant.
        productId:
          type: number
          format: double
          description: ID of the product.
        sku:
          type: string
          description: SKU of the variant.
        name:
          type: string
          description: The itemʼs product name.
        url:
          type: string
          description: The product URL.
        quantity:
          type: number
          format: double
          description: Quantity of this item.
        brand:
          type: string
          description: The item's brand.
        isTaxable:
          type: boolean
          description: Whether the item is taxable.
        imageUrl:
          type: string
          description: A publicly-accessible URL for an image of this item.
        discounts:
          type: array
          items:
            $ref: '#/components/schemas/AppliedDiscount'
          description: A list of discounts applied to this item, as an array of AppliedDiscount objects.
        discountAmount:
          type: number
          format: double
          description: The total value of all discounts applied to this item (excluding coupon).
        couponAmount:
          type: number
          format: double
          description: The total value of all coupons applied to this item.
        listPrice:
          type: number
          format: double
          description: >-
            The net item price before discounts and coupons. BigCommerce derives an item's list price from the product
            default price or, if applicable, the sale price configured in the admin panel.
        salePrice:
          type: number
          format: double
          description: The itemʼs price after all discounts are applied. (The final price before tax calculation.)
        extendedListPrice:
          type: number
          format: double
          description: The itemʼs list price multiplied by the quantity.
        extendedSalePrice:
          type: number
          format: double
          description: The itemʼs sale price multiplied by the quantity.
        type:
          type: string
          description: the product type - physical or digital
        downloadFileUrls:
          type: array
          items:
            type: string
          description: URLs to download all product files.
        downloadPageUrl:
          type: string
          description: The URL for the combined downloads page.
        downloadSize:
          type: string
          description: Specifies the combined download size in human-readable style; for example, `30MB`.
        categories:
          type: array
          items:
            $ref: '#/components/schemas/OrderItemDigitalCategoriesItems'
          description: Categories the item belongs to.
      required:
        - quantity
      title: OrderItemDigital
    OrderItemGiftCertificate:
      type: object
      properties:
        name:
          type: string
          description: The itemʼs product name.
        quantity:
          type: number
          format: double
          description: Quantity of this item.
        isTaxable:
          type: boolean
          description: Whether the item is taxable.
        amount:
          type: number
          format: double
          description: Price of the item
        type:
          type: string
          description: Explicitly specifying the gift certificate type
      title: OrderItemGiftCertificate
    OrderLineItem:
      type: object
      properties:
        physicalItems:
          type: array
          items:
            $ref: '#/components/schemas/ItemPhysical'
          description: Array of `ItemPhysical` objects.
        digitalItems:
          type: array
          items:
            $ref: '#/components/schemas/OrderItemDigital'
          description: Array of `ItemDigital` objects.
        giftCertificate:
          type: array
          items:
            $ref: '#/components/schemas/OrderItemGiftCertificate'
          description: Array of `ItemGiftCertificate` objects.
      required:
        - physicalItems
        - digitalItems
        - giftCertificate
      title: OrderLineItem
    CustomField:
      type: object
      properties:
        fieldId:
          type: string
        fieldValue:
          type: string
          description: This can also be an array for fields that need to support list of values; for example, a set of checkboxes.
      title: CustomField
    AddressProperties:
      type: object
      properties:
        firstName:
          type: string
        lastName:
          type: string
        email:
          type: string
        company:
          type: string
        address1:
          type: string
        address2:
          type: string
        city:
          type: string
        stateOrProvince:
          type: string
          description: Represents state or province.
        stateOrProvinceCode:
          type: string
        country:
          type: string
        countryCode:
          type: string
          description: 'ISO 3166-1 alpha-2 country code. (See: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).'
        postalCode:
          type: string
        phone:
          type: string
        customFields:
          type: array
          items:
            $ref: '#/components/schemas/CustomField'
      required:
        - countryCode
      title: AddressProperties
    Status:
      type: string
      enum:
        - INCOMPLETE
        - PENDING
        - SHIPPED
        - PARTIALLY_SHIPPED
        - REFUNDED
        - CANCELLED
        - DECLINED
        - AWAITING_PAYMENT
        - AWAITING_PICKUP
        - AWAITING_SHIPMENT
        - COMPLETED
        - AWAITING_FULFILLMENT
        - MANUAL_VERIFICATION_REQUIRED
        - DISPUTED
        - PARTIALLY_REFUNDED
      description: Order status.
      title: Status
    OrderTaxesItems:
      type: object
      properties:
        name:
          type: string
        amount:
          type: integer
      title: OrderTaxesItems
    ConsignmentLineItem:
      type: object
      properties:
        id:
          type: integer
      title: ConsignmentLineItem
    ConsignmentFormField:
      type: object
      properties:
        name:
          type: string
        value:
          type:
            - string
            - 'null'
      title: ConsignmentFormField
    ShippingConsignment:
      type: object
      properties:
        lineItems:
          type: array
          items:
            $ref: '#/components/schemas/ConsignmentLineItem'
        shippingAddressId:
          type: integer
        firstName:
          type: string
        lastName:
          type: string
        company:
          type: string
        address1:
          type: string
        address2:
          type: string
        city:
          type: string
        stateOrProvince:
          type: string
        postalCode:
          type: string
        country:
          type: string
        countryCode:
          type: string
        email:
          type: string
        phone:
          type: string
        itemsTotal:
          type: integer
        itemsShipped:
          type: integer
        shippingMethod:
          type: string
        baseCost:
          type: number
          format: double
        costExTax:
          type: number
          format: double
        costIncTax:
          type: number
          format: double
        costTax:
          type: number
          format: double
        costTaxClassId:
          type: integer
        shippingCostBeforeDiscount:
          type: number
          format: double
          description: Estimated consignment shipping cost before any shipping discounts have been applied.
        comparisonShippingCost:
          type: number
          format: double
          description: >
            The consignment shipping cost to be shown to shopper in the summary as struck-through.

            - If the entered-price and display-price have the same tax setting (e.g.: both are tax-inclusive), this
            field will be the estimated shipping cost before any coupons applied (but after automatic promotions
            applied).

            - If the entered-price and display-price have different tax setting (e.g.: one is tax-inclusive, and one is
            tax-exclusive), this field will be the estimated shipping cost before any discounts applied, similar to the
            `shippingCostBeforeDiscount`.
        baseHandlingCost:
          type: number
          format: double
        handlingCostExTax:
          type: number
          format: double
        handlingCostIncTax:
          type: number
          format: double
        handlingCostTax:
          type: number
          format: double
        handlingCostTaxClassId:
          type: integer
        shippingZoneId:
          type: number
          format: double
        shippingZoneName:
          type: string
        customFields:
          type: array
          items:
            $ref: '#/components/schemas/ConsignmentFormField'
      description: Shipping consignment
      title: ShippingConsignment
    Consignments:
      type: object
      properties:
        shipping:
          type: array
          items:
            $ref: '#/components/schemas/ShippingConsignment'
          description: A list of shipping consignments.
      description: All the consignments of the order.
      title: Consignments
    Order:
      type: object
      properties:
        orderId:
          type: number
          format: double
        cartId:
          type: string
          format: uuid
          description: The ID of cart that was converted to order.
        currency:
          $ref: '#/components/schemas/Currency'
        isTaxIncluded:
          type: boolean
          description: Whether this item is taxable.
        baseAmount:
          type: number
          format: double
          description: Cost of cartʼs contents before applying discounts.
        discountAmount:
          type: string
          title: float
          description: Discounted amount.
        giftWrappingCostTotal:
          type: number
          format: double
          description: Gift wrapping for all items, including or excluding tax.
        orderAmount:
          type: number
          format: double
          description: >-
            Sum of line-items amounts, minus cart-level discounts and coupons. This amount includes taxes where
            applicable.
        orderAmountAsInteger:
          type: number
          format: double
          description: Order amount represented in integer. Eg. 1234 for $12.34
        coupons:
          type: array
          items:
            $ref: '#/components/schemas/AppliedCoupon'
          description: Array of `AppliedCoupon` objects applied to this cart.
        lineItems:
          type: array
          items:
            $ref: '#/components/schemas/OrderLineItem'
          description: Array of `LineItem` objects.
        customerId:
          type: string
        billingAddress:
          $ref: '#/components/schemas/AddressProperties'
        status:
          $ref: '#/components/schemas/Status'
        hasDigitalItems:
          type: boolean
          description: Specifies whether this order has at least one digital item.
        isDownloadable:
          type: boolean
          description: Specifies whether this order is fully paid, so that digital items can be downloaded.
        isComplete:
          type: boolean
          description: Specifies whether this order is complete and ready to be taken to the order confirmation page.
        customerMessage:
          type: string
          description: Shopperʼs provided message for the order.
        shippingCostTotal:
          type: number
          format: double
        shippingCostBeforeDiscount:
          type: number
          format: double
          description: Estimated total shipping cost before any shipping discounts have been applied.
        comparisonShippingCost:
          type: number
          format: double
          description: >
            The total shipping cost to be shown to shopper in the summary as struck-through.

            - If the entered-price and display-price have the same tax setting (e.g.: both are tax-inclusive), this
            field will be the estimated total shipping cost before any coupons applied (but after automatic promotions
            applied).

            - If the entered-price and display-price have different tax setting (e.g.: one is tax-inclusive, and one is
            tax-exclusive), this field will be the estimated total shipping cost before any discounts applied, similar
            to the `shippingCostBeforeDiscount`.
        handlingCostTotal:
          type: number
          format: double
        customerCanBeCreated:
          type: boolean
        taxes:
          type: array
          items:
            $ref: '#/components/schemas/OrderTaxesItems'
        taxTotal:
          type: integer
        channelId:
          type: number
          format: double
          description: ID of the channel which the order belongs to.
        consignments:
          $ref: '#/components/schemas/Consignments'
      title: Order
